implement-issue: dispatch child agents to implement ready issues via worktree isolation #7

New Issue

2026-06-26T11:34:36-04:00

steve commented

2026-06-26 11:34:36 -04:00

Problem Statement

A skilled agent triages an issue, verifies its claim, writes an agent brief, and labels it ready-for-agent. Then nothing happens. There is no skill that picks up a ready issue and implements it — the gap between "ready" and "done" is manual.

Solution

A user-invoked skill (/implement-issue <number>) that dispatches a child pi agent in an isolated git worktree to implement the issue end-to-end. The parent agent (the one running the skill) handles pre-flight checks, worktree creation, and child launch, then returns to the user immediately so they can fire the next issue. The child agent explores the codebase, implements with TDD, runs the full quality gate, pushes a branch, creates a PR, comments on the issue, and updates its label — all without further human involvement.

User Stories

As a developer, I want to type /implement-issue 42 and have an agent start working on issue #42 in an isolated workspace, so that I can immediately move on to the next issue.
As a developer, I want the agent to refuse to implement issues that are not labeled ready-for-agent, so that I never accidentally start work on an underspecified or untriaged issue.
As a developer, I want the agent to check for open blocker dependencies before starting, so that I do not waste time implementing something that depends on unfinished work.
As a developer, I want each implementation to happen in an isolated git worktree, so that my main working tree is never polluted by in-progress changes or dependency installs.
As a developer, I want the child agent to follow TDD (red-green-refactor), so that every implementation has test coverage.
As a developer, I want the child agent to run the full project quality gate (tests, lints, type checks) before pushing, so that broken code never reaches a branch.
As a developer, I want the issue label to reflect the implementation state (in-progress → in-review), so that I can query the tracker to see what is actively being worked on and what is awaiting review.
As a developer, I want the child agent to create a PR with a summary of changes and a link to the issue, so that reviewers have immediate context.
As a developer, I want to be able to run multiple implementations in parallel (separate worktrees, separate tmux windows), so that I can dispatch several issues at once.
As a developer, I want the parent agent to fail early and clearly if pre-conditions are not met (missing CLI, branch name collision, existing worktree), rather than wasting time on a doomed child session.
As a developer, I want the child agent to fail loudly and leave a clear recovery path if something goes wrong mid-implementation, so that I can jump into the tmux pane and recover manually.
As a developer, I want the parent agent to print the cleanup command for the worktree when it is done, so that I can remove the isolated workspace when I am finished reviewing.

Implementation Decisions

Skill location and invocation

Location: common/engineering/implement-issue/SKILL.md
Invocation: user-invoked (disable-model-invocation: true)
Leading word: implement-issue

Parent pre-flight checks (hard-stop on any failure)

tea CLI available on PATH
Issue #N exists and is open (tea issue <N>)
Issue is labeled ready-for-agent — refuse otherwise, pointing to /triage
No open blocker: parse issue body for "Blocked by #M" references; if any #M is open, stop
Remote origin exists and target base branch exists on remote (git ls-remote)
Derived branch name issue-<N>-<slug> does not exist on remote (git ls-remote --heads)
Target worktree path ../<repo>-issue-<N> does not already exist (override with --force)

Parent setup

git fetch origin <base> — default base is the repo default branch (inferred or main)
Change issue label: ready-for-agent → in-progress via tea issue edit --add-label "in-progress" --remove-label "ready-for-agent"
git worktree add ../<repo>-issue-<N> <base>

Branch naming

Format: issue-<N>-<slug>
Slug derived by parent from issue title: lowercase, sanitize to [a-z0-9-], truncate to ~4–5 short words (max ~50 chars)
Fallback if title cannot produce a clean slug: issue-<N>

Worktree path

Format: ../<repo-name>-issue-<N> (sibling to main repo)
Cleanup: manual — parent prints git worktree remove ../<repo>-issue-<N> && git worktree prune at end

Child prompt composition

Parent assembles a prompt containing:

Issue body (full) and all comments
Standing instruction: "Implement using TDD: write a failing test first, make it pass, refactor. Explore the codebase before writing code. Respect ADRs and the project domain glossary. Set up the project (install dependencies, build) before starting."
Target: "Base branch: . Target your PR at ."
Numbered checklist: explore → setup deps → implement with TDD → full quality gate → push → PR → comment → label change → DONE banner
Final instruction: "When finished, print DONE — issue #N"

Child launch

Parent runs tmux new-window -c <worktree-path> pi with the composed prompt
Pane stays open after completion for review

Child implementation expectations

Create branch issue-<N>-<slug>
Implement with TDD (red-green-refactor)
Run full project quality gate (infer command from project: package.json scripts, Makefile, Cargo.toml, etc.), fix until green
Commit(s) using conventional commits: feat: for enhancement, fix: for bug, with issue reference (#N)
Push branch
Create PR targeting base branch; PR body: link to issue + one-sentence summary + short key-changes list
Comment on issue with PR link: tea comment <N> "PR #<PR-N> opened: <link>"
Change issue label: in-progress → in-review via tea issue edit
Print DONE — issue #N

Child failure handling

Child reports clearly where it stopped and what remains: "✓ Implementation complete. ✓ Tests pass. ✗ PR creation failed: . Manual: tea pulls create ..."
No automated recovery — user switches to the tmux pane and guides manually

Parallel runs

Allowed. Each invocation creates an independent worktree and tmux window. No cross-issue coordination.

Label vocabulary extension

Two new labels added to the tracker vocabulary:

in-progress — an agent (or human) is actively implementing this issue
in-review — implementation is pushed and a PR is open, awaiting review

Testing Decisions

What makes a good test

The parent pre-flight checks should be tested by invoking the skill in each failure condition and confirming the correct refusal message.
The child should be tested by running against a known ready-for-agent issue and verifying the full chain: worktree created, branch pushed, PR created, issue commented, label updated.
Test with a simulated failure (e.g., no remote) to confirm child failure reporting behavior.

Prior art

No existing skill tests in this repo — this would be the first skill with an automated dispatch component. Manual verification is the initial test strategy: fire /implement-issue against a real issue and observe the child in the tmux pane.
The triage skill has a similar pre-flight pattern (check labels, check blockers, refuse with messages) — follow its style.

Out of Scope

Automated worktree cleanup — cleanup is manual via the printed command
PR merge — the child creates a PR but does not merge it
Issue closure — the child does not close the issue; that happens when the PR merges
Monitoring/retry of failed children — fire-and-forget; the user checks the tmux pane
Queuing or scheduling — each invocation is independent; no global work queue
Support for non-Gitea forges — Gitea only (this repo uses Gitea)
Parent providing codebase analysis in the child prompt — the child explores fresh

Further Notes

The deprecated forge-router, forge-gitea, and forge-interaction skills attempted broad forge workflows. This skill is intentionally narrow: it only implements a single ready issue. It reuses the tea CLI conventions already documented in /docs/agents/issue-tracker.md.
The tea CLI is the only forge tool needed — no git worktree knowledge is assumed in the child; the parent handles worktree creation.
This skill completes the pipeline: to-prd → to-issues → triage → implement-issue → (PR review → merge → close).

## Problem Statement A skilled agent triages an issue, verifies its claim, writes an agent brief, and labels it `ready-for-agent`. Then nothing happens. There is no skill that picks up a ready issue and implements it — the gap between "ready" and "done" is manual. ## Solution A user-invoked skill (`/implement-issue <number>`) that dispatches a child `pi` agent in an isolated git worktree to implement the issue end-to-end. The parent agent (the one running the skill) handles pre-flight checks, worktree creation, and child launch, then returns to the user immediately so they can fire the next issue. The child agent explores the codebase, implements with TDD, runs the full quality gate, pushes a branch, creates a PR, comments on the issue, and updates its label — all without further human involvement. ## User Stories 1. As a developer, I want to type `/implement-issue 42` and have an agent start working on issue #42 in an isolated workspace, so that I can immediately move on to the next issue. 2. As a developer, I want the agent to refuse to implement issues that are not labeled `ready-for-agent`, so that I never accidentally start work on an underspecified or untriaged issue. 3. As a developer, I want the agent to check for open blocker dependencies before starting, so that I do not waste time implementing something that depends on unfinished work. 4. As a developer, I want each implementation to happen in an isolated git worktree, so that my main working tree is never polluted by in-progress changes or dependency installs. 5. As a developer, I want the child agent to follow TDD (red-green-refactor), so that every implementation has test coverage. 6. As a developer, I want the child agent to run the full project quality gate (tests, lints, type checks) before pushing, so that broken code never reaches a branch. 7. As a developer, I want the issue label to reflect the implementation state (`in-progress` → `in-review`), so that I can query the tracker to see what is actively being worked on and what is awaiting review. 8. As a developer, I want the child agent to create a PR with a summary of changes and a link to the issue, so that reviewers have immediate context. 9. As a developer, I want to be able to run multiple implementations in parallel (separate worktrees, separate tmux windows), so that I can dispatch several issues at once. 10. As a developer, I want the parent agent to fail early and clearly if pre-conditions are not met (missing CLI, branch name collision, existing worktree), rather than wasting time on a doomed child session. 11. As a developer, I want the child agent to fail loudly and leave a clear recovery path if something goes wrong mid-implementation, so that I can jump into the tmux pane and recover manually. 12. As a developer, I want the parent agent to print the cleanup command for the worktree when it is done, so that I can remove the isolated workspace when I am finished reviewing. ## Implementation Decisions ### Skill location and invocation - **Location**: `common/engineering/implement-issue/SKILL.md` - **Invocation**: user-invoked (`disable-model-invocation: true`) - **Leading word**: `implement-issue` ### Parent pre-flight checks (hard-stop on any failure) 1. `tea` CLI available on PATH 2. Issue #N exists and is open (`tea issue <N>`) 3. Issue is labeled `ready-for-agent` — refuse otherwise, pointing to `/triage` 4. No open blocker: parse issue body for "Blocked by #M" references; if any #M is open, stop 5. Remote `origin` exists and target base branch exists on remote (`git ls-remote`) 6. Derived branch name `issue-<N>-<slug>` does not exist on remote (`git ls-remote --heads`) 7. Target worktree path `../<repo>-issue-<N>` does not already exist (override with `--force`) ### Parent setup 1. `git fetch origin <base>` — default base is the repo default branch (inferred or `main`) 2. Change issue label: `ready-for-agent` → `in-progress` via `tea issue edit --add-label "in-progress" --remove-label "ready-for-agent"` 3. `git worktree add ../<repo>-issue-<N> <base>` ### Branch naming - Format: `issue-<N>-<slug>` - Slug derived by parent from issue title: lowercase, sanitize to `[a-z0-9-]`, truncate to ~4–5 short words (max ~50 chars) - Fallback if title cannot produce a clean slug: `issue-<N>` ### Worktree path - Format: `../<repo-name>-issue-<N>` (sibling to main repo) - Cleanup: manual — parent prints `git worktree remove ../<repo>-issue-<N> && git worktree prune` at end ### Child prompt composition Parent assembles a prompt containing: - Issue body (full) and all comments - Standing instruction: "Implement using TDD: write a failing test first, make it pass, refactor. Explore the codebase before writing code. Respect ADRs and the project domain glossary. Set up the project (install dependencies, build) before starting." - Target: "Base branch: <base>. Target your PR at <base>." - Numbered checklist: explore → setup deps → implement with TDD → full quality gate → push → PR → comment → label change → DONE banner - Final instruction: "When finished, print DONE — issue #N" ### Child launch - Parent runs `tmux new-window -c <worktree-path> pi` with the composed prompt - Pane stays open after completion for review ### Child implementation expectations - Create branch `issue-<N>-<slug>` - Implement with TDD (red-green-refactor) - Run full project quality gate (infer command from project: package.json scripts, Makefile, Cargo.toml, etc.), fix until green - Commit(s) using conventional commits: `feat:` for enhancement, `fix:` for bug, with issue reference `(#N)` - Push branch - Create PR targeting base branch; PR body: link to issue + one-sentence summary + short key-changes list - Comment on issue with PR link: `tea comment <N> "PR #<PR-N> opened: <link>"` - Change issue label: `in-progress` → `in-review` via `tea issue edit` - Print `DONE — issue #N` ### Child failure handling - Child reports clearly where it stopped and what remains: "✓ Implementation complete. ✓ Tests pass. ✗ PR creation failed: <error>. Manual: tea pulls create ..." - No automated recovery — user switches to the tmux pane and guides manually ### Parallel runs - Allowed. Each invocation creates an independent worktree and tmux window. No cross-issue coordination. ### Label vocabulary extension Two new labels added to the tracker vocabulary: - `in-progress` — an agent (or human) is actively implementing this issue - `in-review` — implementation is pushed and a PR is open, awaiting review ## Testing Decisions ### What makes a good test - The parent pre-flight checks should be tested by invoking the skill in each failure condition and confirming the correct refusal message. - The child should be tested by running against a known `ready-for-agent` issue and verifying the full chain: worktree created, branch pushed, PR created, issue commented, label updated. - Test with a simulated failure (e.g., no remote) to confirm child failure reporting behavior. ### Prior art - No existing skill tests in this repo — this would be the first skill with an automated dispatch component. Manual verification is the initial test strategy: fire `/implement-issue` against a real issue and observe the child in the tmux pane. - The `triage` skill has a similar pre-flight pattern (check labels, check blockers, refuse with messages) — follow its style. ## Out of Scope - Automated worktree cleanup — cleanup is manual via the printed command - PR merge — the child creates a PR but does not merge it - Issue closure — the child does not close the issue; that happens when the PR merges - Monitoring/retry of failed children — fire-and-forget; the user checks the tmux pane - Queuing or scheduling — each invocation is independent; no global work queue - Support for non-Gitea forges — Gitea only (this repo uses Gitea) - Parent providing codebase analysis in the child prompt — the child explores fresh ## Further Notes - The deprecated `forge-router`, `forge-gitea`, and `forge-interaction` skills attempted broad forge workflows. This skill is intentionally narrow: it only implements a single ready issue. It reuses the `tea` CLI conventions already documented in `/docs/agents/issue-tracker.md`. - The `tea` CLI is the only forge tool needed — no `git worktree` knowledge is assumed in the child; the parent handles worktree creation. - This skill completes the pipeline: `to-prd` → `to-issues` → `triage` → `implement-issue` → (PR review → merge → close).

steve added the in-progress label 2026-06-26 11:38:10 -04:00

steve referenced this issue from a commit

2026-06-26 11:39:27 -04:00

feat: add implement-issue skill for dispatching child agents via worktree isolation (#7)

steve referenced a pull request that will close this issue

2026-06-26 11:39:31 -04:00

feat: add implement-issue skill for dispatching child agents via worktree isolation #8

steve commented

2026-06-26 11:39:35 -04:00