cluesmith · waleedkadous · Feb 23, 2026 · Feb 23, 2026 · Feb 23, 2026
diff --git a/.claude/skills/af/SKILL.md b/.claude/skills/af/SKILL.md
@@ -103,14 +103,20 @@ Edit `af-config.json` at project root to customize shell commands.
 
 ## Pre-Spawn Checklist
 
-**Before `af spawn`, commit all local changes.** Builders work in git worktrees
-branched from HEAD — uncommitted files (specs, plans, codev updates) are invisible
-to the builder. The spawn command will refuse if the worktree is dirty (override
-with `--force`).
+**Before every `af spawn`:**
+
+1. **`git status`** — Check for uncommitted changes
+2. **Commit if dirty** — Builders branch from HEAD; uncommitted specs/plans are invisible
+3. **Include `--protocol`** — It is **REQUIRED** for all numbered spawns (e.g., `af spawn 42 --protocol spir`)
+
+The spawn command will refuse if the worktree is dirty (override with `--force`,
+but the builder won't see uncommitted files).
 
 ## Common Mistakes
 
+- **Forgetting `--protocol`** — `af spawn 42` fails; use `af spawn 42 --protocol spir` (or bugfix, tick, etc.)
 - **Spawning with uncommitted changes** — builder won't see specs, plans, or codev updates
+- **Running `git pull` after spawn failure** — Usually unnecessary; check `git status` first, commit, then retry
 - There is NO `codev tower` command — Tower is managed via `af tower`
 - There is NO `restart` subcommand — stop then start
 - There is NO `af start` for Tower — use `af tower start` or `af workspace start`
diff --git a/codev-skeleton/.claude/skills/af/SKILL.md b/codev-skeleton/.claude/skills/af/SKILL.md
@@ -103,14 +103,20 @@ Edit `af-config.json` at project root to customize shell commands.
 
 ## Pre-Spawn Checklist
 
-**Before `af spawn`, commit all local changes.** Builders work in git worktrees
-branched from HEAD — uncommitted files (specs, plans, codev updates) are invisible
-to the builder. The spawn command will refuse if the worktree is dirty (override
-with `--force`).
+**Before every `af spawn`:**
+
+1. **`git status`** — Check for uncommitted changes
+2. **Commit if dirty** — Builders branch from HEAD; uncommitted specs/plans are invisible
+3. **Include `--protocol`** — It is **REQUIRED** for all numbered spawns (e.g., `af spawn 42 --protocol spir`)
+
+The spawn command will refuse if the worktree is dirty (override with `--force`,
+but the builder won't see uncommitted files).
 
 ## Common Mistakes
 
+- **Forgetting `--protocol`** — `af spawn 42` fails; use `af spawn 42 --protocol spir` (or bugfix, tick, etc.)
 - **Spawning with uncommitted changes** — builder won't see specs, plans, or codev updates
+- **Running `git pull` after spawn failure** — Usually unnecessary; check `git status` first, commit, then retry
 - There is NO `codev tower` command — Tower is managed via `af tower`
 - There is NO `restart` subcommand — stop then start
 - There is NO `af start` for Tower — use `af tower start` or `af workspace start`
diff --git a/codev-skeleton/resources/commands/agent-farm.md b/codev-skeleton/resources/commands/agent-farm.md
@@ -146,20 +146,30 @@ Does NOT clean up worktrees - use `af cleanup` for that.
 Spawn a new builder.
 
 ```bash
-af spawn [issue-number] [options]
+af spawn [issue-number] --protocol <name> [options]
 ```
 
 **Arguments:**
 - `issue-number` - Issue number to build (positional, e.g., `42`)
 
+**Required:**
+- `--protocol <name>` - Protocol to use: spir, bugfix, tick, maintain, experiment. **REQUIRED** for all numbered spawns. Only `--task`, `--shell`, and `--worktree` spawns skip this flag.
+
 **Options:**
-- `--task <text>` - Spawn builder with a task description
-- `--protocol <name>` - Spawn builder to run a protocol
-- `--shell` - Spawn a bare Claude session
-- `--worktree` - Spawn worktree session
+- `--task <text>` - Spawn builder with a task description (no `--protocol` needed)
+- `--shell` - Spawn a bare Claude session (no `--protocol` needed)
+- `--worktree` - Spawn worktree session (no `--protocol` needed)
 - `--files <files>` - Context files (comma-separated)
 - `--no-role` - Skip loading role prompt
 
+**Preconditions:**
+
+The spawn command requires a **clean git worktree**. Before spawning:
+
+1. Run `git status` to check for uncommitted changes
+2. Commit any pending changes — builders branch from HEAD, so uncommitted specs/plans are invisible to the builder
+3. The command will refuse to spawn if the worktree is dirty (override with `--force`, but the builder won't see your uncommitted files)
+
 **Description:**
 
 Creates a new builder in an isolated git worktree. The builder gets:
@@ -170,19 +180,30 @@ Creates a new builder in an isolated git worktree. The builder gets:
 **Examples:**
 
 ```bash
-# Spawn builder for issue #42
-af spawn 42
+# Spawn builder for issue #42 — --protocol is REQUIRED
+af spawn 42 --protocol spir
 
-# Spawn with task description
+# Spawn builder for a bugfix
+af spawn 42 --protocol bugfix
+
+# Spawn with task description (no --protocol needed)
 af spawn --task "Fix login bug in auth module"
 
-# Spawn bare Claude session
+# Spawn bare Claude session (no --protocol needed)
 af spawn --shell
 
 # Spawn with context files
-af spawn 42 --files "src/auth.ts,tests/auth.test.ts"
+af spawn 42 --protocol spir --files "src/auth.ts,tests/auth.test.ts"
 ```
 
+**Common Errors:**
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "Missing required flag: --protocol" | Forgot `--protocol` | Add `--protocol spir` (or bugfix, tick, etc.) |
+| "Dirty worktree" | Uncommitted changes | Run `git status`, commit changes, retry |
+| "Builder already exists" | Worktree collision | Use `--resume` to resume, or `af cleanup` first |
+
 ---
 
 ### af status
@@ -532,7 +553,7 @@ Or override via CLI flags:
 
 ```bash
 af workspace start --architect-cmd "claude --model opus"
-af spawn 42 --builder-cmd "claude --model haiku"
+af spawn 42 --protocol spir --builder-cmd "claude --model haiku"
 ```
 
 ---

diff --git a/codev-skeleton/roles/architect.md b/codev-skeleton/roles/architect.md
@@ -16,30 +16,42 @@ Builders work autonomously in isolated git worktrees. The Architect:
 
 | Mode | Command | Use When |
 |------|---------|----------|
-| **Strict** (default) | `af spawn XXXX` | Porch orchestrates - runs autonomously to completion |
-| **Soft** | `af spawn XXXX --soft` | AI follows protocol - you verify compliance |
+| **Strict** (default) | `af spawn XXXX --protocol spir` | Porch orchestrates - runs autonomously to completion |
+| **Soft** | `af spawn XXXX --protocol spir --soft` | AI follows protocol - you verify compliance |
 
 **Strict mode** (default): Porch orchestrates the builder with automated gates, 3-way consultations, and enforced phase transitions. More likely to complete autonomously without intervention.
 
 **Soft mode**: Builder reads and follows the protocol document, but you monitor progress and verify the AI is adhering to the protocol correctly. Use when you want more hands-on oversight.
 
+### Pre-Spawn Checklist
+
+**Before every `af spawn`, complete these steps:**
+
+1. **`git status`** — Ensure worktree is clean (no uncommitted changes)
+2. **Commit if needed** — Builders branch from HEAD; uncommitted specs/plans are invisible
+3. **`af spawn N --protocol <name>`** — `--protocol` is **REQUIRED** (spir, bugfix, tick, etc.)
+
+The spawn command will refuse if the worktree is dirty (override with `--force`, but your builder won't see uncommitted files).
+
 ## Key Tools
 
 ### Agent Farm CLI (`af`)
 
 ```bash
-af spawn 1                          # Strict mode (default) - porch-driven
-af spawn 1 -t "feature"             # Strict mode with title (no spec yet)
-af spawn 1 --resume                 # Resume existing porch state
-af spawn 1 --soft                   # Soft mode - protocol-guided
-af spawn --task "fix the bug"             # Ad-hoc task builder (soft mode)
-af spawn --worktree                       # Worktree with no initial prompt
-af status                                 # Check all builders
-af cleanup -p 0001                        # Remove completed builder
-af workspace start/stop                   # Workspace management
-af send 0001 "message"                    # Short message to builder
+af spawn 1 --protocol spir               # Strict mode (default) - porch-driven
+af spawn 1 --protocol spir -t "feature"  # Strict mode with title (no spec yet)
+af spawn 1 --resume                      # Resume existing porch state
+af spawn 1 --protocol spir --soft        # Soft mode - protocol-guided
+af spawn --task "fix the bug"            # Ad-hoc task builder (soft mode)
+af spawn --worktree                      # Worktree with no initial prompt
+af status                                # Check all builders
+af cleanup -p 0001                       # Remove completed builder
+af workspace start/stop                  # Workspace management
+af send 0001 "message"                   # Short message to builder
 ```
 
+> **Note:** `--protocol` is REQUIRED for all numbered spawns. Only `--task`, `--shell`, and `--worktree` spawns skip it.
+
 **Note:** `af`, `consult`, `porch`, and `codev` are global commands. They work from any directory.
 
 ### Porch CLI (for strict mode)
@@ -79,16 +91,20 @@ wait
 
 ```bash
 # 1. Create a GitHub Issue for the feature
-# 2. Spawn the builder
+# 2. Ensure worktree is clean: git status → commit if needed
+# 3. Spawn the builder (--protocol is REQUIRED)
 
 # Default: Strict mode (porch-driven with gates)
-af spawn 42
+af spawn 42 --protocol spir
 
 # With project title (if no spec exists yet)
-af spawn 42 -t "user-authentication"
+af spawn 42 --protocol spir -t "user-authentication"
 
 # Or: Soft mode (builder follows protocol independently)
-af spawn 42 --soft
+af spawn 42 --protocol spir --soft
+
+# For bugfixes
+af spawn 42 --protocol bugfix
 ```
 
 ### 2. Approving Gates (Strict Mode Only)
@@ -266,8 +282,9 @@ Before approving implementations with UX requirements:
 
 | Task | Command |
 |------|---------|
-| Start feature (strict, default) | `af spawn <id>` |
-| Start feature (soft) | `af spawn <id> --soft` |
+| Start feature (strict, default) | `af spawn <id> --protocol spir` |
+| Start feature (soft) | `af spawn <id> --protocol spir --soft` |
+| Start bugfix | `af spawn <id> --protocol bugfix` |
 | Check all builders | `af status` |
 | Check one project | `porch status <id>` |
 | Approve spec | `porch approve <id> spec-approval` |

diff --git a/codev/resources/commands/agent-farm.md b/codev/resources/commands/agent-farm.md
@@ -146,25 +146,35 @@ Does NOT clean up worktrees - use `af cleanup` for that.
 Spawn a new builder.
 
 ```bash
-af spawn [number] [options]
+af spawn [number] --protocol <name> [options]
 ```
 
 **Arguments:**
 - `[number]` - Issue number (positional)
 
+**Required:**
+- `--protocol <name>` - Protocol to use: spir, bugfix, tick, maintain, experiment. **REQUIRED** for all numbered spawns. Only `--task`, `--shell`, and `--worktree` spawns skip this flag.
+
 **Options:**
-- `--protocol <name>` - Protocol to use (spir, bugfix, tick, maintain, experiment)
-- `--task <text>` - Spawn builder with a task description
+- `--task <text>` - Spawn builder with a task description (no `--protocol` needed)
 - `--amends <number>` - Original spec number for TICK amendments
-- `--shell` - Spawn a bare Claude session
-- `--worktree` - Spawn worktree session
+- `--shell` - Spawn a bare Claude session (no `--protocol` needed)
+- `--worktree` - Spawn worktree session (no `--protocol` needed)
 - `--files <files>` - Context files (comma-separated)
 - `--soft` - Use soft mode (AI follows protocol, you verify compliance)
 - `--strict` - Use strict mode (porch orchestrates, default)
 - `--resume` - Resume an existing builder worktree
 - `--force` - Skip safety checks (dirty worktree, collision detection)
 - `--no-role` - Skip loading role prompt
 
+**Preconditions:**
+
+The spawn command requires a **clean git worktree**. Before spawning:
+
+1. Run `git status` to check for uncommitted changes
+2. Commit any pending changes — builders branch from HEAD, so uncommitted specs/plans/codev updates are invisible to the builder
+3. The command will refuse to spawn if the worktree is dirty (override with `--force`, but the builder won't see your uncommitted files)
+
 **Description:**
 
 Creates a new builder in an isolated git worktree. The builder gets:
@@ -175,7 +185,7 @@ Creates a new builder in an isolated git worktree. The builder gets:
 **Examples:**
 
 ```bash
-# Spawn builder for SPIR project (issue #42)
+# Spawn builder for SPIR project (issue #42) — --protocol is REQUIRED
 af spawn 42 --protocol spir
 
 # Spawn builder for a bugfix
@@ -184,10 +194,10 @@ af spawn 42 --protocol bugfix
 # Spawn TICK amendment to spec 30
 af spawn 42 --protocol tick --amends 30
 
-# Spawn with task description
+# Spawn with task description (no --protocol needed)
 af spawn --task "Fix login bug in auth module"
 
-# Spawn bare Claude session
+# Spawn bare Claude session (no --protocol needed)
 af spawn --shell
 
 # Spawn with context files
@@ -197,6 +207,14 @@ af spawn 42 --protocol spir --files "src/auth.ts,tests/auth.test.ts"
 af spawn 42 --resume
 ```
 
+**Common Errors:**
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "Missing required flag: --protocol" | Forgot `--protocol` | Add `--protocol spir` (or bugfix, tick, etc.) |
+| "Dirty worktree" | Uncommitted changes | Run `git status`, commit changes, retry |
+| "Builder already exists" | Worktree collision | Use `--resume` to resume, or `af cleanup` first |
+
 ---
 
 ### af status

diff --git a/codev/resources/workflow-reference.md b/codev/resources/workflow-reference.md
@@ -26,7 +26,7 @@ Quick reference for the 7-stage project workflow. For protocol details, see `cod
 │                               IMPLEMENTATION                                        │
 ├─────────────────────────────────────────────────────────────────────────────────────┤
 │  → 4. IMPLEMENTING                                                                  │
-│         Architect spawns builder: af spawn XXXX                                  │
+│         Architect spawns builder: af spawn XXXX --protocol spir                  │
 │         Builder reads spec and plan                                                 │
 │         For each phase: Implement → Defend → Evaluate                               │
 │         Builder commits after each phase                                            │
@@ -210,6 +210,35 @@ af cleanup -p XXXX          # Clean up builder worktree
 
 ## Troubleshooting
 
+### Spawn Failures
+
+Common `af spawn` errors and how to recover:
+
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| "Missing required flag: --protocol" | Forgot `--protocol` | Re-run with `--protocol spir` (or bugfix, tick, etc.) |
+| "Dirty worktree" / uncommitted changes | Pending changes in git | `git status` → commit changes → retry spawn |
+| "Builder already exists" | Worktree collision | Use `af spawn N --resume` to resume existing builder |
+
+**Recovery flow:**
+```bash
+# 1. Spawn fails
+af spawn 42 --protocol spir
+# Error: dirty worktree
+
+# 2. Check what's uncommitted
+git status
+
+# 3. Commit pending changes
+git add codev/specs/42-feature.md
+git commit -m "[Spec 42] Initial specification"
+
+# 4. Retry
+af spawn 42 --protocol spir
+```
+
+> **Tip:** Do NOT run `git pull` after a spawn failure unless you specifically need to sync with remote. The most common cause is uncommitted local changes, not a stale branch.
+
 ### Builder Reports Blocked
 
 1. Check builder terminal for blocker message