From rune
Orchestrates TDD workflow for code changes: understand → plan → test → implement → quality → verify → commit. Default for features, bug fixes, refactors, hotfixes.
npx claudepluginhub rune-kit/rune --plugin @rune/analyticsThis skill uses the workspace's default tool permissions.
The primary orchestrator for feature implementation. Coordinates the entire L2 mesh in a phased TDD workflow. Handles 70% of all user requests — any task that modifies source code routes through cook.
references/deviation-rules.mdreferences/error-recovery.mdreferences/exit-conditions.mdreferences/loop-detection.mdreferences/mid-run-signals.mdreferences/output-format.mdreferences/pack-detection.mdreferences/pause-resume-template.mdreferences/rfc-template.mdreferences/sharp-edges.mdreferences/subagent-status.mdDrives AI coding agents through gated Spec → Plan → Build → Test → Review → Ship workflow for non-trivial features, refactors, or multi-file projects.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Share bugs, ideas, or general feedback.
The primary orchestrator for feature implementation. Coordinates the entire L2 mesh in a phased TDD workflow. Handles 70% of all user requests — any task that modifies source code routes through cook.
Before starting ANY implementation: 1. You MUST understand the codebase first (Phase 1) 2. You MUST have a plan before writing code (Phase 2) 3. You MUST write failing tests before implementation (Phase 3) — unless explicitly skipped This applies to EVERY feature regardless of perceived simplicity.Cook supports predefined workflow chains for common task types. Use these as shortcuts instead of manually determining phases:
/rune cook feature → Full TDD pipeline (all phases)
/rune cook bugfix → Diagnose → fix → verify (Phase 1 → 4 → 6 → 7)
/rune cook refactor → Understand → plan → implement → quality (Phase 1 → 2 → 4 → 5 → 6 → 7)
/rune cook security → Full pipeline + sentinel@opus + sast (all phases, security-escalated)
/rune cook hotfix → Production Hotfix Protocol: contain → fix → verify → deploy → watchdog → postmortem (see below)
/rune cook nano → Trivial: do → verify → done (no phases, ≤3 steps)
/rune cook --template <name> → Load pre-built workflow template from installed Pro/Business packs
When hotfix chain is active AND triggered from a live incident (not a dev-time fix), follow the full orchestrated chain — not just fix → verify → commit.
FULL HOTFIX CHAIN (when incident is active):
1. CONTAIN → `rune:incident` (if not already running): triage + contain blast radius first
2. BRANCH → create hotfix branch via worktree (isolate from main)
3. FIX → `rune:fix` (minimal change only — no refactoring, no scope creep)
4. VERIFY → `rune:verification` (full test suite on hotfix branch)
5. SENTINEL → `rune:sentinel` (security check — fix may introduce new surface)
6. DEPLOY → `rune:deploy` (deploy hotfix to production)
7. WATCHDOG → `rune:watchdog` (confirm health check passes post-deploy)
8. POSTMORTEM → `rune:journal` + `rune:neural-memory` (capture root cause + fix pattern)
HARD-GATES:
- Do NOT skip CONTAIN if users are actively affected
- Do NOT skip SENTINEL on hotfix — rushed fixes frequently introduce new vulnerabilities
- Do NOT merge hotfix to main without VERIFY passing
- Do NOT skip POSTMORTEM — hotfix without learning = same incident next month
Minimal hotfix chain (non-incident, dev-time): Phase 4 → 6 → 7 (fix → verify → commit). User provides context, skip scout.
When --template <name> is provided, cook loads a pre-built workflow template instead of auto-detecting:
/rune cook --template product-discovery → Pro: stakeholder interviews → problem framing → competitive → spec → validation
/rune cook --template product-launch → Pro: spec lock → implement → quality gates → staged rollout → announcement
/rune cook --template product-iteration → Pro: metrics review → feedback synthesis → re-prioritize → implement → measure
/rune cook --template data-exploration → Pro: data profiling → hypotheses → statistical testing → visualization → report
/rune cook --template data-pipeline → Pro: schema design → ETL → quality gates → deploy → monitoring
/rune cook --template sales-outreach-campaign → Pro: prospect research → messaging → sequence → A/B test → launch
/rune cook --template sales-deal-review → Pro: account deep-dive → risk assessment → competitive strategy → action plan
/rune cook --template support-incident-response → Pro: triage → diagnose → fix → verify → postmortem → KB update
/rune cook --template support-kb-refresh → Pro: audit → gap analysis → draft → review → publish
Template resolution: Templates are .md files in extensions/pro-*/templates/ or extensions/business-*/templates/. Each template defines: phases, skill connections, mesh signals, and acceptance criteria. The compiler includes templates in pack output during build.
When --template is used:
Chain selection: If user invokes /rune cook without a chain type, auto-detect from the task description:
bugfixrefactorsecurityhotfixnanorune:graft (not a cook chain — hand off entirely)--template → load template workflow (see above)featureNot every task needs every phase:
Nano task: DO → VERIFY → DONE (no phases, auto-detected)
Simple bug fix: Phase 1 → 4 → 6 → 7
Small refactor: Phase 1 → 4 → 5 → 6 → 7
New feature: Phase 1 → 1.5 → 2 → 3 → 4 → 5 → 6 → 7 → 8
Complex feature: All phases + brainstorm in Phase 2
Security-sensitive: All phases + sentinel escalated to opus
Fast mode: Phase 1 → 4 → 6 → 7 (auto-detected, see below)
Multi-session: Phase 0 (resume) → 3 → 4 → 5 → 6 → 7 (one plan phase per session)
Determine complexity BEFORE starting using the Rigor Assessment below. Create TodoWrite with applicable phases.
Before selecting a workflow chain or phase set, compute the task's rigor level from risk signals. This prevents over-engineering trivial changes while ensuring full ceremony for critical ones.
| Risk Signal | Weight | Detection |
|---|---|---|
| Files affected: 1 | 0 | Estimate from task description + scout |
| Files affected: 2-3 | +1 | |
| Files affected: 4+ | +3 | |
| Cross-module impact (changes span 2+ directories) | +2 | scout identifies touch points across boundaries |
| Security-sensitive code (auth, crypto, payments, secrets) | +3 | Keyword match in file paths or task description |
| Public API change (exports, routes, schema) | +2 | Task modifies interfaces consumed by external code |
| Database schema change | +2 | Task mentions migration, schema, ALTER, column |
| New dependency added | +1 | Task requires npm install or equivalent |
| Code will be imported by other modules | +1 | New exports or modifications to shared utilities |
Rigor level mapping:
| Score | Level | Maps To | Phases |
|---|---|---|---|
| 0 | Nano | nano chain | DO → VERIFY → DONE |
| 1-2 | Fast | fast mode | Phase 1 → 4 → 6 → 7 |
| 3-5 | Standard | bugfix / refactor | Phase 1 → 2 → 4 → 5 → 6 → 7 |
| 6-8 | Full | feature | Phase 1 → 1.5 → 2 → 3 → 4 → 5 → 6 → 7 → 8 |
| 9+ | Critical | security / full + adversary | All phases + sentinel@opus + adversary |
Rules:
For trivial tasks that don't need any pipeline at all:
IF all of these are true:
- Task is ≤3 discrete steps (e.g., run command, edit 1 file, commit)
- Task description < 60 chars OR user prefixes with "quick:", "just", "chỉ cần"
- No code logic changes (copy files, config edits, version bumps, git ops, run scripts)
- No new functions/classes/components created
THEN: Nano Mode activated
- Execute directly: DO → VERIFY → DONE
- No phases. No plan. No test. No review.
- Still verify output (check exit codes, confirm file exists, etc.)
- Still use semantic commit message if committing
Announce: "Nano mode: trivial task, executing directly." Override: User can say "full pipeline" or "cook feature" to force phases. Escape hatch: If during execution the task turns out more complex than expected → announce upgrade: "Upgrading to Fast/Full mode — task is more complex than detected." Resume from Phase 1.
Nano mode MUST NOT be used for: - Any code that will be imported/called by other code - Security-relevant files (auth, crypto, payments, .env, secrets) - Database schema changes - Public API changes If any of these are detected mid-task, STOP and upgrade to Fast/Full mode.Cook auto-detects small changes and streamlines the pipeline:
IF all of these are true:
- Total estimated change < 30 LOC
- Single file affected
- No security-relevant code (auth, crypto, payments, .env)
- No public API changes
- No database schema changes
THEN: Fast Mode activated
- Skip Phase 2 (PLAN) — change is too small for a formal plan
- Skip Phase 3 (TEST) — unless existing tests cover the area
- Skip Phase 5b (SENTINEL) — non-security code
- Skip Phase 8 (BRIDGE) — not worth persisting
- KEEP Phase 5a (PREFLIGHT) and Phase 6 (VERIFY) — always run quality checks
Announce fast mode: "Fast mode: small change detected (<30 LOC, single file, non-security). Streamlined pipeline." Override: User can say "full pipeline" to force all phases even on small changes.
SUB-SKILL: Use rune:sentinel-env — verify the environment can run the project before planning.
Auto-trigger: no .rune/ dir (first run) OR build just failed with env-looking errors AND NOT fast mode. Skip silently on subsequent runs. Force with /rune env-check.
Goal: Know what exists before changing anything.
REQUIRED SUB-SKILLS: Use rune:scout. For non-trivial tasks, use rune:ba.
in_progressrune:ba. Task > 50 words or business terms (users, revenue, workflow) → invoke rune:ba. Bug Fix / simple Refactor → skip. BA produces .rune/features/<name>/requirements.md for Phase 2. Synthesis-mode auto-trigger: if user pasted a spec > 200 words, conversation has > 1000 words on this feature, .rune/features/<name>/requirements.md already exists (continuation), or user said "synthesize"/"just write the spec" → BA Step 1.4 activates Synthesis Mode (extract + cite sources + confirm), skipping the 5-question elicitation. Cook does NOT need to choose mode — BA detects automatically.Glob for .rune/decisions.md; if exists, Read + extract constraints for Phase 2. Plan MUST NOT contradict active decisions without explicit user override.
4b. Contract enforcement: If .rune/contract.md was loaded in Phase 0.6, list applicable contract sections for this task (e.g., contract.security for auth work, contract.data for database changes). These rules constrain Phase 2 planning and Phase 4 implementation.Ask 2 questions before planning: (1) "What does success look like?" (2) "What should NOT change?"
Skip if: bug fix with clear repro steps | user said "just do it" | fast mode + <10 LOC | hotfix chain active. Complexity revealed → escalate to rune:ba.
Grep for async indicators (async def, await, aiosqlite, aiohttp, asyncio.run). If ≥3 matches → flag as "async-first Python" — new code defaults to async defcompletedGate: If scout finds the feature already exists → STOP and inform user.
Goal: Detect if domain-specific L4 extension packs apply to this task.
After scout completes, check if the detected tech stack or task description matches any L4 extension pack. This phase is lightweight — a Read + pattern match. It does NOT replace Phase 1 (scout) or Phase 2 (plan). If 0 packs match: skip silently.
Goal: If Phase 1.5 detected a pack AND the task maps to a named workflow, orchestrate the multi-skill sequence.
Trigger: Only runs if Phase 1.5 found a pack match AND the pack's Workflows table has a matching command.
skills/ directory
b. Execute the skill's workflow steps
c. Write output artifact to .rune/<domain>/ (e.g., .rune/hr/jd-[role]-[date].md)
d. The next skill reads the previous artifact as input contextThreading state: Each skill in the sequence produces an artifact file. The next skill's Step 1 reads existing artifacts from .rune/<domain>/. This is already built into each skill — no new plumbing needed.
Skip if: No workflow match found in Phase 1.5. Single-skill tasks proceed directly to Phase 2 (PLAN) as normal.
Goal: Detect if a master plan already exists for this task, or if a --template was specified. If so, skip Phase 1-2 and resume/load the workflow.
Step 0.4 — Template Detection: If user passed --template <name>:
Glob for extensions/*/templates/<name>.md and extensions/pro-*/templates/<name>.mdRead the template file → parse phases, signals, connections, acceptance criteria.rune/plan-<template-name>.md + .rune/plan-<template-name>-phaseN.mdStep 0.5 — Cross-Project Recall: Call neural-memory (Recall Mode) with 3-5 topics relevant to the current task. Always prefix queries with the project name (e.g., "ProjectName auth pattern" not "auth pattern").
Glob to check for .rune/plan-*.md files⬚ Pending or 🔄 Active phase → load ONLY that phase file → announce "Resuming from Phase N" → skip to Phase 4Step 0.6 — Contract Load: Use Glob to check for .rune/contract.md. If it exists:
Read the contract file and parse each ## section as a named rule setThis enables multi-session workflows: Opus plans once → each session picks up the next phase.
Goal: Break the task into concrete implementation steps before writing code.
REQUIRED SUB-SKILL: Use rune:plan
in_progress.rune/features/<feature-name>/ with spec.md, plan.md, decisions.md, status.md. Skip for simple bug fixes, fast mode.rune:brainstorm for trade-off analysis.tsx/.jsx/.vue/.svelte/.css, component files, or mentions "UI/page/screen/design/layout/landing": invoke rune:design BEFORE plan approval. Pass hint mode: "tweaks-default" — design proposes ONE opinionated default per .rune/design-system.md (Step 2.7), not a 5-option menu. User replies with tweaks ("more professional", "darker") rather than picking from a list. If .rune/design-system.md is missing, design creates it first..rune/features/<name>/plan.mdcompletedGate: User MUST approve the plan before proceeding. Do NOT skip this.
Goal: Formal change management for breaking changes. Prevents unreviewed breaking changes from reaching production.
Breaking change without RFC = BLOCKED. No exceptions. "It's just a small change" is the #1 excuse for production incidents from unreviewed breaking changes.Goal: Stress-test the approved plan BEFORE writing code — catch flaws at plan time, not implementation time.
REQUIRED SUB-SKILL: Use rune:adversary
When rune:plan produces a master plan + phase files (non-trivial tasks):
⬚ → ✅, announce "Phase N complete. Phase N+1 ready for next session."Goal: Define expected behavior with failing tests BEFORE writing implementation.
REQUIRED SUB-SKILL: Use rune:test
in_progress.rune/evals/<feature>.md. Capability evals test "can the system do this new thing?" — regression evals test "did we break existing behavior?" Skip for Fast/Standard rigor levels.rune:test references/vertical-tdd.md. Bulk-writing tests = horizontal violation, blocks Phase 4pytest-asyncio is installed and asyncio_mode = "auto" is in pyproject.toml — if missing, warn user before writing async testscompleted (one cycle); Phase 4 implements that one cycle, then loop returns here for the next testGate: Test MUST exist and MUST fail. If test passes without implementation → test is wrong, rewrite. If 2+ tests staged before any GREEN → tdd.horizontal.violation signal, unwind to one test.
Goal: Write the minimum code to make tests pass.
REQUIRED SUB-SKILL: Use rune:fix
Mark Phase 4 as in_progress
Phase-file execution — if working from a master plan + phase file:
## Tasks section wave-by-wave[x] as completedImplement the feature following the plan (Write for new files, Edit for existing)
Run tests after each significant change — if fail → debug and fix
time.sleep → asyncio.sleep, requests → httpx.AsyncClient, use asyncio.gather() for parallel I/OIf stuck → invoke rune:debug (max 3 debug↔fix loops). Fixes outside plan scope require user approval (R4).
.rune/oracle-pending/*.json. For any record with status=pending, invoke session-bridge --reattach <sessionId>. If complete → consume the response (route to debug/fix per sourceSkill). If pending → continue with next independent task. If failed → continue without second opinion.Re-plan check — evaluate before Phase 5: max debug loops hit? out-of-scope files changed? new dep changes approach? user scope change? If any fire → invoke rune:plan with delta context, get user approval before resuming.
Approach Pivot Gate — if re-plan ALSO fails:
Do NOT surrender. Do NOT tell user "no solution exists." Do NOT try a 4th variant of the same approach. MUST invoke brainstorm(mode="rescue") before giving up.Invoke rune:brainstorm(mode="rescue") with failed_approach, failure_evidence[], original_goal. Returns 3-5 alternatives → user picks → restart from Phase 2.
All tests MUST pass before proceeding
Mark Phase 4 as completed
Gate: ALL tests from Phase 3 MUST pass. Do NOT proceed with failing tests.
Goal: Catch issues before they reach production.
Quality checks run in two stages — spec compliance gates code review. Reviewing code quality before verifying it matches the spec wastes effort on code that may need rewriting.
Signal dispatch ordering: When fix emits code.changed, 4 listeners react (preflight, sentinel, test, review). Cook coordinates dispatch order — do NOT let all 4 fire simultaneously:
STAGE 1 (parallel):
Launch 5a (preflight) + 5b (sentinel) simultaneously.
Wait for BOTH to complete.
If 5a returns BLOCK → fix spec gaps, re-run 5a. Code review CANNOT start on non-compliant code.
If 5b returns BLOCK → fix security issue, re-run 5b.
STAGE 2 (after Stage 1 passes):
Launch 5c (review) + 5d (completion-gate) simultaneously.
If any returns BLOCK → fix findings, re-run the blocking check only.
Every BLOCK finding gets a cycle counter. Fix → re-run → still BLOCK? Increment. Max 3 cycles per gate before escalation.
Cycle 1: fix finding → re-run gate
Cycle 2: different fix → re-run gate
Cycle 3: last attempt → re-run gate
Cycle 4: STOP. Escalate to user with all 3 failed attempts + evidence.
Track per-gate, not globally — preflight cycle 2 does not count against sentinel cycle 1. If the SAME finding persists across 3 cycles, the fix approach is wrong — do NOT keep trying the same strategy. Cycle 2+ MUST try a different fix than Cycle 1.
During Phase 5 quality checks, if a gate finding traces to an upstream artifact (plan was wrong, spec was incomplete, architecture was flawed) rather than an implementation bug:
UPSTREAM:<phase> (e.g., UPSTREAM:plan, UPSTREAM:spec)rune:plan for plan issues, rune:ba for spec gaps) with the finding as contextREQUIRED SUB-SKILL: Use rune:preflight
REQUIRED SUB-SKILL: Use rune:sentinel
REQUIRED SUB-SKILL: Use rune:review
team): The review agent MUST be a separate context window from the implementing agent. Author reasoning contaminates review — the reviewer should never have seen the implementation's reasoning chain. Sonnet implements, a fresh Sonnet reviews.REQUIRED SUB-SKILL: Use rune:completion-gate
// ..., // rest of code, bare ellipsis) — agent MUST complete all outputGate: If sentinel finds CRITICAL security issue → STOP, fix it, re-run. Non-negotiable. Gate: If completion-gate finds UNCONFIRMED claim → STOP, re-verify. Non-negotiable.
Projects can define phase-specific rules in .rune/phase-rules.md that apply ONLY during specific cook phases. These are additive — they enhance skill guidance, not replace it.
# .rune/phase-rules.md (example)
## Phase 2: PLAN
- All API endpoints must follow REST naming convention /api/v1/<resource>
- Database changes require a rollback migration
## Phase 3: TEST
- Enforce TDD format: describe → it → arrange → act → assert
- Minimum 3 edge cases per public function
## Phase 5: QUALITY
- Review must check for N+1 queries on any ORM code
- Sentinel must verify CORS configuration on new routes
Loading: Cook reads .rune/phase-rules.md during Phase 0 (resume check). Rules for each phase are injected into the sub-skill's context when that phase starts. If file doesn't exist → skip silently.
Invoke rune:session-bridge after Phase 2, 4, and 5 to save intermediate state. OPT-IN — activate only if task spans 3+ phases, context-watch is ORANGE, or user explicitly requests checkpoints. Before spawning subagents, invoke rune:context-pack to create structured handoff briefings.
Before entering ANY Phase N+1, assert: Phase N completed in TodoWrite | gate condition met | no BLOCK from sub-skills | no unresolved CRITICAL findings. If any fails → STOP, log "BLOCKED at Phase N→N+1: [assertion]", fix, re-check.
Key transitions: 1→2: scout done | 2→3: plan approved | 3→4: failing tests exist | 4→5: all tests pass | 5→6: no CRITICAL findings | 6→7: lint+types+build green.
REQUIRED SUB-SKILL: Use rune:verification — run lint, type check, full test suite, build. Then rune:hallucination-guard to verify imports and API signatures. ALL checks MUST pass before commit.
RECOMMENDED SUB-SKILL: Use rune:git — stage specific files (git add <files>, NOT git add .), generate semantic commit message from diff. If working from master plan: update phase status 🔄 → ✅, announce next phase or "All phases complete."
Goal: Save context for future sessions and record metrics for mesh analytics.
REQUIRED SUB-SKILL: Use rune:session-bridge
Mark Phase 8 as in_progress
Save to .rune/decisions.md (approach + trade-offs), .rune/progress.md (task complete), .rune/conventions.md (new patterns)
Skill metrics → .rune/metrics/skills.json: increment phase run/skip counts, quality gate results, debug loop counts under cook key
Routing overrides (H3): if Phase 4 hit max loops for an error pattern → write rule to .rune/metrics/routing-overrides.json. Max 10 active rules.
Step 8.5 — Cross-Cutting Sweep: After commit, check if this phase changed stats (skill count, test count, signal count, pack count, layer counts). If ANY stat changed:
README.md — stats, badges, feature listdocs/index.html (landing page) — meta tags, hero badge, install section, mesh stats, footerdashboard.html (if local) — KPI cards, test count, skill tabs, layer countsCLAUDE.md — commands, test count, skill listMEMORY.md — milestones, version infoSkip if: No stats changed (pure refactor, docs-only, style change). MANDATORY if any numeric stat in README differs from actual.
Step 8.6 — Capture Learnings: neural-memory (Capture Mode) — 2-5 memories: architecture decisions, patterns, error root-causes, trade-offs. Cognitive language (causal/decisional/comparative). Tags: [project, tech, topic]. Priority 5 routine / 7-8 decisions / 9-10 critical errors.
Mark Phase 8 as completed
When cook runs inside team (L1) or autonomous workflows, these patterns apply.
After Phase 4 completes (all tests green), run a separate focused cleanup pass on all modified files. Two focused passes outperform one constrained pass — let the implementer write freely in Phase 4, then clean up here.
Trigger: Implementation touched 3+ files OR 100+ LOC changed. Skip for nano/fast rigor.
Slop targets (check every modified file):
| Slop Type | Detection | Fix |
|---|---|---|
| Leftover debug | console.log, print(), debugger, TODO: remove | Delete |
| Over-defensive checks | Null checks on values guaranteed non-null by TypeScript/framework | Remove redundant guard |
| Type-test slop | typeof x === 'string' when x is already typed as string | Remove — trust the type system |
| Duplicated logic | Same 3+ lines appear in multiple places | Extract utility |
| Framework-behavior tests | Tests asserting that React renders, that Express routes exist, that mocks work | Delete — test YOUR code, not the framework |
| Inconsistent naming | Mixed camelCase/snake_case in same file | Normalize to project convention |
| Dead imports | Imports no longer used after edits | Remove |
Important: This is NOT a quality gate — it's a cleanup pass. Don't block the pipeline for cosmetic issues. Fix what you find, move on.
cook instance → commit → push → create PR → wait CI
IF CI passes → mark workstream complete
IF CI fails → read CI output → fix → push → wait CI (max 3 retries)
IF 3 retries fail → escalate to user with CI logs
.continue-here.md)When cook must pause mid-phase, create .rune/.continue-here.md with structured handoff, then WIP commit. Phase 0 detects it on resume. More granular than plan-level resume — resumes within a phase.
Two-stage intent classification: keyword fast-path for short messages (<60 chars), context classification for longer ones. Never queue user messages — process immediately.
NEVER treat a Cancel/Pause signal as a Steer or NewTask. User safety signals take absolute priority. If ambiguous between Cancel and Steer → ask user: "Did you mean stop, or change approach?"Hard caps: MAX_DEBUG_LOOPS=3, MAX_QUALITY_LOOPS=2, MAX_REPLAN=1, MAX_PIVOT=1, MAX_FIXES=30, WTF_THRESHOLD=20%. Escalation chain: debug-fix (3x) → re-plan (1x) → brainstorm rescue (1x) → THEN escalate to user.
From agency-agents (msitarzewski/agency-agents, 50.8k★): "After 3 retry failures, structured escalation prevents cargo-cult retrying."
When escalation chain exhausts (all retries hit) or cook returns BLOCKED, produce a Structured Escalation Report instead of a vague "I can't do this":
## Escalation Report
- **Task**: [original task description]
- **Status**: BLOCKED
- **Attempts**: [count] across [N] phases
### Failure History
| # | Approach | Phase | Outcome | Root Cause |
|---|---------|-------|---------|------------|
| 1 | Direct fix | Phase 4 | Tests fail — null ref in auth.ts:42 | Missing user context |
| 2 | Re-plan with guard clause | Phase 4 | Build fails — circular import | Guard approach introduces cycle |
| 3 | Brainstorm rescue → adapter pattern | Phase 4 | Tests pass but perf regression 3x | Adapter adds indirection overhead |
### Root Cause Analysis
[1-2 sentences: why ALL approaches failed — is it architectural, environmental, or requirements-level?]
### Recommended Resolutions (pick one)
1. **Reassign** — different skill/agent with fresh context
2. **Decompose** — break into smaller sub-tasks that CAN succeed independently
3. **Revise requirements** — relax constraint X to unblock (specify which)
4. **Accept partial** — ship what works, defer blocked portion
5. **Defer** — park this task, work on something else first
### Impact Assessment
- **Blocked by this**: [downstream tasks/phases that depend on this]
- **Not blocked**: [independent work that can continue]
"Bad work is worse than no work." Cook MUST produce this report rather than attempting a 4th variant of a failing approach. Escalating is not failure — shipping broken code is.
From superpowers (obra/superpowers, 84k★): "Subagents that start work without asking questions produce the wrong thing 40% of the time."
Before dispatching a sub-skill (fix, test, review) for a non-trivial task (3+ files OR ambiguous scope):
This prevents the #1 parallel work failure: sub-skill assumes wrong interpretation, builds 500 LOC, then gets rejected in review.
Cook and all sub-skills return: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED.
When invoking sub-skills (fix, debug, test, review, etc.), craft exactly the context they need — never pass the full orchestrator session context.
| Pass To Sub-Skill | DO NOT Pass |
|---|---|
| Task description + specific goal | Full conversation history |
| Relevant file paths from scout | Unrelated files from other phases |
| Project conventions (naming, test framework) | Other sub-skill outputs |
| Plan excerpt for THIS phase only | Full master plan |
| Error/stack trace (for debug/fix) | Previous debug attempts from other bugs |
Why: Sub-skills that inherit orchestrator context get polluted — they chase false connections, reference stale data, and consume tokens on irrelevant context. A focused sub-skill with 500 tokens of curated context outperforms one with 5000 tokens of inherited noise.
R1-R3 (bug/security/blocking fix): auto-fix, continue. R4 (architectural change): ASK user first.
Includes phase-by-phase failure handling and repair operators (RETRY → DECOMPOSE → PRUNE) with a 2-attempt budget before escalation.
You MUST either:
Stuck patterns (all banned):
A wrong first attempt that produces feedback beats perfect understanding that never ships.
Track every tool call during Phase 4 (IMPLEMENT) as either observation (read-only) or effect (modifies state):
| Category | Tool Examples |
|---|---|
| Observation | Read, Grep, Glob, Bash(grep/ls/cat/git log) |
| Effect | Write, Edit, Bash(npm/build/test/mkdir) |
Detection rules (check every 8 tool calls during Phase 4):
| Pattern | Threshold | Signal | Action |
|---|---|---|---|
| Observation chain | 6+ consecutive observation tools with zero effects | Agent is stuck reading, not building | Inject: "OBSERVATION LOOP — 6 reads without writing. Act on what you know or report BLOCKED." |
| Low effect ratio | In last 10 calls, effects < 15% | Agent is in analysis mode, not implementation | Inject: "Effect ratio below 15%. Phase 4 is IMPLEMENT — write code, don't just read it." |
| Diminishing returns | Last 3 observations found <2 new relevant facts combined | Searching is no longer productive | Inject: "Diminishing returns — last 3 reads added nothing new. Synthesize and act." |
| Repeating sequences | A-B-A-B or A-B-C-A-B-C pattern across 6+ calls | Circular behavior | Inject: "REPEATING SEQUENCE detected. Break the cycle — try a different approach or report BLOCKED." |
Important: These are injected as advisor messages, not hard blocks. The agent can continue if it has good reason, but the message forces conscious acknowledgment of the pattern.
Skip if: Phase 1 (UNDERSTAND) — observation-heavy is expected during research. Only track during Phase 4+ where effects should dominate.
Beyond the existing Exit Conditions (MAX_DEBUG_LOOPS, MAX_QUALITY_LOOPS, etc.), track cumulative budget across the entire cook session:
| Budget | Limit | What Happens at Limit |
|---|---|---|
| Phase 4 react budget | 15 tool calls per task within Phase 4 | Force: move to next task or report partial completion |
| Global replan budget | 2 replans per session (Phase 4 Step 6) | Force: proceed with current plan or escalate to user |
| Quality retry budget | 3 total quality re-runs across 5a-5d | Force: ship with known issues documented, don't loop |
| Total session tool calls | 150 calls | Force: save state via session-bridge, compact or pause |
Hard override rules:
Why: Without hard budgets, agents get trapped in local optimization loops — retrying the same failing approach indefinitely. Budget constraints force escalation or acceptance of partial results, which is always better than an infinite loop.
Mentally track tool call fingerprints. 3 identical calls → WARN. 5 identical calls → FORCE STOP. Only same-input-AND-same-output counts as a loop.
/rune cook direct invocation — primary entry pointteam (L1): parallel workstream execution (meta-orchestration)| Phase | Sub-skill | Layer | Purpose |
|---|---|---|---|
| 0 / 8 | neural-memory | ext | Recall context at start; capture learnings at end |
| 0.5 | sentinel-env | L3 | Environment pre-flight (first run only) |
| 1 | scout | L2 | Scan codebase before planning |
| 1 | onboard | L2 | Initialize project context if no CLAUDE.md |
| 1 | ba | L2 | Requirement elicitation for features |
| 1 | logic-guardian | L2 | Conditional: when .rune/logic-manifest.json exists — protect complex business logic before any edits |
| 2 | plan | L2 | Create implementation plan |
| 2 | brainstorm | L2 | Trade-off analysis / rescue mode |
| 2 | design | L2 | UI/design phase for frontend features — invoke with mode: "tweaks-default" (one opinionated default + accept natural-language tweaks, not a 5-option menu) |
| 2.5 | adversary | L2 | Red-team challenge on approved plan |
| 3 | test | L2 | Write failing tests (RED phase) |
| 4 | fix | L2 | Implement code changes (GREEN phase) |
| 4 | debug | L2 | Unexpected errors (max 3 loops) |
| 4 | db | L2 | Schema changes detected in diff |
| 4 | worktree | L3 | Worktree isolation for parallel implementation |
| 5a | preflight | L2 | Spec compliance + logic review |
| 5b | sentinel | L2 | Security scan |
| 5c | review | L2 | Code quality review |
| 5 | scope-guard | L3 | Verify changed files match approved plan scope (flag out-of-scope files before commit) |
| 5 | perf | L2 | Performance regression check (optional) |
| 5 | audit | L2 | Project health audit when scope warrants |
| 5 | review-intake | L2 | Structured review intake for complex PRs OR Issue Triage Mode for issue tracker items (state machine: needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix). When external feedback source is an issue (not PR comment), review-intake auto-detects and runs Issue Triage Mode — emits triage.classified + agent.brief.ready (for AFK pickup) |
| 5 | sast | L3 | Static analysis security testing |
| 5d | completion-gate | L3 | Validate agent claims against evidence trail |
| 5 | constraint-check | L3 | Audit HARD-GATE compliance across workflow |
| 6 | verification | L3 | Lint + types + tests + build |
| 6 | hallucination-guard | L3 | Verify imports and API calls are real |
| 7 | journal | L3 | Record architectural decisions |
| 8 | session-bridge | L3 | Save context for future sessions |
| any | context-pack | L3 | create structured handoff briefings before spawning subagents |
| any | skill-forge | L2 | When new skill creation detected during cook |
| 1.5 | L4 extension packs | L4 | Domain-specific patterns when stack matches |
Feeds Into → journal (decisions → ADRs) | session-bridge (context → .rune/ state) | neural-memory (learnings → cross-session)
Fed By ← ba (requirements → Phase 1) | plan (master plan → Phase 2-4) | session-bridge (.continue-here.md → Phase 0 resume) | neural-memory (past decisions → Phase 0 recall)
Feedback Loops ↻ cook↔debug (Phase 4 bug → debug → fix → resume; if plan wrong → Approach Pivot) | cook↔test (RED → GREEN → failures loop back)
.rune/decisions.md without explicit user override| Gate | Requires | If Missing |
|---|---|---|
| Resume Gate | Phase 0 checks for master plan before starting | Proceed to Phase 1 |
| Scout Gate | scout output before Phase 2 | Invoke rune:scout first |
| Plan Gate | User-approved plan before Phase 3 | Cannot proceed |
| Adversary Gate | adversary verdict before Phase 3 for features | Skip for bugfix/hotfix/refactor |
| Phase File Gate | Active phase file only (multi-session) | Load only active phase |
| Test-First Gate | Failing tests before Phase 4 | Write tests or get explicit skip |
| Quality Gate | preflight + sentinel + review before Phase 7 | Fix findings, re-run |
| Verification Gate | lint + types + tests + build green before commit | Fix, re-run |
When cook invokes sub-skills that produce structured output (e.g., ba for requirements, plan for implementation plans, test for test specs), use the Prompt-as-API-Contract pattern: specify the exact output schema in the invocation prompt so the sub-skill returns machine-parseable results, not free-form prose.
INVOCATION: "Analyze [X] and return results as JSON matching this schema:
{
"insights": [{ "id": string, "category": string, "description": string, "actionable": string }],
"confidence": number,
"next_steps": string[]
}
Do NOT include explanatory text outside the JSON block."
| Phase | Sub-skill | Output Contract |
|---|---|---|
| Phase 1 | ba | { requirements: [{id, priority, description, acceptance_criteria}], ambiguities: string[] } |
| Phase 2 | plan | { phases: [{name, tasks: [{description, files, effort}], dependencies}] } |
| Phase 3 | test | { test_cases: [{name, type, file, assertion}], coverage_targets: string[] } |
| Phase 5 | review | `{ findings: [{severity, file, line, description, fix}], verdict: "PASS" |
Free-form sub-skill output forces the calling skill to parse natural language — fragile and lossy. Structured contracts make skill-to-skill communication reliable, enable automated validation, and reduce the tokens wasted on parsing instructions.
Emit a Cook Report with: Status, Phases, Files Changed, Tests, Quality results, Commit hash.
When invoked by team with a NEXUS Handoff, include the Deliverables table — MANDATORY.
| Artifact | Format | Location |
|---|---|---|
| Plan files (master + phase) | Markdown | .rune/plan-<feature>.md, .rune/plan-<feature>-phase<N>.md |
| Implementation code | Source files | Per plan file paths |
| Test files | Source files | Co-located or __tests__/ per project convention |
| Verification results | Inline stdout | Shown in Cook Report |
| Cook Report | Markdown (inline) | Emitted at end of session |
| Session state | Markdown | .rune/decisions.md, .rune/progress.md, .rune/conventions.md |
| Scope | Access | Files |
|---|---|---|
| Owns (read + write) | .rune/plan-*.md, .rune/progress.md, .rune/decisions.md, .rune/conventions.md, source files per approved plan | |
| Reads (never writes) | CLAUDE.md, SKILL.md (any), .rune/contract.md, .rune/checkpoint.md | |
| Never modifies | compiler/**, extensions/**, PACK.md, other skills' SKILL.md, .rune/learnings.jsonl |
When delegating to sub-skills (scout, plan, test, review), each sub-skill owns its own output. Cook coordinates but does not overwrite sub-skill artifacts.
Common multi-agent failures to explicitly avoid. These are NOT edge cases — they are the most frequent cook failures in production.
| Anti-Pattern | Why It Fails | Correct Approach |
|---|---|---|
| Bypass hierarchy — skipping scout/plan and jumping to Phase 4 code | Builds wrong thing. Most "wasted work" traces back to missing Phase 1-2 | Follow phase gates. Even "obvious" tasks benefit from 30s of scout |
| Shadow decisions — making architectural choices without logging to decisions.md | Next session repeats the same debate. Team agents contradict each other | Log every non-trivial choice via decisions.md or journal |
| Gold-plating — adding "nice-to-have" features not in the approved plan | Scope creep, delayed delivery, untested code paths | Build ONLY what's in the plan. Log extras as follow-up tasks |
| Test-after — writing tests after implementation instead of before (TDD violation) | Tests validate implementation bugs, not requirements. Coverage looks good but misses edge cases | Phase 3 (RED) before Phase 4 (GREEN). Always |
| Monolithic commit — one giant commit with all changes | Impossible to revert partially. Review is overwhelming | Commit per phase or per logical unit. Small, reviewable diffs |
| Assumption-based implementation — guessing requirements instead of asking | Builds the wrong thing confidently. User discovers mismatch late | If ambiguous, ask. 30s of clarification saves 30min of rework |
| Infinite remediation loop — fixing the same BLOCK finding 4+ times with the same approach | Wastes tokens, drifts further from solution. If 3 attempts failed, the approach is wrong | Remediation Cycle Counter: max 3 cycles, Cycle 2+ must try different strategy, Cycle 4 escalates to user |
| Code fix for upstream problem — fixing implementation when the plan/spec was wrong | Code "passes" but implements the wrong thing. Bug resurfaces in integration | Upstream Inconsistency Protocol: tag as UPSTREAM, re-invoke upstream skill, get approval, re-run gates |
CRITICAL failures (always check): skipping scout | writing code without plan approval | "done" without evidence trail | surrendering without Approach Pivot Gate | breaking change without RFC | treating Cancel/Pause as scope change.
SELF-VALIDATION (run before emitting Cook Report):
- [ ] Every phase in Phase Skip Rules was either executed or explicitly skipped with reason
- [ ] Plan approval gate was not bypassed — user said "go" (check conversation history)
- [ ] No Phase 4 code was written before Phase 3 tests (TDD order preserved)
- [ ] All Phase 5 quality gates (preflight, sentinel, review) ran — not just claimed
- [ ] No quality gate exceeded 3 remediation cycles without user escalation
- [ ] No upstream issue was fixed by code change alone — UPSTREAM findings re-invoked the source skill
- [ ] Cook Report contains actual commit hash, not placeholder
All applicable phases complete + Self-Validation passed:
~$0.05-0.15 per feature. Haiku for scanning (Phase 1), sonnet for coding (Phase 3-4), opus for complex planning (Phase 2 when needed).