Imported from Rune-kit/rune (skills/cook/SKILL.md). Install upstream with npx skills add Rune-kit/rune --skill cook. Copyright stays with the author.

cook

Purpose

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.

Workflow Chains (Predefined)

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

Production Hotfix Protocol

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.

Template Workflows (Pro/Business)

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:

1. Skip Phase 1.5 (auto-detection) — template pre-selects domain and pack
2. Skip Phase 1.7 (workflow matching) — template IS the workflow
3. Load template phases as the master plan (Phase 2 becomes "review template plan" not "create plan")
4. Execute each template phase in order, invoking declared skills
5. Emit template's declared signals on completion

Chain selection: If user invokes /rune cook without a chain type, auto-detect from the task description:

• Contains "bug", "fix", "broken", "error" → bugfix
• Contains "refactor", "clean", "restructure" → refactor
• Contains "security", "auth", "vulnerability", "CVE" → security
• Contains "urgent", "hotfix", "production" → hotfix
• Contains "quick", "just", "chỉ cần", "copy", "move", "rename", "bump" → nano
• Contains "graft", "port from", "copy from repo", "clone feature from" → delegate to rune:graft (not a cook chain — hand off entirely)
• Contains --template → load template workflow (see above)
• Default → feature

Phase Skip Rules

Not 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 → 6.5 → 7 → 8  (6.5: conditional — requires requirements.md)
Complex feature:     All phases (incl. 6.5) + 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.

Rigor Assessment (Progressive Scaling)

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.

Rigor level mapping:

Rules:

• Security signal (+3) automatically floors rigor at Standard — NEVER nano/fast for security code
• User can override: "full pipeline" forces Full, "just do it" forces Nano
• If rigor upgrades mid-task (e.g., scout reveals cross-module impact not obvious from description), announce: "Rigor upgrade: [signal detected] — upgrading from Fast to Standard."
• Announce chosen level: "Rigor: Fast (score 2 — single file, no security)"

Nano Mode (Auto-Detect)

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.

Fast Mode (Auto-Detect)

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.

Phase 0.5: ENVIRONMENT CHECK (First Run Only)

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.

Phase 1: UNDERSTAND

Goal: Know what exists before changing anything.

REQUIRED SUB-SKILLS: Use rune:scout. For non-trivial tasks, use rune:ba.

1. Create TodoWrite with all applicable phases for this task
2. Mark Phase 1 as in_progress
3. BA gate: Feature Request / Integration / Greenfield → invoke rune: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.
4. Decision enforcement: 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.

Phase 1 Step 3.5 — Clarification Gate

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.

5. Invoke scout to scan the codebase (Glob + Grep + Read on relevant files)
6. Summarize: what exists, project conventions, files likely to change, active decision constraints
7. Python async detection: if Python project detected, Grep for async indicators (async def, await, aiosqlite, aiohttp, asyncio.run). If ≥3 matches → flag as "async-first Python" — new code defaults to async def
8. Explore-Before-Commit: If scout reveals multiple viable approaches (e.g., 2+ libraries, 2+ architectural patterns), do NOT commit to an approach yet. Instead:
   • List alternatives with 1-line trade-off each
   • Flag to Phase 2 (plan) for formal comparison
   • Separating "thinking" (Phase 1) from "committing" (Phase 2) prevents premature lock-in
9. Mark Phase 1 as completed

Gate: If scout finds the feature already exists → STOP and inform user.

Phase 1.5: DOMAIN CONTEXT (L4 Pack Detection)

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.

Phase 1.7: WORKFLOW ORCHESTRATION (Multi-Skill Sequences)

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.

1. Read the matched PACK.md's Workflows section
2. Identify the workflow name and skill sequence
3. For each skill in sequence: a. Load the skill file from the pack's 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 context
4. After all skills complete: summarize the workflow results to the user

Threading 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.

Phase 0: RESUME CHECK (Before Phase 1)

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>:

1. Search installed pack templates for the name: Glob for extensions/*/templates/<name>.md and extensions/pro-*/templates/<name>.md
2. If found: Read the template file → parse phases, signals, connections, acceptance criteria
3. Generate a master plan from the template: each template phase becomes a plan phase
4. Write plan files to .rune/plan-<template-name>.md + .rune/plan-<template-name>-phaseN.md
5. Announce "Loading template: ()" → skip Phase 1, 1.5, 1.7, 2 → proceed to Phase 4 with Phase 1 of the template
6. If template not found: warn user and fall through to normal workflow

Step 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").

1. Use Glob to check for .rune/plan-*.md files
2. If a master plan exists matching the current task:
   • Step 0.55 — Spec-Backfill Gate (HARD-GATE): Before resuming, Glob .rune/features/*/requirements.md. If NO requirements doc exists AND the task is a Feature / Integration / Greenfield (same classification as the Phase 1 BA-gate — NOT a bug fix, refactor, or trivial change), the plan was produced without a spec (e.g., a brainstorm → plan bypass that skipped ba). Do NOT resume blindly:
     1. Invoke rune:ba to backfill requirements (5-question elicitation, or Synthesis Mode if the plan + conversation already carry enough context) → produces .rune/features/<name>/requirements.md.
     2. Re-invoke rune:plan to reconcile the existing plan against the new spec — if the plan contradicts a locked Decision or misses a requirement, revise the affected phase files and get user re-approval (Re-Planning protocol).
     3. THEN resume. For Bug Fix / Refactor / trivial tasks, skip this gate — no spec is expected.
   • Read the (reconciled) master plan → find first ⬚ Pending or 🔄 Active phase → load ONLY that phase file → announce "Resuming from Phase N" → skip to Phase 4
3. If no master plan exists → proceed to Phase 1 as normal

Step 0.6 — Contract Load: Use Glob to check for .rune/contract.md. If it exists:

1. Read the contract file and parse each ## section as a named rule set
2. Hold contract rules in context — they apply as hard gates throughout all phases
3. Any code change that violates a contract rule → STOP and inform user before proceeding
4. If no contract exists → proceed normally (contract is optional)

This enables multi-session workflows: Opus plans once → each session picks up the next phase.

Phase 2: PLAN

Goal: Break the task into concrete implementation steps before writing code.

REQUIRED SUB-SKILL: Use rune:plan

1. Mark Phase 2 as in_progress
2. Feature workspace (opt-in) — for non-trivial features (3+ phases), suggest creating .rune/features/<feature-name>/ with spec.md, plan.md, decisions.md, status.md. Skip for simple bug fixes, fast mode.
3. Create implementation plan: exact files to create/modify, change order, dependencies, active decision constraints
4. If multiple valid approaches exist → invoke rune:brainstorm for trade-off analysis
5. Frontend detection — if task touches .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.
6. Present plan to user for approval
7. If feature workspace was created, write approved plan to .rune/features/<name>/plan.md
8. Mark Phase 2 as completed

Gate: User MUST approve the plan before proceeding. Do NOT skip this.

Phase 2.5: RFC GATE (Breaking Changes Only)

Goal: Formal change management for breaking changes. Prevents unreviewed breaking changes from reaching production.

Phase 2.5: ADVERSARY (Red-Team Challenge)

Goal: Stress-test the approved plan BEFORE writing code — catch flaws at plan time, not implementation time.

REQUIRED SUB-SKILL: Use rune:adversary

1. Skip conditions: bug fixes, hotfixes, simple refactors (< 3 files, no new logic), fast mode
2. Run adversary — Full Red-Team mode for new features/architectural changes; Quick Challenge mode for smaller plans
3. Handle verdict:
   • REVISE → return to Phase 2 with adversary findings as constraints; user must re-approve
   • HARDEN → present remediations, update plan inline, then proceed to Phase 3
   • PROCEED → pass findings as implementation notes to Phase 3
4. Max 1 REVISE loop per cook session — if revised plan also gets REVISE, ask user to decide

Phase-Aware Execution (Master Plan + Phase Files)

When rune:plan produces a master plan + phase files (non-trivial tasks):

1. After plan approval: load ONLY Phase 1's file — do NOT load all phase files
2. Execute through cook Phase 3-6 (test → implement → quality → verify)
3. After phase complete: mark tasks done, update master plan status ⬚ → ✅, announce "Phase N complete. Phase N+1 ready for next session."
4. Next session: Phase 0 detects master plan → loads next phase → executes

Phase 3: TEST (TDD Red)

Goal: Define expected behavior with failing tests BEFORE writing implementation.

REQUIRED SUB-SKILL: Use rune:test

1. Mark Phase 3 as in_progress
2. Eval definitions (Full/Critical rigor only): Before writing tests, define capability evals (pass@k) and regression evals (pass^k) in .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.
3. Write ONE test for the next behavior — vertical slicing required, see rune:test references/vertical-tdd.md. Bulk-writing tests = horizontal violation, blocks Phase 4
4. Python async pre-check (if async-first Python flagged in Phase 1): verify pytest-asyncio is installed and asyncio_mode = "auto" is in pyproject.toml — if missing, warn user before writing async tests
5. Run the test to verify it FAILS — expected: RED because implementation doesn't exist yet
6. Mark Phase 3 as completed (one cycle); Phase 4 implements that one cycle, then loop returns here for the next test

Gate: 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.

Phase 4: IMPLEMENT (TDD Green)

Goal: Write the minimum code to make tests pass.

REQUIRED SUB-SKILL: Use rune:fix

Reuse Ladder (climb before you write)

Before writing the code for each task, climb this ladder and stop at the first rung that holds. Advisory, not a gate — it shapes what you write, never blocks the phase. Runs AFTER you understand the change (scout done, plan approved), never as a substitute for tracing the real flow.

1. Needs to exist at all? Speculative need → skip it, say so in one line (YAGNI).
2. Already in this codebase? A helper, util, type, or pattern that already lives here → reuse it. Re-implementing what sits a few files over is the most common slop — Grep before you write.
3. Stdlib does it? Use it.
4. Native platform feature covers it? DB constraint over app code, CSS over JS, <input type="date"> over a picker lib.
5. Already-installed dependency solves it? Use it. Never add a new dep for what a few lines cover.
6. One line? Make it one line.
7. Only then — the minimum code that makes the test pass.

Two rungs work → take the higher one and move on. Mark a deliberate shortcut with a // yagni: comment naming its ceiling + upgrade path (// yagni: global lock — per-account locks if throughput matters) so the De-Sloppify Pass and later readers see intent, not ignorance.

Bug-fix corollary — the lazy fix IS the root-cause fix: Grep every caller of the function you're about to touch, then fix the shared function once. One guard where all callers route through is a smaller diff than one guard per caller — and patching only the path the ticket names leaves every sibling caller still broken.

Never lazy about: understanding the problem, input validation at trust boundaries, error handling that prevents data loss, security, accessibility, anything explicitly requested. The ladder shortens the solution, never the reading — a small diff you don't understand is a confident wrong fix, not laziness.

1. Mark Phase 4 as in_progress

2. Phase-file execution — if working from a master plan + phase file:

   • Execute tasks from ## Tasks section wave-by-wave
   • Wave N only starts after ALL Wave N-1 tasks complete
   • Follow Code Contracts, Rejection Criteria, Failure Scenarios from the phase file
   • Mark each task [x] as completed

3. Implement the feature following the plan (Write for new files, Edit for existing)

4. Run tests after each significant change — if fail → debug and fix

   • Python async (if async-first flagged): no blocking calls in async functions — time.sleep → asyncio.sleep, requests → httpx.AsyncClient, use asyncio.gather() for parallel I/O

5. If stuck → invoke rune:debug (max 3 debug↔fix loops). Fixes outside plan scope require user approval (R4).

   • Oracle reattach check — between tasks, glob .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.

6. 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.

7. Approach Pivot Gate — if re-plan ALSO fails:

   Invoke rune:brainstorm(mode="rescue") with failed_approach, failure_evidence[], original_goal. Returns 3-5 alternatives → user picks → restart from Phase 2.

8. All tests MUST pass before proceeding

9. Mark Phase 4 as completed

Gate: ALL tests from Phase 3 MUST pass. Do NOT proceed with failing tests.

Phase 5: QUALITY (Staged)

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: preflight + sentinel (parallel — independent checks)
• Stage 2: test (after Stage 1 passes — no point testing non-compliant code)
• Stage 3: review (after test passes — review verified code only)

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.

Remediation Cycle Counter

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.

Upstream Inconsistency Protocol

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:

1. Tag finding as UPSTREAM:<phase> (e.g., UPSTREAM:plan, UPSTREAM:spec)
2. STOP current quality gate — fixing code won't resolve an upstream problem
3. Re-invoke the upstream skill (rune:plan for plan issues, rune:ba for spec gaps) with the finding as context
4. Get user approval on the corrected upstream artifact
5. Resume Phase 5 from the beginning (re-run all gates — upstream change may invalidate prior PASS results)

5a. Preflight (Spec Compliance + Logic) — STAGE 1

REQUIRED SUB-SKILL: Use rune:preflight

• Spec compliance: compare approved plan vs actual diff
• Logic review, error handling, completeness
• Must pass before 5c (review) can start — no point reviewing code quality if it doesn't match the spec

5b. Security — STAGE 1

REQUIRED SUB-SKILL: Use rune:sentinel

• Secret scan, OWASP check (no injection/XSS/CSRF), dependency audit

5c. Code Review — STAGE 2

REQUIRED SUB-SKILL: Use rune:review

• Pattern compliance, code quality, performance bottlenecks
• Reviewer reads code independently — does NOT rely on implementer's claims
• Reviewer isolation (when invoked via 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.

5d. Completion Gate — STAGE 2

REQUIRED SUB-SKILL: Use rune:completion-gate

• Validate agent claims match evidence trail (tests ran, files changed, build passed)
• No truncated code files (// ..., // rest of code, bare ellipsis) — agent MUST complete all output
• Any UNCONFIRMED claim → BLOCK

Gate: 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.

Per-Phase Rules (Project-Specific)

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.

Checkpoint Protocol (Opt-In)

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.

Phase Transition Protocol (MANDATORY)

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→6.5: lint+types+build green | 6.5→7: convergence.clean or documented escalation (features with requirements.md; others pass through).

Phase 6: VERIFY

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.

Quickstart execution: if .rune/features/<name>/quickstart.md exists (plan Step 3.7 boundary artifact), execute its validation blocks — run each command, compare against its Expect line. Any mismatch = verification FAIL (treat like a failing test). If the environment cannot run a block (no browser, no DB), SKIP it with the reason named in the Cook Report — a skipped quickstart is visible debt, never silent.

Phase 6.5: CONVERGE (Spec↔Code Gap Scan)

REQUIRED SUB-SKILL: Use rune:converge — verify the ACTUAL codebase matches the spec before committing.

Trigger: feature/greenfield chains where .rune/features/<name>/requirements.md exists. Skip (announce the skip): nano/fast/bugfix/refactor/hotfix chains, or no requirements.md (ad-hoc task — Phase 5 gates are the only protection).

1. Invoke rune:converge — it re-reads spec/plan/contracts as sole intent, scans present code state, classifies gaps (missing / partial / contradicts / unrequested)
2. convergence.clean → proceed to Phase 7
3. convergence.gaps → inspect the signal's counts payload first:
   • Unrequested-only (counts.missing=0, counts.partial=0, counts.contradicts=0, counts.unrequested>0): no CV tasks were appended — surface the findings in the Cook Report and proceed to Phase 7. Do NOT enter the remediation loop for informational scope-creep findings
   • Otherwise: converge appended CV-* remediation tasks to the active phase file:
     • Execute the CV tasks (return to Phase 4 loop for them; CRITICAL/HIGH first)
     • Re-run Phase 6 VERIFY on the remediated code, then re-invoke converge (round 2)
     • Max 2 remediation rounds. Gaps still present after round 2 → produce a Structured Escalation Report (the same gap surviving 2 rounds means the approach is wrong, not the effort)
4. unrequested findings are surfaced to the user in the Cook Report — never silently deleted, never blocking
5. Stale CV tasks: if converge reports clean but unchecked CV-* tasks remain from earlier rounds (e.g., rules changed between rounds), cook closes them as [x] (resolved — superseded) with a Cook Report note — converge's append-only contract means only cook may touch them

Phase 7: 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."

Phase 8: BRIDGE

Goal: Save context for future sessions and record metrics for mesh analytics.

REQUIRED SUB-SKILL: Use rune:session-bridge

1. Mark Phase 8 as in_progress

2. Save to .rune/decisions.md (approach + trade-offs), .rune/progress.md (task complete), .rune/conventions.md (new patterns)

3. Skill metrics → .rune/metrics/skills.json: increment phase run/skip counts, quality gate results, debug loop counts under cook key

4. 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.

5. 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 list
   • docs/index.html (landing page) — meta tags, hero badge, install section, mesh stats, footer
   • dashboard.html (if local) — KPI cards, test count, skill tabs, layer counts
   • CLAUDE.md — commands, test count, skill list
   • MEMORY.md — milestones, version info

   Skip if: No stats changed (pure refactor, docs-only, style change). MANDATORY if any numeric stat in README differs from actual.

6. 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.

7. Mark Phase 8 as completed

Autonomous Loop Patterns

When cook runs inside team (L1) or autonomous workflows, these patterns apply.

De-Sloppify Pass

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):

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.

Continuous PR Loop (team orchestration only)

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

Formal Pause/Resume (.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.

Mid-Run Signal Detection

Two-stage intent classification: keyword fast-path for short messages (<60 chars), context classification for longer ones. Never queue user messages — process immediately.

Exit Conditions (Mandatory for Autonomous Runs)

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.

Structured Escalation Report

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]

Subagent Question Gate

Subagents that start work without asking questions frequently produce the wrong thing.

Before dispatching a sub-skill (fix, test, review) for a non-trivial task (3+ files OR ambiguous scope):

1. Invite questions: Include in the handoff: "Before starting, ask up to 3 clarifying questions if anything is unclear."
2. Answer before work: If the sub-skill returns questions → answer them, THEN re-dispatch with answers included.
3. Skip if: Fast/Nano rigor, single-file fix, or sub-skill is haiku-tier (too cheap to gate).

This prevents the #1 parallel work failure: sub-skill assumes wrong interpretation, builds 500 LOC, then gets rejected in review.

Subagent Status Protocol

Cook and all sub-skills return: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED.

Subagent Context Isolation

When invoking sub-skills (fix, debug, test, review, etc.), craft exactly the context they need — never pass the full orchestrator session context.

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.

Deviation Rules

R1-R3 (bug/security/blocking fix): auto-fix, continue. R4 (architectural change): ASK user first.

Error Recovery

Includes phase-by-phase failure handling and repair operators (RETRY → DECOMPOSE → PRUNE) with a 2-attempt budget before escalation.

Analysis Paralysis Guard

You MUST either:

1. Act — write code, run a command, create a file
2. Report BLOCKED — state the specific missing piece: "Cannot proceed because [X]"

Stuck patterns (all banned):

• Reading 10+ files to "fully understand" before acting
• Grepping every variation of a string across the entire repo
• Reading the same file twice in one investigation
• "Let me check one more thing" — repeated after 5 reads

A wrong first attempt that produces feedback beats perfect understanding that never ships.

Observation/Effect Ratio Tracking

Track every tool call during Phase 4 (IMPLEMENT) as either observation (read-only) or effect (modifies state):

Detection rules (check every 8 tool calls during Phase 4):

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.

Budget-Aware Phase Progression

Beyond the existing Exit Conditions (MAX_DEBUG_LOOPS, MAX_QUALITY_LOOPS, etc.), track cumulative budget across the entire cook session:

Hard override rules:

• If react budget exhausted for a task but task is IN_PROGRESS → force CONTINUE to next task (don't re-attempt)
• If replan budget exhausted but plan still failing → force escalation (don't attempt 3rd replan)
• If quality retry budget exhausted → emit concerns in Cook Report, proceed to commit with documented caveats

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.

Hash-Based Tool Loop Detection

Mentally track tool call fingerprints. 3 identical calls → WARN. 5 identical calls → FORCE STOP. Only same-input-AND-same-output counts as a loop.

Called By (inbound)

• User: /rune cook direct invocation — primary entry point
• team (L1): parallel workstream execution (meta-orchestration)

Calls (outbound)

Data Flow

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)

Constraints

1. MUST run scout before planning
2. MUST get user plan approval before writing code
3. MUST write failing tests before implementation (TDD) unless explicitly skipped
4. MUST NOT commit with failing tests
5. MUST NOT modify files outside approved plan scope without user confirmation
6. MUST run verification (lint + type-check + tests + build) before commit
7. MUST NOT say "all tests pass" without showing actual test output
8. MUST NOT contradict .rune/decisions.md without explicit user override

Mesh Gates

Structured Output Contract (Prompt-as-API Pattern)

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.

Pattern

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."

When to Apply

Rules

• Include 1-2 concrete examples in the prompt — examples are worth more than schema descriptions
• Always specify "Do NOT include explanatory text outside the JSON/markdown block" — LLMs default to wrapping structured output in prose
• When the output will be consumed by another skill (not displayed to user), ALWAYS use this pattern
• When the output will be displayed to the user, use markdown format instead — humans don't read JSON

Why

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.

Output Format

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.

Returns

Document Ownership

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.

Anti-Patterns

Common multi-agent failures to explicitly avoid. These are NOT edge cases — they are the most frequent cook failures in production.

Sharp Edges

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

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
- [ ] Phase 6.5 converge ran for features with requirements.md — or skip announced (no spec) / escalation documented
- [ ] 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

Done When

All applicable phases complete + Self-Validation passed:

• User approved plan | All tests PASS (output shown) | preflight+sentinel+review PASS | build green
• Convergence: convergence.clean OR skip announced (no requirements.md) OR escalation documented — never silent
• Cook Report emitted with commit hash | Session state saved to .rune/ via session-

*Truncated - read the full file at https://github.com/Rune-kit/rune/blob/feb5f5d5d9cade3e3667913af468a0b1f929ff2e/skills/cook/SKILL.md