learnship 2.1.2 → 2.2.1

package/learnship/workflows/discuss-milestone.md

@@ -33,7 +33,21 @@ Check if a MILESTONE-CONTEXT.md already exists:
 node -e "const fs=require('fs'); console.log(fs.existsSync('.planning/MILESTONE-CONTEXT.md') ? 'EXISTS' : 'MISSING')"
 ```
 
-If exists: ask "A milestone context file already exists from a prior discussion. Update it or start fresh?"
+If exists:
+
+```
+AskUserQuestion([
+  {
+    header: "Existing Context",
+    question: "A milestone context file already exists from a prior discussion.",
+    multiSelect: false,
+    options: [
+      { label: "Update it", description: "Add to or revise existing milestone context" },
+      { label: "Start fresh", description: "Discard prior context and start over" }
+    ]
+  }
+])
+```
 
 ## Step 2: Discuss Goals
 

package/learnship/workflows/discuss-phase.md

@@ -56,13 +56,40 @@ Note any decisions that constrain or inform this phase's approach. Surface them
 ls .planning/phases/*-CONTEXT.md 2>/dev/null
 ```
 
-If CONTEXT.md already exists for this phase:
-- Offer: **Update it** / **View it** / **Skip** (use as-is)
-- If "Skip" → exit workflow
+If CONTEXT.md already exists for this phase, present the choice:
+
+```
+AskUserQuestion([
+  {
+    header: "Existing Context",
+    question: "CONTEXT.md already exists for this phase. What do you want to do?",
+    multiSelect: false,
+    options: [
+      { label: "Update it", description: "Add to or revise existing decisions" },
+      { label: "View it", description: "Show current context, then decide" },
+      { label: "Skip", description: "Use existing context as-is" }
+    ]
+  }
+])
+```
+
+If "Skip" → exit workflow.
 
 If no CONTEXT.md exists but plans already exist for this phase:
-- Warn: "Phase [X] already has plans created without user context. Your decisions here won't affect existing plans unless you re-run plan-phase."
-- Ask: **Continue and replan after** / **Cancel**
+
+```
+AskUserQuestion([
+  {
+    header: "Plans Already Exist",
+    question: "Phase [X] already has plans created without user context. Your decisions here won't affect existing plans unless you re-run plan-phase.",
+    multiSelect: false,
+    options: [
+      { label: "Continue and replan after", description: "Capture decisions now, re-run plan-phase later" },
+      { label: "Cancel", description: "Keep existing plans unchanged" }
+    ]
+  }
+])
+```
 
 ## Step 3: Scout Codebase
 
@@ -119,20 +146,66 @@ Carrying forward from earlier phases:
 - [Decision from Phase N]
 ```
 
-Present 3-4 gray areas for selection (multi-select). Annotate with:
-- Prior decision context: "You chose X in Phase 5"
-- Code context: "You already have a Card component with shadow/rounded variants"
+Present gray areas using a structured multi-select question. Annotate with prior decisions and code context:
+
+```
+AskUserQuestion([
+  {
+    header: "Gray Areas",
+    question: "Which areas do you want to discuss? (select all that apply)",
+    multiSelect: true,
+    options: [
+      { label: "[Area 1]", description: "[Prior context or code context annotation]" },
+      { label: "[Area 2]", description: "[Prior context or code context annotation]" },
+      { label: "[Area 3]", description: "[Prior context or code context annotation]" },
+      { label: "All clear — skip discussion", description: "No gray areas need clarification" }
+    ]
+  }
+])
+```
+
+If "All clear" → skip to Step 6.
 
 **For each selected area, discuss:**
 
 1. Announce: "Let's talk about [Area]."
-2. Ask 4 focused questions with concrete options (not abstract). Include the recommended choice. Annotate options with existing code where relevant.
+2. Ask focused questions with concrete options using structured questions where possible:
+
+```
+AskUserQuestion([
+  {
+    header: "[Area]: [Decision Point]",
+    question: "[Specific implementation question]",
+    multiSelect: false,
+    options: [
+      { label: "[Option A] (Recommended)", description: "[Why, with code context if relevant]" },
+      { label: "[Option B]", description: "[Why]" },
+      { label: "[Option C]", description: "[Why]" }
+    ]
+  }
+])
+```
+
 3. After 4 questions, ask: "More questions about [area], or move to next?"
 4. If more → ask 4 more, then check again
 
 After all selected areas:
 - Summarize decisions captured
-- Ask: "Which gray areas remain unclear?" → "Explore more" or "I'm ready for context"
+- Present final check:
+
+```
+AskUserQuestion([
+  {
+    header: "Wrap Up",
+    question: "All gray areas discussed. Ready to generate CONTEXT.md?",
+    multiSelect: false,
+    options: [
+      { label: "Ready", description: "Generate CONTEXT.md with captured decisions" },
+      { label: "Explore more", description: "Discuss additional areas before writing context" }
+    ]
+  }
+])
+```
 
 <scope_guardrail>
 **No scope creep.** The phase boundary comes from ROADMAP.md and is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.

package/learnship/workflows/ideate.md

@@ -74,14 +74,34 @@ a problem you're trying to solve, or something you're not sure about yet.
 **Mid-conversation research offer (after 2-3 exchanges):**
 
 If the conversation surfaces factual questions, technology comparisons, or unknowns:
-```
-This touches on [specific question]. Want me to do a quick research pass before we continue?
-This would take ~30 seconds and might surface useful context.
 
-[Yes, research this] / [No, let's keep exploring]
+```
+AskUserQuestion([
+  {
+    header: "Research Opportunity",
+    question: "This touches on [specific question]. Want me to do a quick research pass before we continue?",
+    multiSelect: false,
+    options: [
+      { label: "Yes, research this", description: "~30 seconds — may surface useful context" },
+      { label: "No, keep exploring", description: "Continue the conversation without research" }
+    ]
+  }
+])
 ```
 
-If yes and parallelization is enabled, spawn a research agent. Otherwise do an inline research pass. Share findings and continue.
+If yes: read `parallelization` from `.planning/config.json`. If `parallelization.enabled` is true, spawn a researcher agent:
+```
+Task(
+  subagent_type="learnship-researcher",
+  prompt="
+    <objective>
+    Quick research pass on: [specific question].
+    Search web, scan codebase for relevant patterns, and return a concise summary of findings.
+    </objective>
+  "
+)
+```
+If parallelization is false, use `@./agents/researcher.md` as inline persona for a quick research pass. Share findings and continue.
 
 **Crystallize outputs (after 3-6 exchanges):**
 

package/learnship/workflows/list-phase-assumptions.md

@@ -105,11 +105,18 @@ Assumptions validated. Ready to plan.
 ## Step 5: Offer Next Steps
 
 ```
-What's next?
-
-1. discuss-phase [N] — you answer my questions to build CONTEXT.md
-2. plan-phase [N] — create plans now (assumptions noted above apply)
-3. Re-examine — I'll analyze again with your corrections
+AskUserQuestion([
+  {
+    header: "Next Step",
+    question: "What would you like to do with these assumptions?",
+    multiSelect: false,
+    options: [
+      { label: "Discuss Phase", description: "Run discuss-phase [N] — you answer my questions to build CONTEXT.md" },
+      { label: "Plan Now", description: "Run plan-phase [N] — create plans now (assumptions noted above apply)" },
+      { label: "Re-examine", description: "Analyze again with your corrections" }
+    ]
+  }
+])
 ```
 
 Note: Any corrections discussed here are not automatically captured. Run `discuss-phase [N]` to write them to a CONTEXT.md that planners will read.

package/learnship/workflows/new-milestone.md

@@ -32,14 +32,20 @@ Pending todos carried forward:
 Ask openly: **"What do you want to build in this milestone?"**
 
 If a milestone scope was already discussed (look for `.planning/MILESTONE-CONTEXT.md`), load it and confirm:
-```
-I found a milestone context file from a prior discussion:
-[summary of scope]
 
-Use this as the starting point?
 ```
-- **Yes** → proceed with it
-- **No / Start fresh** → ask from scratch
+AskUserQuestion([
+  {
+    header: "Prior Context Found",
+    question: "I found a milestone context file from a prior discussion. Use it as the starting point?",
+    multiSelect: false,
+    options: [
+      { label: "Yes", description: "Proceed with the scope from the prior discussion" },
+      { label: "Start fresh", description: "Discard prior context and ask from scratch" }
+    ]
+  }
+])
+```
 
 Follow the thread. When you have enough to write clear goals, ask for confirmation before continuing.
 

package/learnship/workflows/new-project.md

@@ -6,6 +6,8 @@ description: Initialize a new project — questioning → research → requireme
 
 Initialize a new project with full context gathering, optional research, requirements scoping, and roadmap creation. This is the most leveraged moment in any project — deep questioning now means better plans, better execution, better outcomes.
 
+> **Platform note:** When this workflow shows structured question blocks, use your platform's interactive question tool to present them (the tool that lets users pick from predefined options). If no such tool is available, present each question as a numbered text list with descriptions and ask the user to reply with their choice number or label.
+
 > **This workflow has 9 mandatory steps. You must complete every step in order. Do not skip, defer, or abbreviate any step. Check each one off as you complete it:**
 >
 > - [ ] Step 1 — Setup & codebase check
@@ -80,70 +82,151 @@ Note the tech stack, key directories, and any README content internally. Use thi
 
 ## Step 2: Configuration
 
-Ask the user the following questions to configure the project. Ask them in a conversational way — not all at once, but grouped naturally.
-
-**Group A — Working style:**
-
-Ask: "How do you want to work?"
-- **YOLO** (recommended) — Auto-approve steps, just execute
-- **Interactive** — Confirm at each step
-
-Ask: "How finely should scope be sliced into phases?"
-- **Coarse** (recommended) — Fewer, broader phases (3-5 phases, 1-3 plans each)
-- **Standard** — Balanced phase size (5-8 phases, 3-5 plans each)
-- **Fine** — Many focused phases (8-12 phases, 5-10 plans each)
-
-**Group B — Learning mode:**
-
-Ask: "How should the learning partner (agentic-learning) work during this project?"
-- **Auto** (recommended) — I'll offer relevant learning actions at natural checkpoints (after planning, after execution, etc.)
-- **Manual** — I'll only activate when you explicitly invoke `@agentic-learning`
-
-**Group C — Model profile:**
-
-Ask: "Which model quality tier do you want?"
-- **Quality** — Large-tier models for all decision-making agents (highest cost, best results)
-- **Balanced** (recommended) — Large for planning, medium for execution
-- **Budget** — Medium for code, small for research/verification (lowest cost)
+Present configuration questions using structured question rounds. Use your platform's interactive question tool, or numbered text lists if unavailable.
 
-**Group D — Development style:**
+**Round 1 — Core settings (4 questions):**
 
-Ask: "Test-first (TDD) mode?"
-- **No** (recommended) — Write tests alongside implementation
-- **Yes** — Enforce red-green-refactor: write failing test first, verify red, implement, verify green
-
-**Group E — Workflow agents (these add quality but cost tokens/time):**
-
-Ask: "Which workflow agents and quality steps should be enabled?"
-- **Research** (recommended) — Investigate domain before planning each phase
-- **Plan Check** (recommended) — Verify plans achieve their goals before execution
-- **Verifier** (recommended) — Confirm deliverables match phase goals after execution
-- **Review** (recommended) — Multi-persona code review after verification
-- **Solutions Search** (recommended) — Search prior solutions for reusable patterns during planning
+```
+AskUserQuestion([
+  {
+    header: "Working Style",
+    question: "How do you want to work?",
+    multiSelect: false,
+    options: [
+      { label: "YOLO (Recommended)", description: "Auto-approve steps, just execute" },
+      { label: "Interactive", description: "Confirm at each step" }
+    ]
+  },
+  {
+    header: "Granularity",
+    question: "How finely should scope be sliced into phases?",
+    multiSelect: false,
+    options: [
+      { label: "Coarse (Recommended)", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" },
+      { label: "Standard", description: "Balanced phase size (5-8 phases, 3-5 plans each)" },
+      { label: "Fine", description: "Many focused phases (8-12 phases, 5-10 plans each)" }
+    ]
+  },
+  {
+    header: "Learning Partner",
+    question: "How should agentic-learning work during this project?",
+    multiSelect: false,
+    options: [
+      { label: "Auto (Recommended)", description: "Offer learning actions at natural checkpoints (after planning, execution, etc.)" },
+      { label: "Manual", description: "Only activate when you explicitly invoke @agentic-learning" }
+    ]
+  },
+  {
+    header: "AI Models",
+    question: "Which model quality tier for planning agents?",
+    multiSelect: false,
+    options: [
+      { label: "Balanced (Recommended)", description: "Large for planning, medium for execution — good quality/cost ratio" },
+      { label: "Quality", description: "Large-tier models for all agents (highest cost, best results)" },
+      { label: "Budget", description: "Medium for code, small for research/verification (lowest cost)" }
+    ]
+  }
+])
+```
 
-Ask: "Auto-trigger review after verify-work passes?"
-- **No** (recommended) — Run `/review` manually when ready
-- **Yes** — Automatically start review after verification succeeds
+**Round 2 — Workflow agents (5 questions):**
 
-**Group F — Ship pipeline defaults:**
+```
+AskUserQuestion([
+  {
+    header: "Research",
+    question: "Research domain before planning each phase? (adds tokens/time)",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
+      { label: "No", description: "Plan directly from requirements" }
+    ]
+  },
+  {
+    header: "Plan Check",
+    question: "Verify plans will achieve their goals? (adds tokens/time)",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
+      { label: "No", description: "Execute plans without verification" }
+    ]
+  },
+  {
+    header: "Verifier",
+    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
+      { label: "No", description: "Trust execution, skip verification" }
+    ]
+  },
+  {
+    header: "Review",
+    question: "Multi-persona code review after verification?",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Correctness, security, performance, maintainability review" },
+      { label: "No", description: "Skip code review" }
+    ]
+  },
+  {
+    header: "Solutions Search",
+    question: "Search prior solutions for reusable patterns during planning?",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Check .planning/solutions/ for relevant past fixes" },
+      { label: "No", description: "Plan without searching prior solutions" }
+    ]
+  }
+])
+```
 
-Ask: "Ship pipeline preferences?"
-- **Auto-test before shipping** (recommended: yes) — Run tests before every ship
-- **Conventional commits** (recommended: yes) — Use `feat:`, `fix:`, `docs:` commit prefixes
-- **Auto-generate PR description** (recommended: yes) — Create PR body from commit messages
+**Round 3 — Pipeline & git (4 questions):**
 
-**Group G — Parallel execution:**
+```
+AskUserQuestion([
+  {
+    header: "TDD",
+    question: "Test-first (TDD) mode?",
+    multiSelect: false,
+    options: [
+      { label: "No (Recommended)", description: "Write tests alongside implementation" },
+      { label: "Yes", description: "Red-green-refactor: write failing test first, implement, verify green" }
+    ]
+  },
+  {
+    header: "Ship Pipeline",
+    question: "Ship pipeline preferences?",
+    multiSelect: true,
+    options: [
+      { label: "Auto-test before shipping (Recommended)", description: "Run tests before every ship" },
+      { label: "Conventional commits (Recommended)", description: "Use feat:, fix:, docs: commit prefixes" },
+      { label: "Auto-generate PR description (Recommended)", description: "Create PR body from commit messages" }
+    ]
+  },
+  {
+    header: "Git Tracking",
+    question: "Commit planning docs to git?",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
+      { label: "No", description: "Keep .planning/ local-only (add to .gitignore)" }
+    ]
+  },
+  {
+    header: "Commit Mode",
+    question: "When should learnship commit files to git?",
+    multiSelect: false,
+    options: [
+      { label: "Automatically (Recommended)", description: "Commit after each workflow step completes" },
+      { label: "Manually", description: "You commit when ready; skip all git commit steps" }
+    ]
+  }
+])
+```
 
 <!-- LEARNSHIP_PARALLEL_BLOCK -->
 
-Ask: "Commit planning docs to git?"
-- **Yes** (recommended) — Planning docs tracked in version control
-- **No** — Keep `.planning/` local-only
-
-Ask: "When should learnship commit files to git?"
-- **Automatically** (recommended) — Commit after each workflow step completes (config, requirements, roadmap, AGENTS.md)
-- **Manually** — I'll commit when I say so; skip all git commit steps
-
 Create `.planning/config.json` with all settings:
 
 ```json
@@ -311,24 +394,26 @@ git add .planning/PROJECT.md && git commit -m "docs: initialize project"
 
 > **🔴 MANDATORY USER CHOICE — You must ask this question and wait for a reply. You are NOT allowed to decide this yourself.**
 
-Display this question to the user exactly as written:
+Display the research decision banner, then present the choice using a structured question:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  learnship ► RESEARCH DECISION
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
 
-Before I write the requirements — do you want me to
-research the domain ecosystem first?
-
- 1. Research first (recommended)
-    → Discover standard stacks, expected features,
-      architecture patterns, common pitfalls
-
- 2. Skip research
-    → Go straight to requirements
-
-Reply 1 or 2.
+```
+AskUserQuestion([
+  {
+    header: "Research",
+    question: "Before I write the requirements — do you want me to research the domain ecosystem first?",
+    multiSelect: false,
+    options: [
+      { label: "Research first (Recommended)", description: "Discover standard stacks, expected features, architecture patterns, common pitfalls — writes 5 research files" },
+      { label: "Skip research", description: "Go straight to requirements" }
+    ]
+  }
+])
 ```
 
 > � **HARD GATE — This is a user decision. You MUST wait for the user to reply.**
@@ -359,16 +444,17 @@ Reply 1 or 2.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-> 🔴 **CRITICAL — "Research" in this step means WRITING 5 FILES to disk. It does NOT mean thinking, browsing the web, or analyzing in your head. The deliverable is 5 markdown files on the filesystem. You are not done with research until all 5 files exist and pass verification.**
+> 🔴 **CRITICAL — "Research" in this step means TWO things: (1) SEARCHING THE WEB for current information, then (2) WRITING 5 FILES to disk based on what you found. The deliverable is 5 markdown files grounded in real online research, not training data. You are not done with research until all 5 files exist and pass verification.**
 >
 > **Forbidden behaviors (if you do any of these, the research step has FAILED):**
+> - **Writing files without doing web research first** — reading templates and writing from training data is NOT research. You must run WebSearch queries and WebFetch official docs BEFORE writing any file.
 > - Doing web searches or thinking about the domain and then saying "I have enough research data" WITHOUT writing the 5 files
 > - Writing research findings only in your response text instead of to files
 > - Writing fewer than 5 files (e.g., one combined file)
 > - Moving to Step 6 or writing REQUIREMENTS.md before the verification command below prints `RESEARCH VERIFIED OK`
 > - Saying "Let me proceed to requirements" or "Moving to requirements" before verification passes
 >
-> **The ONLY acceptable sequence is:** mkdir → write file 1 → write file 2 → write file 3 → write file 4 → write file 5 → run verification → see `RESEARCH VERIFIED OK` → present findings → get user confirmation.
+> **The ONLY acceptable sequence is:** mkdir → **web research (WebSearch + WebFetch)** → write file 1 → write file 2 → write file 3 → write file 4 → write file 5 → run verification → see `RESEARCH VERIFIED OK` → present findings → get user confirmation.
 
 **Step 5a — Create the research directory.** Run this command now:
 
@@ -378,10 +464,81 @@ node -e "require('fs').mkdirSync('.planning/research',{recursive:true})"
 
 > 🛑 Did the mkdir command run? If not, run it now before continuing.
 
-**Step 5b — Write all 5 files.** Create each file one at a time using your file write tool. Each file is a separate write operation. Do NOT combine files. Do NOT skip files.
+Read `parallelization` from `.planning/config.json` (defaults to `false`).
+
+**If `parallelization.enabled` is `true` (subagent mode — Claude Code, OpenCode, Codex):**
+
+Spawn a dedicated researcher agent with the project context:
+```
+Task(
+  subagent_type="learnship-researcher",
+  prompt="
+    <objective>
+    Research the domain ecosystem for a new project, then write 5 research files into .planning/research/.
+
+    IMPORTANT: You MUST do online research BEFORE writing any files. Your training data is stale — verify everything.
+
+    Phase 1 — INVESTIGATE (do this first):
+    1. Read .planning/PROJECT.md to understand the project domain and goals
+    2. Run at least 5 WebSearch queries to discover: standard tech stacks, recommended libraries, architecture patterns, common pitfalls, and best practices for this domain. Include the current year in queries.
+    3. Use WebFetch to read official documentation for any key libraries or frameworks discovered
+    4. Read the research persona at @./agents/researcher.md for research principles
+
+    Phase 2 — WRITE FILES (only after investigating):
+    Read each template from @./templates/research-project/ for the expected structure, then write each file based on your actual research findings (not just training data). Include confidence levels (HIGH/MEDIUM/LOW) and cite sources.
+
+    Files to write:
+    1. STACK.md — Must have: ## Recommended Stack, ## Alternatives Considered, ## What NOT to Use, ## Versions
+    2. FEATURES.md — Must have: ## Table Stakes, ## Differentiators, ## Anti-Features
+    3. ARCHITECTURE.md — Must have: ## Component Boundaries, ## Data Flow, ## Build Order, ## Integration Points
+    4. PITFALLS.md — Must have: ## Common Mistakes, ## Warning Signs, ## Prevention Strategies
+    5. SUMMARY.md — Must have: ## Recommended Stack, ## Table Stakes Features, ## Key Architecture Decisions, ## Top Pitfalls
+
+    After writing all 5 files, run the verification command to confirm all files exist with required sections.
+    Return: confirmation that all 5 files pass verification, plus a summary of what you found.
+    </objective>
+
+    <files_to_read>
+    - .planning/PROJECT.md (project description and goals)
+    - @./agents/researcher.md (research persona — read for research principles and tool strategy)
+    - @./templates/research-project/STACK.md (template for STACK.md)
+    - @./templates/research-project/FEATURES.md (template for FEATURES.md)
+    - @./templates/research-project/ARCHITECTURE.md (template for ARCHITECTURE.md)
+    - @./templates/research-project/PITFALLS.md (template for PITFALLS.md)
+    - @./templates/research-project/SUMMARY.md (template for SUMMARY.md)
+    </files_to_read>
+  "
+)
+```
+
+Wait for the agent to complete, then proceed to Step 5c (verification) to confirm files were written correctly.
+
+**If `parallelization.enabled` is `false` (sequential mode):**
+
+Using `@./agents/researcher.md` as your research persona:
+
+**Step 5b-pre — Online research (BEFORE writing any files).**
+
+> 🔴 **You MUST do web research before writing files.** Your training data is stale. Do not write research files from memory alone — investigate first, write second.
+
+Run at least 5 WebSearch queries to discover the current state of this project's domain. Include the current year in all queries. Example queries (adapt to the actual project domain):
+
+1. `"[project domain] recommended tech stack 2026"` — discover what's standard
+2. `"[project domain] best libraries 2026"` — find specific tools
+3. `"[project domain] architecture patterns"` — how systems in this domain are structured
+4. `"[project domain] common mistakes gotchas"` — what goes wrong
+5. `"[key technology from PROJECT.md] best practices"` — specific tech guidance
+
+For any libraries or frameworks discovered, use WebFetch to read their official documentation pages.
+
+Record your findings internally. You will use them to write the 5 files below. Every recommendation in the files should be grounded in what you found online — include confidence levels (HIGH/MEDIUM/LOW) and cite sources where possible.
+
+> 🛑 STOP. Confirm: did you run at least 5 WebSearch queries? If you skipped straight to writing files, go back and search now. Files written purely from training data without web verification are low-quality research.
+
+**Step 5b — Write all 5 files.** Create each file one at a time using your file write tool. Each file is a separate write operation. Do NOT combine files. Do NOT skip files. **Before writing each file, read the corresponding template** from `@./templates/research-project/` to understand the expected structure. Base your content on the web research findings from Step 5b-pre.
 
 **File 1 of 5 — Write `.planning/research/STACK.md` to disk now.**
-Research the standard tech stack for this domain and write the results to this file. The file MUST contain these exact `##` headers:
+First, read the template at `@./templates/research-project/STACK.md` for the expected structure. Then write the stack research based on your web search findings. Include confidence levels and cite sources. The file MUST contain these exact `##` headers:
 - `## Recommended Stack`
 - `## Alternatives Considered`
 - `## What NOT to Use` (with reasons)
@@ -390,26 +547,26 @@ Research the standard tech stack for this domain and write the results to this f
 > 🛑 STOP. Confirm: did you write `.planning/research/STACK.md` to the filesystem? If you only thought about the stack but did not create the file, go back and create it now.
 
 **File 2 of 5 — Write `.planning/research/FEATURES.md` to disk now.**
-Research what features users expect in this domain. Write the results to this file. The file MUST contain these exact `##` headers:
+First, read the template at `@./templates/research-project/FEATURES.md` for the expected structure. Then write the features research based on your web search findings. The file MUST contain these exact `##` headers:
 - `## Table Stakes` (must-haves)
 - `## Differentiators` (nice-to-haves)
 - `## Anti-Features` (what to avoid)
 
 **File 3 of 5 — Write `.planning/research/ARCHITECTURE.md` to disk now.**
-Research how systems in this domain are typically structured. Write the results to this file. The file MUST contain these exact `##` headers:
+First, read the template at `@./templates/research-project/ARCHITECTURE.md` for the expected structure. Then write the architecture research based on your web search findings. The file MUST contain these exact `##` headers:
 - `## Component Boundaries`
 - `## Data Flow`
 - `## Build Order` (suggested sequence)
 - `## Integration Points`
 
 **File 4 of 5 — Write `.planning/research/PITFALLS.md` to disk now.**
-Research common mistakes and prevention strategies. Write the results to this file. The file MUST contain these exact `##` headers:
+First, read the template at `@./templates/research-project/PITFALLS.md` for the expected structure. Then write the pitfalls research based on your web search findings. The file MUST contain these exact `##` headers:
 - `## Common Mistakes`
 - `## Warning Signs`
 - `## Prevention Strategies`
 
 **File 5 of 5 — Write `.planning/research/SUMMARY.md` to disk now.**
-Synthesize the 4 files above into a summary. Write the results to this file. The file MUST contain these exact `##` headers:
+First, read the template at `@./templates/research-project/SUMMARY.md` for the expected structure. Then synthesize the 4 files above into a summary. The file MUST contain these exact `##` headers:
 - `## Recommended Stack`
 - `## Table Stakes Features`
 - `## Key Architecture Decisions`