# Handoff Protocol — Spec File Parsing

How downstream commands locate and parse the spec file produced by `:plan`.

---

## Locating the Spec

1. Derive slug from `$ARGUMENTS` (the first argument passed to the command)
2. Spec path: `courses/specs/{slug}-spec.md`
3. If file not found, list `courses/specs/*.md` and suggest the closest match

## Validating Status

Read the `**Status:**` field in the spec header. See `${CLAUDE_PLUGIN_ROOT}/shared/status-definitions.md` for full acceptance rules per command.

| Status | Meaning |
|--------|---------|
| `DRAFT` | Spec not yet approved. Do not proceed. |
| `APPROVED` | Spec approved, ready for `:create` |
| `CREATED` | Course MD + JSON generated, ready for `:audit` |
| `GENERATED — audit passed` | Content audited, ready for `:assets`, `:visuals`, `:game` |
| `REFINED — v{X.Y.Z}` | Course verified against pipeline v{X.Y.Z}. Accepted by all commands that accept `GENERATED` |

## Detecting Archetype

Read the `**Archetype:**` field in the spec header.
- If `Concept Sprint` or field is absent → use concept sprint extraction rules below
- If `Hands-On` → use hands-on extraction rules (see bottom of this document)

## Extracting Sections

Parse spec by markdown heading:

| Section | Heading | Used by |
|---------|---------|---------|
| Identity | `## The Two Names` | `:create` |
| Genre direction | `## Genre Direction` | `:create`, `:audit`, `:visuals` (Concept Sprint only) |
| Creative decisions | `## Creative Decisions` | `:create`, `:audit` |
| Structural decisions | `## Structural Decisions` | `:create`, `:audit` |
| Visual direction | `## Visual Direction` (placeholder) | `:visuals` (generates art-direction.md) |
| Game concept | `## Game Concept` | `:game`, `:assets` |
| Story arc | `## Story Arc Summary` | `:create` |
| Blueprint | `## Course Blueprint` | `:create`, `:audit`, `:game` |
| Research | `## Research Summary (Appendix)` | `:create` |
| Research Registry | `### Research Registry` (within Research Summary) | `:create`, `:audit` |
| Batch variety | `## Batch Variety Notes` | `:create` |

**v7.3.0:** The Art Direction Brief is generated by `:visuals` Phase 2 and stored in `visuals/{slug}/art-direction.md`, NOT in the spec. Specs created under v7.3.0+ have a placeholder `## Visual Direction` section only. Legacy specs may still contain `## Art Direction Brief` — `:visuals` handles both cases.

## Building the Constraint Block

For `:create`, assemble these fields from the spec into the generation constraint block:

**Genre:** Read from spec `## Genre Direction > **Genre:**`. Accepted values: Literary Journalism, Investigative Journalism, Industry Epic, Corporate Biography, Geopolitical Analysis, Behavioral Science, Legal/Regulatory Thriller, Practitioner Memoir.

**Backward compatibility:** If spec has no `## Genre Direction` section, check for `## Framing Direction`. Auto-map using the migration table in `generation-guide/genre-system.md`:
- Framework-first → score research signals → Behavioral Science (default) or Practitioner Memoir
- Story-first: Historical Novella → score signals → Literary Journalism (default) or other story genre
- Braided Story → score for base genre + Braided Technique modifier

```
Genre: [from Genre Direction > Genre]
Genre Prose Mechanisms: [from Genre Direction > Genre Prose Mechanisms — list of 4]
Genre DO NOTs: [from Genre Direction > Genre DO NOTs — list of 3-4]
Braided Technique: [No / Yes: {details}]
Provocation Level: [from Genre Direction > Provocation Level]
Voice: [from Creative Decisions > Voice]
Layer 1 title: [from The Two Names > Layer 1]
Layer 2 skill: [from The Two Names > Layer 2]
Description: [from The Two Names > Course Description — if present]
Framework type: [from Structural Decisions > Framework]
Artifact type: [from Structural Decisions > Artifact]
Artifact rendering: [from Structural Decisions > Artifact > Rendering — "Narrative" or "Table (NxM)"]
Artifact intro: [from Structural Decisions > Artifact > Intro]
Screen 4 contrast: [from Creative Decisions > Screen 4]
Screen 7 twist: [from Creative Decisions > Screen 7]
Screen 9 framing: [from Creative Decisions > Screen 9]
Screen 12 format: [from Creative Decisions > Screen 12]
Screen 14 synthesis: [from Creative Decisions > Screen 14]
Screen 15 interview: [from Creative Decisions > Screen 15]
Screen 1 scene-entry: [from Creative Decisions > Scene-Entry Plan > Screen 1]
Scene-entry distribution: [from Creative Decisions > Scene-Entry Plan > Distribution]
Research Registry: [from Research Summary > Research Registry — R-number lookup map, or "none" if absent]
```

### Blueprint Detection

Check for the `## Course Blueprint` heading in the spec:
- **Present** → Multi-artifact mode. Extract blueprint data below.
- **Absent** → Default mode. Skip blueprint extraction. Standard single-game, single-interview behavior.

### Extracting Blueprint Data (Multi-artifact only)

From `## Course Blueprint`, extract:
- **Mode:** Always `Multi-artifact` (if section exists)
- **Total Screens:** integer
- **Interactive Block Counts:** Games, Retention, Applied, Current-Affairs
- **Screen Architecture table:** Parse markdown table into ordered list of `{screen_number, type, interactive_block, justification}`
- **Game Placements table:** Parse into list of `{game_number, position_after_screen, mechanic, design_doc}`
- **Interview Subtype Framings table:** Parse into list of `{subtype, screen_number, framing, block_type}`

Add to the constraint block:
```
Blueprint Mode: Multi-artifact
Blueprint Screen Count: [N]
Blueprint Architecture: [parsed table]
Game Placements: [parsed table]
Interview Subtypes: [parsed table]
```

---

## Extracting Research Data

For `:create`, extract from `## Research Summary (Appendix)`:
- Company Examples table (with Verification column) — for Screens 1, 2, 4, 5, 8
- Counterintuitive Finding — for Screen 7
- Domain Metrics table — for Screens 5, 8, 13
- Failure Case — for Screen 9 or 12
- Expert Practice — for Screen 12
- Glossary Terms table — for MCQ glossary cards
- Course Generation Brief — for narrative hooks across all story screens

### Company Examples Table Format

The Company Examples table must include a `Verification` column tracking research validation status:

| Company | Claim | Sources | Verification |
|---------|-------|---------|-------------|
| Example Corp | 26% quarterly growth | Deloitte case study, AWS case study | VERIFIED |
| Acme Inc | Reduced churn by 40% | Company blog post only | MEDIUM RISK |
| GlobalTech | Embedded consultants for 6 weeks | No independent source found | REMOVED |

**Verification statuses:**
- **VERIFIED** — 2+ independent corroborating sources found
- **PLAUSIBLE** — 1 source (not company marketing)
- **MEDIUM RISK** — 1 source (company's own marketing only)
- **REMOVED** — 0 sources; content must not appear in spec or downstream content

**No company case study enters the spec without a verification status annotation. Claims with status REMOVED must not appear in the spec or downstream content.**

### Extracting Research Registry

If `### Research Registry` exists in the spec's Research Summary:
- Parse the R-number table into a lookup map: `{R_number → {claim, type, source_url, evidence, verification, hedging}}`
- Pass to `:create` as part of the constraint block (field: `Research Registry`)
- Pass to `:audit` Agent 5 as the claim verification baseline

**Backward compatibility:** If `### Research Registry` is absent (spec created pre-v8.1), fall back to the Company Examples table's Verification column. The Registry provides per-claim granularity; the Company Examples table provides per-company granularity. Both work; Registry is preferred.

## Extracting Course Narrative (for :visuals, :game, and :assets)

After `:create` runs, downstream commands read the course markdown (`courses/{slug}-concept-sprint.md` for Concept Sprint or `courses/{slug}-hands-on-guide.md` for Hands-On) to extract:
- Company names and stories (Screens 1, 2, 4)
- Artifact structure and data (Screen 5)
- Framework name and stages (Screen 6)
- Twist/tension details (Screens 7, 9)
- Key concepts from MCQs and glossary terms

---

## Hands-On Extraction Rules

When archetype is `Hands-On`, the spec has different sections:

| Section | Heading | Used by |
|---------|---------|---------|
| Identity | `## The Two Names` | `:create` |
| Screen Plan | `## Screen Plan` (replaces Creative/Structural Decisions) | `:create` |
| Visual Direction | `## Visual Direction` (placeholder) | `:visuals` (generates art-direction.md) |
| Game Concept | `## Game` | `:game`, `:assets` |
| Research | `## Research Summary (Appendix)` | `:create` |

### Building the Constraint Block (Hands-On)

For `:create`, assemble these fields from the hands-on spec:

```
Archetype: Hands-On
Voice: The Instructor (fixed)
Layer 1 title: [from The Two Names > Layer 1]
Layer 2 skill: [from The Two Names > Layer 2]
Description: [from Course Description — if present]
Screen count: [from Screen Plan > Screen Count]
Screen plan: [from Screen Plan > table]
Opening hook: [from Opening Hook]
Depth level: [from Depth Level]
Artifact details: [from Artifact Details]
Video details: [from Video Details]
```

### Extracting Research Data (Hands-On)

For `:create`, extract from `## Research Summary (Appendix)`:
- Tool Features table — for demo screens
- Common Pain Points — for intro hook and tip screens
- Step-by-step Workflows — for demo screen sequencing
- Common Errors — for try_it MCQs and tip screens
- Glossary Terms table — for glossary cards (if any)

---

## Stage Artifact Manifest

What files exist after each stage completes. Used by downstream commands to locate artifacts without globbing.

### After :plan (status: APPROVED)
- `courses/specs/{slug}-spec.md`

### After :create (status: CREATED)
- `courses/specs/{slug}-spec.md`
- `courses/{slug}-concept-sprint.md` (Concept Sprint) OR `courses/{slug}-hands-on-guide.md` (Hands-On)
- `courses/JSONS/{slug}.json`

### After :audit (status: GENERATED — audit passed)
- Same as CREATED (files may be modified by rectification)

### After :visuals
- `visuals/{slug}/art-direction.md` (v7.3.0+)
- `visuals/{slug}/visual-0-cover.png`
- `visuals/{slug}/visual-0-cover-mobile.png`
- `visuals/{slug}/visual-{1..N}.png`
- `visuals/{slug}/prompts.md`

### After :game
- `games/{slug}/design.md` (single game) OR `games/{slug}/design-{N}.md` (multi-game)
- `games/{slug}/{slug}-game.html` (single game) OR `games/{slug}/{slug}-game-{N}.html` (multi-game)

### After :db-insert
- `courses/sql/{slug}-insert.sql`

---

## Standard Context Load Protocol

Every command follows this 3-step opening pattern. Commands that already follow this (`:create`, `:audit`) serve as reference implementations.

### Step 1: Validate Prerequisites
1. Read `${CLAUDE_PLUGIN_ROOT}/shared/status-definitions.md`
2. Run the appropriate Validation Protocol (A/B/C/D) for this command
3. Locate and validate required artifacts per the Stage Artifact Manifest above
4. **ABORT** with prescriptive error message if any prerequisite fails

### Step 2: Context Load (single parallel read)
Load ALL files needed for this command in a SINGLE message (parallel Read tool calls).
- Files are listed explicitly in each command's pipeline section
- No ad-hoc file reads later in the pipeline
- The spec file and course files are included in this parallel read

### Step 3: Extract & Parse
Parse loaded files for the specific data needed by this command:
- Build constraint blocks from spec sections
- Extract visual direction, game concept, or research data
- Identify archetype to determine downstream branching

**Reference implementations:**
- `:create` Steps 1-3 (cleanest pattern)
- `:audit` Steps 1-2