Cookbook Run

# /cookbook-run

Execute a Cookbook to build a project from scratch. Reads the cookbook manifest, executes each phase's prompt in dependency order, validates after each phase, and tracks state for resume on failure.

## Arguments

- `$ARGUMENTS` — cookbook path (required) followed by optional parameter overrides
    - First argument: path to the cookbook folder
    - Remaining arguments: `key=value` parameter overrides

Parse `$ARGUMENTS`:

- First token = cookbook path (e.g., `./cookbook`, `./my-saas-cookbook`)
- Remaining tokens = parameter overrides (e.g., `project_name=acme database_url=postgres://localhost/acme`)

If no cookbook path is provided, check if `./cookbook` exists. If not, print:

Usage: /cookbook-run [param=value ...]

---

## Step 1: Load the Cookbook

### 1a. Validate cookbook structure

Check that the cookbook path contains the required files:

$COOKBOOK_PATH/ ├── COOKBOOK.md (required) └── cookbook.yaml (required)

If either is missing:

❌ Invalid cookbook at [path]: missing [file] A cookbook must contain COOKBOOK.md and cookbook.yaml

### 1b. Read the manifest

Read and parse `$COOKBOOK_PATH/cookbook.yaml` fully. Extract:

- `name`, `description`
- `parameters` with defaults
- `phases` with dependencies, conditions, prompts, validation, and doc references

### 1c. Read the entrypoint

Read `$COOKBOOK_PATH/COOKBOOK.md` to understand what this cookbook builds and what prerequisites are needed.

### 1d. Resolve parameters

1. Start with default values from cookbook.yaml
2. Override with user-provided key=value pairs from `$ARGUMENTS`
3. Verify all `required: true` parameters have values
4. If any required parameter is missing:

    ```
    ❌ Missing required parameter: [name]
       [description from manifest]

    Provide it: /cookbook-run [path] [name]=[value]
    ```

### 1e. Validate dependency graph

Build the phase dependency graph from `depends_on` fields. Check for:

- **Circular dependencies:** If found, abort with the cycle path.
- **Missing dependency targets:** If a phase depends on a non-existent phase, abort.
- **Unreachable review phase:** Warn if the final phase doesn't transitively depend on all other phases.

### 1f. Report the plan

📖 Cookbook: [name] 📝 [description]

⚙️ Parameters: [param] = [resolved value] [param] = [resolved value] ...

📋 Build Plan ([count] phases):

1. scaffold
2. [phase]
3. [phase] ─┐
4. [phase] ─┤ (parallel)
5. [phase] ─┘
6. [phase]
7. review

Starting build...

---

## Step 2: Check for Resume

Look for `.cookbook-state.json` in the current working directory.

### If state file exists

Read it and determine what's already done:

```json
{
  "cookbook": "[name]",
  "cookbook_version": "[version]",
  "started_at": "[ISO timestamp]",
  "parameters": { "project_name": "acme", ... },
  "phases": {
    "scaffold": { "status": "complete", "completed_at": "..." },
    "database": { "status": "complete", "completed_at": "..." },
    "auth":     { "status": "failed", "attempts": 2, "last_error": "..." }
  }
}

Version check: If cookbook_version in the state file doesn't match the current cookbook's version, warn:

⚠️  Cookbook version changed since last run ([old] → [new])
   Completed phases may be stale. Consider deleting .cookbook-state.json to start fresh.
   Continuing with existing state...

Print resume status:

🔄 Resuming from previous run:
   ✅ scaffold — complete
   ✅ database — complete
   ❌ auth — failed (attempt 2/3), retrying...
   ⏳ feature-x, feature-y, ui, review — pending

If no state file

Create one:

{
  "cookbook": "[name]",
  "cookbook_version": "[version]",
  "started_at": "[ISO timestamp]",
  "parameters": { ... },
  "phases": {}
}

---

Step 3: Execute Phases

Process phases from cookbook.yaml in dependency order.

Execution loop

Repeat until all phases are processed:

1. Find all phases whose dependencies are ALL satisfied (status: "complete" or status: "skipped")
2. Among those, find phases that haven't been executed yet
3. If multiple phases are ready simultaneously → they're parallel-eligible
4. Execute them (parallel or sequential, depending on tool availability)
5. Update state file after each phase
6. Repeat

For each phase:

a. Check state

If already "complete" or "skipped" in state file → skip silently.

b. Check condition

If the phase has a condition field (e.g., "{{ include_billing }}"), evaluate it against resolved parameters.

If false:

⏭️  Skipping [phase-id] — condition not met ({{ include_billing }} = false)

Mark "status": "skipped" in state file. Continue.

c. Load phase context

1. Read the prompt file from $COOKBOOK_PATH/[phase.prompt]
2. Read ALL doc files listed in the phase's docs array from $COOKBOOK_PATH/
3. Substitute {{parameter_name}} placeholders in the prompt AND in any template files with resolved parameter values

Path resolution: When the prompt says "Read /docs/data-model.md," it means $COOKBOOK_PATH/docs/data-model.md. All paths in prompts are relative to the cookbook root.

d. Print phase header

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 Phase [N]/[total]: [phase-id]
   [goal from prompt's Goal section]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

e. Execute the prompt

Follow the prompt's instructions completely:

• Read all Context Files listed
• Follow the Steps in order
• Run all specified commands
• Create all described files and code
• Copy templates from $COOKBOOK_PATH/templates/ to the project directory, substituting {{parameter}} placeholders
• Copy fixtures/samples from $COOKBOOK_PATH/samples/ where referenced
• Pay special attention to the ⚠️ Watch Out section — these are known gotcha areas

f. Check success criteria

Before running the validation script, check the prompt's Success Criteria yourself:

• Run each lis