common/engineering/implement-issue/SKILL.md

@@ -17,27 +17,31 @@ The issue tracker conventions live in [`docs/agents/issue-tracker.md`](../../../
 ```
 
 - `<N>` — required, the issue number
-- `--agent <name>` — optional, one of `pi`, `opencode`, `goose`, `codex`, `claude`. If omitted, auto-detected from the process tree.
+- `--agent <name>` — **DEPRECATED**: this argument is ignored. The agent CLI is read from `docs/agents/agent-cli.md`, which is set up by `/setup-skills` Section E. Rerun `/setup-skills` to change the agent.
 - `--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.
 
-#### 1a. `tea` CLI
-
-Confirm `tea` is on PATH. If missing, tell the user to install it and stop.
-
 #### 1b. Issue exists and is open
 
-```bash
-tea issue <N> -o json
-```
-
-If the issue is not found (404) or state is not `open`, report and stop.
+If the issue is not found or state is not `open`, report and stop.
 
 #### 1c. Issue is labeled `ready-for-agent`
 
@@ -47,10 +51,6 @@ Check that the issue's labels include `ready-for-agent`. If not, report the curr
 
 Read the issue body for "Blocked by #M" references. For each referenced issue, check whether it is open:
 
-```bash
-tea issue <M> -o json
-```
-
 If any blocker is open, report the blocking issues and stop.
 
 #### 1e. Remote exists and base branch is reachable
@@ -61,9 +61,7 @@ Default base is the repo's default branch — infer from `git ls-remote --heads
 git ls-remote --heads origin <base>
 ```
 
-If the remote is unreachable or the base branch doesn't exist, report and stop. SSH auth issues (e.g. `Permission denied (publickey)`) are a failure — tell the user which key is needed.
-
-> **SSH note:** `tea` uses HTTPS and may work when git-over-SSH does not. If the first `git ls-remote` fails with an SSH error, try `export SSH_AUTH_SOCK=$(gpgconf --list-dirs agent-ssh-socket)` and retry before failing.
+If the remote is unreachable or the base branch doesn't exist, report and stop.
 
 #### 1f. Branch name is free
 
@@ -95,48 +93,35 @@ If it exists, report and stop. Let the user override with `--force`.
 
 Confirm `$TMUX` is set. If not, report "This skill requires a tmux session. Start tmux and rerun." and stop.
 
-#### 1i. Detect the agent binary
+#### 1i. Read agent CLI config
 
-If `--agent <name>` was provided in the invocation args, use that name directly. Otherwise, run the platform-appropriate detection script:
+Read `docs/agents/agent-cli.md` and parse the `selected`, `binary`, and `args` fields. If the file is missing or malformed, report:
 
-```bash
-bash ./detect-agent-linux.sh
-# or on macOS:
-bash ./detect-agent-macos.sh
-```
-
-The script outputs the agent name on success (exit 0), or nothing on failure (exit 1).
-
-If detection fails (no `--agent` flag and script returns nothing), report:
-
-> Could not detect which agent is running. Rerun with `--agent <name>`.
-> Supported agents: pi, opencode, goose, codex, claude.
+> Agent CLI not configured. Run `/setup-skills` Section E to configure the CLI agent for child agents.
 
 Stop.
 
-If detection succeeds, confirm the binary is on PATH:
+#### 1j. Validate binary on PATH
+
+Confirm the configured `binary` is on PATH:
 
 ```bash
-command -v <agent>
+command -v <binary>
 ```
 
-If the binary is not found, report "Agent binary '<agent>' not found on PATH." and stop.
+If the binary is not found, fail with:
+
+> Agent '<binary>' not found on PATH — rerun /setup-skills to reconfigure.
+
+Stop.
 
 ### 2. Setup
 
-#### 2a. Fetch latest base
+#### 2a. Label the issue `in-progress`
 
-```bash
-git fetch origin <base>
-```
+Apply the `in-progress` triage label.
 
-#### 2b. Label the issue `in-progress`
-
-```bash
-tea issues edit <N> --add-labels "in-progress" --remove-labels "ready-for-agent"
-```
-
-#### 2c. Create the worktree
+#### 2b. Create the worktree
 
 ```bash
 git worktree add -b <branch-name> ../<repo-name>-issue-<N> <base>
@@ -173,27 +158,49 @@ PROMPT_EOF
 
 ### 4. Launch the child
 
-Look up the full shell command from the dispatch table below, using the agent name detected in step 1i.
+#### 4a. Detect runtime environment
 
-| Agent | Shell command |
-|-------|--------------|
-| `pi` | `pi -p @/tmp/issue-<N>-prompt.md` |
-| `opencode` | `opencode run -f /tmp/issue-<N>-prompt.md` |
-| `goose` | `goose run -i /tmp/issue-<N>-prompt.md` |
-| `codex` | `cat /tmp/issue-<N>-prompt.md \| codex exec` |
-| `claude` | `cat /tmp/issue-<N>-prompt.md \| claude -p` |
-| *unknown* | `cat /tmp/issue-<N>-prompt.md \| <binary>` |
-
-Substitute the actual temp file path and issue number, then launch in a new tmux window:
+Check if `mise` is available:
 
 ```bash
-tmux new-window -n "issue-<N>-<repo>" -c <absolute-worktree-path> "<shell-command>"
+command -v mise
 ```
 
-For example, with pi:
+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:
+
+- If `args` is non-empty: the agent command is `<binary> <substituted-args>`
+- If `args` is empty (stdin-piping agents): the agent command is `cat <prompt-file> | <binary>`
+
+#### 4c. Compose the full tmux command
 
 ```bash
-tmux new-window -n "issue-42-myrepo" -c ../myrepo-issue-42 "pi -p @/tmp/issue-42-prompt.md"
+tmux new-window -n "issue-<N>-<repo-slug>" -c <absolute-worktree-path> "<runner-prefix> <agent-command>"
+```
+
+**With mise:**
+```bash
+tmux new-window -n "issue-<N>-<repo>" -c /path/to/worktree "mise x --allow-env='*' -- <binary> <args-with-prompt-subbed>"
+```
+
+**Without mise (fallback):**
+```bash
+tmux new-window -n "issue-<N>-<repo>" -c /path/to/worktree "$SHELL -c '<binary> <args-with-prompt-subbed>'"
+```
+
+For stdin-piping agents (empty args), wrap the pipe command:
+
+**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.
@@ -211,7 +218,7 @@ After launching, print:
 - Worktree path
 - Branch name
 - Base branch
-- Agent used
+- 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`
 

common/engineering/implement-issue/agent-cli.test.md

@@ -0,0 +1,161 @@
+# Agent CLI Tests for implement-issue
+
+These tests verify the tmux command composition logic in `implement-issue`. They intercept the generated shell command string rather than the tmux invocation itself.
+
+The seam being tested: given a `docs/agents/agent-cli.md` config and a `mise` availability state, `implement-issue` must compose the correct tmux launch command.
+
+## Test fixtures
+
+### Fixture: pi agent config (stdin-piped via @{prompt})
+
+```yaml
+# docs/agents/agent-cli.md
+selected: pi
+binary: pi
+args: "-p @{prompt}"
+```
+
+### Fixture: opencode agent config
+
+```yaml
+# docs/agents/agent-cli.md
+selected: opencode
+binary: opencode
+args: "run -f @{prompt}"
+```
+
+### Fixture: codex agent config (empty args = stdin pipe)
+
+```yaml
+# docs/agents/agent-cli.md
+selected: codex
+binary: codex
+args: ""
+```
+
+### Fixture: missing binary config
+
+```yaml
+# docs/agents/agent-cli.md
+selected: missing-agent
+binary: totally-not-on-path
+args: ""
+```
+
+## Test cases
+
+### Test: composes correct tmux command for pi with mise available
+
+**Given:**
+- `docs/agents/agent-cli.md` contains the pi fixture
+- `command -v mise` succeeds
+
+**When:** `implement-issue` composes the tmux launch command
+
+**Then:** the generated command string is:
+
+```
+tmux new-window -n "issue-42-ws-sjb-skills" -c /home/sjb/Projects/personal/ws-sjb-skills/ws-sjb-skills-issue-42 "mise x --allow-env='*' -- pi -p /tmp/issue-42-prompt.md"
+```
+
+**Notes:**
+- `@{prompt}` is substituted with the actual temp file path
+- Window name includes issue number and repo slug
+- Worktree path is absolute
+- `mise x --allow-env='*'` is prepended when mise is available
+
+---
+
+### Test: composes correct tmux command for pi without mise (fallback to $SHELL -c)
+
+**Given:**
+- `docs/agents/agent-cli.md` contains the pi fixture
+- `command -v mise` fails (no mise on PATH)
+
+**When:** `implement-issue` composes the tmux launch command
+
+**Then:** the generated command string is:
+
+```
+tmux new-window -n "issue-42-ws-sjb-skills" -c /home/sjb/Projects/personal/ws-sjb-skills/ws-sjb-skills-issue-42 "$SHELL -c 'pi -p /tmp/issue-42-prompt.md'"
+```
+
+**Notes:**
+- Falls back to `$SHELL -c` when mise is absent
+- The agent command is wrapped inside `$SHELL -c '...'`
+
+---
+
+### Test: composes correct tmux command for codex (stdin piping, no @{prompt})
+
+**Given:**
+- `docs/agents/agent-cli.md` contains the codex fixture (args: "")
+- `command -v mise` succeeds
+
+**When:** `implement-issue` composes the tmux launch command
+
+**Then:** the generated command string is:
+
+```
+tmux new-window -n "issue-42-ws-sjb-skills" -c /home/sjb/Projects/personal/ws-sjb-skills/ws-sjb-skills-issue-42 "mise x --allow-env='*' -- sh -c 'cat /tmp/issue-42-prompt.md | codex'"
+```
+
+**Notes:**
+- When args is empty, prompt is piped via `cat <prompt> | <binary>`
+- The pipe syntax is always `cat <prompt> | <binary>` for stdin-based agents
+
+---
+
+### Test: fails fast with clear message when binary not on PATH
+
+**Given:**
+- `docs/agents/agent-cli.md` contains the missing binary fixture
+- `command -v totally-not-on-path` fails
+
+**When:** `implement-issue` validates the binary at invocation time
+
+**Then:** it fails immediately with:
+
+```
+Agent 'totally-not-on-path' not found on PATH — rerun /setup-skills to reconfigure.
+```
+
+**Notes:**
+- Validation happens before any tmux launch
+- Error message directs user to re-run setup-skills
+
+---
+
+### Test: reads selected agent from docs/agents/agent-cli.md
+
+**Given:**
+- `docs/agents/agent-cli.md` exists and contains valid YAML with `selected`, `binary`, and `args` fields
+
+**When:** `implement-issue` reads the config at invocation time
+
+**Then:** it parses the three fields correctly and uses them for dispatch
+
+**Notes:**
+- Does not use hardcoded dispatch table
+- Does not run detection scripts
+- Reads directly from the repo-side config file
+
+---
+
+### Test: @{prompt} placeholder substitution
+
+**Given:**
+- `docs/agents/agent-cli.md` contains opencode fixture (args: "run -f @{prompt}")
+- `command -v mise` succeeds
+
+**When:** `implement-issue` composes the tmux launch command with prompt file at `/tmp/issue-99-prompt.md`
+
+**Then:** the generated command contains:
+
+```
+opencode run -f /tmp/issue-99-prompt.md
+```
+
+**Notes:**
+- `@{prompt}` in args is replaced with the absolute path to the temp prompt file
+- Works regardless of where `@{prompt}` appears in the args string

common/engineering/implement-issue/detect-agent-linux.sh

@@ -1,44 +0,0 @@
-#!/usr/bin/env bash
-# Walk the process tree upward from $PPID to find a known agent binary.
-# Outputs the agent name on stdout if found, exits 0.
-# Outputs nothing and exits 1 if no known agent is found.
-
-set -euo pipefail
-
-# Dispatch table: binary names we recognize.
-KNOWN_AGENTS="pi opencode goose codex claude"
-
-pid=$PPID
-
-while [ "$pid" -gt 1 ]; do
-    # Read command name and parent PID from /proc.
-    comm=$(cat /proc/$pid/comm 2>/dev/null) || { pid=1; continue; }
-    ppid=$(awk '{print $4}' /proc/$pid/stat 2>/dev/null) || ppid=1
-
-    # Direct match against known binaries.
-    for agent in $KNOWN_AGENTS; do
-        if [ "$comm" = "$agent" ]; then
-            echo "$agent"
-            exit 0
-        fi
-    done
-
-    # If the process is node or bun, inspect cmdline for agent script paths.
-    case "$comm" in
-        node|bun)
-            cmdline=$(tr '\0' ' ' < /proc/$pid/cmdline 2>/dev/null) || cmdline=""
-            for agent in $KNOWN_AGENTS; do
-                case "$cmdline" in
-                    *"$agent"*)
-                        echo "$agent"
-                        exit 0
-                        ;;
-                esac
-            done
-            ;;
-    esac
-
-    pid=$ppid
-done
-
-exit 1

common/engineering/implement-issue/detect-agent-macos.sh

@@ -1,48 +0,0 @@
-#!/usr/bin/env bash
-# Walk the process tree upward from $PPID to find a known agent binary.
-# Outputs the agent name on stdout if found, exits 0.
-# Outputs nothing and exits 1 if no known agent is found.
-#
-# macOS version — uses ps(1) since /proc is not available.
-# Requires bash 3.2+ (macOS ships bash 3.2).
-
-set -euo pipefail
-
-KNOWN_AGENTS="pi opencode goose codex claude"
-
-pid=$PPID
-
-while [ "$pid" -gt 1 ]; do
-    # Get parent PID and command name.
-    ppid=$(ps -o ppid= -p "$pid" 2>/dev/null | tr -d ' ') || ppid=1
-    comm=$(ps -o comm= -p "$pid" 2>/dev/null) || { pid=$ppid; continue; }
-    # Strip leading path, keep only the basename.
-    comm=$(basename "$comm" 2>/dev/null || echo "$comm")
-
-    # Direct match against known binaries.
-    for agent in $KNOWN_AGENTS; do
-        if [ "$comm" = "$agent" ]; then
-            echo "$agent"
-            exit 0
-        fi
-    done
-
-    # If the process is node or bun, inspect full command line for agent names.
-    case "$comm" in
-        node|bun)
-            args=$(ps -o args= -p "$pid" 2>/dev/null) || args=""
-            for agent in $KNOWN_AGENTS; do
-                case "$args" in
-                    *"$agent"*)
-                        echo "$agent"
-                        exit 0
-                        ;;
-                esac
-            done
-            ;;
-    esac
-
-    pid=$ppid
-done
-
-exit 1

common/engineering/setup-skills/SKILL.md

@@ -12,6 +12,7 @@ Scaffold the per-repo configuration that the engineering skills assume:
 - Triage labels: the strings used for the canonical triage roles, labels are defined in `triage-labels.md`
 - Domain docs: where `CONTEXT.md` and ADRs live, and the consumer rules for reading them
 - **ADR wiki** — where ADRs are stored (forge wiki, cloned into `docs/adr/`), and the clone/push workflow
+- **Agent CLI** — which CLI agent to use for child agents in `/implement-issue`
 
 This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
 
@@ -29,7 +30,7 @@ Look at the current repo to understand its starting state. Read whatever exists;
 
 ### 2. Present findings and ask
 
-Summarise what's present and what's missing. Then walk the user through the four decisions **one at a time** - present a section, get the user's answer, then move to the next. Don't dump all three at once.
+Summarise what's present and what's missing. Then walk the user through the five decisions **one at a time** - present a section, get the user's answer, then move to the next. Don't dump all at once.
 
 Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.
 
@@ -89,12 +90,43 @@ After the forge is confirmed, present the workflow and confirm:
 
 Record the answers in `docs/agents/adr-wiki.md`.
 
+**Section E — Agent CLI.**
+
+> Explainer: The `implement-issue` skill dispatches a child agent in an isolated git worktree. It needs to know which CLI agent to spawn (pi, opencode, goose, codex, or claude) and how to invoke it. This configuration lives in `docs/agents/agent-cli.md` and is set up once per repo so every developer uses the same agent by default.
+
+Read `agents-seed.md` from this skill directory to get the list of known agents. Present them as a numbered menu:
+
+```
+Available agents:
+1. pi       — My primary agent harness. Accepts prompt file via -p flag.
+2. opencode — OpenCode agent. Accepts prompt file via -f flag.
+3. goose    — Goose agent. Accepts prompt file via -i flag.
+4. codex    — OpenAI Codex. Pipes stdin via cat.
+5. claude   — Anthropic Claude CLI. Pipes stdin via cat.
+```
+
+Ask the user to type the agent name (or number):
+
+> Which CLI agent should `/implement-issue` use for child agents? (default: pi)
+
+Validate the selected agent's binary is on PATH:
+
+```bash
+command -v <selected-binary>
+```
+
+If the binary is not found, tell the user:
+
+> Binary '<binary>' not found on PATH. Please install it or choose a different agent.
+
+Loop until a valid binary is found or the user quits.
+
 ### 3. Confirm and edit
 
 Show the user a draft of:
 
 - The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
-- The contents of `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`, and `docs/agents/adr-wiki.md`
+- The contents of `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`, `docs/agents/adr-wiki.md`, and `docs/agents/agent-cli.md`
 
 Let them edit before writing.
 
@@ -131,23 +163,36 @@ The block:
 
 [one-line summary — forge, wiki URL, auth method]. See `docs/agents/adr-wiki.md`.
 
+### Agent CLI
+
+[one-line summary of the configured CLI agent]. See `docs/agents/agent-cli.md`.
+
  ## Project Context Pack
 
 [Agent memory file that describes the repo's context, codebase, and navigation rules]. See `.agents/project-context.md`.
 
 ```
 
-Then write the four docs files using the seed templates in this skill folder as a starting point:
+Then write the docs files:
 
-- [issue-tracker-github.jd](./issue-tracker-github.md) — GitHub issue tracker
+- [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
 - [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
 - [issue-tracker-gitea.md](./issue-tracker-gitea.md) — Gitea issue tracker
 - [triage-labels.md](./triage-labels.md) — label mapping
 - [domain.md](./domain.md) — domain doc consumer rules + layout
 - [adr-wiki.md](./adr-wiki.md) — ADR wiki clone and push workflow
+- `docs/agents/agent-cli.md` — agent CLI config with `selected`, `binary`, and `args` fields
+
+For Section E, write `docs/agents/agent-cli.md` with the selected agent:
+
+```yaml
+selected: <agent-name>
+binary: <binary-name>
+args: "<args-from-seed>"
+```
 
 For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.
 
 ### 5. Done
 
-Tell the user the setup is complete, which engineering skills will now read from these files, and that ADR changes are pushed to the forge wiki at end of session. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers, restart from scratch, or reconfigure the ADR wiki.
+Tell the user the setup is complete, which engineering skills will now read from these files, and that ADR changes are pushed to the forge wiki at end of session. Mention they can edit `docs/agents/*.md` directly later — re-running this skill is only necessary if they want to switch issue trackers, restart from scratch, or reconfigure the ADR wiki or agent CLI.

common/engineering/setup-skills/agents-seed.md

@@ -0,0 +1,46 @@
+# Agent CLI Seed Data
+
+This file is the source of truth for all supported CLI agents. It is read by `setup-skills` Section E to present the menu and by `implement-issue` for agent dispatch.
+
+## Agents
+
+```yaml
+agents:
+  - name: pi
+    binary: pi
+    args: "@{prompt}"
+    description: "My primary agent harness. Accepts prompt file via @{prompt}."
+
+  - name: opencode
+    binary: opencode
+    args: ""
+    description: "OpenCode agent. Pipes stdin via cat."
+    note: "Uses stdin piping: args must be empty, prompt via pipe."
+
+  - name: goose
+    binary: goose
+    args: ""
+    description: "Goose agent. Accepts prompt file via -i flag."
+    note: "Uses stdin piping: args must be empty, prompt via pipe."
+
+  - name: codex
+    binary: codex
+    args: "@{prompt}"
+    description: "OpenAI Codex. Accepts prompt file via @{prompt}."
+
+  - name: claude
+    binary: claude
+    args: ""
+    description: "Anthropic Claude CLI. Pipes stdin via cat."
+    note: "Uses stdin piping: args must be empty, prompt via pipe."
+```
+
+## Field meanings
+
+| Field | Description |
+|-------|-------------|
+| `name` | Display name used in menus and `--agent` flag |
+| `binary` | Command name expected on PATH |
+| `args` | Static arguments appended after the binary. May include `@{prompt}` which is substituted at invocation time with the absolute path to the prompt file. Empty string means stdin piping (prompt is piped via `cat`). |
+| `description` | Short human-readable description for the setup menu |
+| `note` | Optional additional context |

docs/agents/agent-cli.md

@@ -0,0 +1,23 @@
+# Agent CLI Configuration
+
+The CLI agent used by `/implement-issue` for spawning child agents in isolated git worktrees.
+
+## Configuration
+
+```yaml
+selected: pi
+binary: pi
+args: "-p @{prompt}"
+```
+
+## Fields
+
+| Field | Description |
+|-------|-------------|
+| `selected` | Display name of the selected agent |
+| `binary` | Command name expected on PATH |
+| `args` | Static arguments. `@{prompt}` is substituted with the prompt file path at invocation time. Empty means stdin piping via `cat`. |
+
+## Changing the agent
+
+Run `/setup-skills` Section E to reconfigure. The full list of supported agents is in `common/engineering/setup-skills/agents-seed.md`.