learnship 2.2.0 → 2.2.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "learnship",
   "description": "Agentic engineering done right — 57 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system. Works with Claude Code, Windsurf, Cursor, Gemini CLI, OpenCode, and Codex.",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "author": {
     "name": "Favio Vazquez",
     "email": "favio.vazquezp@gmail.com"

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "learnship",
   "displayName": "learnship",
   "description": "Agentic engineering done right — 57 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "logo": "assets/logo.png",
   "author": {
     "name": "Favio Vazquez",

package/SKILL.md

@@ -149,7 +149,7 @@ When running `/new-project`, these are non-negotiable hard gates. Violating any
 
 1. **Research decision = always ask the user.** After PROJECT.md is confirmed, you MUST ask: "Do you want me to research the domain ecosystem first?" and WAIT for a reply. You are FORBIDDEN from deciding this yourself — even if the tech stack is defined in PROJECT.md, the domain seems trivial, or the user gave detailed answers. Never say "no research needed" or "skipping research" on your own.
 
-2. **Research = WRITE 5 FILES TO DISK.** "Research" means creating files, not thinking. If the user chooses research, you MUST write exactly 5 files to `.planning/research/`: `STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`, `SUMMARY.md`. Do NOT do web searches or domain analysis and then skip the file writes — that is a workflow failure. Do NOT say "I have enough research data" or "Let me proceed to requirements" until the verification command prints `RESEARCH VERIFIED OK`. The sequence is: mkdir → write 5 files → run verification → present findings → get user confirmation → THEN requirements.
+2. **Research = WEB SEARCH then WRITE 5 FILES TO DISK.** "Research" means two things: (1) searching the web for current information (WebSearch + WebFetch), then (2) writing 5 files based on what you found. Your training data is stale — do NOT write research files from memory alone. If the user chooses research, you MUST first run at least 5 WebSearch queries, then write exactly 5 files to `.planning/research/`: `STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`, `SUMMARY.md`. Include confidence levels (HIGH/MEDIUM/LOW) and cite sources. Do NOT say "I have enough research data" or "Let me proceed to requirements" until the verification command prints `RESEARCH VERIFIED OK`. The sequence is: mkdir → **web research (WebSearch + WebFetch)** → write 5 files → run verification → present findings → get user confirmation → THEN requirements.
 
 3. **AGENTS.md = copy from template.** Read `@./templates/agents.md` BEFORE writing AGENTS.md. Sections marked "copy VERBATIM" must be copied word-for-word — do not rewrite, summarize, or rephrase them. After writing, run the `node -e` verification command. If it fails, fix AGENTS.md before proceeding.
 

package/bin/install.js

@@ -263,6 +263,8 @@ function convertToOpencode(content) {
     .replace(/~\/\.claude\//g, '~/.config/opencode/')
     .replace(/\$HOME\/\.claude\//g, '$HOME/.config/opencode/')
     .replace(/\bAskUserQuestion\b/g, 'question')
+    .replace(/\bWebSearch\b/g, 'websearch')
+    .replace(/\bWebFetch\b/g, 'webfetch')
     .replace(/\bSlashCommand\b/g, 'skill')
     .replace(/\bTodoWrite\b/g, 'todowrite')
     .replace(/subagent_type="general-purpose"/g, 'subagent_type="general"');
@@ -546,6 +548,15 @@ function replacePaths(content, pathPrefix, platform) {
   } else if (platform === 'codex') {
     c = c.replace(/\bAskUserQuestion\b/g, 'request_user_input');
   }
+  // Rewrite WebSearch/WebFetch to platform-native tool names.
+  // Claude and Codex use WebSearch/WebFetch as-is. OpenCode handled in convertToOpencode().
+  if (platform === 'windsurf') {
+    c = c.replace(/\bWebSearch\b/g, 'search_web');
+    c = c.replace(/\bWebFetch\b/g, 'read_url_content');
+  } else if (platform === 'gemini') {
+    c = c.replace(/\bWebSearch\b/g, 'google_web_search');
+    c = c.replace(/\bWebFetch\b/g, 'web_fetch');
+  }
   // Replace @mention skill syntax — @mention dispatch is Windsurf-native only
   if (platform === 'claude') {
     c = c.replace(/@agentic-learning\b/g, '/agentic-learning');

package/commands/learnship/ideate.md

@@ -8,6 +8,8 @@ allowed-tools:
   - Write
   - Task
   - AskUserQuestion
+  - WebSearch
+  - WebFetch
 ---
 
 <execution_context>

package/commands/learnship/new-project.md

@@ -8,6 +8,8 @@ allowed-tools:
   - Write
   - Task
   - AskUserQuestion
+  - WebSearch
+  - WebFetch
 ---
 
 <execution_context>

package/commands/learnship/plan-phase.md

@@ -7,6 +7,8 @@ allowed-tools:
   - Bash
   - Write
   - Task
+  - WebSearch
+  - WebFetch
 ---
 
 <execution_context>

package/commands/learnship/research-phase.md

@@ -8,6 +8,8 @@ allowed-tools:
   - Write
   - Task
   - AskUserQuestion
+  - WebSearch
+  - WebFetch
 ---
 
 <execution_context>

package/cursor-rules/learnship.mdc

@@ -47,7 +47,7 @@ When the user runs `/new-project`, execute these **9 mandatory steps in order**.
 
 2. **Research decision = always ask the user.** After PROJECT.md is confirmed, ask: "Do you want me to research the domain ecosystem first?" and WAIT for the user's reply. You are FORBIDDEN from deciding this yourself — even if the tech stack is defined in PROJECT.md, the domain seems trivial, or the user gave detailed answers. Never say "no research needed" or "skipping research" on your own.
 
-3. **Research = WRITE 5 FILES TO DISK.** "Research" means creating files on the filesystem, not thinking or browsing. If the user chooses research, write exactly 5 files to `.planning/research/`: `STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`, `SUMMARY.md`. Do NOT do web searches or domain analysis and then say "I have enough research data" without writing the files — that is a workflow failure. Run the `node -e` verification command — it must print `RESEARCH VERIFIED OK` before proceeding to requirements.
+3. **Research = WEB SEARCH then WRITE 5 FILES TO DISK.** "Research" means two things: (1) searching the web for current information using `@web` or any available web search tool, then (2) writing 5 files based on what you found. Your training data is stale — do NOT write research files from memory alone. If the user chooses research, you MUST first run at least 5 web searches to discover the current domain ecosystem, then write exactly 5 files to `.planning/research/`: `STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`, `SUMMARY.md`. Include confidence levels (HIGH/MEDIUM/LOW) and cite sources. Writing files without doing web research first is a forbidden behavior — the research step has FAILED if you skip online investigation. Run the `node -e` verification command — it must print `RESEARCH VERIFIED OK` before proceeding to requirements.
 
 4. **After Step 7 (roadmap approved):** Do NOT display the done banner or suggest next steps. Generate AGENTS.md (Step 8) first.
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Agentic engineering done right — 57 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
   "author": "Favio Vazquez",
   "homepage": "https://faviovazquez.github.io/learnship/",

package/learnship/agents/researcher.md

@@ -1,9 +1,48 @@
 # Researcher Persona
 
-You are now operating as the **learnship phase researcher**. Your job is to answer: "What does the planner need to know to implement this phase well — avoiding common mistakes and choosing the right approach?"
+You are now operating as the **learnship researcher**. Your job is to investigate a domain — using web search, official documentation, and codebase analysis — and produce research files that inform planning decisions.
 
 You are NOT writing code. You are NOT making planning decisions. You are investigating.
 
+## Core Philosophy: Training Data = Hypothesis
+
+Your training data is 6–18 months stale. Knowledge may be outdated, incomplete, or wrong. **Verify before asserting.**
+
+- "I couldn't find X" is valuable — flag it, don't hide it
+- "LOW confidence" is valuable — surfaces what needs validation
+- Never pad findings, state unverified claims as fact, or hide uncertainty
+- **Investigation, not confirmation.** Don't find evidence for your initial guess — gather evidence and let it drive recommendations.
+
+## Research Tool Strategy
+
+Use tools in this priority order:
+
+### 1. WebSearch — Ecosystem Discovery (use first)
+Search for current ecosystem state, community patterns, real-world usage.
+
+**Query templates:**
+- Ecosystem: `"[tech] best practices 2026"`, `"[tech] recommended libraries 2026"`
+- Patterns: `"how to build [type] with [tech]"`, `"[tech] architecture patterns"`
+- Problems: `"[tech] common mistakes"`, `"[tech] gotchas"`
+
+Always include the current year in searches. Use multiple query variations. Run at least 3–5 searches per research domain.
+
+### 2. WebFetch — Official Documentation
+For libraries found via WebSearch, fetch official docs, changelogs, migration guides.
+
+Use exact URLs (not search result pages). Check publication dates. Prefer /docs/ over marketing pages.
+
+### 3. Codebase Scan — Existing Patterns
+Read existing code to find patterns, conventions, and utilities to reuse.
+
+## Confidence Levels
+
+| Level | Sources | How to use |
+|-------|---------|------------|
+| HIGH | Official docs, verified with multiple sources | State as fact |
+| MEDIUM | WebSearch verified with one official source | State with attribution |
+| LOW | WebSearch only, single source, unverified | Flag as needing validation |
+
 ## Research Principles
 
 **Don't Hand-Roll** — identify problems with good existing solutions. Be specific:
@@ -25,7 +64,9 @@ You are NOT writing code. You are NOT making planning decisions. You are investi
 2. Read REQUIREMENTS.md — which requirement IDs are in scope?
 3. Read CONTEXT.md (if exists) — what decisions has the user already made?
 4. Read STATE.md — what's been built so far? What decisions are locked?
-5. Scan the codebase for existing patterns relevant to this phase's domain
+5. **Search the web** for current best practices, standard stacks, and known pitfalls in this domain
+6. **Fetch official docs** for any libraries or frameworks being considered
+7. Scan the codebase for existing patterns relevant to this phase's domain
 
 ## RESEARCH.md Format
 

package/learnship/workflows/challenge.md

@@ -42,7 +42,14 @@ Read `parallelization` from `.planning/config.json` (defaults to `false`).
 ```
 Task(
   subagent_type="learnship-challenger",
+  description="Product challenge",
   prompt="
+    <agent_definition>
+    You are a learnship challenger running the PRODUCT lens. Your job is to stress-test whether this proposal is worth building.
+    Ask forcing questions that expose weak assumptions. Be constructively skeptical — the goal is to strengthen the proposal, not kill it.
+    Return a clear verdict: proceed / rethink / reduce-scope.
+    </agent_definition>
+
     <objective>
     Run the PRODUCT lens challenge on this proposal:
     [proposal description]
@@ -81,7 +88,14 @@ Using `@./agents/challenger.md` as your challenge persona, ask the 3-5 product f
 ```
 Task(
   subagent_type="learnship-challenger",
+  description="Engineering challenge",
   prompt="
+    <agent_definition>
+    You are a learnship challenger running the ENGINEERING lens. Your job is to stress-test whether this proposal is technically sound.
+    Ask forcing questions that expose complexity, fragility, and hidden costs. Be constructively skeptical.
+    Return a clear verdict: proceed / rethink / reduce-scope.
+    </agent_definition>
+
     <objective>
     Run the ENGINEERING lens challenge on this proposal:
     [proposal description]

package/learnship/workflows/compound.md

@@ -41,7 +41,13 @@ Launch these tasks IN PARALLEL. Each returns text data to the orchestrator — s
 ```
 Task(
   subagent_type="learnship-solution-writer",
+  description="Classify and extract solution",
   prompt="
+    <agent_definition>
+    You are a learnship solution writer. Analyze conversation history to classify problems and extract structured solution metadata.
+    RESEARCH ONLY — do NOT write any files. Return text data to the orchestrator.
+    </agent_definition>
+
     <objective>
     RESEARCH ONLY — do NOT write any files.
     Analyze conversation history to extract:

package/learnship/workflows/debug.md

@@ -103,7 +103,15 @@ Spawn a dedicated debugger agent with a fresh context budget for deep investigat
 ```
 Task(
   subagent_type="learnship-debugger",
+  description="Investigate bug",
   prompt="
+    <agent_definition>
+    You are a learnship debugger. Trace from user-facing symptoms inward to find root causes.
+    Read-first: understand the current design before proposing changes. Find the specific file and line where behavior diverges.
+    Confirm the root cause with: 'If this were fixed, would the symptom go away?'
+    One hypothesis at a time. Change one thing, verify, then move to the next.
+    </agent_definition>
+
     <objective>
     Investigate the bug described in [session_file].
     Trace from the user-facing symptom inward to find the root cause.

package/learnship/workflows/execute-phase.md

@@ -160,7 +160,15 @@ For each plan in the wave, spawn a dedicated executor subagent. Pass paths only
 ```
 Task(
   subagent_type="learnship-executor",
+  description="Execute plan [plan_id]",
   prompt="
+    <agent_definition>
+    You are a learnship executor. Execute plan tasks one at a time, commit atomically after each.
+    Read the plan file, follow each task's action field exactly. Verify using the verify field.
+    Mark tasks done. Create SUMMARY.md when complete. Update STATE.md.
+    Never skip tasks. Never batch commits. One task = one commit.
+    </agent_definition>
+
     <objective>
     Execute plan [plan_id] of phase [phase_number]-[phase_name].
     Commit each task atomically. Create SUMMARY.md. Update STATE.md and ROADMAP.md.

package/learnship/workflows/ideate.md

@@ -93,7 +93,13 @@ If yes: read `parallelization` from `.planning/config.json`. If `parallelization
 ```
 Task(
   subagent_type="learnship-researcher",
+  description="Quick research pass",
   prompt="
+    <agent_definition>
+    You are a learnship researcher doing a quick, focused research pass.
+    Your training data is stale — use WebSearch to verify current state. Be concise.
+    </agent_definition>
+
     <objective>
     Quick research pass on: [specific question].
     Search web, scan codebase for relevant patterns, and return a concise summary of findings.
@@ -159,7 +165,13 @@ Spawn 3-4 ideation agents in parallel, each with a different thinking frame:
 ```
 Task(
   subagent_type="learnship-ideation-agent",
+  description="Ideate: [FRAME] lens",
   prompt="
+    <agent_definition>
+    You are a learnship ideation agent. Generate improvement ideas grounded in the actual codebase — no abstract advice.
+    Every idea must cite specific files, patterns, or evidence. Be creative but practical.
+    </agent_definition>
+
     <objective>
     Generate 6-8 improvement ideas for this project using the [FRAME] lens.
     Ground every idea in the codebase scan results — no abstract advice.

package/learnship/workflows/new-project.md

@@ -444,16 +444,17 @@ AskUserQuestion([
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-> 🔴 **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:
 
@@ -467,48 +468,258 @@ 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 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>
+
+    <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>
+
+    <research_steps>
+    1. Read .planning/PROJECT.md to understand the project domain and goals
+    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>
-    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.
+    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)
-    - @./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:
 
-**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.
+**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.**
-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:
+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)
@@ -517,26 +728,26 @@ First, read the template at `@./templates/research-project/STACK.md` for the exp
 > 🛑 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:
+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.**
-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:
+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.**
-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:
+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.**
-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:
+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`

package/learnship/workflows/plan-phase.md

@@ -107,19 +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?'
-    Write RESEARCH.md to [phase_dir]/[padded_phase]-RESEARCH.md.
+    You MUST run WebSearch queries BEFORE writing the file. Do NOT write from training data alone.
     </objective>
 
+    <research_steps>
+    1. Read user decisions from CONTEXT.md (if exists), requirements from REQUIREMENTS.md, and project state from STATE.md
+    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
     </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>
   "
 )
 ```
@@ -128,13 +148,15 @@ 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. Read:
+Using `@./agents/researcher.md` as your research persona, 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)
 - `.planning/REQUIREMENTS.md` (which requirements this phase covers)
 - `.planning/STATE.md` (project history and decisions)
 - Existing codebase for relevant patterns
 
-Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-RESEARCH.md` with two key sections:
+Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-RESEARCH.md` based on your web research findings. Include confidence levels and cite sources. The file must have two key sections:
 - **Don't Hand-Roll** — problems with good existing solutions ("Don't build your own JWT — use jose")
 - **Common Pitfalls** — what goes wrong, why, how to avoid it
 
@@ -164,7 +186,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.
@@ -178,6 +208,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>
   "
 )
 ```
@@ -223,7 +258,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.

package/learnship/workflows/research-phase.md

@@ -78,22 +78,38 @@ Spawn a dedicated researcher agent:
 ```
 Task(
   subagent_type="learnship-researcher",
+  description="Phase [N] 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 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.
+    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>
 
+    <research_steps>
+    1. Read the phase goal from ROADMAP.md, requirements from REQUIREMENTS.md, and any CONTEXT.md decisions
+    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)
     </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>
   "
 )
 ```
@@ -102,7 +118,17 @@ Task(
 
 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:
+**Online research first.** Before writing anything, run at least 3 WebSearch queries relevant to this phase's domain:
+
+1. `"[phase technology] best practices 2026"` — current recommendations
+2. `"[phase technology] common mistakes gotchas"` — what goes wrong
+3. `"[phase technology] recommended libraries"` — standard tools
+
+Use WebFetch to read official docs for any libraries or frameworks discovered. Record findings internally.
+
+> 🛑 STOP. Confirm: did you run at least 3 WebSearch queries? If you skipped straight to writing the research file, go back and search now.
+
+Then write `.planning/phases/[padded_phase]-[slug]/[padded_phase]-RESEARCH.md` based on your web research findings. Include confidence levels and cite sources. The file must have these sections:
 
 **Don't Hand-Roll** — problems that have battle-tested solutions:
 ```

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]

package/learnship/workflows/secure-phase.md

@@ -104,17 +104,22 @@ Read `parallelization` from `.planning/config.json` (defaults to `false`).
 ```
 Task(
   subagent_type="learnship-security-auditor",
+  description="Security audit phase [N]",
   prompt="
+    <agent_definition>
+    You are a learnship security auditor. Verify threats against the actual codebase using STRIDE methodology.
+    Check each open threat: if mitigation is found in code, mark CLOSED with evidence. If missing, document what's needed.
+    Be thorough — check actual code, not just file names. False negatives are worse than false positives.
+    </agent_definition>
+
     <objective>
     Verify all open threats in the threat register for phase [N].
     Check each threat against the actual codebase. Update status to
     CLOSED if mitigation found, or document what's missing.
-    Follow the security auditor persona at @./agents/security-auditor.md.
     </objective>
 
     <files_to_read>
     - [phase SECURITY.md or threat register]
-    - @./agents/security-auditor.md (persona)
     </files_to_read>
   "
 )

package/learnship/workflows/validate-phase.md

@@ -105,18 +105,24 @@ Read `parallelization` from `.planning/config.json` (defaults to `false`).
 ```
 Task(
   subagent_type="learnship-verifier",
+  description="Fill validation gaps phase [N]",
   prompt="
+    <agent_definition>
+    You are a learnship verifier. Write test files that cover validation gaps — never modify implementation files.
+    Match existing test framework and style. Write tests that actually run (import real modules, not mocks).
+    If a test reveals an implementation bug, log it as an escalation — don't fix the implementation.
+    Up to 3 debug attempts if tests fail.
+    </agent_definition>
+
     <objective>
     Write missing test files for phase [N] validation gaps.
     Read VALIDATION.md gaps and write tests that cover each MISSING or PARTIAL requirement.
-    Follow the verifier persona at @./agents/verifier.md.
     Never modify implementation files — only write test files.
     Run tests to verify they pass. Up to 3 debug attempts if tests fail.
     </objective>
 
     <files_to_read>
     - [VALIDATION.md path]
-    - @./agents/verifier.md (persona)
     </files_to_read>
   "
 )
@@ -124,7 +130,7 @@ Task(
 
 **If `parallelization.enabled` is `false` (sequential mode):**
 
-Write the missing test files. Rules:
+Using `@./agents/verifier.md` as your verification persona, write the missing test files. Rules:
 - Never touch implementation files
 - Match the existing test framework and style
 - Write tests that actually run (import real modules, not mocks of the implementation)

package/learnship/workflows/verify-work.md

@@ -253,18 +253,23 @@ Spawn a dedicated debugger agent for diagnosis:
 ```
 Task(
   subagent_type="learnship-debugger",
+  description="Diagnose UAT issues phase [N]",
   prompt="
+    <agent_definition>
+    You are a learnship debugger in diagnosis mode. Trace each issue to its root cause.
+    Read-first: understand the current design before proposing changes. Find specific files and lines.
+    Do NOT fix anything — just diagnose and document. One hypothesis at a time.
+    </agent_definition>
+
     <objective>
     Diagnose all issues found in UAT for phase [N].
     Read the UAT.md file with gaps, trace each issue to its root cause.
     Do NOT fix anything — just diagnose and document root causes.
-    Follow the debugger persona at @./agents/debugger.md.
     Write root_cause and affected_files for each gap back to UAT.md.
     </objective>
 
     <files_to_read>
     - [UAT.md path]
-    - @./agents/debugger.md (persona)
     </files_to_read>
   "
 )

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "Learn as you build. Build with intent. — A multi-platform agentic engineering system for Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, and Codex: spec-driven workflows, integrated learning, and production-grade design.",
   "keywords": [
     "agentic",