Scaled-Tech-Consulting/Gitea-Tools
2
0
Fork 0
Code Issues 6 Pull Requests 2 Actions Packages Projects Releases Wiki Activity

Standardize isolated branch worktrees for LLM work #38

New Issue
Closed
opened 2026-07-02 01:39:07 -05:00 by jcwalker3 · 2 comments
jcwalker3 commented 2026-07-02 01:39:07 -05:00
Owner
Copy Link
Copy Source

Problem

LLMs must not perform implementation work in the main repository checkout. Each issue/PR should use its own isolated branch folder/worktree so multiple LLMs can work or review concurrently without overwriting, blocking, or contaminating each other’s changes.

Dirty work in one issue currently blocks unrelated issue work when all work happens in the main checkout. The workflow needs to standardize isolated branch worktrees/folders.

Required behavior

  1. Add a standard ignored branch-worktree directory, preferably branches/.
  2. Add it to .gitignore.
  3. Document that:
    • all issue work must be done inside branches/<branch-name>/
    • the main repo checkout is used only for orchestration/status, not edits
    • dirty work in one branch folder does not block creating a separate branch folder for another issue
    • review work should use a separate review worktree/folder
    • once a PR is merged or closed, its branch folder may be removed
  4. Add helper scripts if appropriate, for example scripts/worktree-start, scripts/worktree-review, or scripts/worktree-clean.
  5. Helpers, if added, should fetch/prune first, create branch-specific worktrees under branches/, branch from latest remote master, refuse unsafe reuse, print the worktree path, and avoid deletion unless cleanup is explicitly requested after merge/close.
  6. Update runbooks to make this the default LLM workflow.
  7. Make clear issue creation/claiming can happen from the orchestration checkout, but file edits must happen only in the issue branch worktree.

Safety

  • Do not touch existing untracked artifacts such as .claude/, .codex/, or report.xml.
  • Do not modify or clean up existing dirty work such as fix/issue-36-config-menu-ux.
  • Do not edit another issue’s branch folder unless explicitly assigned.
  • Do not clean another issue’s branch folder unless the PR is merged/closed and cleanup is explicitly part of the task.

Acceptance criteria

  • branches/ is ignored by git.
  • Runbooks clearly require all LLM issue work to happen in isolated branch folders.
  • Dirty work in one issue no longer blocks unrelated issue work.
  • Review and implementation work are isolated.
  • Cleanup rules are documented.
  • Existing dirty issue #36 work is left untouched.
  • Full checks pass.
## Problem LLMs must not perform implementation work in the main repository checkout. Each issue/PR should use its own isolated branch folder/worktree so multiple LLMs can work or review concurrently without overwriting, blocking, or contaminating each other’s changes. Dirty work in one issue currently blocks unrelated issue work when all work happens in the main checkout. The workflow needs to standardize isolated branch worktrees/folders. ## Required behavior 1. Add a standard ignored branch-worktree directory, preferably `branches/`. 2. Add it to `.gitignore`. 3. Document that: - all issue work must be done inside `branches/<branch-name>/` - the main repo checkout is used only for orchestration/status, not edits - dirty work in one branch folder does not block creating a separate branch folder for another issue - review work should use a separate review worktree/folder - once a PR is merged or closed, its branch folder may be removed 4. Add helper scripts if appropriate, for example `scripts/worktree-start`, `scripts/worktree-review`, or `scripts/worktree-clean`. 5. Helpers, if added, should fetch/prune first, create branch-specific worktrees under `branches/`, branch from latest remote `master`, refuse unsafe reuse, print the worktree path, and avoid deletion unless cleanup is explicitly requested after merge/close. 6. Update runbooks to make this the default LLM workflow. 7. Make clear issue creation/claiming can happen from the orchestration checkout, but file edits must happen only in the issue branch worktree. ## Safety - Do not touch existing untracked artifacts such as `.claude/`, `.codex/`, or `report.xml`. - Do not modify or clean up existing dirty work such as `fix/issue-36-config-menu-ux`. - Do not edit another issue’s branch folder unless explicitly assigned. - Do not clean another issue’s branch folder unless the PR is merged/closed and cleanup is explicitly part of the task. ## Acceptance criteria - `branches/` is ignored by git. - Runbooks clearly require all LLM issue work to happen in isolated branch folders. - Dirty work in one issue no longer blocks unrelated issue work. - Review and implementation work are isolated. - Cleanup rules are documented. - Existing dirty issue #36 work is left untouched. - Full checks pass.
jcwalker3 added the status:in-progress label 2026-07-02 01:39:20 -05:00
jcwalker3 commented 2026-07-02 01:39:21 -05:00
Author
Owner
Copy Link
Copy Source

Starting implementation. Planned branch: docs/issue-38-worktree-standard; planned isolated worktree path: branches/docs-issue-38-worktree-standard. I will leave the existing dirty fix/issue-36-config-menu-ux checkout and untracked local artifacts untouched.

Starting implementation. Planned branch: `docs/issue-38-worktree-standard`; planned isolated worktree path: `branches/docs-issue-38-worktree-standard`. I will leave the existing dirty `fix/issue-36-config-menu-ux` checkout and untracked local artifacts untouched.
jcwalker3 commented 2026-07-02 01:45:02 -05:00
Author
Owner
Copy Link
Copy Source

Completing this on the existing branch docs/issue-38-worktree-standard (worktree under branches/): adding scripts/worktree-review + scripts/worktree-clean, tests (path generation + refuse-overwrite), and filling doc gaps (review worktree, no-edit-others, cleanup-only-after-merge). PR to follow. (#39 closed as duplicate.)

Completing this on the existing branch `docs/issue-38-worktree-standard` (worktree under `branches/`): adding `scripts/worktree-review` + `scripts/worktree-clean`, tests (path generation + refuse-overwrite), and filling doc gaps (review worktree, no-edit-others, cleanup-only-after-merge). PR to follow. (#39 closed as duplicate.)
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
chore
documentation
Docs / runbooks
 gitea
Gitea MCP workflow
 important
mcp
MCP server / tooling
 mutating
Mutating action; requires gating
 nice-to-have
read-only
Read-only, no mutation
 roadmap
Roadmap / umbrella issue
 security
Security / trust boundary
 status:in-progress
Issue is being worked on
No Label status:in-progress
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jcwalker3 sysadmin
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#38
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?