@dirtydishes/skills 0.1.1

package/skills/dirtyloops/references/beads.md

@@ -0,0 +1,114 @@
+# Beads
+
+Beads is the canonical tracker for dirtyloops.
+
+## Before Mutating Beads
+
+Inspect the local Beads command surface:
+
+```sh
+bd --help
+bd create --help
+bd update --help
+bd show --help
+```
+
+Inspect dependency commands if present:
+
+```sh
+bd dep --help
+```
+
+Use only commands supported by the installed version.
+
+## Create Loop State
+
+For a new loop:
+
+- create or identify one epic
+- create one child issue per phase
+- link each child issue to its phase doc
+- add dependencies matching the plan
+- record loop metadata on the epic
+- record phase execution metadata on each child issue
+- record quality gates and PR policy in issue text or supported metadata
+
+If `bd create` does not support parent assignment in the same command, create the issue first and update parent/dependencies in separate supported commands.
+
+## Loop Metadata
+
+Use supported Beads metadata/design/body fields to store typed dirtyloop metadata. Prefer metadata when the installed Beads version supports it; otherwise store a clearly labelled JSON block in the epic design or description.
+
+Epic metadata must include:
+
+```json
+{
+  "dirtyloop_version": 1,
+  "workflow": "single-thread-subagent|orchestrator-callback",
+  "stream_slug": "...",
+  "doc_root": "docs/implementation/<stream>",
+  "run_policy": "until-complete",
+  "once_mode": false,
+  "branch_pr_policy": "...",
+  "quality_gates": ["..."],
+  "thread_defaults": {
+    "implementation": { "speed": "standard" },
+    "review": { "speed": "standard" }
+  }
+}
+```
+
+For `orchestrator-callback`, add:
+
+```json
+{
+  "callback_policy": {
+    "requires_concrete_orchestrator_thread_id": true,
+    "requires_source_thread_id": true,
+    "heartbeat_after_minutes": 30,
+    "polling": "fallback-only"
+  }
+}
+```
+
+For `single-thread-subagent`, add:
+
+```json
+{
+  "swarm_policy": {
+    "mode": "mass-subagent",
+    "min_parallel_agents": 8,
+    "target_scout_agents": "8-20",
+    "target_slice_agents": "8-16",
+    "target_implementation_helper_agents": "8-16",
+    "target_review_agents": "8-20",
+    "target_ci_agents": "4-12",
+    "requires_slice_plan_before_implementation": true,
+    "coordinator_direct_implementation": "integration-only"
+  }
+}
+```
+
+Phase metadata must include phase number, phase doc, turn doc, completion criteria, quality gates, branch/PR instructions, and either callback target data or swarm slice policy for the selected workflow.
+
+## Selection
+
+Pick the next phase from Beads, not from the doc list. Prefer a command such as:
+
+```sh
+bd ready
+bd show <epic-id> --deps
+bd show <phase-id>
+```
+
+If Beads is unavailable but `.beads/issues.jsonl` is checked in, use that only as a read-only routing fallback and report the degraded state.
+
+## Export
+
+When this repo tracks `.beads/issues.jsonl`, refresh it after Beads mutations using the local supported export command. In the user's current Beads installations this is commonly:
+
+```sh
+bd export -o .beads/issues.jsonl
+```
+
+Do not assume `bd sync` exists.

package/skills/dirtyloops/references/common.md

@@ -0,0 +1,66 @@
+# Common Contract
+
+These rules apply to every dirtyloop workflow.
+
+## Authority
+
+Beads is canonical for:
+
+- phase status
+- issue ownership
+- ordering
+- dependencies
+- blockers
+- completion
+
+Implementation docs are context. If Beads and docs disagree, report the mismatch and trust Beads.
+
+## Repo Layout
+
+Create or use:
+
+```text
+docs/implementation/<stream>/
+  IMPLEMENT.md
+  00-roadmap.md
+  <phase-docs>.md
+  loop-state.md
+  turn-docs/
+  prompts/
+  schemas/
+```
+
+`loop-state.md` is a compact resume aid, not the source of truth.
+
+All generated paths inside loop docs, prompts, examples, and callback payloads must be repo-relative. Do not include user-specific home directories or usernames in generated loop artifacts.
+
+## Workflow Invariants
+
+- Keep one active implementation PR at a time unless Beads and the phase doc explicitly allow parallel work.
+- Select exactly one next ready phase.
+- Read the linked phase doc before editing.
+- File follow-ups instead of widening a phase.
+- Update Beads first, then mirror compact state into `loop-state.md`.
+- Do not mark a phase complete while review or CI is unresolved.
+
+## Review Skill And Storyboard Policy
+
+Reviewer agents use:
+
+`thermo-nuclear-code-quality-review`
+
+Post-run storyboard generation should use:
+
+`impeccable`
+
+If the `impeccable` skill is not found, continue the storyboard step without it. Add a brief note to the closeout and storyboard saying `impeccable` was not found and was skipped for the storyboard step.
+
+## Storyboard Diff Rule
+
+Closeout must install `@pierre/diffs` in the target repo when missing, using the repo's package manager and normal dependency style.
+
+All storyboard diffs must use:
+
+`@pierre/diffs/ssr`
+
+SSR is required for every diff block.

package/skills/dirtyloops/references/create-loop.md

@@ -0,0 +1,85 @@
+# Create Loop
+
+Use this branch when turning a finalized plan into a Beads-canonical implementation loop.
+
+## Inputs
+
+Use the immediately preceding finalized plan in the conversation unless the user provides a plan path.
+
+Required:
+
+- repo root
+- stream slug
+- epic title
+- workflow
+- run policy
+- thread defaults
+- callback policy for `orchestrator-callback`
+- swarm policy for `single-thread-subagent`
+- quality gates
+- branch/PR policy
+
+If required inputs are missing and cannot be inferred safely, ask one concise question before writing files.
+
+Ask only for missing decisions. Prefer these defaults when the user has not specified otherwise:
+
+- run policy: continue until epic complete, blocked, interrupted, or review/CI unresolved
+- one-shot mode: off unless the user says `run once` or `--once`
+- worker/reviewer speed: standard
+- orchestrator-callback heartbeat: 30 minutes, fallback-only polling
+- single-thread-subagent swarm mode: mass-subagent, minimum 8 parallel agents for broad scout/slice/review work
+
+## Steps
+
+1. Inspect the repo.
+   - Confirm the repo root.
+   - Check existing `docs/implementation/`.
+   - Check Beads availability and command surface.
+   - Completion criterion: you know whether this is a new stream or an update to an existing stream.
+
+2. Normalize the plan into phases.
+   - Each phase gets outcome, scope, out-of-scope, inputs, quality gates, dependencies, and completion criteria.
+   - Prefer focused phases and file follow-ups for adjacent work.
+   - Completion criterion: every plan requirement maps to one phase or an explicit follow-up.
+
+3. Normalize loop metadata.
+   - Record workflow, run policy, branch/PR policy, quality gates, and thread defaults.
+   - For `orchestrator-callback`, record callback policy: concrete orchestrator thread id required in prompts and callback payloads, source thread id required in callback payloads, heartbeat interval, and fallback-only polling.
+   - For `single-thread-subagent`, record swarm policy: mass-subagent mode, minimum parallel agents, scout/slice/implementation-helper/review/CI swarm sizes, mandatory slice plan before implementation, and coordinator-direct-implementation limits.
+   - Completion criterion: the loop can be validated from Beads metadata before any worker, reviewer, or broad implementation work starts.
+
+4. Create Beads state.
+   - Create or update the epic.
+   - Create child phase issues.
+   - Add dependencies.
+   - Link child issues to phase docs.
+   - Store loop metadata on the epic and phase execution metadata on child issues using supported Beads metadata/design/body fields.
+   - Refresh checked-in Beads export when applicable.
+   - Completion criterion: Beads can route the next ready phase without consulting chat.
+
+5. Create repo docs.
+   - Use templates under `templates/common/` plus the selected workflow template.
+   - Create `IMPLEMENT.md`, `00-roadmap.md`, phase docs, `loop-state.md`, `turn-docs/`, `prompts/`, and `schemas/`.
+   - Treat docs as generated execution views of Beads state. If Beads and docs disagree, Beads wins.
+   - Use repo-relative paths inside generated docs and prompts.
+   - Do not include user-specific home directories or usernames in generated artifacts.
+   - Completion criterion: the generated docs are enough to run the loop without the original chat.
+
+6. Generate the run prompt.
+   - Save it as `docs/implementation/<stream>/prompts/run-loop.md`.
+   - Include the selected workflow name.
+   - Include Beads epic id, run policy, phase-doc location, turn-doc rules, review skill, CI ownership, thread defaults, callback/slice preflight rules, and storyboard requirements.
+   - Completion criterion: the user can paste the generated prompt into Codex to start the loop.
+
+## Output Contract
+
+End with:
+
+- files created
+- Beads epic id
+- Beads phase issue ids
+- generated run prompt path
+- exact customized run prompt
+- any blockers or degraded Beads operations
+
+Do not start the implementation loop unless the user explicitly asks.

package/skills/dirtyloops/references/help.md

@@ -0,0 +1,170 @@
+# Help
+
+Use this branch when the user asks how to use `$dirtyloops`, what workflows exist, or what command to run next.
+
+Do not mutate files, Beads, branches, PRs, or threads while answering help.
+
+## What dirtyloops Does
+
+`$dirtyloops` turns a finalized plan into a Beads-canonical implementation loop and can then run, inspect, or close that loop.
+
+Every dirtyloop uses:
+
+- Beads as canonical tracker
+- typed loop metadata on Beads for workflow, run policy, callback policy, thread defaults, swarm policy, quality gates, and branch/PR policy
+- phase docs linked from Beads child issues
+- repo-relative paths in generated docs and prompts
+- one Markdown turn doc per phase
+- bounded subagent swarms
+- reviewer-owned CI
+- `thermo-nuclear-code-quality-review` for reviewers
+- `storyboard-post-run-mm-dd-yyyy.html` for final closeout
+- `impeccable` for the storyboard when available
+- automatic target-repo installation of `@pierre/diffs` when missing
+- `@pierre/diffs/ssr` for every storyboard diff
+
+## Commands
+
+### `$dirtyloops help`
+
+Explain usage. This command is read-only.
+
+### `$dirtyloops create <workflow>`
+
+Turn the finalized plan into a loop.
+
+Required inputs:
+
+- repo path
+- stream slug
+- epic title
+- workflow
+- run policy
+- thread defaults
+- quality gates
+- branch/PR policy
+
+Example:
+
+```text
+$dirtyloops create orchestrator-callback from the finalized plan above
+
+Repo: .
+Stream slug: smart-flow-alerts
+Epic title: Smart-flow alerts migration
+Quality gates: bun test, bun run typecheck, targeted browser QA
+Branch/PR policy: one active implementation PR at a time
+```
+
+Output:
+
+- Beads epic and child phase issues
+- `docs/implementation/<stream>/IMPLEMENT.md`
+- `00-roadmap.md`
+- phase docs
+- `loop-state.md`
+- `turn-docs/`
+- workflow prompts
+- schemas
+- `docs/implementation/<stream>/prompts/run-loop.md`
+
+### `$dirtyloops run <workflow>`
+
+Run an existing loop until the epic is complete, blocked, interrupted, or review/CI is unresolved.
+
+Use `run once` or `--once` to run only the next ready phase and stop after closeout.
+
+Example:
+
+```text
+$dirtyloops run single-thread-subagent
+
+Repo: .
+Stream: docs/implementation/smart-flow-alerts/
+Beads epic: islandflow-ghce
+```
+
+### `$dirtyloops inspect`
+
+Read Beads and loop docs without mutation. Use this when resuming a loop or checking whether it is blocked.
+
+### `$dirtyloops closeout`
+
+Verify the epic is complete, then generate the post-run storyboard.
+
+If `impeccable` is missing, closeout still completes and records that the skill was skipped. If `@pierre/diffs` is missing from the target repo, closeout installs it before rendering diffs.
+
+## Workflows
+
+### `single-thread-subagent`
+
+Use this when you want one visible Codex coordinator thread with mass subagent swarms.
+
+Shape:
+
+```text
+main coordinator thread
+  -> selector/scout/slice/implementation-helper/reviewer/CI subagents
+  -> coordinator synthesizes and integrates
+  -> coordinator closeout
+```
+
+Use it for CLI-friendly or context-controlled loops where separate callback threads are not desired. Single-thread means one visible coordinator, not solo implementation; broad phases should use 8+ subagents and a slice plan before implementation.
+
+### `orchestrator-callback`
+
+Use this for the original multi-thread loop.
+
+Shape:
+
+```text
+orchestrator thread
+  -> selector subagent
+  -> implementation thread
+  -> implementation callback when PR-ready
+  -> review thread
+  -> review callback when review + CI are resolved
+  -> orchestrator closeout
+  -> next selector
+```
+
+Only the orchestrator creates implementation and review threads. Worker threads do not create review threads. Worker and reviewer prompts must contain the concrete orchestrator thread id as callback target.
+
+## Which Workflow Should I Pick?
+
+Pick `orchestrator-callback` when:
+
+- you want separate visible worker/reviewer threads
+- the work is long-running
+- implementation and review should happen in distinct contexts
+- you want callback-driven orchestration
+
+Pick `single-thread-subagent` when:
+
+- you want one visible thread
+- you are running in a CLI-friendly style
+- you want less thread management
+- you want mass internal subagent swarms without separate visible worker/reviewer threads
+
+## Examples And Plan
+
+Human-readable overview:
+
+`plan.html`
+
+Generated output examples:
+
+- `examples/single-thread-subagent/`
+- `examples/orchestrator-callback/`
+
+## Good Help Answer Shape
+
+When answering `$dirtyloops help`, lead with:
+
+1. one sentence explaining dirtyloops
+2. the two workflows
+3. the create/run commands
+4. the decision rule for workflow choice
+5. links to `plan.html` and examples
+
+Keep it practical. Do not dump every internal rule unless the user asks.

package/skills/dirtyloops/references/inspect-loop.md

@@ -0,0 +1,11 @@
+# Inspect Loop
+
+Use this branch to report dirtyloop state without changing files, Beads, branches, PRs, or threads.
+
+## Steps
+
+1. Read `IMPLEMENT.md`, `loop-state.md`, and Beads state.
+2. Compare docs against Beads.
+3. Report current phase, ready phase candidates, active PR/thread state if recorded, blockers, and next recommended action.
+
+Completion criterion: the user can see whether the loop is ready to run, blocked, or complete.

package/skills/dirtyloops/references/review-ci.md

@@ -0,0 +1,37 @@
+# Review And CI
+
+Review and CI are owned by reviewer and CI verification agents, not by a passive coordinator.
+
+## Review Skill
+
+Every reviewer agent must use:
+
+`thermo-nuclear-code-quality-review`
+
+The review bar is structural: simplification, abstraction quality, spaghetti growth, wrong-layer logic, file-size blowups, unnecessary wrappers, type looseness, and canonical-helper duplication are real blockers when they affect maintainability.
+
+## CI Ownership
+
+Reviewer and CI verification agents own:
+
+- CI inspection
+- CI failure diagnosis
+- safe repairs when assigned
+- reruns
+- final CI evidence
+- turn-doc updates for review and CI
+
+The coordinator must not close a phase while CI is unknown, failing, or still running.
+
+Allowed CI closeout states:
+
+- `ci-green`
+- `ci-repaired-and-green`
+- `ci-unavailable-with-evidence`
+- `ci-blocked-with-cause`
+
+Unknown CI is not approval.
+
+## Existing Turn Doc
+
+Reviewers and CI agents update the existing phase turn doc. They do not create a separate review or CI doc.

package/skills/dirtyloops/references/run-loop.md

@@ -0,0 +1,41 @@
+# Run Loop
+
+Use this branch to execute an existing dirtyloop. Continue phase-by-phase by default until the epic is complete, blocked, interrupted, or review/CI is unresolved. If the user requested `run once` or `--once`, run only the next ready phase and stop after closeout.
+
+## Steps
+
+1. Read Beads.
+   - Inspect the epic and ready child issues.
+   - Read dirtyloop metadata from the epic and phase execution metadata from the selected child issue.
+   - Completion criterion: the next ready Beads issue, run policy, workflow, thread defaults, and callback/slice policy are known; or a concrete blocker is known.
+
+2. Read the execution context.
+   - Read `IMPLEMENT.md`.
+   - Read `loop-state.md`.
+   - Read the linked phase doc.
+   - Completion criterion: selected scope, dependencies, gates, and workflow are known.
+
+3. Validate launch preflight.
+   - For `orchestrator-callback`, require a concrete orchestrator thread id before launching workers/reviewers. The actual worker/reviewer prompt text must name that exact id as the callback target and must not rely on phrases like `current orchestrator thread`, `this thread`, or `source thread wrapper`.
+   - For `orchestrator-callback`, require worker/reviewer thread defaults to be explicit, defaulting to standard speed/reasoning when metadata does not override it.
+   - For `single-thread-subagent`, require a mass-subagent slice/scout plan before broad implementation. The coordinator may perform integration and final repairs, but it must not do most broad discovery or implementation itself.
+   - Completion criterion: the workflow can start without relying on inherited thread settings, vague callback targets, or solo coordinator implementation.
+
+4. Run the selected workflow.
+   - Follow the selected workflow reference.
+   - Use required swarms for the workflow.
+   - Keep implementation to exactly one phase.
+   - Completion criterion: the workflow reaches PR-ready, approved, repaired, blocked, or stream-complete state.
+
+5. Close out the phase.
+   - Update the existing turn doc.
+   - Update Beads first.
+   - Record lifecycle events or notes for worker launch, callbacks, review launch, CI state, phase closeout, and next phase selection when supported by Beads.
+   - Refresh Beads export when applicable.
+   - Update `loop-state.md`.
+   - Completion criterion: Beads and docs agree on the phase state.
+
+6. Continue or stop.
+   - Default: select the next ready Beads child issue and continue the loop.
+   - Stop when the epic is complete, blocked, interrupted, review/CI is unresolved, or the user requested `run once` / `--once`.
+   - Completion criterion: final response includes the current phase, PR/CI state, Beads updates, whether the loop continued or stopped, and the exact stop reason when stopped.

package/skills/dirtyloops/references/storyboard.md

@@ -0,0 +1,64 @@
+# Storyboard Closeout
+
+Use this branch when the Beads epic is complete or ready to close.
+
+## Artifact
+
+Generate:
+
+```text
+docs/implementation/<stream>/storyboard-post-run-mm-dd-yyyy.html
+```
+
+Use the actual current date for the filename.
+
+## Storyboard Skill
+
+Use when available:
+
+`impeccable`
+
+If the `impeccable` skill exists, follow that skill's setup before designing or generating the storyboard.
+
+If the `impeccable` skill is not found, continue without it. Add a brief note to the closeout and inside the storyboard saying `impeccable` was not found and was skipped for the storyboard step.
+
+## Required Diff Renderer
+
+Every diff block must use:
+
+`@pierre/diffs/ssr`
+
+SSR is required. Do not hand-roll diff rendering. Do not use a client-only diff renderer.
+
+If `@pierre/diffs` is missing, install it in the target repo before generating the storyboard. Inspect the repo package manager and add it in the repo's normal style. Do not substitute another diff renderer.
+
+## Inputs
+
+- Beads epic and child issues
+- every Markdown turn doc
+- phase docs
+- PRs and commits
+- review findings and repairs
+- CI evidence
+- follow-ups
+
+## Narrative
+
+Tell the story of the implementation. Avoid a rigid status template.
+
+Include:
+
+- setup
+- each phase's arc
+- important snippets
+- discoveries
+- failed attempts
+- repairs
+- review moments
+- CI evidence
+- final state
+- follow-ups
+
+## Completion Criterion
+
+The storyboard exists, has been visually/technically verified, includes all phases, installs `@pierre/diffs` if it was missing, and uses `@pierre/diffs/ssr` for every diff.

package/skills/dirtyloops/references/swarms.md

@@ -0,0 +1,59 @@
+# Swarms
+
+dirtyloops use bounded swarms. Fan out aggressively when the phase has broad surface area, shared architecture, CI risk, or user-facing behavior. In `single-thread-subagent`, mass subagent work is mandatory for broad phases: the visible coordinator orchestrates, synthesizes, integrates, and closes out; subagents do much of the discovery, slicing, implementation analysis, review, and CI verification.
+
+## Default Sizes
+
+- 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
+- storyboard synthesis swarm: 3-8 agents
+
+For `single-thread-subagent`, use at least 8 parallel agents before broad implementation unless the phase is explicitly tiny. If fewer than 8 agents are used, record the reason in the turn doc.
+
+## Bounds
+
+Each subagent gets:
+
+- one mission
+- explicit files, commands, or questions
+- no loop-state ownership
+- no Beads mutation unless explicitly assigned
+- no implementation unless explicitly assigned to an implementation slice
+- compact structured output
+- max 5 context facts to retain
+
+## Slice Planning
+
+For non-trivial `single-thread-subagent` phases, run a slice planning swarm before implementation. Slices should be bounded by module, file group, workflow, test surface, or risk area.
+
+The coordinator must synthesize the slice reports before broad edits. Direct coordinator implementation is limited to integration, glue, conflict resolution, final repairs, and Beads/PR state.
+
+## Report Shape
+
+Use compact reports:
+
+```json
+{
+  "mission": "scout|slice-plan|implementation-helper|review|ci|storyboard",
+  "slice_id": "string-or-null",
+  "status": "ready|blocked|risk-found|done",
+  "scope_checked": ["..."],
+  "findings": [
+    {
+      "severity": "high|medium|low|info",
+      "evidence": "path:line or command summary",
+      "summary": "...",
+      "recommendation": "..."
+    }
+  ],
+  "recommendations": ["..."],
+  "artifacts": ["repo-relative path, command summary, or patch summary"],
+  "context_to_keep": ["max 5 bullets"]
+}
+```
+
+The coordinator or lead thread synthesizes reports into the turn doc.

package/skills/dirtyloops/references/turn-docs.md

@@ -0,0 +1,29 @@
+# Turn Docs
+
+Turn docs are Markdown. They are the durable narrative log for the loop.
+
+Each phase has exactly one turn doc:
+
+```text
+docs/implementation/<stream>/turn-docs/<phase-id>.md
+```
+
+Implementation, review, CI, repairs, PR state, Beads updates, follow-ups, and closeout all go into that same file.
+
+## Required Sections
+
+Each turn doc should include:
+
+- phase selection
+- scope
+- implementation log
+- subagent swarm summary
+- review
+- CI and gates
+- PR and commits
+- Beads updates
+- follow-ups filed
+- context to keep
+- closeout
+
+The doc can be narrative. It does not need to be rigidly filled out if the information is present and easy to scan.