work-on-issues

Work on Issues

There are three phases to work on issues:

1. Tracker Setup

Detect host via git remote -v. Set $TRACKER to gh or glab. Terminologies:

• GitHub: pr / comment
• GitLab: mr / note

---

2. Phase 1: Fetch & Triage

1. List open issues: Use gh issue list --state open --json number,title,labels or glab issue list -O json.
2. Filter: Keep only main issues (title starts with PRD: or feat:). Others are skipped for auto/batch runs (but allowed if explicitly picked).
3. Choice: User selects issue number or onwards mode.
4. Pre-checks:
   • Verify open (Skip if closed).
   • Detect PRD/Epic by label PRD or title prefix PRD:. Skip implementation, add to $PRD_TRACKER for auto-close check.
5. Read Details: Fetch full issue view and comments (gh issue view --comments / glab issue view --comments).
6. Resolve Parent PRD: Find the PRD owning this issue — search open PRD issues (PRD: prefix or PRD label) for a body referencing #<number>, or use tracker sub-issue/blocked-by links — and fetch its body and comments. This context is passed to the implementer in Phase 2.
7. Assign & Label: Mark in-progress (by applying in-progress label and removing ready-for-agent and needs-triage).

---

3. Dependencies & Linking

Parse ## Blocked by in issue body (matches #42 or full issue URL) to build DEPS[issue] = [blockers]. If possible, create native tracker links (e.g., GitLab API /links with is_blocked_by or GitHub sub-issues API with blocked_by=true). Fall back to text references.

---

4. Phase 2: Implement (One Main Issue at a Time)

Sub-agent only. Every issue is implemented by a dispatched sub-agent — in single-issue mode, batch mode, and onwards mode alike. The orchestrator fetches, triages, dispatches, and submits; it never edits files, writes code, or runs tests itself. If an issue looks too small to bother dispatching, that is exactly the case that still goes to a sub-agent.

1. Create Worktree:

   git worktree add .claude/worktrees/issue-<number> -b work-on-issue-<number>
   

2. Copy .env files: Copy .env and .env.* files into worktree directory.
3. Dispatch Sub-Agent using haiku model (inside .claude/worktrees/issue-<number>): The sub-agent starts with no context beyond this prompt — a constraint not inlined here does not exist for the implementer. Fill every slot below; an AC line like "follows PRD #3" carries no weight until the PRD's actual constraints are inlined. Prompt spec:

   Implement issue #<number>: <title>.
   Issue body (verbatim):
   <full issue description — summary, acceptance criteria, everything in the body>
   Issue comments (verbatim, in order, or "none"):
   <all comments, attributing each to its author>
   Parent PRD context (#<PRD number>: <PRD title>, or "none"):
   <full PRD body and its comments, or "no comments">
   Branch/Worktree: work-on-issue-<number> in .claude/worktrees/issue-<number>
   API/best-practices: Search via `context7`, `/brightdata-plugin:search`, `/search`, or WebSearch before writing code if unsure.
   Stuck on errors: If 2+ consecutive failures, you MUST research via `context7`, `/brightdata-plugin:search`, `/search`, or WebSearch first (they are available) to find the correct API/approach, then retry. Only escalate after researching.
   Parallel subtasks: Decompose & dispatch sub-agents if tasks are independent (no shared files/dirs).
   Post-implementation: Check output, diff, and run tests and run `/find-mismatch` skill on modified files only. If the programming language is typescript or javascript, run `npx fallow audit` (Make sure to install `fallow` if not present). If errors, fix and re-run tests.
   Output: Summary, find-mismatch fixes, tests run, and commit hash.
   Commit format: `fix: resolve #<number> — <short description>`
   

4. Commit: Ensure changes are committed in worktree (fix: resolve #<number> — <desc>).

---

5. Phase 3: Submit & Close

1. Create PR/MR: Link to issue using "Closes #".
2. Auto-Merge: Merge immediately (squash & delete branch).
3. Comment: Post summary of implementation.
4. Close: Remove triage/progress labels (like in-progress), add closed, and close issue.
5. Propagate .env files: Copy modified env files back to main working directory before worktree removal:

   WT=.claude/worktrees/issue-<number>
   for wtf in "$WT"/.env "$WT"/.env.*; do
     [ -f "$wtf" ] || continue
     base=$(basename "$wtf")
     if [ ! -f "$base" ] || ! cmp -s "$base" "$wtf"; then
       cp "$wtf" "$base" && echo "Propagated $base back"
     fi
   done
   

6. Clean up:

   git worktree remove .claude/worktrees/issue-<number>
   git branch -d work-on-issue-<number>
   

---

6. PRD Auto-Close

After closing a sub-issue, check all PRDs in PRD_TRACKER. Read PRD description/links. If all referenced sub-issues (#42 etc.) are closed, close the PRD and remove from PRD_TRACKER.

---

7. Subtask Parallelization

The dispatched sub-agent decomposes the issue into subtasks if:

• Touch non-overlapping files/folders.
• Independent outputs (no order dependency). Keep sequential if they share files, have strict flow dependencies, or need configuration first.

Subtask Prompt Spec:

Sub-agents are fresh contexts too — each subtask prompt inlines the context bearing on that subtask (same rule as the main dispatch).

Implement subtask for issue #<number>: <title>.
Subtask: <details>
Issue context (verbatim excerpts bearing on this subtask): <issue body / comments / parent-PRD constraints>
Working Directory: .claude/worktrees/issue-<number>
Scope: Modify <MAY_MODIFY>, DO NOT modify <MUST_NOT_MODIFY>.
Compile/Lint errors: If 2+ consecutive failures or any 3rd party dependency issues, research via `context7`, `/brightdata-plugin:search`, `/search`, or WebSearch first (they are available) to find the correct API/approach, then retry. Check Reference Directories (<RefDirs>) to align configurations.
Post-implementation: Run `/find-mismatch` skill on modified files, auto-fix.
Verification: Run relevant tests. Return summary, modified files, test results.

---

8. Execution Modes

Batch & Onwards Mode

1. Fetch all open issues, filter to main issues (PRD:, feat:).
2. Parse DEPS map from issue bodies, set formal links.
3. Show progress table: | Issue | Title | Type | Blocked By | Agent | Status | PR/MR |
4. Loop:
   • Select next issue with zero unresolved blockers. Skip closed or PRD issues.
   • Dispatch sub-agent to worktree.
   • Run verification -> PR/MR merge -> close -> env propagation -> clean up -> check PRDs.
   • Re-evaluate dependencies. Repeat.
5. Re-fetch all open issues after finishing (Outer loop) to pick up new main issues. Exit only if no open main issues remain or user interrupts.

Single Issue Mode

Execute only the selected issue, end to end, via the same Phase 2 sub-agent dispatch. Skip dependency graph processing.

---

9. Labels & Helpers

Label	Meaning	Color
PRD	Parent tracking issue	#0075CA
in-progress	Active	#E4E669
ready-for-agent	Ready for agent	#0E8A16
closed	Closed by AI / Finished	#5319E7

To apply labels, try updating directly. If not found, create label first (e.g. color #E4E669 for in-progress) and retry.

---

10. Edge Cases

• No CLI: Use APIs directly or ask user to install gh/glab.
• No Fallow: Ask user to install fallow for JS/TS security audit.
• Conflict/Cycle: Report circular dependencies, skip affected issues.
• External Blockers: Treat open external issues as unresolved blockers.
• API Link Failure: Fall back to text references.
• No Main Issues: Inform user, ask if they want to process non-main issues.
• Env files gitignored: Env files must be propagated back before worktree removal to persist across runs. Do not commit secrets.