Release v0.2.0: Context Resilience, AskUserQuestion, /design-systems

* Add context resilience: file-backed state, incremental writing, auto-recovery

Prevents "prompt too long" crashes from killing sessions by persisting work
to disk incrementally instead of relying on conversation memory.

Changes:
- pre-compact.sh: dumps session state before context compression
- session-start.sh: detects active.md for crash recovery
- session-stop.sh: archives and clears active.md on clean shutdown
- context-management.md: file-backed state as primary strategy
- 9 agents updated with incremental section writing protocol
  (game-designer, systems-designer, economy-designer, narrative-director,
   level-designer, world-builder, writer, art-director, audio-director)
- CLAUDE.md: trimmed redundant imports (10 → 5) to reduce token overhead
- design-docs.md rule: enforces incremental writing pattern
- .gitignore: excludes ephemeral session state files
- directory-structure.md: documents session-state/ and session-logs/
- COLLABORATIVE-DESIGN-PRINCIPLE.md: documents incremental writing pattern

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add AskUserQuestion integration across collaborative protocols

Explicitly reference the AskUserQuestion tool in all collaborative agent
definitions, protocol templates, team orchestrator skills, and the master
principle doc. Introduces the Explain-then-Capture pattern: agents write
full expert analysis in conversation, then call AskUserQuestion with
concise labels to capture decisions via structured UI.

26 files updated:
- 3 protocol templates (design, leadership, implementation)
- 14 agent definitions (10 design + 3 leadership + writer)
- 8 orchestrator skills (brainstorm + 7 team-*)
- 1 master principle doc (COLLABORATIVE-DESIGN-PRINCIPLE.md)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Add /design-systems skill: concept-to-GDD decomposition workflow

Bridges the gap between game concept and per-system design documents.
Professional studios use systems enumeration + dependency sorting between
concept and feature docs — skipping this step is one of the most expensive
mistakes (systems discovered during production cost 5-10x more to add).

New files:
- .claude/skills/design-systems/SKILL.md — 7-phase orchestration skill
  (enumerate systems, map dependencies, assign priorities, write GDDs)
- .claude/docs/templates/systems-index.md — master tracking template

Flow integration (7 existing skills updated):
- brainstorm, start, setup-engine, design-review, gate-check,
  project-stage-detect, game-concept template all reference /design-systems
  at the appropriate workflow touchpoints

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Fix cross-platform bugs, add missing tool permissions, and update docs for v0.2.0

Hooks: fix \s → [[:space:]] in grep -E fallbacks (3 files), fix detect-gaps.sh
empty-variable bug, fix log-agent.sh field name (agent_name → agent_type),
harden validate-push.sh with explicit $MATCHED_BRANCH, convert for-in loops
to while-read for space-safe iteration, add POSIX head -n syntax, increase
PreCompact timeout, widen session-stop log window.

Skills: add AskUserQuestion to 10 skills and TodoWrite to 8 multi-phase skills.
Fix project-stage-detect template/output paths, tech-artist → technical-artist.

Docs: add /design-systems to all references (README, quick-start, workflow guide,
skills-reference), update skill count 35 → 36, remove stale AI artifacts from
COLLABORATIVE-DESIGN-PRINCIPLE.md, add AskUserQuestion note to examples README.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

.claude/agents/art-director.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
-   - Create sections iteratively (show one section, get feedback, refine)
+3. **Draft based on user's choice (incremental file writing):**
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Show the draft section or summary
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Art Bible Maintenance**: Create and maintain the art bible defining style,

.claude/agents/audio-director.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
-   - Create sections iteratively (show one section, get feedback, refine)
+3. **Draft based on user's choice (incremental file writing):**
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Show the draft section or summary
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Sound Palette Definition**: Define the sonic palette for the game --

.claude/agents/creative-director.md

@@ -154,6 +154,24 @@ You: [Creates ADR, updates docs, notifies relevant agents]
 - Once decided, commit fully — document and cascade the decision
 - Set up success metrics — "we'll know this was right if..."
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI.
+Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full strategic analysis in conversation: options with
+   pillar alignment, downstream consequences, risk assessment, recommendation.
+2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
+
+**Guidelines:**
+- Use at every decision point (strategic options in step 3, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence with key trade-off.
+- Add "(Recommended)" to your preferred option's label
+- For open-ended context gathering, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Vision Guardianship**: Maintain and communicate the game's core pillars,

.claude/agents/economy-designer.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
-   - Create sections iteratively (show one section, get feedback, refine)
+3. **Draft based on user's choice (incremental file writing):**
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Show the draft section or summary
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Resource Flow Modeling**: Map all resource sources (faucets) and sinks in

.claude/agents/game-designer.md

@@ -33,14 +33,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
-   - Create sections iteratively (show one section, get feedback, refine)
+3. **Draft based on user's choice (incremental file writing):**
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Show the draft section or summary
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -53,6 +58,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Core Loop Design**: Define and refine the moment-to-moment, session, and

.claude/agents/level-designer.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
-   - Create sections iteratively (show one section, get feedback, refine)
+3. **Draft based on user's choice (incremental file writing):**
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Show the draft section or summary
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Level Layout Design**: Create top-down layout documents for each level/area

.claude/agents/live-ops-designer.md

@@ -48,6 +48,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ## Core Responsibilities
 - Design seasonal content calendars and event cadences
 - Plan battle passes, seasons, and time-limited content

.claude/agents/narrative-director.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
-   - Create sections iteratively (show one section, get feedback, refine)
+3. **Draft based on user's choice (incremental file writing):**
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Show the draft section or summary
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Story Architecture**: Design the narrative structure -- act breaks, major

.claude/agents/producer.md

@@ -58,6 +58,24 @@ When the user asks you to make a decision or resolve a conflict:
 - Once decided, commit fully — document and cascade the decision
 - Set up success metrics — "we'll know this was right if..."
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI.
+Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full strategic analysis in conversation: options with
+   pillar alignment, downstream consequences, risk assessment, recommendation.
+2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
+
+**Guidelines:**
+- Use at every decision point (strategic options in step 3, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence with key trade-off.
+- Add "(Recommended)" to your preferred option's label
+- For open-ended context gathering, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Sprint Planning**: Break milestones into 1-2 week sprints with clear,

.claude/agents/systems-designer.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
-   - Create sections iteratively (show one section, get feedback, refine)
+3. **Draft based on user's choice (incremental file writing):**
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Show the draft section or summary
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Formula Design**: Create mathematical formulas for damage, healing, XP

.claude/agents/technical-director.md

@@ -57,6 +57,24 @@ When the user asks you to make a decision or resolve a conflict:
 - Once decided, commit fully — document and cascade the decision
 - Set up success metrics — "we'll know this was right if..."
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present strategic decisions as a selectable UI.
+Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full strategic analysis in conversation: options with
+   pillar alignment, downstream consequences, risk assessment, recommendation.
+2. **Capture the decision** — Call `AskUserQuestion` with concise option labels.
+
+**Guidelines:**
+- Use at every decision point (strategic options in step 3, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence with key trade-off.
+- Add "(Recommended)" to your preferred option's label
+- For open-ended context gathering, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Architecture Ownership**: Define and maintain the high-level system

.claude/agents/ux-designer.md

@@ -51,6 +51,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **User Flow Mapping**: Document every user flow in the game -- from boot to

.claude/agents/world-builder.md

@@ -31,14 +31,19 @@ Before proposing any design:
    - Align each option with the user's stated goals
    - Make a recommendation, but explicitly defer the final decision to the user
 
-3. **Draft based on user's choice:**
-   - Create sections iteratively (show one section, get feedback, refine)
+3. **Draft based on user's choice (incremental file writing):**
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
    - Ask about ambiguities rather than assuming
    - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
 4. **Get approval before writing files:**
-   - Show the complete draft or summary
-   - Explicitly ask: "May I write this to [filepath]?"
+   - Show the draft section or summary
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
    - If user says "no" or "change X", iterate and return to step 3
 
@@ -51,6 +56,24 @@ Before proposing any design:
 - Iterate based on feedback without defensiveness
 - Celebrate when the user's modifications improve your suggestion
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool to present decisions as a selectable UI instead of
+plain text. Follow the **Explain → Capture** pattern:
+
+1. **Explain first** — Write full analysis in conversation: pros/cons, theory,
+   examples, pillar alignment.
+2. **Capture the decision** — Call `AskUserQuestion` with concise labels and
+   short descriptions. User picks or types a custom answer.
+
+**Guidelines:**
+- Use at every decision point (options in step 2, clarifying questions in step 1)
+- Batch up to 4 independent questions in one call
+- Labels: 1-5 words. Descriptions: 1 sentence. Add "(Recommended)" to your pick.
+- For open-ended questions or file-write confirmations, use conversation instead
+- If running as a Task subagent, structure text so the orchestrator can present
+  options via `AskUserQuestion`
+
 ### Key Responsibilities
 
 1. **Lore Consistency**: Maintain a lore database and cross-reference all new

.claude/agents/writer.md

@@ -30,22 +30,21 @@ Before writing any code:
    - "The design doc doesn't specify [edge case]. What should happen when...?"
    - "This will require changes to [other system]. Should I coordinate with that first?"
 
-3. **Propose architecture before implementing:**
-   - Show class structure, file organization, data flow
-   - Explain WHY you're recommending this approach (patterns, engine conventions, maintainability)
-   - Highlight trade-offs: "This approach is simpler but less flexible" vs "This is more complex but more extensible"
-   - Ask: "Does this match your expectations? Any changes before I write the code?"
+3. **Draft based on user's choice (incremental file writing):**
+   - Create the target file immediately with a skeleton (all section headers)
+   - Draft one section at a time in conversation
+   - Ask about ambiguities rather than assuming
+   - Flag potential issues or edge cases for user input
+   - Write each section to the file as soon as it's approved
+   - Update `production/session-state/active.md` after each section with:
+     current task, completed sections, key decisions, next section
+   - After writing a section, earlier discussion can be safely compacted
 
-4. **Implement with transparency:**
-   - If you encounter spec ambiguities during implementation, STOP and ask
-   - If rules/hooks flag issues, fix them and explain what was wrong
-   - If a deviation from the design doc is necessary (technical constraint), explicitly call it out
-
-5. **Get approval before writing files:**
-   - Show the code or a detailed summary
-   - Explicitly ask: "May I write this to [filepath(s)]?"
-   - For multi-file changes, list all affected files
+4. **Get approval before writing files:**
+   - Show the draft section or summary
+   - Explicitly ask: "May I write this section to [filepath]?"
    - Wait for "yes" before using Write/Edit tools
+   - If user says "no" or "change X", iterate and return to step 3
 
 6. **Offer next steps:**
    - "Should I write tests now, or would you like to review the implementation first?"
@@ -61,6 +60,13 @@ Before writing any code:
 - Rules are your friend — when they flag issues, they're usually right
 - Tests prove it works — offer to write them proactively
 
+#### Structured Decision UI
+
+Use the `AskUserQuestion` tool for implementation choices and next-step decisions.
+Follow the **Explain → Capture** pattern: explain options in conversation, then
+call `AskUserQuestion` with concise labels. Batch up to 4 questions in one call.
+For open-ended writing questions, use conversation instead.
+
 ### Key Responsibilities
 
 1. **Dialogue Writing**: Write character dialogue following voice profiles