learnship 2.1.1 → 2.2.0

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:**
+Present configuration questions using structured question rounds. Use your platform's interactive question tool, or numbered text lists if unavailable.
 
-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)
+**Round 1 — Core settings (4 questions):**
 
-**Group D — Development style:**
-
-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.**
@@ -355,62 +440,121 @@ Reply 1 or 2.
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- learnship ► RESEARCHING
+ learnship ► WRITING RESEARCH FILES
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-**You MUST create exactly 5 separate markdown files.** Do NOT write a single monolithic research file. Do NOT combine multiple files into one. Each file is a separate write operation.
+> 🔴 **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.**
+>
+> **Forbidden behaviors (if you do any of these, the research step has FAILED):**
+> - 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.
 
-Create the research directory first:
+**Step 5a — Create the research directory.** Run this command now:
 
 ```bash
 node -e "require('fs').mkdirSync('.planning/research',{recursive:true})"
 ```
 
-Now create each file one at a time. After writing each file, move to the next.
+> 🛑 Did the mkdir command run? If not, run it now before continuing.
 
-**File 1 of 5 — Write `.planning/research/STACK.md` now:**
-Research the standard tech stack for this domain. The file MUST contain these exact `##` headers:
+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>
+    Write 5 research files for a new project into .planning/research/.
+    Before writing each file, read the corresponding template from @./templates/research-project/ for the expected structure.
+
+    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.
+    </objective>
+
+    <files_to_read>
+    - .planning/PROJECT.md (project description and goals)
+    - @./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 — 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.
+
+**File 1 of 5 — Write `.planning/research/STACK.md` to disk now.**
+First, read the template at `@./templates/research-project/STACK.md` for the expected structure. Then research the standard tech stack for this domain and write the results to this file. Use the template as your structural guide. The file MUST contain these exact `##` headers:
 - `## Recommended Stack`
 - `## Alternatives Considered`
 - `## What NOT to Use` (with reasons)
 - `## Versions`
 
-**File 2 of 5 — Write `.planning/research/FEATURES.md` now:**
-Research what features exist in this domain. The file MUST contain these exact `##` headers:
+> 🛑 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.**
+First, read the template at `@./templates/research-project/FEATURES.md` for the expected structure. Then research what features users expect in this domain. Write the results to this file. Use the template as your structural guide. 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` now:**
-Research how systems in this domain are typically structured. The file MUST contain these exact `##` headers:
+**File 3 of 5 — Write `.planning/research/ARCHITECTURE.md` to disk now.**
+First, read the template at `@./templates/research-project/ARCHITECTURE.md` for the expected structure. Then research how systems in this domain are typically structured. Write the results to this file. Use the template as your structural guide. 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` now:**
-Research common mistakes and prevention strategies. The file MUST contain these exact `##` headers:
+**File 4 of 5 — Write `.planning/research/PITFALLS.md` to disk now.**
+First, read the template at `@./templates/research-project/PITFALLS.md` for the expected structure. Then research common mistakes and prevention strategies. Write the results to this file. Use the template as your structural guide. The file MUST contain these exact `##` headers:
 - `## Common Mistakes`
 - `## Warning Signs`
 - `## Prevention Strategies`
 
-**File 5 of 5 — Write `.planning/research/SUMMARY.md` now:**
-Synthesize the 4 files above into a summary. The file MUST contain these exact `##` headers:
+**File 5 of 5 — Write `.planning/research/SUMMARY.md` to disk now.**
+First, read the template at `@./templates/research-project/SUMMARY.md` for the expected structure. Then synthesize the 4 files above into a summary. Write the results to this file. Use the template as your structural guide. The file MUST contain these exact `##` headers:
 - `## Recommended Stack`
 - `## Table Stakes Features`
 - `## Key Architecture Decisions`
 - `## Top Pitfalls`
 
-> 🔴 **HARD GATE — Run this verification command now. Do not skip it. Do not proceed without running it.**
+**Step 5c — Verify all 5 files exist on disk.** Run this verification command now. Do not skip it.
+
+> 🔴 **HARD GATE — You MUST run this command. If you skip it and proceed to Step 6, the workflow has FAILED.**
 
 ```bash
-node -e "const fs=require('fs'),path=require('path');const dir='.planning/research/';const checks={'STACK.md':['Recommended Stack','What NOT to Use'],'FEATURES.md':['Table Stakes','Differentiators'],'ARCHITECTURE.md':['Component Boundaries','Data Flow'],'PITFALLS.md':['Common Mistakes','Prevention Strategies'],'SUMMARY.md':['Recommended Stack','Top Pitfalls']};const missing=[];for(const[file,sections]of Object.entries(checks)){const fp=path.join(dir,file);if(!fs.existsSync(fp)){missing.push(file+' MISSING');continue;}const c=fs.readFileSync(fp,'utf8');for(const s of sections){if(!c.includes('## '+s))missing.push(file+': missing ## '+s);}}if(missing.length){console.log('RESEARCH INCOMPLETE:\\n'+missing.join('\\n'));process.exit(1);}console.log('RESEARCH VERIFIED OK — all 5 files present with required sections');"
+node -e "const fs=require('fs'),path=require('path');const dir='.planning/research/';const checks={'STACK.md':['Recommended Stack','What NOT to Use'],'FEATURES.md':['Table Stakes','Differentiators'],'ARCHITECTURE.md':['Component Boundaries','Data Flow'],'PITFALLS.md':['Common Mistakes','Prevention Strategies'],'SUMMARY.md':['Recommended Stack','Top Pitfalls']};const missing=[];for(const[file,sections]of Object.entries(checks)){const fp=path.join(dir,file);if(!fs.existsSync(fp)){missing.push(file+' MISSING');continue;}const c=fs.readFileSync(fp,'utf8');for(const s of sections){if(!c.includes('## '+s))missing.push(file+': missing ## '+s);}}if(missing.length){console.log('RESEARCH FAILED — files missing or incomplete:\\n'+missing.join('\\n'));console.log('\\nGo back and create the missing files. Do NOT proceed to requirements.');process.exit(1);}console.log('RESEARCH VERIFIED OK — all 5 files present with required sections');"
 ```
 
-> 🛑 **If the command prints `RESEARCH INCOMPLETE` or exits with code 1:** Go back and create or fix the missing files. Then run the verification again. You MUST see `RESEARCH VERIFIED OK` before continuing. Do NOT proceed to Step 6 without a passing verification.
+> 🛑 **If the command prints `RESEARCH FAILED` or exits with code 1:** Go back and create or fix the missing files. Run the verification again. You MUST see `RESEARCH VERIFIED OK` before continuing.
+>
+> **If you did not run the command at all:** You have skipped verification. Go back and run it now. You cannot proceed to Step 5d without a passing verification.
 
-**Read all 5 research files now** and present their findings in full. Do NOT summarize into 3 bullets. Display this exact structure, populated from the actual file contents:
+**Step 5d — Present findings.** Read all 5 research files from disk now and present their findings in full. Do NOT summarize into 3 bullets — display the actual content from the files you wrote. Display this exact structure, populated from the actual file contents:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

package/learnship/workflows/quick.md

@@ -73,13 +73,27 @@ Report: "Creating quick task ${NEXT_NUM}: ${DESCRIPTION}"
 
 Analyze `DESCRIPTION` to identify 2-4 gray areas — implementation decisions that would change the outcome.
 
-Present them for selection (multi-select):
-- Each area is a concrete decision point (not generic)
-- Include an "All clear — skip discussion" option
+Present them for selection using a structured multi-select question:
+
+```
+AskUserQuestion([
+  {
+    header: "Gray Areas",
+    question: "Which areas need clarification? (select all that apply)",
+    multiSelect: true,
+    options: [
+      { label: "[Area 1]", description: "[Concrete decision point]" },
+      { label: "[Area 2]", description: "[Concrete decision point]" },
+      { label: "[Area 3]", description: "[Concrete decision point]" },
+      { label: "All clear — skip discussion", description: "No gray areas need clarification" }
+    ]
+  }
+])
+```
 
 If "All clear" → skip to Step 4.
 
-For each selected area, ask 1-2 focused questions with concrete options. Max 2 questions per area — keep it lightweight.
+For each selected area, ask 1-2 focused questions with concrete options using structured questions. Max 2 questions per area — keep it lightweight.
 
 Write `CONTEXT.md` to the task directory:
 

package/learnship/workflows/research-phase.md

@@ -30,16 +30,21 @@ ls ".planning/phases/"*"/"*"-RESEARCH.md" 2>/dev/null | grep "^[N]-\|/[N][^0-9]"
 ```
 
 If RESEARCH.md already exists for this phase:
-```
-Research already exists: .planning/phases/[phase-dir]/[N]-RESEARCH.md
 
-Options:
-1. View existing research
-2. Re-run and overwrite
-3. Skip — use existing
 ```
-
-Wait for choice.
+AskUserQuestion([
+  {
+    header: "Existing Research",
+    question: "Research already exists for this phase. What do you want to do?",
+    multiSelect: false,
+    options: [
+      { label: "View existing", description: "Show current research, then decide" },
+      { label: "Re-run and overwrite", description: "Discard existing research and re-run" },
+      { label: "Skip", description: "Use existing research as-is" }
+    ]
+  }
+])
+```
 
 ## Step 3: Load Context
 
@@ -65,6 +70,36 @@ If CONTEXT.md exists, read it — user decisions shape what to research.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+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:
+```
+Task(
+  subagent_type="learnship-researcher",
+  prompt="
+    <objective>
+    Research phase [N] for this project. Read the phase goal from ROADMAP.md,
+    requirements from REQUIREMENTS.md, and any CONTEXT.md decisions.
+    Write [padded_phase]-RESEARCH.md with Don't Hand-Roll, Common Pitfalls,
+    Existing Patterns, and Recommended Approach sections.
+    Follow the researcher persona at @./agents/researcher.md.
+    </objective>
+
+    <files_to_read>
+    - .planning/ROADMAP.md
+    - .planning/REQUIREMENTS.md
+    - .planning/STATE.md
+    - .planning/phases/[padded_phase]-[slug]/[padded_phase]-CONTEXT.md (if exists)
+    - @./agents/researcher.md (persona)
+    </files_to_read>
+  "
+)
+```
+
+**If `parallelization.enabled` is `false` (sequential mode):**
+
 Using `@./agents/researcher.md` as your research persona in **phase research mode**:
 
 Read all loaded context, then investigate how to implement this phase. Write `.planning/phases/[padded_phase]-[slug]/[padded_phase]-RESEARCH.md` with two sections: