gitadmin
a6b00a7f11
Replace the `@{prompt}` placeholder with `{prompt}` across all skill docs and
agent-cli configs, remove the deprecated `--agent` flag from the invocation
syntax, delete the now-obsolete agent-cli test file, clarify that only one
triage label should be active at a time, and defer prompt-file cleanup to the
OS/child instead of removing it immediately after tmux launch.
229 lines
7.6 KiB
Markdown
229 lines
7.6 KiB
Markdown
---
|
||
name: implement-issue
|
||
description: Dispatch a child agent in an isolated git worktree to implement a `ready-for-agent` issue end-to-end.
|
||
disable-model-invocation: true
|
||
---
|
||
|
||
# Implement Issue
|
||
|
||
Dispatch a child agent in an isolated git worktree to implement a `ready-for-agent` issue end-to-end — explore, implement with TDD, run the full quality gate, push a branch, create a PR, comment on the issue, and update labels.
|
||
|
||
The issue tracker conventions live in [`docs/agents/issue-tracker.md`](../../../docs/agents/issue-tracker.md) and the triage label vocabulary in [`docs/agents/triage-labels.md`](../../../docs/agents/triage-labels.md). Both should have been provided to you already.
|
||
|
||
## Invocation
|
||
|
||
```
|
||
/skill:implement-issue <N> [--base <branch>] [--force]
|
||
```
|
||
|
||
- `<N>` — required, the issue number
|
||
- `--base <branch>` — optional, target base branch (default: repo default branch).
|
||
- `--force` — optional, allow overwriting an existing worktree.
|
||
|
||
## Agent CLI Configuration
|
||
|
||
The CLI agent for child agents is configured in `docs/agents/agent-cli.md`. This file is written by `/setup-skills` Section E and contains:
|
||
|
||
```yaml
|
||
selected: <agent-name>
|
||
binary: <binary-name>
|
||
args: "<arguments including @{prompt}>"
|
||
```
|
||
|
||
Supported agents and their configurations are defined in `agents-seed.md` in the setup-skills skill directory.
|
||
|
||
## Process
|
||
|
||
### 1. Pre-flight checks
|
||
|
||
Stop on any failure and report clearly what needs fixing. Do not proceed.
|
||
|
||
#### 1b. Issue exists and is open
|
||
|
||
If the issue is not found or state is not `open`, report and stop.
|
||
|
||
#### 1c. Issue is labeled `ready-for-agent`
|
||
|
||
Check that the issue's labels include `ready-for-agent`. If not, report the current state and point the user to `/triage`. Stop.
|
||
|
||
#### 1d. No open blockers
|
||
|
||
Read the issue body for "Blocked by #M" references. For each referenced issue, check whether it is open:
|
||
|
||
If any blocker is open, report the blocking issues and stop.
|
||
|
||
#### 1e. Remote exists and base branch is reachable
|
||
|
||
Default base is the repo's default branch — infer from `git ls-remote --heads origin` (look for `main` or `master`). Allow an explicit `--base <branch>` override.
|
||
|
||
```bash
|
||
git ls-remote --heads origin <base>
|
||
```
|
||
|
||
If the remote is unreachable or the base branch doesn't exist, report and stop.
|
||
|
||
#### 1f. Branch name is free
|
||
|
||
Derive the branch name from the issue title:
|
||
|
||
- Format: `issue-<N>-<slug>`
|
||
- Slug: lowercase the title, strip to `[a-z0-9-]`, truncate to ~4–5 short words (max ~50 chars), collapse double hyphens
|
||
- If the title yields no usable slug, fall back to `issue-<N>`
|
||
|
||
Check that the branch doesn't already exist on the remote:
|
||
|
||
```bash
|
||
git ls-remote --heads origin <branch-name>
|
||
```
|
||
|
||
If it exists, report and stop. (No auto-suffix, no force-push.)
|
||
|
||
#### 1g. Worktree path is free
|
||
|
||
The worktree path is a sibling to the main repo: `../<repo-name>-issue-<N>`. Check that it doesn't already exist:
|
||
|
||
```bash
|
||
ls -d ../<repo-name>-issue-<N>
|
||
```
|
||
|
||
If it exists, report and stop. Let the user override with `--force`.
|
||
|
||
#### 1h. Running inside a tmux session
|
||
|
||
Confirm `$TMUX` is set. If not, report "This skill requires a tmux session. Start tmux and rerun." and stop.
|
||
|
||
#### 1i. Read agent CLI config
|
||
|
||
Read `docs/agents/agent-cli.md` and parse the `selected`, `binary`, and `args` fields. If the file is missing or malformed, report:
|
||
|
||
> Agent CLI not configured. Run `/setup-skills` Section E to configure the CLI agent for child agents.
|
||
|
||
Stop.
|
||
|
||
#### 1j. Validate binary on PATH
|
||
|
||
Confirm the configured `binary` is on PATH:
|
||
|
||
```bash
|
||
command -v <binary>
|
||
```
|
||
|
||
If the binary is not found, fail with:
|
||
|
||
> Agent '<binary>' not found on PATH — rerun /setup-skills to reconfigure.
|
||
|
||
Stop.
|
||
|
||
### 2. Setup
|
||
|
||
#### 2a. Label the issue `in-progress`
|
||
|
||
Change the issue triage labels to `in-progress`
|
||
|
||
#### 2b. Create the worktree
|
||
|
||
```bash
|
||
git worktree add -b <branch-name> ../<repo-name>-issue-<N> <base>
|
||
```
|
||
|
||
### 3. Compose and write 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: 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. The issue body may contain Implementation Decisions and Testing Decisions sections — treat these as constraints."
|
||
- **Context**: "Base branch: `<base>`. Target your PR at `<base>`. Branch name: `<branch-name>`."
|
||
- **Checklist** — a numbered checklist the child should work through:
|
||
1. Explore the codebase and read the issue body + comments thoroughly
|
||
2. Install dependencies and build the project
|
||
3. Implement the change using TDD (red-green-refactor)
|
||
4. Run the full project quality gate (infer from package.json, Makefile, Cargo.toml, etc.), fix until green
|
||
5. Commit with conventional commits (`feat:` for enhancement, `fix:` for bug) referencing `(#<N>)`
|
||
6. Push the branch: `git push origin <branch-name>`
|
||
7. Create a PR with: link to the issue, one-sentence summary, short key-changes list
|
||
8. Comment on the issue with the PR link: `"PR opened: <url>"`
|
||
9. Change the issue triage label to `needs-review`
|
||
10. remove the prompt file from `/tmp` (the child may have already read it)
|
||
11. Print `DONE — issue #<N>`
|
||
- **Failure instruction**: "If any step fails, report where you stopped and what remains for manual recovery. Print the exact commands needed."
|
||
|
||
Write the full prompt to a temp file:
|
||
|
||
```bash
|
||
cat > /tmp/issue-<N>-prompt.md <<'PROMPT_EOF'
|
||
<full-composed-prompt>
|
||
PROMPT_EOF
|
||
```
|
||
|
||
### 4. Launch the child
|
||
|
||
#### 4a. Detect runtime environment
|
||
|
||
Check if `mise` is available:
|
||
|
||
```bash
|
||
command -v mise
|
||
```
|
||
|
||
If available, use `mise x --allow-env='*' --` as the runner prefix. Otherwise, fall back to `$SHELL -c`.
|
||
|
||
#### 4b. Compose the agent command
|
||
|
||
Substitute `{prompt}` in the configured `args` with the absolute path to the temp prompt file. The prompt file path is `/tmp/issue-<N>-prompt.md`:
|
||
|
||
```bash
|
||
prompt_file="/tmp/issue-<N>-prompt.md"
|
||
substituted_args="${args//\{prompt\}/$prompt_file}"
|
||
```
|
||
|
||
- If `args` was non-empty: the agent command is `<binary> $substituted_args`
|
||
- If `args` was empty (stdin-piping agents): the agent command is `cat $prompt_file | <binary>`
|
||
|
||
#### 4c. Compose the full tmux command
|
||
|
||
Use `$substituted_args` from step 4b:
|
||
|
||
```bash
|
||
tmux new-window -n "issue-<N>-<repo-slug>" -c <absolute-worktree-path> "<runner-prefix> <binary> $substituted_args"
|
||
```
|
||
|
||
**With mise:**
|
||
```bash
|
||
tmux new-window -n "issue-<N>-<repo>" -c /path/to/worktree "mise x --allow-env='*' -- $binary $substituted_args"
|
||
```
|
||
|
||
**Without mise (fallback):**
|
||
```bash
|
||
tmux new-window -n "issue-<N>-<repo>" -c /path/to/worktree "$SHELL -c '$binary $substituted_args'"
|
||
```
|
||
|
||
For stdin-piping agents (empty args), use the pipe form:
|
||
|
||
**With mise:**
|
||
```bash
|
||
tmux new-window -n "issue-<N>-<repo>" -c /path/to/worktree "mise x --allow-env='*' -- sh -c 'cat $prompt_file | $binary'"
|
||
```
|
||
|
||
**Without mise:**
|
||
```bash
|
||
tmux new-window -n "issue-<N>-<repo>" -c /path/to/worktree "$SHELL -c 'cat $prompt_file | $binary'"
|
||
```
|
||
|
||
The window stays open after the child completes so the user can review the output.
|
||
|
||
Do not remove the prompt file immediately — the child agent may not have read it yet. The file will be read from `/tmp` and cleaned up by the OS or the child after use.
|
||
|
||
### 5. Print summary
|
||
|
||
After launching, print:
|
||
- Issue number and title
|
||
- Worktree path
|
||
- Branch name
|
||
- Base branch
|
||
- Agent used (from `docs/agents/agent-cli.md`)
|
||
- Tmux window name (so the user can find it)
|
||
- Cleanup command: `git worktree remove <worktree-path> && git worktree prune`
|
||
|
||
The parent's turn ends here. The user can dispatch another issue immediately.
|