implement

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# 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:

```bash
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.

   ```bash
   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:

```json
{"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

From PVMalove/claude-agent-harness, MIT.

More from PVMalove/claude-agent-harness