Add Section E to setup-skills: agent CLI selection #9

New Issue

2026-06-27T16:11:48-04:00

steve commented

2026-06-27 16:11:48 -04:00

Problem Statement

The implement-issue skill currently embeds a hardcoded dispatch table (agent name → shell command) and platform-specific detection scripts (detect-agent-linux.sh, detect-agent-macos.sh) to select which CLI agent spawns a child agent in an isolated worktree. This approach is brittle — the detection scripts are fragile, the list of known agents is hidden inside the skill rather than configurable, and the setup phase never validates that the chosen agent is available on the system.

Solution

Add Section E to setup-skills, which presents the list of known agents to the user at skill-run time, validates the selected agent's binary is on PATH, and writes the choice to docs/agents/agent-cli.md. Refactor implement-issue to read docs/agents/agent-cli.md at invocation time instead of using a hardcoded table or detection scripts.

User Stories

As a developer, I want the CLI agent for child agents to be configured once per repo, so that every developer on the project uses the same agent by default.
As a developer, I want setup-skills to validate that the selected agent is available on PATH, so that I don't discover a broken config hours later at invocation time.
As a developer, I want the list of supported agents to live in a reference file, so that adding a new agent means editing one file rather than hunting through skill logic.
As a developer, I want implement-issue to fail fast with a clear message if the configured agent binary is missing, so that I know to rerun /setup-skills to reconfigure.
As a developer, I want implement-issue to detect mise and use it for agent isolation when available, so that child agents run in a consistent runtime environment.
As a developer, I want implement-issue to fall back to $SHELL -c when mise is absent, so that agent dispatch still works on systems without mise.
As a skill author, I want the full dispatch table to live in agents-seed.md in the skill directory, so that setup-time presentation and invocation-time execution are backed by the same source of truth.
As a skill author, I want implement-issue to stop maintaining its own detection scripts, so that there is one less thing to keep in sync across platforms.

Implementation Decisions

Section E of setup-skills will read agents-seed.md (a YAML file in the skill directory listing all known agents with their binary and args), present them as a menu, prompt the user to type the agent name, validate the binary on PATH, and write a minimal docs/agents/agent-cli.md containing only selected, binary, and args.
docs/agents/agent-cli.md (repo-side config) contains only the selected entry — not the full table — to keep token count low. Re-running setup-skills replaces it.
implement-issue will read docs/agents/agent-cli.md at invocation time, validate binary on PATH, and compose the full tmux launch command from binary + args.
Agent dispatch composition: the tmux command is tmux new-window -n "<window-name>" -c <worktree> "cd <worktree> && <runner> -- <binary> <args>" where <runner> is mise x --allow-env='*' if command -v mise succeeds, else $SHELL -c.
{prompt} placeholder: each agent's args field may include @{prompt}, which implement-issue substitutes with the absolute path to the temp prompt file at invocation time. Agents that pipe stdin have args: "".
implement-issue validation at invocation time: if binary is not on PATH, fail with "Agent '' not found on PATH — rerun /setup-skills to reconfigure."
Remove: the hardcoded dispatch table, detect-agent-linux.sh, and detect-agent-macos.sh from implement-issue.
agents-seed.md location: common/engineering/setup-skills/agents-seed.md, not copied to the repo.
No per-agent requires-mise flag: the mise/$SHELL -c choice is a global runtime check, not per-agent configuration.

File deliverables

common/engineering/setup-skills/agents-seed.md — skill-side YAML reference file with the full agents dispatch table (not copied to repo)
common/engineering/setup-skills/SKILL.md — add Section E: read agents-seed.md, present menu, validate binary on PATH, write docs/agents/agent-cli.md
docs/agents/agent-cli.md — repo-side config with selected, binary, args fields only
common/engineering/implement-issue/SKILL.md — remove hardcoded dispatch table and detection scripts; read docs/agents/agent-cli.md; add mise/$SHELL -c runtime detection; add invocation-time binary validation

Testing Decisions

A good test checks that implement-issue composes the correct tmux command for a given docs/agents/agent-cli.md — specifically that {prompt} is substituted, the worktree path is correct, and mise vs $SHELL -c is chosen based on command -v mise availability.
Existing implement-issue tests (if any) that rely on the hardcoded dispatch table will need updating to use a fixture docs/agents/agent-cli.md.
The seam is at implement-issue's tmux command composition — test by intercepting or asserting the generated shell command string rather than the tmux invocation itself.
No tests needed for setup-skills Section E beyond confirming it writes the expected YAML to docs/agents/agent-cli.md given valid user input.

Out of Scope

Changing implement-issue's tmux layout (always new-window, no split-window option).
Auto-detection of the parent agent from the process tree (removed entirely).
Per-agent runtime configuration beyond binary and args.
Migrating existing repos' implement-issue configurations to the new format.

Further Notes

The agents-seed.md seed file is a skill-side reference only — it is never copied to the repo. This keeps the repo-side config minimal and prevents the two from drifting out of sync.

## Problem Statement The `implement-issue` skill currently embeds a hardcoded dispatch table (agent name → shell command) and platform-specific detection scripts (`detect-agent-linux.sh`, `detect-agent-macos.sh`) to select which CLI agent spawns a child agent in an isolated worktree. This approach is brittle — the detection scripts are fragile, the list of known agents is hidden inside the skill rather than configurable, and the setup phase never validates that the chosen agent is available on the system. ## Solution Add Section E to `setup-skills`, which presents the list of known agents to the user at skill-run time, validates the selected agent's binary is on PATH, and writes the choice to `docs/agents/agent-cli.md`. Refactor `implement-issue` to read `docs/agents/agent-cli.md` at invocation time instead of using a hardcoded table or detection scripts. ## User Stories 1. As a developer, I want the CLI agent for child agents to be configured once per repo, so that every developer on the project uses the same agent by default. 2. As a developer, I want `setup-skills` to validate that the selected agent is available on PATH, so that I don't discover a broken config hours later at invocation time. 3. As a developer, I want the list of supported agents to live in a reference file, so that adding a new agent means editing one file rather than hunting through skill logic. 4. As a developer, I want `implement-issue` to fail fast with a clear message if the configured agent binary is missing, so that I know to rerun `/setup-skills` to reconfigure. 5. As a developer, I want `implement-issue` to detect `mise` and use it for agent isolation when available, so that child agents run in a consistent runtime environment. 6. As a developer, I want `implement-issue` to fall back to `$SHELL -c` when `mise` is absent, so that agent dispatch still works on systems without `mise`. 7. As a skill author, I want the full dispatch table to live in `agents-seed.md` in the skill directory, so that setup-time presentation and invocation-time execution are backed by the same source of truth. 8. As a skill author, I want `implement-issue` to stop maintaining its own detection scripts, so that there is one less thing to keep in sync across platforms. ## Implementation Decisions - **Section E of `setup-skills`** will read `agents-seed.md` (a YAML file in the skill directory listing all known agents with their `binary` and `args`), present them as a menu, prompt the user to type the agent name, validate the binary on PATH, and write a minimal `docs/agents/agent-cli.md` containing only `selected`, `binary`, and `args`. - **`docs/agents/agent-cli.md`** (repo-side config) contains only the selected entry — not the full table — to keep token count low. Re-running `setup-skills` replaces it. - **`implement-issue`** will read `docs/agents/agent-cli.md` at invocation time, validate `binary` on PATH, and compose the full tmux launch command from `binary` + `args`. - **Agent dispatch composition**: the tmux command is `tmux new-window -n "<window-name>" -c <worktree> "cd <worktree> && <runner> -- <binary> <args>"` where `<runner>` is `mise x --allow-env='*'` if `command -v mise` succeeds, else `$SHELL -c`. - **`{prompt}` placeholder**: each agent's `args` field may include `@{prompt}`, which `implement-issue` substitutes with the absolute path to the temp prompt file at invocation time. Agents that pipe stdin have `args: ""`. - **`implement-issue` validation at invocation time**: if `binary` is not on PATH, fail with "Agent '<binary>' not found on PATH — rerun /setup-skills to reconfigure." - **Remove**: the hardcoded dispatch table, `detect-agent-linux.sh`, and `detect-agent-macos.sh` from `implement-issue`. - **`agents-seed.md`** location: `common/engineering/setup-skills/agents-seed.md`, not copied to the repo. - **No per-agent `requires-mise` flag**: the `mise`/`$SHELL -c` choice is a global runtime check, not per-agent configuration. ### File deliverables 1. **`common/engineering/setup-skills/agents-seed.md`** — skill-side YAML reference file with the full `agents` dispatch table (not copied to repo) 2. **`common/engineering/setup-skills/SKILL.md`** — add Section E: read `agents-seed.md`, present menu, validate binary on PATH, write `docs/agents/agent-cli.md` 3. **`docs/agents/agent-cli.md`** — repo-side config with `selected`, `binary`, `args` fields only 4. **`common/engineering/implement-issue/SKILL.md`** — remove hardcoded dispatch table and detection scripts; read `docs/agents/agent-cli.md`; add `mise`/`$SHELL -c` runtime detection; add invocation-time binary validation ## Testing Decisions - A good test checks that `implement-issue` composes the correct tmux command for a given `docs/agents/agent-cli.md` — specifically that `{prompt}` is substituted, the worktree path is correct, and `mise` vs `$SHELL -c` is chosen based on `command -v mise` availability. - Existing `implement-issue` tests (if any) that rely on the hardcoded dispatch table will need updating to use a fixture `docs/agents/agent-cli.md`. - The seam is at `implement-issue`'s tmux command composition — test by intercepting or asserting the generated shell command string rather than the tmux invocation itself. - No tests needed for `setup-skills` Section E beyond confirming it writes the expected YAML to `docs/agents/agent-cli.md` given valid user input. ## Out of Scope - Changing `implement-issue`'s tmux layout (always `new-window`, no split-window option). - Auto-detection of the parent agent from the process tree (removed entirely). - Per-agent runtime configuration beyond `binary` and `args`. - Migrating existing repos' `implement-issue` configurations to the new format. ## Further Notes The `agents-seed.md` seed file is a skill-side reference only — it is never copied to the repo. This keeps the repo-side config minimal and prevents the two from drifting out of sync.

steve added the ready-for-agent label 2026-06-27 16:11:54 -04:00

steve added in-progress and removed ready-for-agent labels 2026-06-27 16:17:56 -04:00

steve referenced this issue from a commit

2026-06-27 16:21:42 -04:00

feat(implement-issue): add Section E to setup-skills for agent CLI selection

steve closed this issue

2026-06-27 16:21:42 -04:00

steve referenced this issue from a commit

2026-06-27 16:26:23 -04:00

feat(implement-issue): add Section E to setup-skills for agent CLI selection

steve referenced a pull request that will close this issue

2026-06-27 16:26:28 -04:00