Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_019dpKwZWtahQU4V2NhpVmLt
106 lines
9.8 KiB
Markdown
106 lines
9.8 KiB
Markdown
---
|
|
name: phase-loop
|
|
description: 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 | `grok -p` headless | `grok-4.7-build-fast` (Grok subscription, logged in 2026-10-19). Wave 0 ran on goose with OpenRouter DeepSeek and is allowed to finish; every later run uses grok | 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 branch `ws/<ws-id>`, created from the current `main` (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)
|
|
|
|
1. Wave 0, parallel: WS-T, WS-A task A0 only. WS-D rmcp conditional-tools spike (read-only, writes a note to its Log).
|
|
2. Merge A0 first. Gate: build, clippy, test, fmt green on `main`.
|
|
3. Wave 1, parallel: WS-A (A1..A4), B, C, D, E. WS-F F1 and doc drafts.
|
|
4. Wave 2: WS-F F2..F4 once T, C, D, E are merged. Needs the nix gate.
|
|
5. 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
|
|
|
|
1. **Setup.** `git worktree add ../skyg-ws/<id> -b ws/<id> <base>`. Claim the workstream: set Owner and Status in its `ws-*.md`, commit on the branch.
|
|
2. **Code.** Render `loop/<id>/prompt.md` from 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.
|
|
3. **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 new `pub fn` / route / tool / config key. Fail if production `src/` changed with zero test lines added.
|
|
- **duplication check:** run `nix run nixpkgs#duplicate-window check` over `src/` and `tests/` (changed files only), report-only for pre-existing clones over the diff; fail above the threshold in `loop/config.env`.
|
|
- **ownership check:** `git diff --name-only base...HEAD` must be a subset of the workstream's "Owned files". Violations fail.
|
|
- **docs check:** config/CLI change requires `config.example.toml` and README diffs.
|
|
- **nix check** (only if the workstream lists nix files): `nix flake check` for 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.
|
|
4. **Review.** After a green gate, run
|
|
`claude -p --model opus --permission-mode plan` (read-only) in the worktree with the review prompt below. It writes `loop/<id>/review-<n>.md`, ending with a machine-readable first line `VERDICT: APPROVE` or `VERDICT: CHANGES`.
|
|
5. **Feedback.** On CHANGES, resume the coder with: "Address every finding in loop/<id>/review-<n>.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.
|
|
6. **Merge.** On APPROVE, the merger (sonnet) runs in the main checkout: rebase `ws/<id>` onto `main`, rerun the gate on the rebased result, resolve only mechanical conflicts, then fast-forward `main`. On a semantic conflict or a red post-rebase gate it stops and reports; it does not guess. It ticks the workstream's boxes in `TODO.md` and sets Status in `ws-*.md`. It does not push. Remove the worktree after the merge.
|
|
7. **Unblock.** Update `loop/STATE.md`; start any workstream whose dependencies are now merged. Rebase running worktrees onto the new `main` when a contract changed.
|
|
|
|
## Goose prompt template (loop/<id>/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=4` workstreams at once, `MAX_ROUNDS=3`. Each worktree has its own `target/` (no shared `CARGO_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 with `ScheduleWakeup` after 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 `main` and 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 `main` only. 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 `main` by anyone except the merger, no `--no-verify`.
|
|
- Keep `loop/STATE.md` as 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.
|