Doer. Ticket Execution Orchestrator

Executes a single ticket end-to-end on a feature branch: 5 sequential stages, a bounded doer/reviewer loop on the build stage, on-device runtime verification via wk:protologs, lessons that accumulate across projects. State persists on disk; closing the session is pausing. BDD-style throughout: ACs are captured as Given/When/Then scenarios and tests derive from them (Stage 1, Stage 3), unless the change is trivial/cosmetic.

Scope: one ticket, one branch, up to (but not including) PR and deploy.

Protocols (read once, refer as needed)

Stages

Stage transition rule. Every stage transition and every resume runs the Transition Sync (lib/sync.md) as its first action, unconditionally: re-read metadata.json, then read ONLY the file for the current stage. One stage file resident at a time; this keeps peak context bounded and re-hydrates instructions after any compaction. A finished stage auto-proceeds to N+1 in the same turn; stopping between stages without an explicit pause is a sync violation, not a resting point.

Entry-point dispatch

Every /doer ... invocation, in order:

1. Resolve locale (first action): LOCALE="$("${CLAUDE_PLUGIN_ROOT}/lib/helpers/preferences.sh" get-locale)". All chat output binds to it (persistent state stays English; see lib/narration.md).
2. Route by command:
   • /doer list, /doer status <ID>, /doer cleanup-history <ID> → read _commands.md, execute, end turn.
   • /doer <ID> [--no-pr] → strip --no-pr from the arguments first (it is not part of the ID), then check ./.doer/tickets/<ID>/metadata.json:
     • Exists → read _resume.md and ONLY that file. Do NOT re-ask intake questions. A --no-pr typed here is ignored with a one-line narration: the mode is fixed when the ticket is created and lives in metadata.no_pr.
     • Missing → read 01-ac.md and ONLY that file (intake lives there); hold whether --no-pr was given for its Step 3.
3. Workspace Guard + lock (ticket-scoped commands only, not list/status): run "${CLAUDE_PLUGIN_ROOT}/lib/helpers/workspace-guard.sh" acquire "<TICKET-ID>" doer (contract: lib/workspace-guard.md) before touching metadata.

Version stamp. New tickets record skill_version from this frontmatter. On resume, "${CLAUDE_PLUGIN_ROOT}/lib/helpers/metadata.sh" version-check "<TICKET-ID>" "<this frontmatter's version>" compares the ticket's MAJOR against the current MAJOR; on incompatible <old> vs <current> (exit 1), stop and narrate: the ticket was created with an incompatible schema; finish it by hand or recreate it. No auto-migration machinery exists; if a future 7.x change ever needs one, it will be written then.

Implicit activation: natural language ("keep going", "pause here") with an active ticket (status == "in_progress" under ./.doer/tickets/*/metadata.json) is a directive to the orchestrator, not a new query. There is no pause command: state persists after every Agent return; stop / wait / hold on halts, anything else resumes.

Stages cannot be skipped manually. The only skip path is Stage 1's pre-existing-work detection; the orchestrator decides.

Agent invocation contract

Sub-agents receive the relevant metadata.json slices inlined in their prompt (no sidecar reads), write real artifacts directly to the working tree, and return JSON with a changelog_appendix plus stage-specific output. Doer agents also return {"status": "success" | "failed", "summary": "<one line>"}. Sub-agents never call AskUserQuestion; the orchestrator is the sole user-facing voice. Heavy artifact work (planning happens in plan mode; test/code writing, reviewing, log analysis go through Agent) is delegated; the orchestrator itself only does state reads/writes (via lib/helpers/metadata.sh, never a direct Edit/Write on metadata.json), deterministic validation, narration, and transitions.

Error handling

• Agent error: narrate it, end turn; the user decides (retry max 3, or pause).
• Git failure: narrate, present options (resolve manually, pause, abort stage).
• Test command unknown: ask once, persist as metadata.test_command via a single metadata.sh write.
• Halt signal: narrate current position and stop. Resume later with /doer <ID>.