Complete isolated-worktree helpers (worktree-review, worktree-clean, tests) #39

New Issue

2026-07-02T01:42:56-05:00

jcwalker3 commented

2026-07-02 01:42:56 -05:00

Problem

LLMs should not do implementation or review work in the main repository checkout. Dirty work from one issue can block unrelated work and risks overwriting/contaminating another LLM's changes.

Goal

All issue work happens in isolated branch worktrees under an ignored branches/ directory, so multiple LLMs can work/review concurrently without blocking each other.

Required behavior

Standard ignored worktree dir: branches/.
Add branches/ to .gitignore.
Document the rule: main checkout = orchestration/status only; implementation work in branches/<branch-name>/; review work in a separate review worktree; no LLM edits another issue's branch folder unless assigned; branch folders removed only after PR merge/close + explicit cleanup.
Helper scripts: scripts/worktree-start, scripts/worktree-review, scripts/worktree-clean.
Helpers: fetch/prune first; create branch-specific worktrees under branches/; branch from latest remote master; refuse to overwrite an existing worktree; print the created path; delete nothing unless cleanup is explicitly requested.

Example

git fetch prgs --prune
git worktree add -b fix/issue-123-example branches/fix-issue-123-example prgs/master
cd branches/fix-issue-123-example

Cleanup after merge:

git fetch prgs --prune
git worktree remove branches/fix-issue-123-example
git branch -d fix/issue-123-example

Acceptance criteria

branches/ ignored by git.
Runbooks require isolated worktrees for implementation + review.
Dirty work in one issue no longer blocks unrelated work.
Cleanup rules documented.
No unrelated local artifacts touched.
bash -n on new scripts, full pytest, git diff --check pass.

Non-goals

No change to MCP runtime, Gitea API operations, credential storage, or the canonical profile model.

## Problem LLMs should not do implementation or review work in the main repository checkout. Dirty work from one issue can block unrelated work and risks overwriting/contaminating another LLM's changes. ## Goal All issue work happens in isolated branch worktrees under an ignored `branches/` directory, so multiple LLMs can work/review concurrently without blocking each other. ## Required behavior 1. Standard ignored worktree dir: `branches/`. 2. Add `branches/` to `.gitignore`. 3. Document the rule: main checkout = orchestration/status only; implementation work in `branches/<branch-name>/`; review work in a separate review worktree; no LLM edits another issue's branch folder unless assigned; branch folders removed only after PR merge/close + explicit cleanup. 4. Helper scripts: `scripts/worktree-start`, `scripts/worktree-review`, `scripts/worktree-clean`. 5. Helpers: fetch/prune first; create branch-specific worktrees under `branches/`; branch from latest remote `master`; refuse to overwrite an existing worktree; print the created path; delete nothing unless cleanup is explicitly requested. ## Example ```bash git fetch prgs --prune git worktree add -b fix/issue-123-example branches/fix-issue-123-example prgs/master cd branches/fix-issue-123-example ``` Cleanup after merge: ```bash git fetch prgs --prune git worktree remove branches/fix-issue-123-example git branch -d fix/issue-123-example ``` ## Acceptance criteria - `branches/` ignored by git. - Runbooks require isolated worktrees for implementation + review. - Dirty work in one issue no longer blocks unrelated work. - Cleanup rules documented. - No unrelated local artifacts touched. - `bash -n` on new scripts, full pytest, `git diff --check` pass. ## Non-goals No change to MCP runtime, Gitea API operations, credential storage, or the canonical profile model.

jcwalker3 added the status:in-progress label 2026-07-02 01:43:06 -05:00

jcwalker3 commented

2026-07-02 01:45:00 -05:00

Duplicate of #38 (same task, already in-progress with a pushed branch docs/issue-38-worktree-standard). Closing; completing the work under #38.

Duplicate of #38 (same task, already in-progress with a pushed branch `docs/issue-38-worktree-standard`). Closing; completing the work under #38.

jcwalker3 removed the status:in-progress label 2026-07-02 01:45:01 -05:00

jcwalker3 closed this issue

2026-07-02 01:45:01 -05:00

jcwalker3 referenced this issue

2026-07-02 01:45:02 -05:00

Standardize isolated branch worktrees for LLM work #38

jcwalker3 changed title from ~~Standardize isolated branch worktrees for LLM work~~ to Complete isolated-worktree helpers (worktree-review, worktree-clean, tests)

2026-07-02 01:52:16 -05:00

jcwalker3 reopened this issue

2026-07-02 01:52:16 -05:00

jcwalker3 added the status:in-progress label 2026-07-02 01:52:17 -05:00

jcwalker3 commented

2026-07-02 01:52:17 -05:00

Reopened + repurposed. #38 merged only the partial standard (branches/ gitignore + runbook + scripts/worktree-start) into master (7e8256c). This issue tracks the remainder of the acceptance criteria: scripts/worktree-review, scripts/worktree-clean, and tests. Branch: feat/issue-39-worktree-helpers from master.

Note: the #38 branch worktree under branches/ was removed by external cleanup mid-task; completing on a normal branch in the main checkout.

Reopened + repurposed. #38 merged only the partial standard (`branches/` gitignore + runbook + `scripts/worktree-start`) into master (7e8256c). This issue tracks the remainder of the acceptance criteria: `scripts/worktree-review`, `scripts/worktree-clean`, and tests. Branch: `feat/issue-39-worktree-helpers` from master. Note: the #38 branch worktree under `branches/` was removed by external cleanup mid-task; completing on a normal branch in the main checkout.

jcwalker3 referenced this issue from a commit

2026-07-02 01:55:01 -05:00

feat: complete isolated-worktree helpers — worktree-review, worktree-clean, tests (#39)

jcwalker3 referenced a pull request that will close this issue

2026-07-02 01:55:25 -05:00

feat: complete isolated-worktree helpers — worktree-review, worktree-clean, tests (#39) #41

jcwalker3 closed this issue

2026-07-02 02:02:59 -05:00

~~jcwalker3 referenced this issue 2026-07-02 02:21:15 -05:00~~

Refactor and expand portable LLM workflow skill templates #46

jcwalker3 referenced this issue from a commit

2026-07-02 02:26:27 -05:00