@dirtydishes/skills 0.1.1

package/skills/dirtyloops/references/workflows/orchestrator-callback.md

@@ -0,0 +1,120 @@
+# Workflow: Orchestrator Callback
+
+Use this workflow for the original loop style: a main orchestrator thread creates implementation threads and review threads that call back to a concrete orchestrator thread id.
+
+## Topology
+
+```text
+orchestrator thread
+  -> selector subagent chooses next ready Beads phase
+  -> orchestrator creates implementation thread
+  -> implementation thread may use subagents
+  -> implementation thread opens PR and calls back
+  -> orchestrator creates review thread
+  -> review thread may use subagents
+  -> review thread owns CI and repairs
+  -> review thread calls back after review + CI are resolved
+  -> orchestrator updates Beads and loop state
+  -> orchestrator launches next selector when continuing
+```
+
+## Authority
+
+The orchestrator owns:
+
+- Beads canonical state
+- phase selection
+- implementation thread creation
+- review thread creation
+- concrete callback target, callback preflight, and heartbeat
+- phase closeout
+- launching the next selector
+- stream closeout and storyboard generation
+
+The implementation thread owns:
+
+- exactly one selected Beads issue
+- branch/worktree setup assigned by the orchestrator
+- implementation
+- local gates before PR when feasible
+- PR creation
+- updating the existing Markdown turn doc
+- callback when PR-ready or blocked
+
+The review thread owns:
+
+- thermo-nuclear review
+- reviewer subagent swarms
+- CI inspection, diagnosis, repair, rerun, and evidence
+- updating the existing Markdown turn doc
+- callback when approved, repaired, or blocked with concrete CI state
+
+## Non-Negotiable Thread Rules
+
+- Only the orchestrator creates implementation and review threads.
+- Implementation threads do not create review threads.
+- Review threads do not create follow-up implementation threads.
+- Selector subagents never implement.
+- Reviewer subagents never close Beads issues.
+- The orchestrator is the only actor that advances to the next phase.
+- Implementation and review threads default to standard speed/reasoning unless Beads metadata explicitly overrides it.
+- Before launch, the orchestrator must verify the actual worker/reviewer prompt text includes the exact orchestrator thread id as callback target. Do not launch if the prompt relies on generic wording such as `current orchestrator thread`, `this thread`, or a hidden wrapper.
+
+## Implementation Callback
+
+Implementation threads call back exactly once when:
+
+- PR is open and ready for review
+- the task is complete but PR cannot be created, with exact blocker
+- the thread is genuinely blocked
+
+Payload:
+
+```json
+{
+  "type": "implementation-callback",
+  "orchestrator_thread_id": "...",
+  "source_thread_id": "...",
+  "phase_issue_id": "...",
+  "status": "pr-ready|blocked",
+  "branch": "...",
+  "pr": "...",
+  "commits": ["..."],
+  "turn_doc": "...",
+  "local_gates": ["..."],
+  "changed_files": ["..."],
+  "blockers": [],
+  "context_to_keep": []
+}
+```
+
+## Review Callback
+
+Review threads call back exactly once when review and CI are resolved.
+
+Payload:
+
+```json
+{
+  "type": "review-callback",
+  "orchestrator_thread_id": "...",
+  "source_thread_id": "...",
+  "phase_issue_id": "...",
+  "status": "approved|repaired|blocked",
+  "pr": "...",
+  "ci_state": "ci-green|ci-repaired-and-green|ci-unavailable-with-evidence|ci-blocked-with-cause",
+  "review_skill": "thermo-nuclear-code-quality-review",
+  "repairs": ["..."],
+  "findings_remaining": [],
+  "turn_doc": "...",
+  "context_to_keep": []
+}
+```
+
+## Heartbeat
+
+Prefer callback-driven coordination over polling. Use a lightweight fallback heartbeat around 30 minutes for long-running worker/reviewer threads.
+
+## Completion Criterion
+
+The orchestrator has received and validated the required callback, updated Beads and the existing turn doc, and either launched the next selector or reported an allowed stop state.

package/skills/dirtyloops/references/workflows/single-thread-subagent.md

@@ -0,0 +1,45 @@
+# Workflow: Single-Thread Subagent
+
+Use this workflow when the user wants one visible Codex coordinator thread with mass subagent swarms. Single-thread means one visible coordinator, not solo implementation.
+
+## Topology
+
+```text
+main coordinator thread
+  -> selector subagents
+  -> scout swarm
+  -> slice planning swarm
+  -> implementation helper swarm
+  -> coordinator synthesizes and integrates
+  -> reviewer subagents
+  -> CI verification subagents
+  -> coordinator closeout
+```
+
+## Rules
+
+- Do not create separate Codex worker or reviewer threads.
+- The main thread owns branch state, integration, PR state, Beads updates, and closeout.
+- Subagents inspect, compare, critique, slice the phase, prepare implementation guidance or patches, verify, and report.
+- Subagents do not advance loop state.
+- Use 8+ agents by default for broad scout, slice, implementation-helper, and review work; 8-20 agents is normal when the phase has meaningful surface area.
+- Before broad implementation, launch a slice planning swarm and record the synthesized slice plan in the turn doc.
+- For non-trivial phases, create or record intra-phase implementation slices. Use ephemeral Beads child issues when supported and useful; otherwise record the slices in the turn doc.
+- The coordinator may implement glue, integration, conflict resolution, and final repairs. If it performs most broad discovery or implementation itself, the loop has violated this workflow.
+- If fewer than 8 subagents are used for a broad phase, record the reason in the turn doc.
+
+## Slice Contract
+
+Each implementation slice has:
+
+- slice id
+- files or modules
+- expected behavior change
+- tests or gates
+- out-of-scope boundary
+- assigned helper mission
+- compact report using `schemas/swarm-report.schema.json`
+
+## Completion Criterion
+
+The main coordinator has selected one phase, received and synthesized scout/slice/implementation-helper reports, integrated one phase, received reviewer/CI subagent reports, updated the existing turn doc, updated Beads, and either continued to the next ready phase or stopped with an allowed stop reason.

package/skills/dirtyloops/schemas/implementation-callback.schema.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ImplementationCallback",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "orchestrator_thread_id", "source_thread_id", "phase_issue_id", "status", "branch", "pr", "commits", "turn_doc", "local_gates", "changed_files", "blockers", "context_to_keep"],
+  "properties": {
+    "type": { "const": "implementation-callback" },
+    "orchestrator_thread_id": { "type": "string", "minLength": 1 },
+    "source_thread_id": { "type": "string", "minLength": 1 },
+    "phase_issue_id": { "type": "string" },
+    "status": { "enum": ["pr-ready", "blocked"] },
+    "branch": { "type": ["string", "null"] },
+    "pr": { "type": ["string", "null"] },
+    "commits": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "turn_doc": { "type": "string" },
+    "local_gates": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "changed_files": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "blockers": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "context_to_keep": {
+      "type": "array",
+      "maxItems": 5,
+      "items": { "type": "string" }
+    }
+  }
+}

package/skills/dirtyloops/schemas/review-callback.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ReviewCallback",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["type", "orchestrator_thread_id", "source_thread_id", "phase_issue_id", "status", "pr", "ci_state", "review_skill", "repairs", "findings_remaining", "turn_doc", "context_to_keep"],
+  "properties": {
+    "type": { "const": "review-callback" },
+    "orchestrator_thread_id": { "type": "string", "minLength": 1 },
+    "source_thread_id": { "type": "string", "minLength": 1 },
+    "phase_issue_id": { "type": "string" },
+    "status": { "enum": ["approved", "repaired", "blocked"] },
+    "pr": { "type": ["string", "null"] },
+    "ci_state": {
+      "enum": ["ci-green", "ci-repaired-and-green", "ci-unavailable-with-evidence", "ci-blocked-with-cause"]
+    },
+    "review_skill": {
+      "const": "thermo-nuclear-code-quality-review"
+    },
+    "repairs": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "findings_remaining": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "turn_doc": { "type": "string" },
+    "context_to_keep": {
+      "type": "array",
+      "maxItems": 5,
+      "items": { "type": "string" }
+    }
+  }
+}

package/skills/dirtyloops/schemas/swarm-report.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "SwarmReport",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["mission", "slice_id", "status", "scope_checked", "findings", "recommendations", "artifacts", "context_to_keep"],
+  "properties": {
+    "mission": { "enum": ["selector", "scout", "slice-plan", "implementation-helper", "review", "ci", "storyboard"] },
+    "slice_id": { "type": ["string", "null"] },
+    "status": { "enum": ["ready", "blocked", "risk-found", "done"] },
+    "scope_checked": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["severity", "evidence", "summary", "recommendation"],
+        "properties": {
+          "severity": { "enum": ["high", "medium", "low", "info"] },
+          "evidence": { "type": "string" },
+          "summary": { "type": "string" },
+          "recommendation": { "type": "string" }
+        }
+      }
+    },
+    "recommendations": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "artifacts": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "context_to_keep": {
+      "type": "array",
+      "maxItems": 5,
+      "items": { "type": "string" }
+    }
+  }
+}

package/skills/dirtyloops/templates/common/00-roadmap.md.template

@@ -0,0 +1,33 @@
+# {{STREAM_NAME}} Roadmap
+
+Canonical tracker: Beads epic `{{EPIC_ID}}`
+
+## Plan Source
+
+{{PLAN_SOURCE}}
+
+## Outcome
+
+{{STREAM_GOAL}}
+
+## Phase Sequence
+
+{{PHASE_SEQUENCE}}
+
+## Dependencies
+
+{{DEPENDENCY_NOTES}}
+
+## Risks
+
+{{KNOWN_RISKS}}
+
+## Quality Gates
+
+{{QUALITY_GATES}}
+
+## Closeout
+
+The final closeout artifact is:
+
+`docs/implementation/{{STREAM_SLUG}}/storyboard-post-run-{{MM_DD_YYYY}}.html`

package/skills/dirtyloops/templates/common/IMPLEMENT.md.template

@@ -0,0 +1,79 @@
+# {{STREAM_NAME}} Implementation Loop
+
+Workflow: `{{WORKFLOW}}`
+
+Canonical tracker: Beads epic `{{EPIC_ID}}`
+
+This stream is driven by Beads. These docs are execution context and resume aids. If Beads and these docs disagree, Beads wins.
+
+## Goal
+
+{{STREAM_GOAL}}
+
+## Sources Of Truth
+
+- Beads epic: `{{EPIC_ID}}`
+- Beads loop metadata: workflow, run policy, branch/PR policy, quality gates, callback/thread defaults, and swarm policy
+- Roadmap: `docs/implementation/{{STREAM_SLUG}}/00-roadmap.md`
+- Loop state mirror: `docs/implementation/{{STREAM_SLUG}}/loop-state.md`
+- Phase docs linked from Beads child issues
+- Turn docs: `docs/implementation/{{STREAM_SLUG}}/turn-docs/`
+
+## Loop Rules
+
+- Select exactly one next ready Beads child issue.
+- Read the linked phase doc before editing.
+- Continue phase-by-phase by default until the epic is complete, blocked, interrupted, or review/CI is unresolved.
+- Use `run once` / `--once` only when intentionally running one phase and stopping after closeout.
+- Keep one active implementation PR at a time unless Beads and the phase doc explicitly allow parallel work.
+- File Beads follow-ups instead of widening the selected phase.
+- Update Beads first, then update `loop-state.md`.
+- Use the workflow's required subagent swarms.
+- Worker and reviewer threads default to standard speed/reasoning unless Beads loop metadata explicitly overrides it.
+
+## Review And CI
+
+Reviewer agents must use:
+
+`thermo-nuclear-code-quality-review`
+
+Reviewer and CI verification agents own CI.
+
+Allowed CI closeout states:
+
+- `ci-green`
+- `ci-repaired-and-green`
+- `ci-unavailable-with-evidence`
+- `ci-blocked-with-cause`
+
+## Turn Docs
+
+Each phase has exactly one Markdown turn doc:
+
+`docs/implementation/{{STREAM_SLUG}}/turn-docs/{{PHASE_ID}}.md`
+
+Implementation, review, CI, repairs, PR state, Beads updates, follow-ups, and closeout all go into the same doc.
+
+## Storyboard
+
+When the epic is complete, generate:
+
+`docs/implementation/{{STREAM_SLUG}}/storyboard-post-run-{{MM_DD_YYYY}}.html`
+
+Use `impeccable` when present. If missing, continue without it and note that it was skipped.
+
+Install `@pierre/diffs` in the target repo if missing. Every diff must use `@pierre/diffs/ssr`.
+
+## Phase Ledger
+
+| Beads Issue | Phase | Phase Doc | Depends On | Status |
+|---|---|---|---|---|
+{{PHASE_LEDGER_ROWS}}
+
+## Quality Gates
+
+{{QUALITY_GATES}}
+
+## Branch And PR Policy
+
+{{BRANCH_PR_POLICY}}

package/skills/dirtyloops/templates/common/loop-state.md.template

@@ -0,0 +1,39 @@
+# Loop State
+
+Canonical tracker: Beads epic `{{EPIC_ID}}`
+
+This file is a compact resume aid only. If this file disagrees with Beads, Beads wins.
+
+Status: active
+
+Stream: `{{STREAM_SLUG}}`
+
+Workflow: `{{WORKFLOW}}`
+
+Current phase: none
+
+Current Beads issue: none
+
+Current PR: none
+
+Last completed phase: none
+
+Blocked: no
+
+## Decisions
+
+{{INITIAL_DECISIONS}}
+
+## Context To Keep
+
+{{INITIAL_CONTEXT_TO_KEEP}}
+
+## Phase Ledger
+
+| Phase | Beads Issue | Status | PR | Turn Doc |
+|---|---|---|---|---|
+{{PHASE_STATE_ROWS}}
+
+## Last Coordinator Update
+
+Not started.

package/skills/dirtyloops/templates/common/phase.md.template

@@ -0,0 +1,56 @@
+# Phase {{PHASE_NUMBER}}: {{PHASE_TITLE}}
+
+Canonical Beads issue: `{{PHASE_ISSUE_ID}}`
+
+Epic: `{{EPIC_ID}}`
+
+Status is tracked in Beads. This doc is implementation context.
+
+## Outcome
+
+{{PHASE_OUTCOME}}
+
+## Scope
+
+Allowed:
+
+{{PHASE_ALLOWED_SCOPE}}
+
+Out of scope:
+
+{{PHASE_OUT_OF_SCOPE}}
+
+## Inputs
+
+{{PHASE_INPUTS}}
+
+## Implementation Notes
+
+{{PHASE_IMPLEMENTATION_NOTES}}
+
+## Beads
+
+- Epic: `{{EPIC_ID}}`
+- Issue: `{{PHASE_ISSUE_ID}}`
+- Depends on: `{{PHASE_DEPENDENCY_IDS}}`
+- Parallel-safe: `{{PHASE_PARALLEL_SAFE}}`
+
+## Expected Files Or Areas
+
+{{EXPECTED_FILES_OR_AREAS}}
+
+## Suggested Swarms
+
+{{PHASE_SWARM_GUIDANCE}}
+
+## Quality Gates
+
+{{PHASE_QUALITY_GATES}}
+
+## Completion Criteria
+
+{{PHASE_COMPLETION_CRITERIA}}
+
+## Follow-Up Policy
+
+Do not widen this phase. File Beads follow-ups for adjacent discoveries.

package/skills/dirtyloops/templates/common/run-loop.md.template

@@ -0,0 +1,46 @@
+# Run Loop: {{STREAM_NAME}}
+
+Workflow: `{{WORKFLOW}}`
+
+Canonical tracker: Beads epic `{{EPIC_ID}}`
+
+Start from:
+
+- Beads epic: `{{EPIC_ID}}`
+- Beads loop metadata on the epic
+- Implementation index: `docs/implementation/{{STREAM_SLUG}}/IMPLEMENT.md`
+- Resume aid: `docs/implementation/{{STREAM_SLUG}}/loop-state.md`
+
+## Rules
+
+- Beads is canonical.
+- Select exactly one next ready Beads child issue.
+- Continue phase-by-phase by default until the epic is complete, blocked, interrupted, or review/CI is unresolved.
+- Stop after one phase only when this run explicitly says `run once` or `--once`.
+- Read the linked phase doc before editing.
+- Keep one active implementation PR at a time unless Beads and the phase doc explicitly allow parallel work.
+- Use the workflow's required large bounded subagent swarms.
+- Reviewer agents must use `thermo-nuclear-code-quality-review`.
+- Reviewer and CI verification agents own CI.
+- Worker and reviewer threads default to standard speed/reasoning unless Beads loop metadata explicitly overrides it.
+- Update the existing Markdown turn doc.
+- Update Beads first, then update `loop-state.md`.
+- Do not widen the selected phase.
+
+## Workflow Addendum
+
+{{WORKFLOW_ADDENDUM}}
+
+## Stream Completion
+
+When the Beads epic is complete:
+
+1. Verify every phase has a Markdown turn doc.
+2. Generate `docs/implementation/{{STREAM_SLUG}}/storyboard-post-run-{{MM_DD_YYYY}}.html`.
+3. Use `impeccable` when present. If missing, continue and note that it was skipped.
+4. Install `@pierre/diffs` in the target repo if missing, then render every diff with `@pierre/diffs/ssr`.
+5. Verify the storyboard.
+
+## Start Prompt
+
+{{CUSTOM_RUN_PROMPT}}

package/skills/dirtyloops/templates/common/storyboard-post-run.html.template

@@ -0,0 +1,77 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{STREAM_NAME}} Post-Run Storyboard</title>
+  <meta name="description" content="Implementation storyboard for {{STREAM_NAME}}">
+  <style>
+    /*
+      Starter only. The final document should be generated with the impeccable
+      skill when present and adapted to the target repo. If impeccable is
+      missing, note that it was skipped. Every diff must be rendered
+      server-side with @pierre/diffs/ssr.
+    */
+    :root {
+      color-scheme: dark;
+      --bg: oklch(0.14 0.03 265);
+      --ink: oklch(0.95 0.01 260);
+      --muted: oklch(0.76 0.03 260);
+      --accent: oklch(0.76 0.16 170);
+      --surface: oklch(0.2 0.04 265);
+      --line: oklch(0.33 0.04 265);
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      background: var(--bg);
+      color: var(--ink);
+      line-height: 1.5;
+    }
+    main {
+      width: min(1120px, calc(100% - 32px));
+      margin: 0 auto;
+      padding: 64px 0;
+    }
+    h1, h2, h3 {
+      text-wrap: balance;
+      letter-spacing: -0.02em;
+    }
+    p {
+      max-width: 72ch;
+      text-wrap: pretty;
+      color: var(--muted);
+    }
+    .storyboard-shell { display: grid; gap: 48px; }
+    .phase {
+      border: 1px solid var(--line);
+      border-radius: 16px;
+      padding: 24px;
+      background: var(--surface);
+    }
+    .diff-scene {
+      overflow: auto;
+      border-radius: 12px;
+      border: 1px solid var(--line);
+    }
+    @media (prefers-reduced-motion: no-preference) {
+      .phase { animation: rise 700ms cubic-bezier(.16, 1, .3, 1) both; }
+      @keyframes rise {
+        from { opacity: .001; transform: translateY(16px); }
+        to { opacity: 1; transform: translateY(0); }
+      }
+    }
+  </style>
+</head>
+<body>
+  <main class="storyboard-shell">
+    <header>
+      <p>{{STORYBOARD_DATE}}</p>
+      <h1>{{STREAM_NAME}}</h1>
+      <p>{{STORYBOARD_DECK}}</p>
+    </header>
+    {{PHASE_STORY_SECTIONS}}
+  </main>
+</body>
+</html>

package/skills/dirtyloops/templates/common/turn-doc.md.template

@@ -0,0 +1,61 @@
+# Phase {{PHASE_NUMBER}} Turn Doc: {{PHASE_TITLE}}
+
+Beads issue: `{{PHASE_ISSUE_ID}}`
+
+Phase doc: `docs/implementation/{{STREAM_SLUG}}/{{PHASE_DOC_FILENAME}}`
+
+This is the single Markdown turn doc for the phase.
+
+## Phase Selection
+
+{{PHASE_SELECTION}}
+
+## Scope
+
+{{PHASE_SCOPE_SUMMARY}}
+
+## Implementation Log
+
+{{IMPLEMENTATION_LOG}}
+
+## Subagent Swarms
+
+{{SUBAGENT_SWARM_SUMMARY}}
+
+## Review
+
+Reviewer skill:
+
+`thermo-nuclear-code-quality-review`
+
+{{REVIEW_NOTES}}
+
+## CI And Gates
+
+CI owner: reviewer/verification agents
+
+Current CI state: `{{CI_STATE}}`
+
+Evidence:
+
+{{CI_EVIDENCE}}
+
+## PR And Commits
+
+{{PR_AND_COMMITS}}
+
+## Beads Updates
+
+{{BEADS_UPDATES}}
+
+## Follow-Ups Filed
+
+{{FOLLOW_UPS_FILED}}
+
+## Context To Keep
+
+{{CONTEXT_TO_KEEP}}
+
+## Closeout
+
+{{PHASE_CLOSEOUT}}