--- name: dirtyloops description: Create and operate Beads-canonical implementation loops with adaptive or orchestrator-callback ownership profiles. argument-hint: "help|create [adaptive|orchestrator-callback] [for] [codex|pi]|update|convert |run|inspect|closeout" disable-model-invocation: true --- # dirtyloops A dirtyloop is a portable control plane for executing an accepted plan. Planning owns discovery and consequential decisions; dirtyloops validates and materializes the plan, binds it to one harness and one ownership profile, then lets stage owners choose evidence-driven helper missions inside durable state, safety, review, and evidence constraints. ## Steps 1. Parse the command. - `create [adaptive|orchestrator-callback] [for] [codex|pi]`: parse with `scripts/create-command.mjs`, validate an accepted plan, block unsafe execution granularity, and compile it into Beads issues plus project-local execution docs. Omitted profile means `adaptive`; omitted harness means `codex`. Unknown or duplicate tokens fail before mutation. - `update`: migrate an existing loop's generated contract to dirtyloops v2 without rewriting its authored plan or history. - `convert `: transactionally replace the active harness binding and generated run surfaces while preserving protected project state. - `run`: execute ready phases until the epic is complete, blocked, interrupted, review/CI is unresolved, or `--once` is requested. - `inspect`: report current loop state without mutation. - `closeout`: verify completion and generate the post-run storyboard. - `help`: explain the plan-then-create-then-run flow. - Completion criterion: exactly one command is selected. 2. Resolve the harness binding. - `create`: use the explicit harness or default to `codex`. - `convert`: require one destination harness; a missing destination is read-only usage help. - `run` and `inspect`: read the persisted binding; never infer a replacement from the current application. - `update`: historical loops without a binding receive `codex` because dirtyloops v2 was Codex-only when generated. - Completion criterion: the source, destination when applicable, and active binding are explicit. 3. Resolve the execution profile. - `create`: persist the parsed `adaptive` or `orchestrator-callback` profile. - `run`, `inspect`, and `closeout`: read the persisted profile; never reinterpret it from prose. - `update`: preserve an explicit profile. Historical `Workflow: orchestrator-callback` becomes the `orchestrator-callback` profile; other historical loops become `adaptive`. - `convert`: preserve the profile while changing only the harness binding. - Completion criterion: exactly one persisted ownership profile is explicit. 4. Load only the references required by that command. - `help`: read `references/help.md`. - `create`: read `references/common.md`, `references/beads.md`, `references/harness-binding.md`, `references/execution-profiles.md`, `references/create-loop.md`, the selected `references/harnesses/.md`, and only the templates named there. - `update`: also read `references/update-loop.md`; use `scripts/migrate-v2.mjs` for discovery and generated-file migration. - `convert`: read `references/common.md`, `references/beads.md`, `references/harness-binding.md`, `references/convert-loop.md`, and both source and destination harness references. - `run`: read `references/common.md`, `references/beads.md`, `references/harness-binding.md`, `references/execution-profiles.md`, `references/run-loop.md`, `references/delegation.md`, `references/builder-bootstrap.md`, `references/launch-safety.md`, `references/review-ci.md`, `references/turn-docs.md`, and the bound harness reference. - `inspect`: read `references/harness-binding.md`, `references/execution-profiles.md`, and `references/inspect-loop.md`. - `closeout`: read `references/common.md`, `references/beads.md`, `references/execution-profiles.md`, `references/review-ci.md`, `references/turn-docs.md`, and `references/storyboard.md`. - Completion criterion: every command-specific reference is read before mutation or execution. 5. Execute the selected command. - Preserve Beads as canonical. - Preserve accepted intent; dirtyloops may clarify structure but must not invent product or architectural intent. - Enforce the persisted ownership profile. Within it, choose model tier, reasoning effort, helper missions, concurrency, and coordination from phase evidence, runtime capabilities, and user constraints. - Completion criterion: the command reference's completion criterion is satisfied or a concrete blocker is reported. ## Invariants - Beads is canonical for status, ordering, dependencies, blockers, ownership, and completion. - The harness binding is explicit, schema-valid, and mirrored in Beads. Runtime capabilities come from a certified adapter rather than product names or inferred versions. - `create` requires an accepted, decision-complete, implementation-open plan. It validates and materializes; it does not perform open-ended planning. - Phase docs preserve outcomes, constraints, settled decisions, open questions, acceptance evidence, dependencies, replanning triggers, and scope boundaries. They do not prescribe execution topology. - Every executable phase or qualified tracer-bullet Beads leaf passes the bundled execution-readiness audit before `create` materializes or `run` mutates. A leaf projection preserves and hashes its immutable shared phase doc plus the canonical Beads issue; it cannot silently rewrite authored intent. `update` and `convert` report readiness without rewriting authored phase docs. - Generated artifacts use repo-relative paths and never contain user-specific home directories or usernames. - Keep one active external implementation PR at a time unless the accepted plan and Beads explicitly permit more. Parallel internal owner branches may feed that integration PR. - Exactly one actor owns each mutable checkout or branch at a time. - A child that will mutate or review code must start in the intended repo, worktree, and symbolic branch/ref. Wrong environment or detached HEAD is a launch failure, not something the child repairs with `cd`. - Any cross-thread callback target is bound to the concrete run-time orchestrator thread before launch. Never persist a creation-thread callback id as future loop state. - Normal structured completion is callback-driven and uses no status, sleep, or wait polling. Delivery may repeat: persist one logical terminal result, return a replayable acknowledgement for each valid delivery, and apply downstream effects once. Status and recovery actions require an explicit certified reason, durable evidence, and adapter-enforced rate limits. - Degraded completion delivery requires a fresh coordinator renewal at a safe ownership boundary. Adaptive context-pressure renewal records current Beads, turn-doc, PR, branch, checkout, and adapter-observed context evidence without prescribing a fixed lifetime or topology. - The orchestrator records a compact orchestration brief before broad work and may revise it when evidence changes. - Ownership topology follows the persisted profile. `orchestrator-callback` keeps the control thread orchestrator-only and requires separate implementation and review owners with one logical terminal-result identity each. - Implementation and review stages strongly encourage evidence-driven helper fanout, with at most 20 helper missions per stage and active concurrency bounded by user configuration, certified runtime capacity, and available slots. Non-trivial zero-helper stages record a rationale. Never invent an undocumented default limit. - Helper missions and their models, effort, and coordination are adaptive. Do not impose a permanent helper persona catalog or create filler agents to meet a count. - Review must be independent enough to challenge the implementation and must preserve every role named by the accepted phase. Thermonuclear reviewers use `thermo-nuclear-code-quality-review`. Adversarial reviewers must not invoke or consult that skill. - When an accepted phase defines a shared review-repair process, wait for every required role, combine and deduplicate findings, appoint one repair owner, rerun the affected gates and reviewers, and count one pass across the whole review set. Enforce the accepted pass limit and ask the user when it is exhausted. - CI has an explicit owner and must resolve to green, repaired-and-green, unavailable-with-evidence, or blocked-with-cause before phase completion. - Use one Markdown turn doc per phase. Implementation, orchestration decisions, review, CI, repairs, PR state, Beads updates, follow-ups, and closeout share that doc. - File follow-up Beads issues instead of silently widening phase scope. - `run` continues phase-by-phase by default. Stop only when complete, blocked, interrupted, review/CI is unresolved, or `--once` was requested. - `run` never updates, converts, migrates, regenerates, or synchronizes the skill implicitly. An identity mismatch blocks and names the separate repair command. - `update` is conservative: preserve authored phase docs, turn docs, implementation code, branch/PR state, issue state/dependencies, loop history, and storyboards unless the user explicitly authorizes wider migration. - Material `create`, `update`, and `convert` operations install one complete generated contract through `applyGeneratedContractTransaction`; `runtime/generation.json` records deterministic artifact and adapter identity hashes. - Material operations also update mutable `loop-state.md` and `runtime/activation.json` sidecars inside the rollback boundary but outside deterministic generation identity. Pi destinations remain `activation-required` until a different coordinator session proves its captured runtime closure through one acknowledged vanilla completion. Codex destinations are builder-generation-ready because no reloadable Dirtyloops adapter is injected; this state is not runtime-adapter certification. Every run still fails closed unless the chosen strategy's required first-party capabilities are proved. An adaptive direct strategy may proceed without a separate owner adapter after exact coordinator checkout and ownership proof; mutable delegated owners may not. - When an accepted self-upgrade plan declares a certified builder bootstrap, immutable builder certification and mutable fresh-coordinator activation are separate gates after generated activation. Before both gates, mutation remains direct in one prepared coordinator-owned worktree. After them, mutable parallel owners may launch only through the exact certified builder closure. Compare that loaded builder to its frozen release and certificate, never to moving candidate source. Candidate control-plane code never certifies or launches itself. - Keep boundary readiness separate from launch readiness. A well-sliced leaf is not launchable until its exact ID appears in live `bd ready`, its path and interface ownership is concrete, its dependency mirror and generation match, and any required frozen-builder records pass. - `convert` changes only generated harness surfaces and binding metadata. Protected artifacts remain byte-identical, and any failed generation restores the exact pre-conversion files plus Beads metadata. - Closeout generates `storyboard-post-run-mm-dd-yyyy.html`, uses `impeccable` when available, installs `@pierre/diffs` if missing, and renders every diff with `@pierre/diffs/ssr`.