Files
skyg-linux-tracker/.claude/skills/phase-loop/SKILL.md
T

9.8 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 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//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.
  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//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.