diff --git a/.claude/skills/af/SKILL.md b/.claude/skills/af/SKILL.md
index 4a9decfa..1ce852c0 100644
--- 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
index 53911381..8a329ddb 100644
--- 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
index 36f26659..bf143be2 100644
--- 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
index 21779c7d..4b0d3094 100644
--- 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
index 97c1ab58..479f0b2e 100644
--- a/codev/resources/commands/agent-farm.md
+++ b/codev/resources/commands/agent-farm.md
@@ -146,18 +146,20 @@ 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)
@@ -165,6 +167,14 @@ af spawn [number] [options]
 - `--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
index 5b829b56..e4da21cc 100644
--- 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
diff --git a/codev/roles/architect.md b/codev/roles/architect.md
index 21779c7d..4b0d3094 100644
--- a/codev/roles/architect.md
+++ b/codev/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/packages/codev/src/__tests__/bugfix-527-spawn-docs.test.ts b/packages/codev/src/__tests__/bugfix-527-spawn-docs.test.ts
new file mode 100644
index 00000000..db9a7042
--- /dev/null
+++ b/packages/codev/src/__tests__/bugfix-527-spawn-docs.test.ts
@@ -0,0 +1,81 @@
+/**
+ * Regression test for bugfix #527: af spawn docs must include --protocol
+ *
+ * Ensures all `af spawn <number>` examples in key documentation files
+ * include `--protocol` (or use an exempted form like --task, --shell,
+ * --worktree, --resume).
+ */
+
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// Resolve repo root (packages/codev -> repo root)
+const repoRoot = path.resolve(__dirname, '..', '..', '..', '..');
+
+/** Files that contain af spawn examples agents will read */
+const DOC_FILES = [
+  'codev-skeleton/roles/architect.md',
+  'codev/roles/architect.md',
+  'codev/resources/commands/agent-farm.md',
+  'codev-skeleton/resources/commands/agent-farm.md',
+  'codev/resources/workflow-reference.md',
+  '.claude/skills/af/SKILL.md',
+  'codev-skeleton/.claude/skills/af/SKILL.md',
+];
+
+/**
+ * Extract af spawn invocations from code blocks in a markdown file.
+ * Returns lines that match `af spawn <number>` (with a numeric arg).
+ */
+function extractSpawnLines(content: string): string[] {
+  const lines: string[] = [];
+  let inCodeBlock = false;
+
+  for (const line of content.split('\n')) {
+    if (line.trim().startsWith('```')) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+    if (inCodeBlock && /af spawn\s+\d/.test(line)) {
+      lines.push(line.trim());
+    }
+  }
+  return lines;
+}
+
+/**
+ * Check if a spawn line is exempted from requiring --protocol.
+ * Exempted: --resume, --task, --shell, --worktree
+ */
+function isExempted(line: string): boolean {
+  return /--resume|--task|--shell|--worktree/.test(line);
+}
+
+describe('bugfix-527: af spawn docs require --protocol', () => {
+  for (const relPath of DOC_FILES) {
+    const fullPath = path.join(repoRoot, relPath);
+
+    it(`${relPath} — all numbered af spawn examples include --protocol`, () => {
+      if (!fs.existsSync(fullPath)) {
+        // File doesn't exist in this context (e.g., skeleton not present) — skip
+        return;
+      }
+
+      const content = fs.readFileSync(fullPath, 'utf-8');
+      const spawnLines = extractSpawnLines(content);
+
+      const violations: string[] = [];
+      for (const line of spawnLines) {
+        if (!isExempted(line) && !line.includes('--protocol')) {
+          violations.push(line);
+        }
+      }
+
+      expect(
+        violations,
+        `Found af spawn examples without --protocol in ${relPath}:\n${violations.map(v => `  - ${v}`).join('\n')}`,
+      ).toHaveLength(0);
+    });
+  }
+});