210 lines
12 KiB
Markdown
210 lines
12 KiB
Markdown
# 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.
|