From f4e953186e0e41df0f73d98ba7b26a9890e24657 Mon Sep 17 00:00:00 2001 From: Steve Beaulac Date: Fri, 24 Jul 2026 00:44:51 -0400 Subject: [PATCH] refactor(engineering): split implement into isolation-tmux and isolation Replace the monolithic implement-issue and implement skills with two focused alternatives: implement-isolation (subagent + reviewer) and implement-isolation-tmux (tmux-launch-agent for fire-and-forget). Update the README to list the new skills. --- common/engineering/README.md | 3 +- .../implement-isolation-tmux/SKILL.md | 72 ++++++++++++++++++ .../engineering/implement-isolation/SKILL.md | 59 +++++++++++++++ common/engineering/implement-issue/SKILL.md | 74 ------------------- common/engineering/implement/SKILL.md | 47 ------------ 5 files changed, 133 insertions(+), 122 deletions(-) create mode 100644 common/engineering/implement-isolation-tmux/SKILL.md create mode 100644 common/engineering/implement-isolation/SKILL.md delete mode 100644 common/engineering/implement-issue/SKILL.md delete mode 100644 common/engineering/implement/SKILL.md diff --git a/common/engineering/README.md b/common/engineering/README.md index b4cf3c0..32f8a0e 100644 --- a/common/engineering/README.md +++ b/common/engineering/README.md @@ -5,7 +5,8 @@ Daily code work. ## User-invoked - [commit-staged](commit-staged/SKILL.md) — Commit staged files with a conventional commit message. -- [implement-issue](implement-issue/SKILL.md) — Dispatch a child agent in an isolated git worktree to implement a piece of work based on a PRD or set of issues. +- [implement-isolation](implement-isolation/SKILL.md) — Implement work in an isolated git worktree via subagent with review. +- [implement-isolation-tmux](implement-isolation-tmux/SKILL.md) — Dispatch a child agent into its own tmux window in an isolated git worktree for fire-and-forget implementation. - [project-context-pack](project-context-pack/SKILL.md) — Use when the user wants a bounded repo context pack, project map, codebase index, or cached memory file so later work uses fd/rg/tree-sitter/LSP instead of repeated browsing. - [setup-skills](setup-skills/SKILL.md) — Configure this repo for the engineering skills, set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills. diff --git a/common/engineering/implement-isolation-tmux/SKILL.md b/common/engineering/implement-isolation-tmux/SKILL.md new file mode 100644 index 0000000..c96d72a --- /dev/null +++ b/common/engineering/implement-isolation-tmux/SKILL.md @@ -0,0 +1,72 @@ +--- +name: implement-isolation-tmux +description: "Dispatch a child agent in an isolated git worktree to implement a piece of work based on a PRD or set of issues." +disable-model-invocation: true +--- + +## Invocation + +/skill:implement-isolation-tmux [--base ] [--force] + +- `` — required, the issue number +- `--base ` — optional, target base branch (default: repo default branch) +- `--force` — optional, remove the existing worktree directory first, then recreate + +Triage labels follow the vocabulary in `docs/agents/triage-labels.md`. + +## Process + +## 1. Claim and isolate + +Change the issue triage label to `in-progress`, remove all other labels. Derive `` from the issue title: lowercase, replace spaces with hyphens, strip non-alphanumeric characters (keep hyphens). Then create a git worktree for the ticket as a sibling directory named `../issue--`, checked out from the base branch. Switch to the worktree. The branch name matches the directory: `issue--`. + +```bash +git worktree add -b issue-- ../issue-- +``` + +Stay in the worktree directory for the rest of the process. + +Completion criterion: The issue label is confirmed as `in-progress` and the worktree exists at `../issue--` with branch `issue--` checked out. + +### 2. Compose the child prompt + +Assemble a single prompt that the child agent will receive. Include: + +- **Issue body** — the full markdown body of the issue. +- **Comments** — all comments, if any +- **Standing instruction**: "Implement the work described by the user in the spec or tickets, using tdd skill where possible. Run typechecking regularly, run single test files regularly, and run the full test suite once at the end. Once done, use code-review skill to review the work. Commit your work and push the new branch and create a PR with a link to the issue, one-sentence summary, and short key-changes list. Comment on the issue with the PR link: `PR opened: `. Change the issue triage label to needs-review when done. Remove all other labels" + +- **Failure instruction**: "If any step fails, report where you stopped and what remains for manual recovery. Print the exact commands needed." + +Completion criterion: The prompt is composed with all required sections (issue body, comments, standing instruction, failure instruction). + +### 3. Launch the child via tmux-launch-agent + +Use the `tmux-launch-agent` skill to fork the child agent into a new tmux window. Tmux-launch-agent handles agent detection, config lookup, command building (prompt-file or stdin-pipe), mise/SHELL wrapping, and `tmux new-window` creation. + +Pass these parameters: + +| Parameter | Value | +|-----------|-------| +| `--name` | `"issue--"` — tmux window title | +| Remaining args | The full prompt text composed in step 2 | + +Ensure the child agent starts in the worktree. If the current pane's working directory is already inside `` (from step 1), tmux-launch-agent's new window inherits it. Otherwise, pass `-c ` when invoking tmux-launch-agent so the child agent starts in the worktree directory. + +Let tmux-launch-agent handle prompt-file creation — it writes a temp file automatically when the target agent uses prompt-file mode. Pass the prompt text inline. + +The window stays open after the child completes so the user can review the output. + +Completion criterion: `tmux-launch-agent` exits 0 and a new tmux window appears with the child agent session active. + +### 4. Print summary + +After launching, print: + +- Issue number and title +- Worktree path +- Branch name +- Base branch +- Agent used (detected by tmux-launch-agent) +- Tmux window name (so the user can find it) +- Cleanup command: `git worktree remove && git worktree prune` diff --git a/common/engineering/implement-isolation/SKILL.md b/common/engineering/implement-isolation/SKILL.md new file mode 100644 index 0000000..9a514aa --- /dev/null +++ b/common/engineering/implement-isolation/SKILL.md @@ -0,0 +1,59 @@ +--- +name: implement-isolation +description: "Implement a piece of work based on a spec or set of tickets in isolation." +disable-model-invocation: true +--- + +## Invocation + +/skill:implement-isolation [--base ] [--force] + +- `` — required, the ticket/issue number +- `--base ` — optional, target base branch (default: repo default branch) +- `--force` — optional, remove the existing worktree directory first, then recreate + +Triage labels follow the vocabulary in `docs/agents/triage-labels.md`. + +## Process + +### 1. Claim and isolate + +Change the issue triage label to `in-progress`, remove all other labels. Derive `` from the issue title: lowercase, replace spaces with hyphens, strip non-alphanumeric characters (keep hyphens). Then create a git worktree for the ticket as a sibling directory named `../issue--`, checked out from the base branch. Switch to the worktree. The branch name matches the directory: `issue--`. + +```bash +git worktree add -b issue-- ../issue-- +``` + +Stay in the worktree directory for the rest of the process. + +Completion criterion: The issue label is confirmed as `in-progress` and the worktree exists at `../issue--` with branch `issue--` checked out. + +### 2. Implement + +Start a subagent to implement the work in isolation. The subagent receives a single prompt that includes: + +- Issue body: the full markdown body of the issue. +- Comments: all comments, if any +- Implement: the work described by the user in the spec or tickets, using tdd skill where possible. Run typechecking regularly, run single test files regularly, and run the full test suite once at the end. + +Completion criterion: The subagent exits with code 0 and all changes are committed. + +### 3. Review + +Start a reviewer subagent that runs the `code-review` skill against the base branch to identify findings in the diff. Wait for the reviewer to finish. + +Review each finding and fix the code until zero findings remain. Commit fixes as you go. + +Completion criterion: All code-review findings are resolved (zero open findings) and fixes are committed. + +### 4. Ship + +Push the branch, open a PR. The PR description must include a link to the ticket and a key-changes list. + +Comment on the issue: `PR opened: `. Label the issue `needs-review`, remove all other labels. + +Print a cleanup command for the user: `git worktree remove ../issue-- && git worktree prune` + +### Failure recovery + +If the implement subagent exits non-zero or the review finds issues that cannot be fully resolved, stop. Report to the user: issue number, what was completed, what failed, and the exact commands needed to resume or clean up (including `git worktree remove ...`). Do not push partial work. diff --git a/common/engineering/implement-issue/SKILL.md b/common/engineering/implement-issue/SKILL.md deleted file mode 100644 index c73aff9..0000000 --- a/common/engineering/implement-issue/SKILL.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -name: implement-issue -description: "Dispatch a child agent in an isolated git worktree to implement a piece of work based on a PRD or set of issues." -disable-model-invocation: true ---- - -## Invocation - -/skill:implement-issue [--base ] [--force] - -- `` — required, the issue number -- `--base ` — optional, target base branch (default: repo default branch) -- `--force` — optional, allow overwriting an existing worktree - -## Process - -### 1. Setup - -#### a. Label the issue `in-progress` - -Change the issue triage label to `in-progress`, remove all other labels. - -Completion criterion: The issue label is confirmed as `in-progress`. - -#### b. Create the worktree - -```bash -git worktree add -b ../issue-- -``` - -Completion criterion: The worktree exists at `../issue--` and the new branch is checked out. - -### 2. Compose the child prompt - -Assemble a single prompt that the child agent will receive. Include: - -- **Issue body** — the full markdown body of the issue. -- **Comments** — all comments, if any -- **Standing instruction**: "Implement using tdd skill where possible, at the pre-agreed seam. Run typechecking regularly, run single test files regularly, and run the full test suite once at the end. Once done, use code-review skill to review the work. Commit your work and push the new branch and create a PR with a link to the issue, one-sentence summary, and short key-changes list. Comment on the issue with the PR link: `PR opened: `. Change the issue triage label to needs-review when done. Remove all other labels" - -- **Failure instruction**: "If any step fails, report where you stopped and what remains for manual recovery. Print the exact commands needed." - -Completion criterion: The prompt is composed with all required sections (issue body, comments, standing instruction, failure instruction). - -### 3. Launch the child via tmux-launch-agent - -Use the `tmux-launch-agent` skill to fork the child agent into a new tmux window. Tmux-launch-agent handles agent detection, config lookup, command building (prompt-file or stdin-pipe), mise/SHELL wrapping, and `tmux new-window` creation. - -Pass these parameters: - -| Parameter | Value | -|-----------|-------| -| `--name` | `"issue--"` — tmux window title | -| Remaining args | The full prompt text composed in step 2 | - -Ensure the child agent starts in the worktree. If the current pane's working directory is already inside `` (from step 1b), tmux-launch-agent's new window inherits it. Otherwise, add `-c ` to the `tmux new-window` command in tmux-launch-agent's step 6. - -Do **not** pre-write the prompt to a separate file — tmux-launch-agent writes its own temp file if the target agent uses prompt-file mode. - -The window stays open after the child completes so the user can review the output. - -Completion criterion: `tmux new-window` exits 0 and a new tmux window appears with the child agent session active. - -### 4. Print summary - -After launching, print: - -- Issue number and title -- Worktree path -- Branch name -- Base branch -- Agent used (detected by tmux-launch-agent) -- Tmux window name (so the user can find it) -- Cleanup command: `git worktree remove && git worktree prune` diff --git a/common/engineering/implement/SKILL.md b/common/engineering/implement/SKILL.md deleted file mode 100644 index f303423..0000000 --- a/common/engineering/implement/SKILL.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: implement-isolation -description: "Implement a piece of work based on a spec or set of tickets in isolation." -disable-model-invocation: true ---- - -## Invocation - -/skill:implement [--base ] [--force] - -- `` — required, the ticket/issue number -- `--base ` — optional, target base branch (default: repo default branch) -- `--force` — optional, allow overwriting an existing `worktree` - -Triage labels follow the vocabulary in `docs/agents/triage-labels.md`. - -## Process - -### 1. Claim the ticket - -Label the issue `in-progress`, remove all other labels. - -### 2. Isolate the workspace - -```bash -git worktree add -b ../issue-- -``` - -Change into the new worktree directory. - -### 3. Implement - -Drive every acceptance criterion through **red-green-refactor**: write the test first (red), make it pass (green), clean up (refactor). No code without a failing test first. - -### 4. Verify - -Run the full test suite. Every test must pass. - -### 5. Review - -Run /code-review against the base branch. Fix every finding before proceeding. - -### 6. Ship - -Push the branch, open a PR. The PR description must include a link to the ticket and a key-changes list. - -Comment on the issue: `PR opened: `. Label the issue `needs-review`, remove all other labels.