@dirtydishes/skills 0.1.1

package/skills/dirtyloops/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: dirtyloops
+description: Create, run, inspect, close, and explain Beads-canonical Codex implementation loops.
+argument-hint: "help|create|run|inspect|closeout, optional workflow"
+disable-model-invocation: true
+---
+
+# dirtyloops
+
+A dirtyloop is a Beads-canonical Codex implementation loop: phase docs, one Markdown turn doc per phase, bounded subagent swarms, strict review, subagent-owned CI, and a final storyboard.
+
+## Steps
+
+1. Parse the branch from the user's request.
+   - `create`: turn a finalized plan into Beads issues, typed loop metadata, implementation docs, templates, and a run prompt.
+   - `run`: execute the loop until the epic is complete, blocked, interrupted, or `run once` is requested.
+   - `inspect`: summarize the current loop state without changing it.
+   - `closeout`: verify completion and generate the post-run storyboard.
+   - `help`: explain dirtyloops commands, workflows, examples, and usage.
+   - If the branch is missing, infer it only when obvious from the request. Otherwise ask one concise question.
+   - Completion criterion: one branch is selected and no other branch instructions are followed yet.
+
+2. Select the workflow.
+   - Skip this step for `help`.
+   - `single-thread-subagent`: one coordinator thread uses mass subagent swarms for selection, scouting, slice planning, implementation assistance, review, and CI; no separate Codex worker/reviewer threads.
+   - `orchestrator-callback`: an orchestrator thread creates implementation threads, then review threads; workers and reviewers call back to a concrete orchestrator thread id.
+   - Choose `orchestrator-callback` when the user mentions original loop flow, new threads, callbacks, worker threads, implementation threads, or review threads.
+   - Choose `single-thread-subagent` when the user mentions single thread, CLI-friendly, or keeping all orchestration in one thread.
+   - If the workflow is ambiguous for `create` or `run`, ask one concise question.
+   - Completion criterion: exactly one workflow is selected.
+
+3. Load the required references before acting.
+   - For `help`, read only `references/help.md`, then answer without mutating files, Beads, branches, PRs, or threads.
+   - For all non-help branches, read `references/common.md`, `references/beads.md`, `references/swarms.md`, `references/review-ci.md`, and `references/turn-docs.md`.
+   - For `create`, read `references/create-loop.md`.
+   - For `run`, read `references/run-loop.md`.
+   - For `inspect`, read `references/inspect-loop.md`.
+   - For `closeout`, read `references/storyboard.md`.
+   - For non-help branches, read the selected workflow file under `references/workflows/`.
+   - For `create`, read the selected workflow example under `examples/`.
+   - Read only the templates needed for the selected branch and workflow.
+   - Completion criterion: every referenced file for the selected branch/workflow has been read before file edits, Beads mutation, thread creation, or loop execution.
+
+4. Execute the selected branch.
+   - Follow the branch reference's completion criterion.
+   - Preserve Beads as canonical.
+   - Do not widen phase scope; file Beads follow-ups instead.
+   - Completion criterion: the branch reference's output contract has been satisfied, or a concrete blocker has been reported.
+
+## Hard Requirements
+
+- Beads is canonical for status, ordering, blockers, dependencies, and completion.
+- Beads records typed dirtyloop metadata: workflow, run policy, branch/PR policy, quality gates, callback policy, thread defaults, and swarm policy.
+- Phase docs are execution context linked from Beads.
+- Generated docs, prompts, examples, and callback payloads use repo-relative paths. Do not include user-specific home directories or usernames in generated loop artifacts.
+- Use one Markdown turn doc per phase.
+- Reviewers update the existing phase turn doc; they do not create a separate review doc.
+- Reviewer agents must use `thermo-nuclear-code-quality-review`.
+- Reviewer and CI verification agents own CI.
+- `dirtyloops run` continues phase-by-phase by default. Stop only when the epic is complete, blocked, interrupted, review/CI is unresolved, or the user explicitly asked for `run once` / `--once`.
+- Orchestrator-callback prompts and callback payloads must carry the concrete orchestrator thread id. Do not launch a worker or reviewer if the actual instruction text says only `current orchestrator thread`, `this thread`, or another generic target.
+- Worker and reviewer threads default to standard speed/reasoning unless the Beads loop metadata explicitly says otherwise.
+- For `single-thread-subagent`, the coordinator orchestrates, synthesizes, integrates, owns branch/PR/Beads state, and closes out. It must launch mass subagent swarms before broad implementation; direct coordinator implementation is for integration, glue, and final repair work.
+- Use large bounded subagent swarms: 8+ by default for broad scout, slice, implementation-helper, and review work, and up to 20 when the phase warrants it.
+- Closeout generates `storyboard-post-run-mm-dd-yyyy.html`.
+- The storyboard should use `impeccable` when present. If it is missing, continue without it and add a brief note that the skill was not found and was skipped during closeout.
+- Closeout must install `@pierre/diffs` in the target repo if missing, then use `@pierre/diffs/ssr` for every storyboard diff. SSR is required for every diff block.

package/skills/dirtyloops/examples/README.md

@@ -0,0 +1,8 @@
+# dirtyloops examples
+
+These examples show the shape `$dirtyloops create` should produce.
+
+- `single-thread-subagent/` shows one visible coordinator thread with mass subagent swarms, slice planning, implementation helpers, review, and CI verification.
+- `orchestrator-callback/` shows the original thread-callback loop: orchestrator thread, implementation threads, review threads, concrete callback targets, and callback payloads.
+
+Treat these as shape examples, not content to copy verbatim. New loops should fill in repo-specific Beads ids, phase docs, gates, branch policy, callback target ids, thread defaults, swarm policy, and prompt wording.

package/skills/dirtyloops/examples/orchestrator-callback/README.md

@@ -0,0 +1,18 @@
+# Example: Orchestrator Callback Workflow
+
+This example shows the generated files for the original dirtyloops flow.
+
+Topology:
+
+```text
+orchestrator thread
+  -> selector subagent
+  -> implementation thread with exact callback target
+  -> implementation callback when PR-ready
+  -> review thread with exact callback target
+  -> review callback when review + CI resolved
+  -> orchestrator closeout
+  -> next selector
+```
+
+Beads is canonical. The docs are execution context. Implementation and review callbacks echo the concrete orchestrator thread id and source thread id. Review and CI update the existing phase turn doc.

package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/00-roadmap.md

@@ -0,0 +1,26 @@
+# Example Stream Roadmap
+
+Canonical tracker: Beads epic `example-epic`
+
+## Outcome
+
+Replace the old reporting path with a simpler implementation that has durable review and CI evidence.
+
+## Phase Sequence
+
+1. `example-epic.1` - Foundation
+2. `example-epic.2` - Integration
+
+## Dependencies
+
+Integration depends on Foundation.
+
+## Risks
+
+- The old reporting path may contain hidden behavior.
+- Shared helpers may tempt ad-hoc branching.
+- CI failures must be owned by reviewer/verification agents.
+
+## Closeout
+
+The final closeout artifact is `storyboard-post-run-mm-dd-yyyy.html`.

package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/01-foundation.md

@@ -0,0 +1,51 @@
+# Phase 01: Foundation
+
+Canonical Beads issue: `example-epic.1`
+
+Epic: `example-epic`
+
+Status is tracked in Beads. This doc is implementation context.
+
+## Outcome
+
+Introduce the new reporting model behind a narrow internal API.
+
+## Scope
+
+Allowed:
+
+- add the model module
+- add focused tests for the model boundary
+- document migration assumptions in the turn doc
+
+Out of scope:
+
+- replacing public UI
+- deleting the old path
+- widening shared helper behavior
+
+## Inputs
+
+- existing report payloads
+- target internal API shape
+- quality gates from `IMPLEMENT.md`
+
+## Beads
+
+- Epic: `example-epic`
+- Issue: `example-epic.1`
+- Depends on: none
+- Parallel-safe: no
+
+## Suggested Swarms
+
+- 8 scouts to inspect old reporting assumptions
+- 8 reviewers for structural simplification and boundary quality
+- 4 CI verification agents if CI fails
+
+## Completion Criteria
+
+- model API exists
+- tests cover core behavior
+- PR is open
+- reviewer thread has approved or repaired with concrete CI state

package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/02-integration.md

@@ -0,0 +1,45 @@
+# Phase 02: Integration
+
+Canonical Beads issue: `example-epic.2`
+
+Epic: `example-epic`
+
+Status is tracked in Beads. This doc is implementation context.
+
+## Outcome
+
+Route the reporting surface through the new model while preserving behavior.
+
+## Scope
+
+Allowed:
+
+- swap the reporting adapter to the new model
+- add regression tests
+- update docs and close follow-ups
+
+Out of scope:
+
+- unrelated UI polish
+- broad report redesign
+- deleting fallback code not touched by this phase
+
+## Beads
+
+- Epic: `example-epic`
+- Issue: `example-epic.2`
+- Depends on: `example-epic.1`
+- Parallel-safe: no
+
+## Suggested Swarms
+
+- 10 scouts across adapter, tests, and call sites
+- 12 reviewers for structural and behavioral review
+- 6 CI verification agents if failures appear
+
+## Completion Criteria
+
+- adapter uses the new model
+- behavior remains covered
+- review and CI are resolved
+- Beads issue is closed

package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/IMPLEMENT.md

@@ -0,0 +1,68 @@
+# Example Stream Implementation Loop
+
+Workflow: `orchestrator-callback`
+
+Canonical tracker: Beads epic `example-epic`
+
+This example shows the shape of a generated orchestrator-callback loop. Beads is canonical; these docs are execution context and resume aids.
+
+## Goal
+
+Replace an old reporting path with a simpler evidence-backed implementation while preserving behavior.
+
+## Sources Of Truth
+
+- Beads epic: `example-epic`
+- Beads loop metadata: workflow, run policy, callback policy, thread defaults, quality gates, and branch/PR policy
+- Roadmap: `docs/implementation/example-stream/00-roadmap.md`
+- Loop state mirror: `docs/implementation/example-stream/loop-state.md`
+- Phase docs linked from Beads child issues
+- Turn docs: `docs/implementation/example-stream/turn-docs/`
+
+## Thread Topology
+
+Only the orchestrator creates implementation and review threads.
+
+Implementation threads:
+
+- receive the full phase doc, Beads issue id, branch policy, quality gates, and orchestrator thread id
+- default to standard speed/reasoning unless Beads metadata explicitly overrides it
+- have prompt text that names the exact orchestrator thread id as callback target
+- may use bounded subagents
+- update the existing phase turn doc
+- open the PR
+- call back exactly once when PR-ready or blocked, echoing `orchestrator_thread_id` and including `source_thread_id`
+- do not create review threads
+
+Review threads:
+
+- use `thermo-nuclear-code-quality-review`
+- default to standard speed/reasoning unless Beads metadata explicitly overrides it
+- have prompt text that names the exact orchestrator thread id as callback target
+- may use reviewer and CI verification subagents
+- own CI, repairs, reruns, and evidence
+- update the existing phase turn doc
+- call back exactly once when review and CI are resolved, echoing `orchestrator_thread_id` and including `source_thread_id`
+
+The orchestrator owns Beads closeout and next selector launch. The loop continues phase-by-phase until the epic is complete, blocked, interrupted, or review/CI is unresolved.
+
+## Phase Ledger
+
+| Beads Issue | Phase | Phase Doc | Depends On | Status |
+|---|---|---|---|---|
+| `example-epic.1` | Foundation | `01-foundation.md` | none | pending |
+| `example-epic.2` | Integration | `02-integration.md` | `example-epic.1` | pending |
+
+## Quality Gates
+
+- `bun test`
+- `bun run typecheck`
+- targeted browser QA when UI changes
+
+## Branch And PR Policy
+
+One active implementation PR at a time. Use branch prefix `example-stream/`.
+
+## Storyboard
+
+When the epic is complete, generate `storyboard-post-run-mm-dd-yyyy.html` using `impeccable` when present. If missing, continue and note that it was skipped. Install `@pierre/diffs` if missing, and use `@pierre/diffs/ssr` for every diff.

package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/loop-state.md

@@ -0,0 +1,36 @@
+# Loop State
+
+Canonical tracker: Beads epic `example-epic`
+
+This file is a compact resume aid only. If this file disagrees with Beads, Beads wins.
+
+Status: active
+
+Stream: `example-stream`
+
+Workflow: `orchestrator-callback`
+
+Current phase: none
+
+Current Beads issue: none
+
+Current implementation thread: none
+
+Current review thread: none
+
+Current PR: none
+
+Last completed phase: none
+
+Blocked: no
+
+## Phase Ledger
+
+| Phase | Beads Issue | Status | PR | Turn Doc |
+|---|---|---|---|---|
+| Foundation | `example-epic.1` | pending | | `turn-docs/01-foundation.md` |
+| Integration | `example-epic.2` | pending | | `turn-docs/02-integration.md` |
+
+## Last Orchestrator Update
+
+Not started.

package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/prompts/implementation-thread.md

@@ -0,0 +1,30 @@
+# Implementation Thread Prompt
+
+You are the implementation thread for Beads issue `example-epic.1`.
+
+Callback target:
+
+`THREAD_ORCHESTRATOR_ID`
+
+Send your final callback to exact orchestrator thread id `THREAD_ORCHESTRATOR_ID`. Do not rely on `current orchestrator thread`, `this thread`, or implicit wrapper metadata.
+
+## Inputs
+
+- Beads issue: `example-epic.1`
+- Phase doc: `docs/implementation/example-stream/01-foundation.md`
+- Implementation index: `docs/implementation/example-stream/IMPLEMENT.md`
+- Turn doc: `docs/implementation/example-stream/turn-docs/01-foundation.md`
+- Branch policy: create or use `example-stream/01-foundation`
+- Thread default: standard speed/reasoning
+
+## Rules
+
+- Implement exactly this phase.
+- Do not widen scope.
+- Use bounded implementation/scout subagents when useful.
+- Update the existing Markdown turn doc.
+- Run local gates before PR when feasible.
+- Open or update the PR.
+- Do not create the review thread.
+- Call back exactly once to the orchestrator when PR-ready or blocked.
+- The callback payload must include `orchestrator_thread_id: "THREAD_ORCHESTRATOR_ID"` and your `source_thread_id`.

package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/prompts/review-thread.md

@@ -0,0 +1,35 @@
+# Review Thread Prompt
+
+You are the review thread for Beads issue `example-epic.1`.
+
+Callback target:
+
+`THREAD_ORCHESTRATOR_ID`
+
+Send your final callback to exact orchestrator thread id `THREAD_ORCHESTRATOR_ID`. Do not rely on `current orchestrator thread`, `this thread`, or implicit wrapper metadata.
+
+## Mandatory Skill
+
+Use:
+
+`thermo-nuclear-code-quality-review`
+
+## Inputs
+
+- Beads issue: `example-epic.1`
+- Phase doc: `docs/implementation/example-stream/01-foundation.md`
+- Turn doc: `docs/implementation/example-stream/turn-docs/01-foundation.md`
+- PR: `#123`
+- Required gates: `bun test`, `bun run typecheck`
+- Thread default: standard speed/reasoning
+
+## Rules
+
+- Be ambitious about structural simplification.
+- Use reviewer and CI verification subagents when useful.
+- Own CI through green, repaired-and-green, unavailable-with-evidence, or blocked-with-cause.
+- Apply safe in-scope repairs when assigned.
+- Update the existing Markdown turn doc.
+- Do not create follow-up implementation threads.
+- Call back exactly once when review and CI are resolved.
+- The callback payload must include `orchestrator_thread_id: "THREAD_ORCHESTRATOR_ID"` and your `source_thread_id`.

package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/prompts/run-loop.md

@@ -0,0 +1,33 @@
+# Run Loop: Example Stream
+
+Workflow: `orchestrator-callback`
+
+Canonical tracker: Beads epic `example-epic`
+
+Start from:
+
+- Beads epic: `example-epic`
+- Implementation index: `docs/implementation/example-stream/IMPLEMENT.md`
+- Resume aid: `docs/implementation/example-stream/loop-state.md`
+
+## Rules
+
+- Beads is canonical.
+- Orchestrator selects exactly one next ready Beads child issue.
+- Continue phase-by-phase until the epic is complete, blocked, interrupted, or review/CI is unresolved.
+- Only the orchestrator creates implementation and review threads.
+- Worker and reviewer threads default to standard speed/reasoning unless Beads metadata says otherwise.
+- Worker and reviewer prompt text must include the exact orchestrator thread id `THREAD_ORCHESTRATOR_ID` as callback target.
+- Implementation threads call back exactly once when PR-ready or blocked.
+- Implementation callbacks echo `orchestrator_thread_id` and include `source_thread_id`.
+- Implementation threads do not create review threads.
+- Review threads use `thermo-nuclear-code-quality-review`.
+- Review threads own CI, repairs, reruns, and evidence.
+- Review threads call back exactly once when review and CI are resolved.
+- Review callbacks echo `orchestrator_thread_id` and include `source_thread_id`.
+- All actors update the existing Markdown phase turn doc.
+- Update Beads first, then update `loop-state.md`.
+
+## Start Prompt
+
+Run the Example Stream dirtyloop with workflow `orchestrator-callback`. Use Beads epic `example-epic` as canonical. Read `docs/implementation/example-stream/IMPLEMENT.md` and `docs/implementation/example-stream/loop-state.md`, select one next ready Beads child issue with a selector subagent, create an implementation thread at standard speed with the full linked phase doc and exact callback target `THREAD_ORCHESTRATOR_ID` in the prompt text, wait for an implementation callback that echoes `orchestrator_thread_id` and includes `source_thread_id`, then create a review thread at standard speed that uses `thermo-nuclear-code-quality-review` and owns CI. Close out only after the review callback reports concrete CI state and echoes the same callback target. Do not let worker threads create review threads. Continue to the next ready phase unless the epic is complete, blocked, interrupted, or review/CI is unresolved.

package/skills/dirtyloops/examples/orchestrator-callback/docs/implementation/example-stream/turn-docs/01-foundation.md

@@ -0,0 +1,79 @@
+# Phase 01 Turn Doc: Foundation
+
+Beads issue: `example-epic.1`
+
+Phase doc: `docs/implementation/example-stream/01-foundation.md`
+
+This is the single Markdown turn doc for the phase.
+
+## Phase Selection
+
+Selected by the orchestrator after `bd ready` showed `example-epic.1` unblocked.
+
+## Implementation Log
+
+- Implementation thread `THREAD_IMPLEMENTATION_ID` created with orchestrator callback target `THREAD_ORCHESTRATOR_ID`.
+- Worker created branch `example-stream/01-foundation`.
+- Worker opened PR `#123`.
+
+## Implementation Callback
+
+```json
+{
+  "type": "implementation-callback",
+  "orchestrator_thread_id": "THREAD_ORCHESTRATOR_ID",
+  "source_thread_id": "THREAD_IMPLEMENTATION_ID",
+  "phase_issue_id": "example-epic.1",
+  "status": "pr-ready",
+  "branch": "example-stream/01-foundation",
+  "pr": "#123",
+  "commits": ["abc1234"],
+  "turn_doc": "docs/implementation/example-stream/turn-docs/01-foundation.md",
+  "local_gates": ["bun test: passed"],
+  "changed_files": ["src/reporting/model.ts", "src/reporting/model.test.ts"],
+  "blockers": [],
+  "context_to_keep": ["The new model boundary is report-in/report-out and does not know UI concerns."]
+}
+```
+
+## Review
+
+Reviewer skill:
+
+`thermo-nuclear-code-quality-review`
+
+- Review thread `THREAD_REVIEW_ID` created by orchestrator after PR-ready callback.
+- Reviewer swarm found one simplification opportunity and repaired it on the branch.
+
+## CI And Gates
+
+CI owner: reviewer/verification agents
+
+Current CI state: `ci-repaired-and-green`
+
+Evidence:
+
+- Validate check passed on commit `def5678`.
+
+## Review Callback
+
+```json
+{
+  "type": "review-callback",
+  "orchestrator_thread_id": "THREAD_ORCHESTRATOR_ID",
+  "source_thread_id": "THREAD_REVIEW_ID",
+  "phase_issue_id": "example-epic.1",
+  "status": "repaired",
+  "pr": "#123",
+  "ci_state": "ci-repaired-and-green",
+  "review_skill": "thermo-nuclear-code-quality-review",
+  "repairs": ["Collapsed adapter branching into the model boundary."],
+  "findings_remaining": [],
+  "turn_doc": "docs/implementation/example-stream/turn-docs/01-foundation.md",
+  "context_to_keep": ["Adapter branching should stay behind the model boundary."]
+}
+```
+
+## Closeout
+
+Orchestrator merged PR `#123`, closed `example-epic.1`, refreshed Beads export, and launched the next selector.

package/skills/dirtyloops/examples/single-thread-subagent/README.md

@@ -0,0 +1,14 @@
+# Example: Single-Thread Subagent Workflow
+
+This example shows the generated files for the single-thread dirtyloops flow.
+
+Topology:
+
+```text
+main coordinator thread
+  -> selector/scout/slice/implementation-helper/reviewer/CI subagents
+  -> coordinator synthesizes and integrates
+  -> coordinator closeout
+```
+
+Beads is canonical. Subagents are bounded and disposable. The main thread owns loop state, branch/PR state, integration, and closeout. Broad implementation starts only after a mass subagent slice plan.

package/skills/dirtyloops/examples/single-thread-subagent/docs/implementation/example-stream/00-roadmap.md

@@ -0,0 +1,16 @@
+# Example Stream Roadmap
+
+Canonical tracker: Beads epic `example-epic`
+
+## Outcome
+
+Replace the old reporting path inside one visible coordinator thread with mass subagent swarms.
+
+## Phase Sequence
+
+1. `example-epic.1` - Foundation
+2. `example-epic.2` - Integration
+
+## Closeout
+
+The final closeout artifact is `storyboard-post-run-mm-dd-yyyy.html`.

package/skills/dirtyloops/examples/single-thread-subagent/docs/implementation/example-stream/01-foundation.md

@@ -0,0 +1,36 @@
+# Phase 01: Foundation
+
+Canonical Beads issue: `example-epic.1`
+
+Epic: `example-epic`
+
+## Outcome
+
+Introduce the new reporting model behind a narrow internal API.
+
+## Scope
+
+Allowed:
+
+- add the model module
+- add focused tests
+- update the turn doc
+
+Out of scope:
+
+- separate worker/reviewer threads
+- replacing public UI
+- deleting the old path
+
+## Beads
+
+- Epic: `example-epic`
+- Issue: `example-epic.1`
+- Depends on: none
+- Parallel-safe: no
+
+## Suggested Swarms
+
+- 8 scouts for old behavior assumptions
+- 12 reviewers for structural simplification
+- 4 CI verification agents if gates fail

package/skills/dirtyloops/examples/single-thread-subagent/docs/implementation/example-stream/02-integration.md

@@ -0,0 +1,23 @@
+# Phase 02: Integration
+
+Canonical Beads issue: `example-epic.2`
+
+Epic: `example-epic`
+
+## Outcome
+
+Route the reporting surface through the new model while preserving behavior.
+
+## Beads
+
+- Epic: `example-epic`
+- Issue: `example-epic.2`
+- Depends on: `example-epic.1`
+- Parallel-safe: no
+
+## Completion Criteria
+
+- adapter uses the model
+- review subagents approve or repair
+- CI verification subagents report concrete state
+- Beads issue is closed

package/skills/dirtyloops/examples/single-thread-subagent/docs/implementation/example-stream/IMPLEMENT.md

@@ -0,0 +1,50 @@
+# Example Stream Implementation Loop
+
+Workflow: `single-thread-subagent`
+
+Canonical tracker: Beads epic `example-epic`
+
+This example shows the shape of a generated single-thread subagent loop. Single-thread means one visible coordinator, not solo implementation.
+
+## Goal
+
+Replace an old reporting path with a simpler evidence-backed implementation while preserving behavior.
+
+## Sources Of Truth
+
+- Beads epic: `example-epic`
+- Roadmap: `docs/implementation/example-stream/00-roadmap.md`
+- Beads loop metadata: workflow, run policy, swarm policy, quality gates, and branch/PR policy
+- Loop state mirror: `docs/implementation/example-stream/loop-state.md`
+- Phase docs linked from Beads child issues
+- Turn docs: `docs/implementation/example-stream/turn-docs/`
+
+## Topology
+
+The main coordinator thread owns integration, branch state, PR state, Beads updates, and closeout.
+
+Subagents are bounded swarms:
+
+- selector swarm: 4-8 agents
+- scout swarm: 8-20 agents
+- slice planning swarm: 8-16 agents
+- implementation helper swarm: 8-16 agents
+- reviewer swarm: 8-20 agents
+- CI verification swarm: 4-12 agents
+
+Subagents split the phase into slices, inspect, prepare implementation guidance or patches, review, verify, and report. They do not own loop state.
+
+The coordinator runs a slice planning swarm before broad implementation. Direct coordinator implementation is limited to synthesis, integration, glue, conflicts, final repairs, and Beads/PR closeout.
+
+## Phase Ledger
+
+| Beads Issue | Phase | Phase Doc | Depends On | Status |
+|---|---|---|---|---|
+| `example-epic.1` | Foundation | `01-foundation.md` | none | pending |
+| `example-epic.2` | Integration | `02-integration.md` | `example-epic.1` | pending |
+
+## Review And CI
+
+Reviewer subagents must use `thermo-nuclear-code-quality-review`.
+
+Reviewer and CI verification subagents own CI evidence.