# Skill Test Spec: /team-narrative ## Skill Summary Orchestrates the narrative team through a five-phase pipeline: narrative direction (narrative-director) → world foundation + dialogue drafting (world-builder and writer in parallel) → level narrative integration (level-designer) → consistency review (narrative-director) → polish + localization compliance (writer, localization-lead, and world-builder in parallel). Uses `AskUserQuestion` at each phase transition to present proposals as selectable options. Produces a narrative summary report and delivers narrative documents via subagents that each enforce the "May I write?" protocol. Verdict is COMPLETE when all phases succeed, or BLOCKED when a dependency is unresolved. --- ## Static Assertions (Structural) - [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools` - [ ] Has ≥2 phase headings - [ ] Contains verdict keywords: COMPLETE, BLOCKED - [ ] Contains "File Write Protocol" section - [ ] File writes are delegated to sub-agents — orchestrator does not write files directly - [ ] Sub-agents enforce "May I write to [path]?" before any write - [ ] Has a next-step handoff at the end (references `/design-review`, `/localize extract`, `/dev-story`) - [ ] Error Recovery Protocol section is present - [ ] `AskUserQuestion` is used at phase transitions before proceeding - [ ] Phase 2 explicitly spawns world-builder and writer in parallel - [ ] Phase 5 explicitly spawns writer, localization-lead, and world-builder in parallel --- ## Test Cases ### Case 1: Happy Path — All five phases complete, narrative doc delivered **Fixture:** - A game concept and GDD exist for the target feature (e.g., `design/gdd/faction-intro.md`) - Character voice profiles exist (e.g., `design/narrative/characters/`) - Existing lore entries exist for cross-reference (e.g., `design/narrative/lore/`) - No lore contradictions exist between existing entries and the new content **Input:** `/team-narrative faction introduction cutscene for the Ironveil faction` **Expected behavior:** 1. Phase 1: narrative-director is spawned; outputs a narrative brief defining the story beat, characters involved, emotional tone, and lore dependencies 2. `AskUserQuestion` presents the narrative brief; user approves before Phase 2 begins 3. Phase 2: world-builder and writer are spawned in parallel; world-builder produces lore entries for the Ironveil faction; writer drafts dialogue lines using character voice profiles 4. `AskUserQuestion` presents world foundation and dialogue drafts; user approves before Phase 3 begins 5. Phase 3: level-designer is spawned; produces environmental storytelling layout, trigger placement, and pacing plan 6. `AskUserQuestion` presents level narrative plan; user approves before Phase 4 begins 7. Phase 4: narrative-director reviews all dialogue against voice profiles, verifies lore consistency, confirms pacing; approves or flags issues 8. `AskUserQuestion` presents review results; user approves before Phase 5 begins 9. Phase 5: writer, localization-lead, and world-builder are spawned in parallel; writer performs final self-review; localization-lead validates i18n compliance; world-builder finalizes canon levels 10. Final summary report is presented; subagent asks "May I write the narrative document to [path]?" before writing 11. Verdict: COMPLETE **Assertions:** - [ ] narrative-director is spawned in Phase 1 before any other agents - [ ] `AskUserQuestion` appears after Phase 1 output and before Phase 2 launch - [ ] world-builder and writer Task calls are issued simultaneously in Phase 2 (not sequentially) - [ ] level-designer is not launched until Phase 2 `AskUserQuestion` is approved - [ ] narrative-director is re-spawned in Phase 4 for consistency review - [ ] Phase 5 spawns all three agents (writer, localization-lead, world-builder) simultaneously - [ ] Summary report includes: narrative brief status, lore entries created/updated, dialogue lines written, level narrative integration points, consistency review results - [ ] No files are written by the orchestrator directly - [ ] Verdict is COMPLETE after delivery --- ### Case 2: Lore Contradiction Found — world-builder finds conflict before writer proceeds **Fixture:** - Existing lore entry at `design/narrative/lore/ironveil-history.md` states the Ironveil faction was founded 200 years ago - The new narrative brief (from Phase 1) states the Ironveil were founded 50 years ago - The writer has been spawned in parallel with the world-builder in Phase 2 **Input:** `/team-narrative ironveil faction introduction cutscene` **Expected behavior:** 1. Phases 1–2 begin normally 2. Phase 2 world-builder detects a factual contradiction between the narrative brief and existing lore: founding date conflict 3. world-builder returns BLOCKED with reason: "Lore contradiction found — founding date conflicts with `design/narrative/lore/ironveil-history.md`" 4. Orchestrator surfaces the contradiction immediately: "world-builder: BLOCKED — Lore contradiction: founding date in narrative brief (50 years ago) conflicts with existing canon (200 years ago in `ironveil-history.md`)" 5. Orchestrator assesses dependency: the writer's dialogue depends on canon lore — the writer's draft cannot be finalized without resolving the contradiction 6. `AskUserQuestion` presents options: - Revise the narrative brief to match existing canon (200 years ago) - Update the existing lore entry to reflect the new canon (50 years ago) - Stop here and resolve the contradiction in the lore docs first 7. Writer output is preserved but flagged as pending canon resolution — work is not discarded 8. Orchestrator does NOT proceed to Phase 3 until the contradiction is resolved or user explicitly chooses to skip **Assertions:** - [ ] Contradiction is surfaced before Phase 3 begins - [ ] Orchestrator does not silently resolve the contradiction by picking one version - [ ] `AskUserQuestion` presents at least 3 options including "stop and resolve first" - [ ] Writer's draft output is preserved in the partial report, not discarded - [ ] Phase 3 (level-designer) is not launched until the user resolves the contradiction - [ ] Verdict is BLOCKED (not COMPLETE) if the user stops to resolve the contradiction --- ### Case 3: No Argument — Usage guidance shown **Fixture:** - Any project state **Input:** `/team-narrative` (no argument) **Expected behavior:** 1. Skill detects no argument is provided 2. Outputs usage guidance: e.g., "Usage: `/team-narrative [narrative content description]` — describe the story content, scene, or narrative area to work on (e.g., `boss encounter cutscene`, `faction intro dialogue`, `tutorial narrative`)" 3. Skill exits without spawning any agents **Assertions:** - [ ] Skill does NOT spawn any agents when no argument is provided - [ ] Usage message includes the correct invocation format with an argument example - [ ] Skill does NOT attempt to guess or infer a narrative topic from project files - [ ] No `AskUserQuestion` is used — output is direct guidance --- ### Case 4: Localization Compliance — localization-lead flags a non-translatable string **Fixture:** - Phases 1–4 complete successfully - Phase 5 begins; writer and world-builder complete without issues - localization-lead finds a dialogue line that uses a hardcoded formatted date string (e.g., `"On March 12th, Year 3"`) that cannot survive locale-specific translation without a locale-aware formatter **Input:** `/team-narrative ironveil faction introduction cutscene` (Phase 5 scenario) **Expected behavior:** 1. Phase 5 spawns writer, localization-lead, and world-builder in parallel 2. localization-lead completes its review and flags: "String key `dialogue.ironveil.intro.003` contains a hardcoded date format (`March 12th, Year 3`) that will not localize correctly — requires a locale-aware date placeholder" 3. Orchestrator surfaces the localization blocker in the summary report 4. The localization issue is labeled as BLOCKING in the final report (not advisory) 5. `AskUserQuestion` presents options: - Fix the string now (writer revises the line) - Note the gap and deliver the narrative doc with the issue flagged - Stop and resolve before finalizing 6. If the user chooses to proceed with the issue flagged, verdict is COMPLETE with noted localization debt; if user stops, verdict is BLOCKED **Assertions:** - [ ] localization-lead is spawned in Phase 5 simultaneously with writer and world-builder - [ ] Hardcoded date format is identified as a localization blocker (not silently passed) - [ ] The specific string key and reason are included in the issue report - [ ] `AskUserQuestion` offers the option to fix now vs. flag and proceed - [ ] Verdict notes the localization debt if the user proceeds without fixing - [ ] Skill does NOT automatically rewrite the offending line without user approval --- ### Case 5: Writer Blocked — Missing character voice profiles **Fixture:** - Phase 1 narrative-director produces a narrative brief referencing two characters: Commander Varek and Advisor Selene - No character voice profiles exist in `design/narrative/characters/` for either character - Phase 2 begins; world-builder proceeds normally **Input:** `/team-narrative ironveil surrender negotiation scene` **Expected behavior:** 1. Phase 1 completes; narrative brief lists Commander Varek and Advisor Selene as characters 2. Phase 2: writer is spawned in parallel with world-builder 3. writer returns BLOCKED: "Cannot produce dialogue — no voice profiles found for Commander Varek or Advisor Selene in `design/narrative/characters/`. Voice profiles required to match character tone and speech patterns." 4. Orchestrator surfaces the blocker immediately: "writer: BLOCKED — Missing prerequisite: character voice profiles for Commander Varek and Advisor Selene" 5. world-builder output is preserved; partial report is produced with lore entries 6. `AskUserQuestion` presents options: - Create voice profiles first (redirects to the narrative-director or design workflow) - Provide minimal voice direction inline and retry the writer with that context - Stop here and create voice profiles before proceeding 7. Orchestrator does NOT proceed to Phase 3 (level-designer) without writer output **Assertions:** - [ ] Writer block is surfaced before Phase 3 begins - [ ] world-builder's completed lore output is preserved in the partial report - [ ] Missing prerequisite (voice profiles) is named specifically (character names and expected file path) - [ ] `AskUserQuestion` offers at least one option to resolve the missing prerequisite - [ ] Orchestrator does not fabricate voice profiles or invent character voices - [ ] Phase 3 is not launched while writer is BLOCKED without explicit user authorization --- ## Protocol Compliance - [ ] `AskUserQuestion` is used after every phase output before the next phase launches - [ ] Parallel spawning: Phase 2 (world-builder + writer) and Phase 5 (writer + localization-lead + world-builder) issue all Task calls before waiting for results - [ ] No files are written by the orchestrator directly — all writes are delegated to sub-agents - [ ] Each sub-agent enforces the "May I write to [path]?" protocol before any write - [ ] BLOCKED status from any agent is surfaced immediately — not silently skipped - [ ] A partial report is always produced when some agents complete and others block - [ ] Verdict is exactly COMPLETE or BLOCKED — no other verdict values used - [ ] Next Steps handoff references `/design-review`, `/localize extract`, and `/dev-story` --- ## Coverage Notes - Phase 3 (level-designer) and Phase 4 (narrative-director review) happy-path behavior are validated implicitly by Case 1. Separate edge cases are not needed for these phases as their failure modes follow the standard Error Recovery Protocol. - The "Retry with narrower scope" and "Skip this agent" resolution paths from the Error Recovery Protocol are not separately tested — they follow the same `AskUserQuestion` + partial-report pattern validated in Cases 2 and 5. - Localization concerns that are advisory (e.g., German/Finnish +30% expansion warnings) vs. blocking (hardcoded formats) are distinguished in Case 4; advisory-only scenarios follow the same pattern but do not change the verdict. - The writer's "all lines under 120 characters" and "string keys not raw strings" checks in Phase 5 are covered implicitly by Case 4's localization compliance scenario.