learnship 2.2.0 → 2.2.1

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.1",
   "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.1",
   "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.1",
   "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/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:
 
@@ -473,8 +474,18 @@ 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.
+    Research the domain ecosystem for a new project, then write 5 research files into .planning/research/.
+
+    IMPORTANT: You MUST do online research BEFORE writing any files. Your training data is stale — verify everything.
+
+    Phase 1 — INVESTIGATE (do this first):
+    1. Read .planning/PROJECT.md to understand the project domain and goals
+    2. Run at least 5 WebSearch queries to discover: standard tech stacks, recommended libraries, architecture patterns, common pitfalls, and best practices for this domain. Include the current year in queries.
+    3. Use WebFetch to read official documentation for any key libraries or frameworks discovered
+    4. Read the research persona at @./agents/researcher.md for research principles
+
+    Phase 2 — WRITE FILES (only after investigating):
+    Read each template from @./templates/research-project/ for the expected structure, then write each file based on your actual research findings (not just training data). Include confidence levels (HIGH/MEDIUM/LOW) and cite sources.
 
     Files to write:
     1. STACK.md — Must have: ## Recommended Stack, ## Alternatives Considered, ## What NOT to Use, ## Versions
@@ -484,11 +495,12 @@ Task(
     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.
+    Return: confirmation that all 5 files pass verification, plus a summary of what you found.
     </objective>
 
     <files_to_read>
     - .planning/PROJECT.md (project description and goals)
+    - @./agents/researcher.md (research persona — read for research principles and tool strategy)
     - @./templates/research-project/STACK.md (template for STACK.md)
     - @./templates/research-project/FEATURES.md (template for FEATURES.md)
     - @./templates/research-project/ARCHITECTURE.md (template for ARCHITECTURE.md)
@@ -505,10 +517,28 @@ Wait for the agent to complete, then proceed to Step 5c (verification) to confir
 
 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 +547,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

@@ -112,13 +112,25 @@ Task(
     <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.
+
+    IMPORTANT: You MUST do online research BEFORE writing the research file. Your training data is stale — verify everything.
+
+    Phase 1 — INVESTIGATE (do this first):
+    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>
 
     <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>
   "
 )
@@ -128,13 +140,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
 

package/learnship/workflows/research-phase.md

@@ -80,11 +80,19 @@ 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.
+    Research how to implement phase [N] for this project.
+
+    IMPORTANT: You MUST do online research BEFORE writing the research file. Your training data is stale — verify everything.
+
+    Phase 1 — INVESTIGATE (do this first):
+    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>
 
     <files_to_read>
@@ -92,7 +100,7 @@ Task(
     - .planning/REQUIREMENTS.md
     - .planning/STATE.md
     - .planning/phases/[padded_phase]-[slug]/[padded_phase]-CONTEXT.md (if exists)
-    - @./agents/researcher.md (persona)
+    - @./agents/researcher.md (persona — read for research principles and tool strategy)
     </files_to_read>
   "
 )
@@ -102,7 +110,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "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",