implement

Coordinate one backend ticket through the approved architect, developer, review, QA, and publish handoffs.

SKILL.md

GitHub

Implement

Objective: Coordinate exactly one ticket through architect → developer → code-review → qa → publish, then offer /to-pull-requests. This session is the coordinator: it creates and observes dispatches but never implements the ticket itself.

Language contract: agents communicate with each other and write free-text protocol/state evidence in English. Every completion report addressed to this coordinator is in Russian and includes "report_language": "ru"; preserve commands, paths, IDs, and quoted evidence verbatim. Machine-read report values stay exact English enums: outcome: completed | blocked | failed, check result: pass | fail | not_run, and blockers.status / risks.status: none | present. Each blockers/risks field is a status/details object; translate only its description. This binds the text this session writes, not only the text it reads: translate the ticket into English before it reaches a batch or a worker prompt. definition_of_done and prohibited_changes are rejected outright when they carry Cyrillic, and a worker prompt carrying the untranslated ticket body is the same contract violation the coordinator cannot see.

Route

This is the opt-in backend-orchestration route. Confirm that its installed coordinator is usable:

python .harness/orchestration/coordinator.py --repo . dispatch status

If the command is unavailable or cannot read its state, stop and tell the developer to run /fast-implement instead. A ledger_busy answer is not unavailability: another coordinator operation holds the ledger lock, so repeat the command after its retry_after_seconds. Do not infer or repair an opt-in capability. Process one ticket to a terminal batch state before beginning another.

If another batch holds the same unfinished ticket, branch or worktree, or the concurrency_budget is exhausted, inspect batch list --open, the conflicting dispatch, and its decision packet. Tell the developer which batch is blocking and how to finish it normally. If its worker can no longer produce a report, first run batch auto-report, batch decision-packet, dispatch status and ledger validate, and quote the dispatch's startup assessment: worker state, classification and unknowns. Explain which of waiting, launch repair, human-approved batch resume-stop, batch rewind and cancelling an unsent dispatch applies, and why the others do not. Offer batch abandon only after that, as a separate explicit human choice for the whole batch: show a copyable command with the actual batch ID, the verified operator name, --approved-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)", and a reason grounded in the observed failure. Never supply --approved-by as though they already approved, or execute the command for them without that approval. ledger clean only removes orphaned evidence, and ledger reset does not clear an active batch.

Batch preparation

The coordinator must take every procedure from agent sources only: this skill, .harness/orchestration/playbook.md, .harness/orchestration/roles/, the guides in docs/agents/, and the --help and remedy output of the coordinator CLI. The coordinator must not take a procedure from a Russian human document (backend-orchestration.md, harness-guide.md, ARCHITECTURE.md, docs/skills/, docs/hooks/). The coordinator must not copy conventions from another batch and must not read ledger files in .harness/orchestration/state/. The coordinator must read state only through CLI commands (batch list, batch decision-packet, dispatch status). If these sources do not give a step, that gap is a blocker: the coordinator must stop and report it to the developer, and must not reconstruct the step.

Start these steps only after the ticket pre-flight in "Coordinator contract" (blockers, status::in-progress).

  1. Integration ref. Use the ticket's ## Integration Branch value. If the ticket has no such section, use its ## Git base value. If it has neither, use the same section of the parent epic. A missing value for a ticket that has a parent epic is a blocker; do not infer it from the checkout or from memory. A ticket without a parent epic uses base_branch: omit --integration-ref.

  2. Issue worktree. Create it before batch create. batch create refuses a worktree that git worktree list does not show. Use the exact commands, and the recovery after a half-done git worktree add -b, in docs/agents/worktrees.md → Coordinator issue worktree. Stay in the main checkout.

  3. Batch scope. Run batch preflight with the same scope flags as batch create. Translate the ticket into English first: batch create rejects Cyrillic in --goal, --definition-of-done and --prohibited-change. Keep commands, paths, and IDs verbatim.

  4. Create the batch. Repeat the list flags once for each value.

    python .harness/orchestration/coordinator.py --repo . batch create \
      --ticket "#<ID>" --branch "feature/issue-<ID>-<slug>" --worktree "<absolute worktree path>" \
      --integration-ref "<integration-branch>" --goal "<English goal>" \
      --definition-of-done "<English item>" --prohibited-change "<English item>" \
      --allowed-path "<path or glob>" --expected-file "<path>" --expected-service "<service>" \
      --expected-changed-lines <N> --required-gate review --required-gate qa
    

    --ticket, --branch, --worktree, --definition-of-done, --prohibited-change and at least one --allowed-path are mandatory. --branch must match branch_pattern. --expected-file, --expected-service and --expected-changed-lines are mandatory when the project policy requires estimates. The CLI refuses an oversized ticket and prints a remedy.

  5. Approve the batch. batch approve --batch <id> --approved-by <operator> --approved-at <UTC time> moves the batch from planned to awaiting-approval. This needs the operator's explicit approval: present the command, as for batch abandon, and do not run it for them.

Commit plan file. Pin the architect's plan with batch decide --batch <id> --decision accept --approved-by <operator> --approved-at <UTC time> --commit-plan-file <path>. The operator approves this decision; never supply --approved-by for them. The file is a JSON object with the single key commit_plan, a non-empty list in commit order:

{"commit_plan": [{"id": "tests", "summary": "Add failing tests", "expected_paths": ["tests/**"], "covers": [1]}]}

Each entry has exactly these fields: id (unique; up to 64 characters of letters, digits, ., _, -; the first character is a letter or digit), summary (non-empty), expected_paths (non-empty list of relative paths or globs, with no leading / and no ..), and covers (non-empty list of 1-based --definition-of-done item numbers, without repeats). Every definition-of-done item must appear in at least one entry. The CLI rejects a broken file and prints the expected format.

Coordinator contract

Resolve the tracker ticket, issue branch and blockers without opening a second batch for the same work. Ticket status is part of that pre-flight, before batch create and before the issue branch exists: check the ticket's blockers whatever its current label (any still open → stop, name them, and make sure it carries status::blocked); otherwise replace its status::* label with status::in-progress exactly as /fast-implement Phase 1 steps 2–3 do, and confirm it is the only status::* label. A failed label write is a blocker, not a warning. Before batch create, run the batch-level preflight with bounded expected files, services and diff size. Pin the writer's explicit scope with --allowed-path (repeat it; a path or glob inside the developer's write ceiling): batches with overlapping files run in parallel in their own worktrees, and a change outside the scope is rejected. If it rejects the ticket, split it with /to-tickets; never ask an architect to discover whether an oversized ticket should have been split. When creating the batch with batch create, specify --required-gate review --required-gate qa: the full implement pipeline explicitly sets both independent Standards/Spec review and serialized clean-room QA gates. Before dispatching the write-role (developer) worker, verify that these mandatory gates are recorded in the batch's required_gates; halt early if missing rather than sending a worker into a risk-gate omission.

For each handoff, choose the worker checkout and pass its absolute path as --worktree to dispatch preflight. Show batch decision-packet, then create an approved immutable brief. Pass the same explicit --worktree to dispatch send; code-review also keeps --checkout. Preflight and send verify the selected path, branch and startup SHA. Start the worker in exactly send.worker_worktree using a runtime-supported mechanism for that existing directory. Verify that mechanism before launch: isolation: worktree alone does not prove attachment to an existing worktree. If the runtime cannot select that checkout, report a blocker. The coordinator stays in the main checkout. A selected path is intent; self-report proves the worker's actual CWD. Pass the brief's report_staging_path to the worker verbatim; a role that has to guess where its report belongs writes it outside the project.

Claude Code runtime. The Agent tool cannot select an existing checkout: a subagent starts in the main checkout, and EnterWorktree refuses it there. Two paths exist; state which one the batch uses.

  • external (strict): set the worker roles' transport to external in .harness/orchestration.json and send with --adapter <main-repo>/.harness/adapters/claude_worker.py (absolute path). dispatch send runs the adapter in send.worker_worktree, and it starts a detached headless claude -p there on the brief's model, effort and allowed_tools, so the worker's CWD is the issue worktree. The adapter builds the prompt; for a retry, put the retry lines in a file inside the repository and pass --adapter-arg=--extra-prompt-file=<path>. A permission layer may refuse launching an agent from the coordinator session; that refusal is a stop, so show the developer the exact dispatch send command to run in their own terminal, then continue with dispatch wait.
  • in-process (weaker evidence): the subagent's CWD is the main checkout, so the template's CWD check would stop it. Replace that check in its prompt: probe git -C <worker_worktree> for the top-level, branch and HEAD, run every command with git -C or cd <worker_worktree> &&, and use absolute paths for every file. Its self-report then proves the checkout it works in, not its CWD; say so in the final report.

dispatch send checks the adapter's flags against its dispatch --help before the handoff and refuses an unsupported one: fix the --adapter-arg values and send the same approved dispatch again. Show any limitation in the send result's adapter_preflight. To diagnose an app-server runtime without a worker, run dispatch runtime-probe; its result is evidence, and the worker's model self-report stays mandatory.

The coordinator never writes feature code or repairs state by hand. A report is evidence, not permission to advance. Architect precedes developer; accepted candidate proceeds through the required review/QA/publish gates. A write-role worker stopped early before making changes returns a truthful outcome: blocked report bound to the verified checkout commit with empty changed_files and unrun checks; the coordinator decision packet returns an explicit recovery route (retry, block, or a human-selected abandon) without registering a candidate or weakening completed report validation.

Before every write-role dispatch, the immutable brief carries an ordered commit plan. Each entry names one independently reviewable logical change, its expected files and the DoD items it covers; use one entry only when the entire approved change is inseparable. The coordinator derives one entry per DoD item; to use the architect's plan instead, pin it on the architect accept with batch decide --decision accept --commit-plan-file <path>. A recovery preserves the accepted plan, or replaces it with a newly approved plan that explains the changed boundary. The developer's completion report maps every created commit to the entries it closes; a mapping that is not one-to-one needs dod_coverage and divergence_justification, and a report with a not_covered item can be accepted only by override-warning with a note other than none, or returned with retry. A report whose changed_files lie outside the brief's write_paths is recorded with a scope_warnings entry and is accepted only the same way. Do not collapse unrelated implementation, tests, documentation, or type-only repairs into a recovery commit merely because they are staged together.

Follow the configured approval policy. Under manual_all, every transition needs explicit approval: show the decision packet, ask, and wait. Under low_risk, a clean completed report of a batch whose allowed paths lie inside low_risk_paths is accepted by the coordinator with an audited policy decision, and the next eligible dispatch may already be approved. Under milestone, clean reports outside QA, publish and risk milestones are also accepted automatically; stop for the remaining milestone decisions. Continue from the recorded next_action without asking the operator to repeat a policy decision. Blockers, failed checks, risk triggers, review findings and publish still require the applicable manual decision. Never write --approved-by on the operator's behalf or narrate a decision they did not make. human_approval_gate: tty requires confirmation on the operator's terminal for transitions that still require human approval. When choosing a recovery route for retry or abandon, show the decision packet's route_preview (with the --reason-category or --retry-role you intend to pass to batch decide) and follow the Recovery route table in .harness/orchestration/playbook.md (situation → route → who approves → evidence). Report each startup failure under its own classification (unsupported flag, missing or refused self-report, capacity, rate-limit, service-unavailable) together with its recovery route.

Under approval_policy: auto, the coordinator takes every path decision by policy and records it as policy:auto; follow "Automatic path" in .harness/orchestration/playbook.md. Do not write --approved-by or --approved-at: run batch approve, dispatch create and a planned dispatch resume --trigger without them. For every pending report that the report submit or qa run chain did not accept, including the publish report, run batch auto-decide --batch <id>. Pass --commit-plan-file with the architect's plan copied exactly, --findings-file for coordinator findings on a developer report, --bug-ticket after you file or reuse the tool's bug ticket through the tracker CLI, and --block-bypass --note when a role worked around a block. Pass nothing else, and never choose the decision yourself. After a refused command, run batch auto-report --batch <id> to observe evidence. This read-only command does not record a stop. If it shows observed_stop, run batch auto-decide --batch <id> to record the pause, even without a pending report, then show batch auto-report again. The automatic path ends permanently at that pause. Inspect batch decision-packet, dispatch status and ledger validate before you propose waiting, launch repair, human-approved batch resume-stop, or batch rewind --to <gate> to repeat an earlier gate. An exhausted infrastructure budget keeps the batch paused for that human choice. Use the playbook's "Operator recovery" procedure. The original stop stays historical; all later approvals, including recognized 429 continuations, follow manual_all. Honor an approval already explicitly given in this session for the concrete operation; never invent one.

When a stage's report is blocked only by an infrastructure failure although its work looks complete (a developer's commits match the plan, for example), a human may decide batch decide --decision accept-conditional --infrastructure-failure --note <cause>. The pipeline advances as after accept, but the stage stays an open condition that a later code-review or qa accept must independently close; publish refuses while one is open. Never choose it yourself, and prefer resume-stop when the stage can simply be restarted.

A worker that works around a hook or tool block (another command form, tool, script file, eval, interpreter or a split command) breaks the protocol: never accept or warning-override that report, and record the violation in --note. For an architect or developer (publish included), decide retry with a developer reason category (not tooling) or block. For a read-only code-review, qa or verification role, pass --reason-category block-bypass to batch decision-packet and, once its route_preview.retry.route is bypass-rerun, to batch decide --decision retry: the same stage re-runs on the same SHA with no new candidate and no developer retry spent, and its new dispatch needs explicit approval under every approval_policy except auto. A report that stops with tooling_blocker instead is confirmed before its retry: check that its command is legitimate under the brief (allowed paths and tool policy) and that its message refuses that command. For a false positive, file or reuse a bug ticket against the tool through the tracker CLI (tool, command, message, dispatch ID), name the ticket in --note, and run batch decide --decision retry once route_preview.retry.route is tooling-retry; it re-runs the same stage on the same SHA (a developer continues its last commit) and spends no retry_policy.max_developer_retries. A command that is not legitimate is no false positive: retry with the developer reason category its evidence supports. Resolve the tooling-retry-repeated attention, raised by the third consecutive tooling retry on one candidate, only once the tool is fixed.

When you find a defect in a clean developer report whose DoD is met inside its allowed paths, do not retry it: accept it with batch decide --findings-file <path>, or after a policy auto-accept run batch carry-over --batch <id> --findings-file <path> before its code-review dispatch exists. The finding travels into the code-review brief as a carried item (route carry-over), and the one developer retry is spent after review. Retry a developer report without accept only for an unmet DoD item or an out-of-scope change.

Each worker records a model self-report and is observed by the event-driven watchdog; those facts are evidence, never a reason to edit an immutable brief.

Use the brief's shared Context Package ID across architect, developer and resumed worker sessions when the pinned base/candidate is unchanged. Read only its starting files and directly referenced symbols before escalating. A changed candidate creates one new shared package for its review, not a role-specific duplicate. Continuations and retries stop at the project budget; a 429 is not an exception to that budget.

Run dispatch wait between send and report. stale, model/worktree mismatch, changed harness snapshot, and a failed deterministic gate are blockers for the coordinator, not prompts for broad LLM recovery. Silence or a timeout does not prove that a worker stopped. batch resume-stop refuses a worker whose startup state is live or unknown: stop it through its runtime and repeat the command with --runtime-stopped. In-process and external transports preserve the same brief and evidence contract.

A busy ledger (ledger is locked by another operation, or ledger_busy from dispatch status) is transient: repeat dispatch wait or dispatch status. When a relayed report submit result carries completion, the report is already recorded: never ask the worker to submit it again. Run its command (report complete --dispatch <dispatch-id>) yourself and repeat it until no step fails; it is idempotent. When the failed step needs a human, follow its remedy instead. Never remove the ledger lock or any state file by hand; a lock that stays held goes to coordinator.py --repo . ledger release-lock, which refuses a lock whose owner process is alive. ledger lock-status shows the holder and the time left until a timeout release without taking the lock. For the lock of a stopped sandboxed worker, show the operator a copyable ledger release-lock --force --approved-by <operator> --approved-at <time> --reason <why>; it is their action, never yours, under every approval_policy.

Worker prompt

Every worker prompt is this template, filled from the dispatch send result and the CLI invocation used to send it. The brief and Context Package carry the task; the prompt also carries the mandatory lifecycle. Fill <coordinator CLI> with the Python executable, absolute coordinator.py path and absolute --repo (plus --state-dir when supplied) used for that dispatch. Quote paths for the worker's shell. Keep this same ledger address even when the worker runs in another worktree. Copy the heartbeat interval from dispatch send.heartbeat.every_seconds verbatim.

You are the <role> worker for dispatch <dispatch_id>.
Brief: <brief path from dispatch send>
Report staging path: <report_staging_path from dispatch send, verbatim>
Coordinator CLI: <coordinator CLI>
Expected worker checkout: <worker_worktree from dispatch send, canonical absolute path>
Expected startup SHA: <worker_snapshot_commit from dispatch send>
Before task work, run git rev-parse --show-toplevel, git branch --show-current and git rev-parse HEAD
in your runtime's current directory. Compare the top-level path and HEAD with the expected values
above, and the branch with the brief. Stop on any mismatch; do not reset Git history or claim
another checkout as your actual directory. Confirm your active model and the probed Git top-level:
<coordinator CLI> dispatch self-report --dispatch <dispatch_id> --model "<actual active model>" --worktree "<probed Git top-level>"
Proceed only after a successful self-report; escalate a mismatch or unavailable model identity.
Immediately after self-report and at least every <heartbeat.every_seconds> seconds while working, run:
<coordinator CLI> dispatch heartbeat --dispatch <dispatch_id>
Context Package <context_package_id>: start from its starting_files, symbol_graph and
related_tests. For a starting file with non-empty sections, read only the start_line–end_line
ranges the task needs.
Work within the brief; escalate a blocker for anything the brief and the package leave out.
Before your final reply, write the completion report JSON to the exact report staging path using
the common and role-specific report contract, with report_language: ru.
Use exact English enums: outcome = completed | blocked | failed; checks_run[].result = pass | fail | not_run.
Set blockers and risks (also in every review axis) to {"status": "none", "details": ""} when absent,
or {"status": "present", "details": "<Russian description>"} when present. A none status requires empty
details; present requires a non-empty description. Put other explanations in output. Strings, translated
statuses, passed and not-run are invalid; no aliases or old report formats are accepted.
Then run:
<coordinator CLI> report submit --file "<report_staging_path>"
Completion means the report is recorded in the ledger. Include the submit result in your final reply.
If submission fails before recording, return the command and error as a blocker; keep the report file.
If the result includes completion, relay it to the coordinator for report complete; the report is
already recorded, so submit it only once. Chat text alone does not complete the dispatch.

An architect retry adds one line. batch decide --note does not reach the brief, and retry_start exists only for a developer retry. Pass the reason of the retry in --note, in English, and add this line after the template lines:

Retry reason: <the exact --note text of the retry decision>; previous architect dispatch: <previous dispatch id>

The new architect uses the line as evidence of what the previous report lacked. The line does not widen the brief's scope.

A developer retry adds two lines from the retry_start of its dispatch preflight:

Retry handoff: <retry_start.handoff, verbatim JSON>
Retry starting files: <paths from retry_start.starting_files>

Use this lifecycle for every new or resumed worker session, including developer-retry. A continuation that stops at a checkpoint follows the checkpoint protocol instead of submitting a completion report. The coordinator treats a final reply without recorded completion or a valid checkpoint as an unfinished handoff and requests the missing protocol from the same available worker session.

Large documents (the role catalog, playbook.md, git-workflow.md) and prior reports reach a worker only as Context Package section ranges or through the retry handoff. The work a prompt asks for is exactly its brief plus, for a retry, the handoff's blocking findings (developer) or the retry reason line (architect).

A developer retry is always a new session started from its compact handoff, never a continuation of the previous developer session's history. The preflight's decision packet carries the retry's retry_context_estimate and retry_context_warning as evidence; they never gate the dispatch. Code-review and QA stay new independent sessions; only their prompt follows this template. The playbook's "Developer-retry handoff" defines the handoff, the smart-zone threshold and the compact.

Authoritative guidance

This is a short coordinator contract, not a second orchestration manual. Full rules are module-owned guidance:

  • .harness/orchestration/playbook.md owns lifecycle, authority, immutable brief, completion evidence, parallelism, and metric rules.
  • .harness/orchestration/roles/ owns each role's boundary, required proof, and specialist trigger.
  • The --help output and the remedy of the coordinator CLI own command syntax and operational recovery.
  • docs/agents/git-workflow.md owns issue-branch, commit, push, and PR boundaries.
  • docs/agents/worktrees.md owns issue worktree creation and its recovery.

Follow those files rather than duplicating or weakening their rules here. In particular, do not invent token metrics: use only provider- or runtime-observed telemetry and preserve missing-data notes.

Wrap-up

After an accepted publish, record the integration link before the branch is merged or deleted: python .harness/orchestration/coordinator.py --repo . integration prepare --ticket "#<ID>" --branch "<issue-branch>" (add --batch <batch-id> when several batches published the branch). It writes only an immutable integration record and is safe to repeat; if it refuses, report its remedy to the developer and do not work around it. Never edit the completed batch or its reports by hand.

Under approval_policy: auto, first show the final report of batch auto-report --batch <id> (decisions, accepted risks, findings, retries, budget, DoD coverage, review and QA results). Then offer /to-pull-requests <ticket>. Do not invoke it automatically, open or merge a PR, write to an integration branch, or close the ticket in this skill. A pull request needs the developer's explicit confirmation under every approval_policy; auto-merge is forbidden. Leave status::in-progress on the ticket: closing it and moving its unblocked dependents to status::ready belong to /to-pull-requests after the merge.