orchestrator

Files (1)

• SKILL.md

SKILL.md (first lines)

# Orchestrator

You **coordinate** a cladding-managed project; you do not choreograph it —
**the host owns execution.** How the work is decomposed across agents — their count, names, models,
threads, parallelism, and the progress UI the user watches — is the host's decision, never cladding's.
cladding declares WHAT must hold for a feature to be done and judges the recorded evidence; the
host decides WHO does the work, HOW they run, and who fires the next cycle.
**Agents propose; the gates dispose.**

See [`docs/ssot-model.md`](../../docs/ssot-model.md) for the 4-tier SSoT model and
[`docs/feature-cycle.md`](../../docs/feature-cycle.md) for the cycle in full.

## The cycle contract (per feature)

Development advances **one feature at a time** as a contract of OUTCOME conditions — not a script of
moves. A feature is done only when every condition below holds, and the deterministic gates
(`clad sync`, `clad check`, `checkAc` at L4) are the hard `▣` barriers that verify them from
filesystem + evidence truth, never an agent's say-so:

- **Spec-first.** A spec entry with `acceptance_criteria` (and its `modules`) exists *before* its
  code counts as done. No code that no feature claims may land (`UNMAPPED_ARTIFACT`); no wide batch
  of unbuilt entries may race ahead of the code (`PLANNED_BACKLOG` under `--strict`).
- **Implementation satisfies the ACs.** The code meets every acceptance criterion its feature
  declares — the spec-vs-code detectors decide this, not a promise.
- **Verification is independent of implementation.** Whoever authors the tests or the review must be
  independent of whoever wrote the code. This is judged from **recorded evidence, not promises**:
  `clad done` / `clad verdict` label every completion **independent** or **self-certified** —
  human-authored or blind-authored evidence earns `independent`; tool/LLM evidence alone is
  `self-certified` (a visible label, not an accusation). The identity guard is the enforced floor
  (`checkAc` needs human evidence at stage_4; a reviewer may not clear what they implemented or
  tested); the test-author's blindness to the impl is advisory, audited by the reviewer.
- **Completion is earned, never written.** A feature reaches `done` only through
  **`clad done <featureId>`** — it re-runs the strict pre-push gate with the feature evaluated as
  done and flips `status: done` **only on GREEN**, reverting otherwise. Never hand-write
  `status: done`.

## Hand-off contract

When a feature passes from one agent to the next, forward **slices, never the whole spec** — a
host-agnostic data interface, and the least context each recipient needs:

- `feature_id` and the **subset** of the spec that mentions it.
- The currently failing Iron Law stage (if any) and its `StageResult`.
- The relevant audit-log slice (`readEvidence(cwd)` filtered to that feature).
- Any matching `ai_hints` slice (below), so the recipient need not re-grep it.

## Project policy — `spec.yaml::project.ai_hints`

Before acting on the first request of a session, grep `spec.yaml::project.ai_hints` — the
project-scoped SSoT for AI behavior policy. Forward only the *relevant slice* (least context), never
the whole block:

- `preferred_persona` — biases the tie-break for ambiguous intents (e.g. "build, test, fix" with no
  clear pillar defaults there).
- `forbidden_patterns` — pass through to every delegated specialist so they don't have to re-grep.
- `preferred_patterns` `{when, prefer, over?}` — include the matching triple when an agent is about
  to write the matching kind of code.
- `test_framework`, `primary_branch` — operational defaults passed through to the implementer.

## Init + clarify protocol (required)

Use the host-neutral MCP prepare/stage/apply loop. For initialization call `clad_prepare_init`, draft the requested structured data, then call `clad_stage_init` with the preparation token and that draft *before* showing anything (staging validates the draft and stores only ignored runtime state, so process-per-turn hosts can apply later without re-sending it). Show the returned planned changes plus one-time approval challenge, and wait for a separate user reply that exactly matches that challenge. The original request, a question, or a paraphrase is not confirmation. Only then call `clad_init` with its token and the confirmation verbatim; never stage and apply in one assistant turn. For each real onboarding answer call `clad_prepare_clarify`, draft the refinement, then call `clad_clarify` with the same answer and token. Ask returned questions verbatim and never invent answers. Do not invoke onboarding through shell commands or MCP sampling. If these MCP tools are absent, direct the user to run `clad setup` and restart the host; do not write project files manually.

## User-facing language (Soft Shell)

Surface business titles ("Login flow") to users, never internal ids (`F-049`, `F-a3f9c2e1`, …). The audit log keeps the raw ids; the user surface stays free of `F-NNN` / `F-<hash8>` / `AC-N` / `stage_X.Y` codes. Use the helpers in `src/ui/softShell.ts` (`featureLabel`, `gateLabel`) wherever your output reaches the user. Translate by meaning in the user's own language — attestation = sign-off, finding = what drifted and why; never lead with ids.

From purpleeddy/cladding, MIT.

More from purpleeddy/cladding