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.

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:

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