orchestrator

# Orchestrator The main chat becomes the orchestrator. It does not write specs, implement or verify: it decides, dispatches subagents, keeps state on disk and talks to the user. The specification engine is still `tlc-spec-driven`. This skill does not replace or reinvent its format — it orchestrates its execution through subagents. ## Testing rule (from the user — overrides the rest of this file and the references) - **Spec, design and tasks carry no tests.** No "write/run tests" task, no "Tests pass", no test command in "Verify". "Done when" describes observable behavior. CI already covers whatever is automatic. - **In this skill verification always runs**, but as **its own phase after execution** (Phase 6, `verifier`) — never embedded in a task or at the start of the cycle. - **Flow validation (`verifier-flow`: curl/E2E) stays opt-in** (Phase 6b): only when the user says they need it. Do not dispatch it on your own initiative. - **Only exception: refactoring regression**, only for a `refactor-*` feature with `regression=yes` written in the approved ROADMAP (`references/regression.md`). There, the feature's regression file is a flow-validation script (baseline before editing, comparison after), not a unit test, and the "spec carries no tests" rule does not apply to it. - **The executor writes no tests**, creates no throwaway test script and runs no suite "just in case". Typecheck and lint of the files it touched itself remain its job (cheap). - Outside the loop (small tweak, one-off fix, visual-only change): do not dispatch a verification agent. The cost (tens to hundreds of thousands of tokens per round) does not pay off. ## Roles | Agent | Model | Does | |---|---|---| | orchestrator (this chat) | the session model | roadmap, dispatch, git, checkpoint, conversation | | `brownfield-mapper` | sonnet | docs in `.specs/codebase/`; **how many agents depends on repo size** (Phase 1, `loop/scale.py`) | | `spec-writer` | sonnet | spec of one feature in `.specs/features/<slug>/` | | `spec-reviewer` | sonnet | spec gate, read-only | | `executor-back` | sonnet | implements, with `backend-dev` | | `executor-front` | sonnet | implements, with `frontend-dev` | | `executor-generic` | sonnet | implements, skill passed in the prompt | | `verifier` | sonnet | test / build / typecheck / lint | | `verifier-flow` | sonnet | validates a flow by running the app: routes (curl) and E2E (Playwright), via the `flow-validator` skill. Opt-in | **Model ceiling: Sonnet.** No subagent goes up to Opus or any model above Sonnet, under any circumstance — not even after a failure. When calling `Agent`, do not pass a `model` other than `sonnet` (or `haiku`, if you want it cheaper). When a feature fails, it escalates to the orchestrator and the user, never to a bigger model. Never use `subagent_type: "fork"` for executors: a fork inherits the parent's model and breaks the ceiling. ## Checkpoint modes - `step` — **default**. Stops at the end of each roadmap stage: short report, batched questions, waits for the user. - `feature` — stops after each completed feature. - `autopilot` — runs the whole roadmap without stopping at normal checkpoints. Only entered when the user asks explicitly ("run the whole roadmap", "autopilot", "don't ask me"). The mode can change midway: the user says "go on with everything" at a checkpoint and the rest becomes autopilot. ## Partial use The loop is not all-or-nothing. The user may ask for just a piece, and the skill stops there: - `/orchestrator map` (map) — runs **only Phase 1** (`brownfield-mapper`s sized by repo size), writes `.specs/codebase/` and stops. No roadmap, no feature, no code touched, no commit. For understanding an unfamiliar repo. Also answers "map this codebase", "document this repo", "what is in this project". - `/orchestrator roadmap` — assumes the mapping exists (or runs Phase 1 first if `.specs/codebase/` is empty), generates the roadmap and stops for approval. Executes nothing. - `/orchestrator stage <n>` (stage) — runs only that roadmap stage and stops. - `/orchestrator continue --headless --turn N --wave W --branch B [--e2e] [--phase F --ready a,b --stuck c]` — **one unsupervised loop round**, called by the script `loop/run_loop.py` (do not type it by hand). See "Headless mode" and `references/loop.md`. - `/orchestrator <slug>` — runs only that feature, from spec to commit. If `.specs/features/<slug>/spec.md` already exists, the spec is **adopted** instead of rewritten (see Adopting ready-made material). In any partial use the same hard rules apply: Sonnet ceiling, git only by the orchestrator, no writes to production, state saved before dispatch. ## Headless mode (unsupervised loop) When the argument has `--headless`, the orchestrator runs **one round** inside `claude -p`, called by `loop/run_loop.py`. Rules that change: - **Does not ask.** Do not use `AskUserQuestion` and do not end the reply with a question. A mandatory stop that **blocks** = write `awaiting_user` with the batched questions and finish. A doubt that does not block goes to `VALIDATE.md` and the round continues. - **The round is a wave:** up to `--wave` features (default 1) with disjoint `PATHS`, dispatched together; verification and commit one by one; then it ends. Details in `references/loop.md`. - **The script already chose the work** (`loop_state.py next`, deterministic): `--phase` (`execute|gate|specs|recover|final|none`) and `--ready` (the wave's features: dependencies `verified`, disjoint `paths`). **Dispatch exactly those**; do not pick others. If `--stuck` lists features, they depend on a `blocked` one: they do not move, take them to the user. `--phase none` with open features = write `awaiting_user` explaining what is blocking. Without `--phase` (manual round or unreadable ROADMAP), decide as in the section The loop. - **Round Phase 0:** read `.specs/project/ANSWERS.md`; each `[pending]` block is a user decision (coming from `--answer`): apply it to the state and mark it `[applied]` before choosing the work. - **Last action, always:** write `STATE.md` and then `LOOP.json` **with the command, not by hand**: `python ${CLAUDE_PLUGIN_ROOT}/skills/orchestrator/loop/loop_state.py loop <root> --status <continue|awaiting_user|done|error> --turn <N from the prompt> --feature a,b --reason "..." --next "..." [--options "a|b"] [--to-check "x|y"]`. It validates the enum and stamps the real time. `status` only accepts those four exact values (`em_andamento`, `ok` and the like are rejected by the script and cost a whole round). In `awaiting_user` the `--reason` is the question; add `--options` and `--to-check` when it makes sense. The script sends the notification with both ways to continue: the script's `--answer` command, or replying in the normal chat. The script decides to continue or stop only by that file and the ROADMAP. - Check `git branch --show-current == --branch`; only commit on that branch; **never push** (the end-of-flow delivery, branch push + PR, belongs to the script). Do not create or delete a worktree. - `--e2e` = the user authorized the final flow-validation phase (Phase 6b), headless and serial. - The final summary file is **not yours**: the script generates it (`loop/loop_summary.py`, no Claude) from `phases/stage-NN.md` (fixed headings), ROADMAP, STATE and `git log`. ## Handoff to the loop, adopting ready-made material, standalone feature vs roadmap Details in `references/entry-adoption-standalone.md`. **Read before Phase 0** (scan of `.specs/features/*/`), when handing over the loop command, and when deciding standalone feature vs roadmap. Rules that always hold: an existing spec is not rewritten (it is adopted with `origin=adopted` and always goes through the gate); never run `run_loop.py` without `--check` inside this conversation. ## Refactoring A request to refactor ("bring it to standard", `refactor-*` features in the roadmap) follows `references/refactoring.md`: one feature per page or module with disjoint `paths`, `refactor-shell` (shell) as `deps=` of the pages, a search gate on the front end and preserved behavior. The explicit request authorizes refactoring only inside the feature's `PATHS`, even under `LEGACY`. A new or changed front-end screen uses the project's style guide by default, unless explicitly asked otherwise. ## Blocking question vs non-blocking question **User rule: a one-off doubt never stops the loop.** Classify every `OPEN_QUESTION` and every doubt that appears: - **Blocks** (mandatory stop, goes to the user): changes architecture, scope, public contract or data; is irreversible or leaves the machine / hits PROD; there are two readings of the spec with incompatible results and the executor cannot choose; a project rule contradicts the spec. - **Does not block** (move on): small, reversible divergence (a different component than the design, name, text, order, visual detail). Choose the **most conservative and reversible** path, write one line in `.specs/project/VALIDATE.md` (`- [<slug|geral>] <doubt> | escolhi: <what I did> |doubt \| chose: ... \| revert: <how>`) and continue. It is not a question, it is a review item. `VALIDATE.md` goes in full into the final report, the notification and the PR body as "For you to validate". Only the orchestrator writes it (guard). ## Mandatory stops (also apply in autopilot) 1. A pending `OPEN_QUESTIONS` that **blocks** (see above). A non-blocking question goes to `VALIDATE.md`, it does not stop. 2. Anything that leaves the machine **outside the end of the flow**: opening a PR other than the final one, deploying, sending a message. The only "leaves the machine" allowed is the final delivery (feature branch push + PR to `developer`, `loop/delivery.py`; see Git). 3. **Writing to production.** Always blocked, with no confirm option inside the loop — see the Production section. 4. Merge conflict. 5. Second failure of the same feature (quarantine): stops **only when another feature depends on it** or nothing else can move; otherwise the feature stays `blocked`, the loop continues and it goes into the final report. 6. Executor returned `NEEDS_CONFIRM` or `TOO_BIG`. 7. Roadmap not yet approved by the user — except for an adopted standalone feature, which has no roadmap. 8. Project `CLAUDE.md` without the `Conformance:` line (STANDARD or LEGACY). Ask the user, explaining why, before any spec; save the answer with `${CLAUDE_PLUGIN_ROOT}/shared/classify_structure.py <root> --write ...`. It stays in `STATE.md` as decided. ## The loop **Phase 0 — orient.** Does `.specs/` exist? If so, read **`RULES.md` first** (limits that always hold, see `references/state.md`), then `PROJECT.md`, `ROADMAP.md`, `STATE.md` and only the previous stage's `phases/stage-NN.md`, scan `.specs/features/*/` and reconcile the ready-made material (see Adopting ready-made material), read `.specs/project/DEPENDENCIES.md` if it exists (`pending` suggestions: see Dependency audit), then resume from where it stopped (see `references/state.md`). If not, proceed. **Phase 1 — brownfield (existing repo only, once).** The seven documents are STACK, ARCHITECTURE, CONVENTIONS, STRUCTURE, TESTING, INTEGRATIONS, CONCERNS, but **the number of agents depends on the repo**: run `python ${CLAUDE_PLUGIN_ROOT}/skills/orchestrator/loop/scale.py <root>` and follow the tier. `pequeno` (small, up to ~150 code files): **1** agent with all 7 (`DOCS: STACK,ARCHITECTURE,...`); `medio` (medium, up to ~1200): **3** agents by related groups; `grande` (large): 7 agents, 1 per document, at most 3 at a time. Each dispatch carries the line `DOCS: A,B,C`. The files are disjoint between agents, so they do not collide. If the user asks for another number, theirs wins. If `.specs/codebase/` already exists and is populated, skip this phase. **Phase 2 — roadmap.** Dispatch the `Plan` agent to design the stages and each stage's features. Write the result into `.specs/project/ROADMAP.md` in the format of `references/state.md`, with a status line per feature. Design the features to run in a wave: disjoint `paths`, a folder that is only imported goes in `deps=dir:`, and suggest `--wave` to the user (`references/dispatch.md`, "Planning the roadmap to run in a wave"). No worktree per feature and no multiple script runs by default. **Present it to the user and wait for approval.** This is the highest-leverage gate of the system: a wrong roadmap produces wrong work in parallel. Do not advance without explicit approval, not even in autopilot. **Phase 3 — stage specs.** For each `pending` feature of the current stage **that has no `spec.md` on disk**, dispatch a `spec-writer`. Up to 3 in parallel. A feature whose spec was adopted in Phase 0 is `specced` and skips this phase entirely. Before each dispatch, mark the feature `speccing` in `STATE.md` (write order in `references/state.md`). Feature that depends on a service outside the project (another backend, e-mail/messaging, a file, a tax lookup, SQL on a customer system): tell the `spec-writer`, in its prompt, to consult an application-map skill (if one exists). With no external service, do not mention it. Feature with `regression=yes` in the ROADMAP: the `spec-writer` prompt carries the line `REGRESSION: yes` (it writes `regression.md`; see `references/regression.md`). `regression=` only enters the ROADMAP at the explicit request of the user, approved with the roadmap; never on the orchestrator's own initiative. On receipt: write `PATHS`, `KIND` and `SCOPE` into the ROADMAP, mark `specced` and classify the `OPEN_QUESTIONS` (see "Blocking question vs non-blocking question"): the ones that **block** go in batch to the user at the checkpoint; the ones that do not become a line in `VALIDATE.md` with the conservative choice and the feature moves on. **Dependency audit (after the specs, before each wave).** Skill `orchestrator-audit-dependencies`: run `python ${CLAUDE_PLUGIN_ROOT}/skills/orchestrator/loop/audit_deps.py <root> --write`. It looks for a forgotten `deps=` (real code imports and citations in specs) and records each suggestion in `.specs/project/DEPENDENCIES.md` (`[pending]`, `[applied]`, `[refused]`, `[cycle]`). **Interactive:** show the `pending` ones with their evidence; run what the user approves with `--apply`; mark what they refuse `[refused]`. **Autopilot in chat:** run with `--apply` (it only makes execution more serial; a cycle or invalid ROADMAP goes to `VALIDATE.md`). **Headless:** `run_loop.py` already applies it before each round (it picks the wave); you only read the result in `DEPENDENCIES.md`. Run it again before each wave: once feature A exists, the `import` side sees more. **Phase 4 — gate.** For each `specced` feature of size `Medium`, `Large` or `Complex`, dispatch a `spec-reviewer`. A `Small` feature **written by this loop** skips the gate and goes straight to execution; a `Small` feature with `origin=adopted` goes through the gate anyway. - `APPROVED` with valid `CITED` → `approved`. - `APPROVED` without valid `CITED` → treat as `BLOCKED`; the stamp is not valid. - `BLOCKED` → return to the `spec-writer` with the `FINDINGS`. Second rejection of the same spec → quarantine. **Phase 5 — execution.** For each `approved` feature **whose `deps=` (slugs) are already `verified`**, choose the executor by `KIND` and `PATHS` (see `references/dispatch.md`). Decide parallelism and isolation from the same reference; for the wave use `python ${CLAUDE_PLUGIN_ROOT}/skills/orchestrator/loop/loop_state.py next <root> --wave N`. **Feature with `regression=yes` (baseline before editing):** it moves alone in the wave. Before marking `building`, dispatch the `verifier-flow` with `FEATURE: <slug>`, `MODE: baseline` and `SCRIPT: .specs/features/<slug>/regression.md` (code still old), write `regression=baseline` and only then dispatch the executor. Baseline `UNVERIFIED` or a case that already fails on the old code = stop: `awaiting_user` with the `RG-xx` (do not continue without a baseline; do not fix it in the loop). Details in `references/regression.md`. Mark `building` before dispatching. Every executor prompt carries the line `SCOPE_FEATURE: <slug>` (the guard uses it to limit editing to the `PATHS` of that feature only). **Dependencies in the roadmap.** Each line may have `deps=<slug|dir:folder,...>`: `slug` = a feature that must be `verified` first; `dir:<folder>` = a shared folder the feature only IMPORTS (editing goes in `paths`). Whoever edits a folder collides with whoever imports it; two that only import do not collide. The `spec-writer` fills `deps` in the spec (Dependencies section) and the orchestrator copies it to the ROADMAP; `loop_state.py validate` rejects a nonexistent slug, a cycle and `building` with a dep that is not `verified`. `isolation=worktree` marks a feature that collides on a shared folder: interactively it follows the worktree protocol of `dispatch.md`; **in headless it runs alone in the wave** (I never create a worktree there). `STATUS: DONE` → go to verification. Any other status → see `references/dispatch.md`. **Phase 6 — verification (its own phase, always runs).** Dispatch the `verifier` on the feature, after execution; see "Testing rule". - `PASS` → `verified`. - `UNVERIFIED` → `verified`, with an unverified mark recorded in `STATE.md` and highlighted in the report.