implement-tmux

Implement tmux

Goal

implement-tmux is the scheduling layer of mattpocock/skills /implement , and does not replace the single-ticket implementation process. It is only responsible for generating a candidate execution plan from planning documents, creating isolated tmux windows, strictly serially scheduling workers, consuming one-shot terminal-state messages, independently verifying, and cleaning up.

In the shared workspace, at any moment only one ticket is in running or verifying; tickets with no dependency relationship must also not run in parallel. At runtime, only the native tmux CLI is used, with no reliance on smux、tmux-bridge, daemon, MCP, or custom services.

The main window only processes final structured messages and brief verification results. Do not continuously read worker panes, thought processes, or intermediate logs; only when the terminal state is missing, failure/blockage evidence is needed, or the user explicitly requests it, read a small amount of pane tail output.

Input and Candidate Plan

Accepts the following inputs:

/wayfinder the map.md generated by map.md；
/to-tickets the spec.md generated by spec.md；
an optional, already-confirmed persistent manifest;
the project path, tmux session, and explicit ticket order provided by the user (the explicit order may override the document default order).

The manifest is optional, and the user is not required to re-enter information already present in the documents. At startup, generate a candidate plan in memory:

Read ticket id, order, dependencies, tracker, scope, and acceptance information from the map/spec; supplement missing information from the tracker, project structure, Git status, and package.json scripts.
Infer allowedPathsfrom the files explicitly listed in the ticket, the tracker change scope, the spec artifacts, and the corresponding test files. Paths that cannot be reliably inferred remain uncertain and must not be guessed.
Infer verifyfrom the ticket acceptance commands and the project's existing scripts. Commands must be recognizable and executable in the project; unrecognizable acceptance commands must block.
maxRepairRounds When 2is missing, use /implement ; do not copy
Record the result message target mainPane, the detected worker CLI, the ticket order, each item's scope, acceptance commands, and protection boundaries.

Before startup, the complete candidate plan must be shown, and confirmation must be requested only once. The plan must show at least:

project、session、mainPane and agent policy;
ticket order and dependencies;
each ticket's allowedPaths、verify, tracker, and uncertain items;
the modified, untracked, and staged paths in the Git baseline at startup;
additional protected paths (coverage, lock, scheduling state, and user-declared items);
maxRepairRounds: 2 or the user's explicit value;
The terminal-state message is sent back using tmux send-keys , without creating resultFile。

Before user confirmation, creating ticket windows, starting workers, or modifying the workspace is prohibited. If the explicit order differs from the map/spec, the plan must show both orders and request a choice in the same confirmation; only when the user has not explicitly chosen, report TICKET_BLOCKED. If any of the following cannot be determined safely, report directly TICKET_BLOCKED and list the specific gaps: unclear project/session, tracker/scope/acceptance cannot be inferred, or the candidate scope overlaps with the protection boundary. Do not substitute gaps with default paths, default tests, or guessed dependencies.

State machine

pending → running → verifying → done
                    ├→ failed
                    └→ blocked

done: final-state message, commit, file scope, staging, acceptance, and evidence all independently verified as passed.
failed: code, assertions, configuration, tests, or artifacts failed; only evidence-based fix-rerun is allowed according to the results of /implement and the plan limit.
blocked：tmux、worker CLI、/implement, external build, DevTools, or other environment/tools unavailable.

failed and blocked both stop subsequent tickets. blocked must not be reported as passed, and must not automatically retry, reset, rollback, stash, delete logs, or overwrite user changes.

Execution steps

1. Establish the startup baseline

Confirm the tools and session exist, then record the real pane, window, Git workspace, and staging area in the main window:

tmux -V
tmux has-session -t "$session"
main_pane="${mainPane:-$(tmux display-message -p '#{pane_id}')}"
tmux display-message -p -t "$main_pane" '#{pane_id}'
tmux list-windows -t "$session" -F '#{window_id}\t#{window_name}\t#{pane_id}'
git -C "$project" status --short --untracked-files=all
git -C "$project" diff --cached --name-only

Add all modified, untracked, and staged paths at startup to the protection baseline, and save the necessary content/hash for later comparison. coverage, lock files, scheduling state, and user-declared protectedPaths are also added to the protection boundary. If the ticket's candidate scope overlaps with any baseline change, block first rather than letting the worker risk sharing files.

Completion conditions: session、mainPane, baseline paths, and the set of windows created this time have been recorded; the set is initially empty.

2. Confirm the candidate plan and probe the worker

After presenting the candidate plan, wait for the user to explicitly confirm it once. After confirmation and before creating the first window, probe in a fixed order:

agent_command=""
for candidate in codebuddy codebuddy-code cbc claude; do
  if command -v "$candidate" >/dev/null 2>&1; then
    agent_command="$candidate"
    break
  fi
done

codebuddy、codebuddy-code、cbc is the equivalent command name for CodeBuddy Code,claude is the only allowed fallback. Both types of CLI must use --permission-mode bypassPermissions. Arbitrary agent commands in the manifest are not accepted, and falling back to Codex or other tools is not allowed.

At the same time, confirm that the target agent session can use /implement. If it cannot be verified in the current agent's skill registry/installation directory that /implement, report TICKET_BLOCKED, and do not create a ticket window. If none of the four CLIs exist, tmux/session is unavailable, or /implement is unavailable, it must also block before window creation.

Completion conditions: has recorded the candidate plan, user confirmation,agent_command and /implement availability; or explicitly report blocked before creating a window.

3. Create the current ticket

Select the first ticket in plan order that has not been independently verified as done , and confirm that its dependencies are all complete. Create only one new window:

tmux new-window -d -t "$session" -n "ticket-<ID>" -c "$project" \
  "$agent_command --permission-mode bypassPermissions"

Immediately save the new window's real window_id、pane_id, and do not rely on numeric indexes that may be reordered. For the first message to the new session, send a complete, self-contained prompt, and it must be entered literally followed by Enter:

tmux send-keys -t "$pane_id" -l -- "$prompt"
tmux send-keys -t "$pane_id" Enter

The prompt must include the current ticket, tracker, confirmed allowedPaths、protectedPaths、verify、maxRepairRounds, project constraints,mainPane and the final-state protocol, and must explicitly require:

Only handle the current ticket, do not expand the scope, and do not touch baseline-protected changes;
must explicitly call /implementin its own agent session, and /implement is responsible for TDD, typecheck, tests, code-review, and commit; this process must not be copied or replaced;
/implement after completion, send the final-state message only once, and stop working after sending it;
mark tools/environment unavailable as TICKET_BLOCKED, and mark code/test/artifact failures as TICKET_FAILED；
The final message passes through tmux send-keys sent to mainPane, do not write resultFile。

When a busy CodeBuddy Code/Claude Code session receives an appended prompt, first input the content literally, then send Tab to queue; do not use Enter to interrupt the current session. Especially when mainPane the main agent is running, when the worker returns the terminal state it must also first input the JSON, then send Tab to queue. Only the first prompt of a new window uses Enter.

4. Receive the single terminal-state message

After the worker completes, send to mainPane a single line of JSON, in the following format:

{"event":"TICKET_DONE","ticket":"唯一 ID","status":"done","commit":"abc1234","changedFiles":["src/example.ts"],"verification":[{"command":"npm test -- --runInBand","result":"passed","evidence":".scratch/runs/01-test.log"}],"evidence":[".scratch/runs/01-test.log"],"summary":"完成当前 ticket 并通过验收"}

event can only be TICKET_DONE、TICKET_FAILED or TICKET_BLOCKED；status can only be done、failed or blocked. The message must include the ticket id, commit (for failure/blocked this may be null), changedFiles, the command/result/evidence of each verification, the evidence list, and a brief summary. The worker sends the terminal state only once and does not send progress messages.

After the expected terminal state arrives, the main window uses only one capture-pane to confirm that the single-line message has appeared:

tmux capture-pane -p -t "$mainPane" -S -30

Only parse the matching terminal-state JSON; do not bring continuous pane output back into the main context, and do not poll intermediate output. If the terminal state is missing, the JSON cannot be parsed, the ticket id does not match, fields are missing, or the worker exits abnormally, all are TICKET_BLOCKED, and keep the current window and evidence. Do not treat silence as success.

5. Independent verification

Upon receiving TICKET_DONE you also cannot directly unlock the next ticket. The main window independently performs:

git -C "$project" status --short --untracked-files=all
git -C "$project" diff --cached --name-only
git -C "$project" show --stat --oneline <commit>
git -C "$project" diff-tree --no-commit-id --name-only -r <commit>

Confirm item by item:

the commit exists, is an independent commit for the current ticket, and all files in the commit are located in the confirmed allowedPaths；
baseline modified/untracked/staged paths, protected paths, coverage, lock, and scheduling state have not entered ticket staging or commit; the content/path boundaries of the startup staging and the current staging are consistent;
changedFiles is consistent with the actual files in the commit, and no unexplained workspace pollution has appeared;
the tracker status, checklist, Resolution/Comments (if any) are consistent with the real results, but do not automatically modify the tracker;
the result of each verification command, the tests/artifacts, and the evidence paths truly exist and can be reviewed; code/test failures are failed, and only an unavailable environment is blocked。

If any item does not pass, it cannot be marked done. Classify by cause as TICKET_FAILED or TICKET_BLOCKED, keep the window and evidence, and stop the chain.

6. Clean up and proceed

Only close the window created this time if all independent verifications pass:

tmux kill-window -t "$window_id"
tmux list-windows -t "$session" -F '#{window_id}\t#{window_name}\t#{pane_id}'

Only operate on the real window_idrecorded in this run, and keep all windows that existed before startup. Only then start the next pending ticket. Windows that failed or are blocked are not closed, so that they can be inspected and recovered.

7. Recovery and whole-group terminal state

During recovery, re-establish the Git baseline and regenerate/confirm the plan: tickets that have been independently verified as done are skipped directly;failed or blocked only reset to pendingif the user explicitly approves a retry; do not automatically replay or retry in a loop.

Finally output only the ticket status, commit, verification conclusion, and evidence. Only when all tickets have been independently verified as done report overall completion; when there are failed or blocked , report the stopping point, the reason, the retained windows, and the recovery actions the user needs to approve.

Verify implement-tmux

After releasing or modifying this skill, prioritize using a disposable tmux fixture and a fake CodeBuddy Code/Claude Code CLI to record window creation, the first Enter, busy-session Tab queueing, final-state message arrival, independent verification, and cleanup. The fixture must at least verify:

CodeBuddy detection priority, Claude fallback, and blocked before window creation when neither is available;
the default order of map/spec, a single confirmation gate for explicit order conflicts, and no worker window before confirmation;
two independent tickets are still strictly serial, and the worker prompt explicitly invokes /implement；
missing/corrupted final state,TICKET_FAILED、TICKET_BLOCKED will stop the chain and retain the window;
TICKET_DONE the next ticket is started only after commit, file scope, staging, baseline protection, verification, and evidence all pass independently;
on success, only the window created this time is closed; on resumption, already-verified tickets are skipped, and the user must explicitly approve retrying failed/blocked tickets.

If no usable real tmux fixture is available, use deterministic command transcript tests to cover the same set of observable state transitions; before running the real fixture, do not claim that the real tmux runtime has passed.