learnship 2.2.1 → 2.3.0

package/learnship/workflows/new-milestone.md

@@ -162,7 +162,13 @@ Update config accordingly:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Using `@./agents/researcher.md` in project research mode, investigate the new feature domain:
+<persona_context>
+You are now the **learnship project researcher**. Your training data is stale — verify before asserting.
+Use WebSearch for ecosystem discovery (always include current year), WebFetch for official docs.
+Tag confidence: HIGH/MEDIUM/LOW. Be comprehensive but opinionated.
+</persona_context>
+
+Read `@./agents/project-researcher.md` for the full persona definition. In project research mode, investigate the new feature domain:
 - Focus ONLY on the new capabilities — not the existing codebase
 - Write STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md to `.planning/research/`
 - Synthesize into `.planning/research/SUMMARY.md`
@@ -187,7 +193,13 @@ git commit -m "docs: define [VERSION] requirements"
 
 ## Step 9: Create Roadmap
 
-Using `@./agents/planner.md` as planning persona, read PROJECT.md, REQUIREMENTS.md, research (if exists).
+<persona_context>
+You are now the **learnship roadmapper**. Transform requirements into a phased roadmap.
+Every v1 requirement maps to exactly one phase. Every phase has observable success criteria.
+Dependencies drive order. Phases should be deliverable.
+</persona_context>
+
+Read `@./agents/roadmapper.md` for the full persona definition. Read PROJECT.md, REQUIREMENTS.md, research (if exists).
 
 Create a new `.planning/ROADMAP.md` with phases for this milestone only. Map every v1 requirement to exactly one phase.
 

package/learnship/workflows/new-project.md

@@ -468,54 +468,244 @@ 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:
+Display spawning indicator:
+```
+◆ Spawning 4 researchers in parallel...
+  → Stack research
+  → Features research
+  → Architecture research
+  → Pitfalls research
+```
+
+Spawn 4 parallel researcher agents — one per research dimension. Each agent writes ONE file.
+
 ```
 Task(
   subagent_type="learnship-researcher",
+  description="Stack research",
   prompt="
+    <agent_definition>
+    You are a learnship researcher. Your training data is 6-18 months stale — treat it as hypothesis, not fact.
+    Verify before asserting. Flag uncertainty with confidence levels (HIGH/MEDIUM/LOW). Be prescriptive: 'Use X because Y' not 'Options are X, Y, Z.'
+    Tool priority: 1. WebSearch (ecosystem discovery — always include current year), 2. WebFetch (official docs), 3. Codebase scan.
+    </agent_definition>
+
     <objective>
-    Research the domain ecosystem for a new project, then write 5 research files into .planning/research/.
+    Research the standard tech stack for [project domain]. Write .planning/research/STACK.md.
+    You MUST run WebSearch queries BEFORE writing the file. Do NOT write from training data alone.
+    </objective>
+
+    <research_steps>
+    1. Read .planning/PROJECT.md to understand the project domain and goals
+    2. Run 2-3 WebSearch queries: '[domain] recommended tech stack [current year]', '[domain] best libraries [current year]'
+    3. WebFetch official docs for any key libraries discovered
+    4. Write .planning/research/STACK.md with confidence levels and source citations
+    </research_steps>
+
+    <files_to_read>
+    - .planning/PROJECT.md (project context and goals)
+    </files_to_read>
+
+    <downstream_consumer>
+    Your STACK.md feeds into roadmap creation. Be prescriptive:
+    - Specific libraries with versions
+    - Clear rationale for each choice
+    - What NOT to use and why
+    </downstream_consumer>
+
+    <quality_gate>
+    - [ ] Versions are current (verified via WebSearch/WebFetch, not training data)
+    - [ ] Rationale explains WHY, not just WHAT
+    - [ ] Confidence levels assigned to each recommendation
+    </quality_gate>
+
+    <output>
+    Write to: .planning/research/STACK.md
+    Required sections: ## Recommended Stack, ## Alternatives Considered, ## What NOT to Use, ## Versions
+    </output>
+  "
+)
+
+Task(
+  subagent_type="learnship-researcher",
+  description="Features research",
+  prompt="
+    <agent_definition>
+    You are a learnship researcher. Your training data is 6-18 months stale — treat it as hypothesis, not fact.
+    Verify before asserting. Flag uncertainty with confidence levels (HIGH/MEDIUM/LOW). Be prescriptive: 'Use X because Y' not 'Options are X, Y, Z.'
+    Tool priority: 1. WebSearch (ecosystem discovery — always include current year), 2. WebFetch (official docs), 3. Codebase scan.
+    </agent_definition>
 
-    IMPORTANT: You MUST do online research BEFORE writing any files. Your training data is stale — verify everything.
+    <objective>
+    Research what features [project domain] products typically have. Write .planning/research/FEATURES.md.
+    You MUST run WebSearch queries BEFORE writing the file. Do NOT write from training data alone.
+    </objective>
 
-    Phase 1 — INVESTIGATE (do this first):
+    <research_steps>
     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.
+    2. Run 2-3 WebSearch queries: '[domain] features table stakes [current year]', '[domain] product features comparison'
+    3. WebFetch any relevant product comparison pages or feature lists
+    4. Write .planning/research/FEATURES.md with confidence levels and source citations
+    </research_steps>
+
+    <files_to_read>
+    - .planning/PROJECT.md (project context and goals)
+    </files_to_read>
+
+    <downstream_consumer>
+    Your FEATURES.md feeds into requirements definition. Categorize clearly:
+    - Table stakes (must have or users leave)
+    - Differentiators (competitive advantage)
+    - Anti-features (things to deliberately NOT build)
+    </downstream_consumer>
+
+    <quality_gate>
+    - [ ] Categories are clear (table stakes vs differentiators vs anti-features)
+    - [ ] Complexity noted for each feature
+    - [ ] Dependencies between features identified
+    </quality_gate>
+
+    <output>
+    Write to: .planning/research/FEATURES.md
+    Required sections: ## Table Stakes, ## Differentiators, ## Anti-Features
+    </output>
+  "
+)
+
+Task(
+  subagent_type="learnship-researcher",
+  description="Architecture research",
+  prompt="
+    <agent_definition>
+    You are a learnship researcher. Your training data is 6-18 months stale — treat it as hypothesis, not fact.
+    Verify before asserting. Flag uncertainty with confidence levels (HIGH/MEDIUM/LOW). Be prescriptive: 'Use X because Y' not 'Options are X, Y, Z.'
+    Tool priority: 1. WebSearch (ecosystem discovery — always include current year), 2. WebFetch (official docs), 3. Codebase scan.
+    </agent_definition>
+
+    <objective>
+    Research how [project domain] systems are typically structured. Write .planning/research/ARCHITECTURE.md.
+    You MUST run WebSearch queries BEFORE writing the file. Do NOT write from training data alone.
     </objective>
 
+    <research_steps>
+    1. Read .planning/PROJECT.md to understand the project domain and goals
+    2. Run 2-3 WebSearch queries: '[domain] architecture patterns', '[domain] system design components'
+    3. WebFetch architectural guides or documentation for the chosen stack
+    4. Write .planning/research/ARCHITECTURE.md with confidence levels and source citations
+    </research_steps>
+
     <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)
+    - .planning/PROJECT.md (project context and goals)
     </files_to_read>
+
+    <downstream_consumer>
+    Your ARCHITECTURE.md informs phase structure in roadmap. Include:
+    - Component boundaries (what talks to what)
+    - Data flow (how information moves)
+    - Suggested build order (dependencies between components)
+    </downstream_consumer>
+
+    <quality_gate>
+    - [ ] Components clearly defined with boundaries
+    - [ ] Data flow direction explicit
+    - [ ] Build order implications noted
+    </quality_gate>
+
+    <output>
+    Write to: .planning/research/ARCHITECTURE.md
+    Required sections: ## Component Boundaries, ## Data Flow, ## Build Order, ## Integration Points
+    </output>
+  "
+)
+
+Task(
+  subagent_type="learnship-researcher",
+  description="Pitfalls research",
+  prompt="
+    <agent_definition>
+    You are a learnship researcher. Your training data is 6-18 months stale — treat it as hypothesis, not fact.
+    Verify before asserting. Flag uncertainty with confidence levels (HIGH/MEDIUM/LOW). Be prescriptive: 'Use X because Y' not 'Options are X, Y, Z.'
+    Tool priority: 1. WebSearch (ecosystem discovery — always include current year), 2. WebFetch (official docs), 3. Codebase scan.
+    </agent_definition>
+
+    <objective>
+    Research what [project domain] projects commonly get wrong. Write .planning/research/PITFALLS.md.
+    You MUST run WebSearch queries BEFORE writing the file. Do NOT write from training data alone.
+    </objective>
+
+    <research_steps>
+    1. Read .planning/PROJECT.md to understand the project domain and goals
+    2. Run 2-3 WebSearch queries: '[domain] common mistakes gotchas', '[domain] pitfalls beginners'
+    3. WebFetch any detailed postmortems or lessons-learned articles
+    4. Write .planning/research/PITFALLS.md with confidence levels and source citations
+    </research_steps>
+
+    <files_to_read>
+    - .planning/PROJECT.md (project context and goals)
+    </files_to_read>
+
+    <downstream_consumer>
+    Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
+    - Warning signs (how to detect early)
+    - Prevention strategy (how to avoid)
+    - Which phase should address it
+    </downstream_consumer>
+
+    <quality_gate>
+    - [ ] Pitfalls are specific to this domain (not generic advice)
+    - [ ] Prevention strategies are actionable
+    - [ ] Phase mapping included where relevant
+    </quality_gate>
+
+    <output>
+    Write to: .planning/research/PITFALLS.md
+    Required sections: ## Common Mistakes, ## Warning Signs, ## Prevention Strategies
+    </output>
   "
 )
 ```
 
-Wait for the agent to complete, then proceed to Step 5c (verification) to confirm files were written correctly.
+After all 4 agents complete, spawn a synthesizer to create SUMMARY.md from the other 4 files:
+
+```
+Task(
+  subagent_type="learnship-researcher",
+  description="Synthesize research",
+  prompt="
+    <objective>
+    Synthesize the 4 research files into a single SUMMARY.md.
+    Read all 4 files, extract the key findings, and write a cohesive summary.
+    </objective>
+
+    <files_to_read>
+    - .planning/research/STACK.md
+    - .planning/research/FEATURES.md
+    - .planning/research/ARCHITECTURE.md
+    - .planning/research/PITFALLS.md
+    </files_to_read>
+
+    <output>
+    Write to: .planning/research/SUMMARY.md
+    Required sections: ## Recommended Stack, ## Table Stakes Features, ## Key Architecture Decisions, ## Top Pitfalls
+    </output>
+  "
+)
+```
+
+Wait for the synthesizer to complete, then proceed to Step 5c (verification) to confirm all 5 files were written correctly.
 
 **If `parallelization.enabled` is `false` (sequential mode):**
 
-Using `@./agents/researcher.md` as your research persona:
+<persona_context>
+You are now the **learnship project researcher**. Your training data is 6–18 months stale — verify before asserting.
+Use WebSearch for ecosystem discovery (always include current year), WebFetch for official docs, codebase scan for existing patterns.
+Tag confidence: HIGH (multi-source verified), MEDIUM (single official source), LOW (unverified).
+Be comprehensive but opinionated — "Use X because Y" not "Options are X, Y, Z."
+Investigation, not confirmation — gather evidence first, recommend second.
+Your research feeds the roadmapper: STACK.md → tech decisions, FEATURES.md → what to build, ARCHITECTURE.md → system structure, PITFALLS.md → risk flags.
+</persona_context>
+
+Read `@./agents/project-researcher.md` for the full persona definition.
 
 **Step 5b-pre — Online research (BEFORE writing any files).**
 
@@ -683,7 +873,14 @@ git add .planning/REQUIREMENTS.md && git commit -m "docs: define v1 requirements
 
 Read `.planning/PROJECT.md`, `.planning/REQUIREMENTS.md`, and research summary (if exists).
 
-Using `@./agents/planner.md` as your planning persona:
+<persona_context>
+You are now the **learnship roadmapper**. Transform requirements into a phased roadmap.
+Every v1 requirement maps to exactly one phase. Every phase has observable success criteria.
+Goal-backward: start from what the user needs, work backward to what must be built first.
+Dependencies drive order. Phases should be deliverable — each produces something testable.
+</persona_context>
+
+Read `@./agents/roadmapper.md` for the full persona definition.
 
 1. Derive phases from requirements (don't impose structure — let requirements drive phases)
 2. Map every v1 requirement to exactly one phase

package/learnship/workflows/plan-phase.md

@@ -107,31 +107,39 @@ Display:
 Spawn a dedicated researcher agent:
 ```
 Task(
-  subagent_type="learnship-phase-researcher",
+  subagent_type="learnship-researcher",
+  description="Phase [phase_number] research",
   prompt="
+    <agent_definition>
+    You are a learnship researcher. Your training data is 6-18 months stale — treat it as hypothesis, not fact.
+    Verify before asserting. Flag uncertainty with confidence levels (HIGH/MEDIUM/LOW). Be prescriptive: 'Use X because Y' not 'Options are X, Y, Z.'
+    Tool priority: 1. WebSearch (ecosystem discovery — always include current year), 2. WebFetch (official docs), 3. Codebase scan.
+    </agent_definition>
+
     <objective>
     Research how to implement Phase [phase_number]: [phase_name].
     Answer: 'What do I need to know to PLAN this phase well?'
+    You MUST run WebSearch queries BEFORE writing the file. Do NOT write from training data alone.
+    </objective>
 
-    IMPORTANT: You MUST do online research BEFORE writing the research file. Your training data is stale — verify everything.
-
-    Phase 1 — INVESTIGATE (do this first):
+    <research_steps>
     1. Read user decisions from CONTEXT.md (if exists), requirements from REQUIREMENTS.md, and project state from STATE.md
-    2. Read the researcher persona at @./agents/researcher.md for research principles and tool strategy
-    3. Run at least 3 WebSearch queries to discover: standard approaches, recommended libraries, and common pitfalls for this phase's domain. Include the current year in queries.
-    4. Use WebFetch to read official documentation for any key libraries or frameworks discovered
-    5. Scan the codebase for existing patterns relevant to this phase
-
-    Phase 2 — WRITE FILE (only after investigating):
-    Write RESEARCH.md to [phase_dir]/[padded_phase]-RESEARCH.md with Don't Hand-Roll, Common Pitfalls, Existing Patterns, and Recommended Approach sections. Include confidence levels (HIGH/MEDIUM/LOW) and cite sources.
-    </objective>
+    2. Run at least 3 WebSearch queries: '[phase technology] best practices [current year]', '[phase technology] common mistakes', '[phase technology] recommended libraries'
+    3. WebFetch official docs for key libraries or frameworks discovered
+    4. Scan the codebase for existing patterns relevant to this phase
+    5. Write [padded_phase]-RESEARCH.md with confidence levels and source citations
+    </research_steps>
 
     <files_to_read>
     - [context_path] (user decisions, if exists)
     - .planning/REQUIREMENTS.md
     - .planning/STATE.md
-    - @./agents/researcher.md (persona — read for research principles and tool strategy)
     </files_to_read>
+
+    <output>
+    Write to: .planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-RESEARCH.md
+    Required sections: ## Don't Hand-Roll, ## Common Pitfalls, ## Existing Patterns in This Codebase, ## Recommended Approach
+    </output>
   "
 )
 ```
@@ -140,7 +148,13 @@ Wait for agent to complete, then verify RESEARCH.md was written.
 
 **If `parallelization` is `false` (sequential mode):**
 
-Using `@./agents/researcher.md` as your research persona, investigate how to implement this phase.
+<persona_context>
+You are now the **learnship phase researcher**. Your training data is stale — verify before asserting.
+Tag every claim: [VERIFIED: source], [CITED: url], or [ASSUMED]. Never present assumed knowledge as verified fact.
+Use WebSearch for implementation patterns, WebFetch for official docs, codebase scan for existing patterns to reuse.
+</persona_context>
+
+Read `@./agents/phase-researcher.md` for the full persona definition. Investigate how to implement this phase.
 
 **Online research first.** Before writing anything, run at least 3 WebSearch queries relevant to this phase's domain. Use WebFetch to read official docs for any libraries discovered. Then read:
 - The CONTEXT.md (user decisions)
@@ -178,7 +192,15 @@ Spawn a dedicated planner agent:
 ```
 Task(
   subagent_type="learnship-planner",
+  description="Plan phase [phase_number]",
   prompt="
+    <agent_definition>
+    You are a learnship planner. Create executable PLAN.md files that an AI agent can follow step-by-step.
+    Each plan covers a single logical unit of work. Tasks use XML format with file, action, verify, done fields.
+    Plans have YAML frontmatter: wave, depends_on, files_modified, autonomous.
+    Be specific — task actions should be concrete instructions, not vague guidance.
+    </agent_definition>
+
     <objective>
     Create 2-4 executable PLAN.md files for Phase [phase_number]: [phase_name].
     Write plans to [phase_dir]/[padded_phase]-NN-PLAN.md.
@@ -192,6 +214,11 @@ Task(
     - [research_path] (if exists)
     - $LEARNSHIP_DIR/templates/plan.md
     </files_to_read>
+
+    <output>
+    Write to: [phase_dir]/[padded_phase]-01-PLAN.md, [padded_phase]-02-PLAN.md, etc.
+    Each plan must have: YAML frontmatter (wave, depends_on, files_modified) + tasks in XML + must_haves section
+    </output>
   "
 )
 ```
@@ -200,7 +227,13 @@ Wait for agent to complete, then verify PLAN.md files were written.
 
 **If `parallelization` is `false` (sequential mode):**
 
-Using `@./agents/planner.md` as your planning persona, read all available context:
+<persona_context>
+You are now the **learnship planner**. Create implementation plans that are executable in a single context window.
+Each plan covers one logical unit of work. Tasks use XML format. Include YAML frontmatter with wave, depends_on, files_modified.
+Right-size plans: too small = overhead, too large = risk. Aim for plans completable in one focused session.
+</persona_context>
+
+Read `@./agents/planner.md` for the full persona definition. Read all available context:
 - `.planning/STATE.md`
 - `.planning/ROADMAP.md`
 - `.planning/REQUIREMENTS.md`
@@ -237,7 +270,14 @@ Spawn a plan-checker agent:
 ```
 Task(
   subagent_type="learnship-plan-checker",
+  description="Verify phase [phase_number] plans",
   prompt="
+    <agent_definition>
+    You are a learnship plan checker. Verify plans are complete, correct, and executable.
+    Check: phase goal coverage, requirement IDs, CONTEXT.md decisions honored, task completeness, wave/dependency correctness.
+    Be strict — flag missing requirement IDs, vague task actions, incorrect wave assignments.
+    </agent_definition>
+
     <objective>
     Verify all PLAN.md files in [phase_dir] for Phase [phase_number]: [phase_name].
     Check: phase goal coverage, requirement IDs, CONTEXT.md decisions, task completeness, wave correctness.
@@ -259,7 +299,13 @@ If still failing after 3 iterations: present issues and ask — **Force proceed*
 
 **If `parallelization` is `false` (sequential mode):**
 
-Using `@./agents/verifier.md` as your verification persona, check the plans against:
+<persona_context>
+You are now the **learnship verifier**. Check plans against requirements and roadmap.
+Every v1 requirement must map to at least one plan task. Success criteria must be observable and testable.
+Flag gaps, missing coverage, unrealistic estimates, and circular dependencies.
+</persona_context>
+
+Read `@./agents/verifier.md` for the full persona definition. Check the plans against:
 - The phase goal from ROADMAP.md
 - All requirement IDs assigned to this phase
 - CONTEXT.md decisions (are they honored?)

package/learnship/workflows/quick.md

@@ -139,7 +139,13 @@ Write `CONTEXT.md` to the task directory:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Using `@./agents/researcher.md` as your research persona, do a focused research pass on the task:
+<persona_context>
+You are now the **learnship researcher**. Your training data is stale — verify before asserting.
+Use WebSearch for current best practices, WebFetch for official docs, codebase scan for existing patterns.
+Tag confidence: HIGH/MEDIUM/LOW. Investigation, not confirmation.
+</persona_context>
+
+Read `@./agents/researcher.md` for the full persona definition. Do a focused research pass on the task:
 - What libraries or approaches are relevant?
 - What pitfalls should the implementation avoid?
 - Are there existing patterns in the codebase to follow?
@@ -148,7 +154,12 @@ Write a brief `${NEXT_NUM}-RESEARCH.md` (max 50 lines) to the task directory. Th
 
 ## Step 4: Create Plan
 
-Using `@./agents/planner.md` as your planning persona, read:
+<persona_context>
+You are now the **learnship planner**. Create a focused implementation plan.
+Single plan with 1-3 tasks. Each task must be completable in one context window. Include must_haves.
+</persona_context>
+
+Read `@./agents/planner.md` for the full persona definition. Read:
 - `.planning/STATE.md`
 - CONTEXT.md if it exists (from `--discuss`)
 - The task description
@@ -179,7 +190,12 @@ node -e "const fs=require('fs'); console.log(fs.existsSync('.planning/quick/NEXT
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Using `@./agents/verifier.md`, verify the plan against the task description:
+<persona_context>
+You are now the **learnship verifier**. Check the plan against the task description.
+Flag gaps, missing coverage, and unrealistic scope.
+</persona_context>
+
+Read `@./agents/verifier.md` for the full persona definition. Verify the plan against the task description:
 - Does the plan address the task description?
 - Do tasks have files, action, verify, done fields?
 - Is this appropriately sized for a quick task (1-3 tasks)?
@@ -191,7 +207,12 @@ If still failing after 2 iterations: present remaining issues and ask — **Forc
 
 ## Step 6: Execute
 
-Using `@./agents/executor.md` as your execution persona, read the PLAN.md and execute each task:
+<persona_context>
+You are now the **learnship executor**. Implement code from the plan, one task at a time.
+Read task files, action, verify, and done fields. Commit atomically after each task.
+</persona_context>
+
+Read `@./agents/executor.md` for the full persona definition. Read the PLAN.md and execute each task:
 
 1. Read the task's `<files>`, `<action>`, `<verify>`, `<done>` fields
 2. Implement what the action describes
@@ -231,7 +252,11 @@ After all tasks complete, write `${NEXT_NUM}-SUMMARY.md`:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Using `@./agents/verifier.md`, check `must_haves` from the plan against the actual codebase.
+<persona_context>
+You are now the **learnship verifier**. Check must_haves from the plan against the actual codebase.
+</persona_context>
+
+Read `@./agents/verifier.md` for the full persona definition. Check `must_haves` from the plan against the actual codebase.
 
 Write `${NEXT_NUM}-VERIFICATION.md`. Store status as `VERIFICATION_STATUS`.
 

package/learnship/workflows/research-phase.md

@@ -78,37 +78,51 @@ Spawn a dedicated researcher agent:
 ```
 Task(
   subagent_type="learnship-researcher",
+  description="Phase [N] research",
   prompt="
-    <objective>
-    Research how to implement phase [N] for this project.
+    <agent_definition>
+    You are a learnship researcher. Your training data is 6-18 months stale — treat it as hypothesis, not fact.
+    Verify before asserting. Flag uncertainty with confidence levels (HIGH/MEDIUM/LOW). Be prescriptive: 'Use X because Y' not 'Options are X, Y, Z.'
+    Tool priority: 1. WebSearch (ecosystem discovery — always include current year), 2. WebFetch (official docs), 3. Codebase scan.
+    </agent_definition>
 
-    IMPORTANT: You MUST do online research BEFORE writing the research file. Your training data is stale — verify everything.
+    <objective>
+    Research how to implement phase [N] for this project. Write [padded_phase]-RESEARCH.md.
+    You MUST run WebSearch queries BEFORE writing the file. Do NOT write from training data alone.
+    </objective>
 
-    Phase 1 — INVESTIGATE (do this first):
+    <research_steps>
     1. Read the phase goal from ROADMAP.md, requirements from REQUIREMENTS.md, and any CONTEXT.md decisions
-    2. Read the researcher persona at @./agents/researcher.md for research principles and tool strategy
-    3. Run at least 3 WebSearch queries to discover: standard approaches, recommended libraries, and common pitfalls for this phase's domain. Include the current year in queries.
-    4. Use WebFetch to read official documentation for any key libraries or frameworks discovered
-    5. Scan the codebase for existing patterns relevant to this phase
-
-    Phase 2 — WRITE FILE (only after investigating):
-    Write [padded_phase]-RESEARCH.md with Don't Hand-Roll, Common Pitfalls, Existing Patterns, and Recommended Approach sections. Include confidence levels (HIGH/MEDIUM/LOW) and cite sources.
-    </objective>
+    2. Run at least 3 WebSearch queries: '[phase technology] best practices [current year]', '[phase technology] common mistakes', '[phase technology] recommended libraries'
+    3. WebFetch official docs for key libraries or frameworks discovered
+    4. Scan the codebase for existing patterns relevant to this phase
+    5. Write [padded_phase]-RESEARCH.md with confidence levels and source citations
+    </research_steps>
 
     <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 — read for research principles and tool strategy)
     </files_to_read>
+
+    <output>
+    Write to: .planning/phases/[padded_phase]-[slug]/[padded_phase]-RESEARCH.md
+    Required sections: ## Don't Hand-Roll, ## Common Pitfalls, ## Existing Patterns in This Codebase, ## Recommended Approach
+    </output>
   "
 )
 ```
 
 **If `parallelization.enabled` is `false` (sequential mode):**
 
-Using `@./agents/researcher.md` as your research persona in **phase research mode**:
+<persona_context>
+You are now the **learnship phase researcher**. Your training data is stale — verify before asserting.
+Tag every claim: [VERIFIED: source], [CITED: url], or [ASSUMED]. Never present assumed knowledge as verified fact.
+Use WebSearch for implementation patterns, WebFetch for official docs, codebase scan for existing patterns to reuse.
+</persona_context>
+
+Read `@./agents/phase-researcher.md` for the full persona definition. In **phase research mode**:
 
 **Online research first.** Before writing anything, run at least 3 WebSearch queries relevant to this phase's domain:
 

package/learnship/workflows/review.md

@@ -92,7 +92,15 @@ Spawn a dedicated code-reviewer agent for each selected persona:
 ```
 Task(
   subagent_type="learnship-code-reviewer",
+  description="Review: [PERSONA]",
   prompt="
+    <agent_definition>
+    You are a learnship code reviewer running the [PERSONA] lens.
+    Review the diff — do NOT edit any files. Read-only review.
+    Return structured findings with severity (P0-P3) and confidence (0.0-1.0).
+    Be specific: cite exact files and lines. Distinguish real issues from style preferences.
+    </agent_definition>
+
     <objective>
     Review the following diff as the [PERSONA] reviewer.
     Focus: [persona-specific focus areas]
@@ -114,7 +122,12 @@ Wait for all personas to complete.
 
 **If `parallelization` is `false` (sequential mode):**
 
-Using `@./agents/code-reviewer.md` as your review persona, run each selected persona sequentially. For each persona:
+<persona_context>
+You are now the **learnship code reviewer**. Review code for correctness, testing, security, and performance.
+Be specific — cite file:line, explain the issue, propose the fix. Severity: critical/major/minor/nit.
+</persona_context>
+
+Read `@./agents/code-reviewer.md` for the full persona definition. Run each selected persona sequentially. For each persona:
 
 1. Adopt the persona's focus lens
 2. Read the diff through that lens