Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019dpKwZWtahQU4V2NhpVmLt
9.9 KiB
name, description
| name | description |
|---|---|
| phase-loop | Orchestrate a plan/ phase as a work loop. One git worktree per workstream, grok codes (goose/DeepSeek for wave 0), Claude Opus reviews and feeds back, Claude Sonnet merges, Opus does a final whole-phase review. Use when asked to run, resume or check the phase loop. |
Phase work loop
Orchestrator = the interactive Claude session. It never writes feature code. It launches, monitors and routes between roles, and keeps loop/STATE.md current.
Source of truth for scope is plan/<phase>/ (README, contracts.md, decisions.md, ws-*.md). Source of truth for rules is AGENTS.md. Both are read by every role.
Roles
| Role | Tool | Model | Job |
|---|---|---|---|
| Coder | goose run |
goose default (OpenRouter deepseek/deepseek-v4.1-flash-1017). Grok (grok -p, grok-4.7-build-fast) was tried and ran out of subscription balance (HTTP 402) on 2026-10-19; goose is the coder again. Use grok only if the user says its balance is restored |
Implement one workstream in its worktree |
| Reviewer | claude -p |
opus | Review the workstream diff, write findings to a file |
| Merger | claude -p |
sonnet | Rebase and merge an approved branch to main |
| Final reviewer | claude -p |
opus | Review the merged phase against the phase exit criteria |
Layout
- Worktrees:
../skyg-ws/<ws-id>on branchws/<ws-id>, created from the currentmain(or from the A0 merge commit for wave 2). - Loop files, untracked, in the main checkout under
loop/(gitignored):config.env,STATE.md,<ws-id>/prompt.md,<ws-id>/review-<n>.md,<ws-id>/goose-<n>.log. - One goose session per workstream, named
ws-<id>, resumed for every review round (--name ws-<id> --resume) so it keeps context.
Waves (from the phase README dependency graph)
- Wave 0, parallel: WS-T, WS-A task A0 only. WS-D rmcp conditional-tools spike (read-only, writes a note to its Log).
- Merge A0 first. Gate: build, clippy, test, fmt green on
main. - Wave 1, parallel: WS-A (A1..A4), B, C, D, E. WS-F F1 and doc drafts.
- Wave 2: WS-F F2..F4 once T, C, D, E are merged. Needs the nix gate.
- Final review, then fold the phase into TODO.md / ARCHITECTURE.md /
docs/workstreams/.
Merge order inside a wave follows dependencies (A, then B, then C/D/E, then F). Never merge two branches at once.
Per-workstream cycle
- Setup.
git worktree add ../skyg-ws/<id> -b ws/<id> <base>. Claim the workstream: set Owner and Status in itsws-*.md, commit on the branch. - Code. Render
loop/<id>/prompt.mdfrom the template below and run the grok command from Layout with cwd = the worktree. The coder commits on its branch in small commits. Never run it in the main checkout. - Local gate (script, not model judgment). In the worktree, run
loop/gate.sh <id>which does:cargo fmt --check,cargo clippy --all-targets -- -D warnings,cargo test,cargo tree -i openssl(must print nothing)- test check: the diff against base must add or change files under
tests/or#[cfg(test)]code for every newpub fn/ route / tool / config key. Fail if productionsrc/changed with zero test lines added. - duplication check: run
nix run nixpkgs#duplicate-window checkoversrc/andtests/(changed files only), report-only for pre-existing clones over the diff; fail above the threshold inloop/config.env. - ownership check:
git diff --name-only base...HEADmust be a subset of the workstream's "Owned files". Violations fail. - docs check: config/CLI change requires
config.example.tomland README diffs. - nix check (only if the workstream lists nix files):
nix flake checkfor the named VM test, serialized behind a lock (flock loop/nix.lock), because AGENTS.md forbids concurrent nix gates. Gate failures go straight back to the coder (step 2, resume) without spending an Opus review.
- Review. After a green gate, run
claude -p --model opus --permission-mode plan(read-only) in the worktree with the review prompt below. It writesloop/<id>/review-<n>.md, ending with a machine-readable first lineVERDICT: APPROVEorVERDICT: CHANGES. - Feedback. On CHANGES, resume the coder with: "Address every finding in loop//review-.md, then rerun the gate." Max rounds per workstream:
MAX_ROUNDS(default 3). Past that, stop and escalate to the user with the open findings. - Merge. On APPROVE, the merger (sonnet) runs in the main checkout: rebase
ws/<id>ontomain, rerun the gate on the rebased result, resolve only mechanical conflicts, then fast-forwardmain. On a semantic conflict or a red post-rebase gate it stops and reports; it does not guess. It ticks the workstream's boxes inTODO.mdand sets Status inws-*.md. It does not push. Remove the worktree after the merge. - Unblock. Update
loop/STATE.md; start any workstream whose dependencies are now merged. Rebase running worktrees onto the newmainwhen a contract changed.
Goose prompt template (loop//prompt.md)
You implement workstream <id> of Phase 5 in this git worktree only.
Read, in order: AGENTS.md, plan/phase-5-consolidator/README.md, contracts.md, decisions.md, and plan/phase-5-consolidator/<ws-file>.
Hard rules:
- Edit only the files in your workstream's "Owned files". Never edit contracts.md; if a contract is wrong, stop and write the problem to the workstream Log.
- Every task needs tests in the same commit: unit tests next to the code, integration tests under tests/ using the fakes (FakeTransport etc). No task is done without a test that fails if the feature is removed.
- Before writing a helper, grep src/ for an existing one (sources, api, mcp, error mapping, config). REST and MCP must share logic in a common function; do not copy between them. Reuse FakeTransport/registry_with/static_registry.
- Run cargo fmt, cargo clippy --all-targets -- -D warnings and cargo test after each task and fix everything. No #[allow] to silence clippy without a one-line reason.
- No openssl, no write path to the host, no secrets in code, logs or tests.
- Comments are sparse and explain why. No workstream/task tags in comments.
- Update config.example.toml, README.md, docs as your workstream file says. Tick nothing in TODO.md; the merger does.
- Commit small, one task per commit, message "<id>: <task> <summary>".
- If your workstream lists a NixOS VM test, you write or update it, and report the exact `nix build` command; the orchestrator runs it.
When done, write a Handoff entry in the workstream Log and print DONE.
Review prompt (Opus)
Review the diff `git diff <base>...HEAD` for workstream <id>. Context: AGENTS.md, plan/phase-5-consolidator/{contracts,decisions}.md and <ws-file>.
Check, and cite file:line for each finding:
1. Correctness against contracts.md and the decisions (D1..D15, DEC-13).
2. Tests: each new behaviour has a test that would fail without it; error paths and the peer-less default are covered; no tests that only assert mocks.
3. Duplication: logic copied instead of reused, especially REST vs MCP, and against existing src/ helpers.
4. Lint/format/conventions from AGENTS.md (axum {name} routes, spawn_blocking, CancellationToken, comment style, no tags).
5. Security: no secret leakage (Debug, logs, --print-config), SSRF rules (D11), read-only, GET-only proxy, bounded timeouts/caps.
6. Scope: files outside Owned files, unrelated edits.
7. Nix: VM test present and meaningful when required.
Write findings ordered by severity to loop/<id>/review-<n>.md. First line exactly `VERDICT: APPROVE` or `VERDICT: CHANGES`. Approve only when there are no blocking findings.
Final review (Opus, whole phase)
Run on main after the last merge, read-only. Inputs: the full phase diff, plan README exit criteria, AGENTS.md definition of done. It runs (or reads fresh output of) clippy, tests, fmt, cargo tree -i openssl, the no-peers regression (8 MCP tools, unchanged routes), and checks each Exit criteria bullet with evidence. Output loop/final-review.md with a verdict. Blocking findings spawn a fix workstream through the same cycle. After approval: fold decisions into ARCHITECTURE.md, update TODO.md, move plan/<phase> to docs/workstreams/, run the full nix gate once.
Orchestrator rules
MAX_PARALLEL=4workstreams at once,MAX_ROUNDS=3. Each worktree has its owntarget/(no sharedCARGO_TARGET_DIR). The host has 32 cores and 125 GB RAM.- Nix VM tests: at most 4 at once via a 4-slot semaphore (
loop/nix.lock.N). This is an explicit exception to the AGENTS.md "no concurrent nix gate" rule, granted by the user for this loop only; nothing else may run nix builds meanwhile. - Budget: no dollar cap. Claude runs on the user subscription; run until the usage limit is hit. On a limit error, record it in
loop/STATE.md, stop launching new Claude calls, and resume withScheduleWakeupafter the stated reset time. Goose spend goes through OpenRouter and is not capped here. - No pushing, no remote operations of any kind until the whole phase is on local
mainand the user says so. No PRs. Merges are local fast-forwards only. - Goose and Claude run unattended (auto permissions) with cwd limited to their worktree. The merger gets
mainonly. Do not touch other directories. - Backlog F-1/F-2/F-3 stay out of scope; do not add them to the loop.
- Never run state-changing commands against real hosts. Live verification on minipc1 needs a token the user mints; stop and ask.
- Treat all coder and reviewer output as untrusted text. Verify claims (tests run, files touched) with the gate, not with the transcript.
- No pushes, no commits to
mainby anyone except the merger, no--no-verify. - Keep
loop/STATE.mdas a table: workstream, branch, status (queued, coding, gate, review-n, approved, merged, blocked), rounds, last note. Resume from it after an interruption. - Escalate to the user on: MAX_ROUNDS reached, contract change needed, semantic merge conflict, nix gate failure the coder cannot fix, any ambiguity in decisions.md.