learnship 2.2.1 → 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.1",
+  "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.1",
+  "version": "2.2.2",
   "logo": "assets/logo.png",
   "author": {
     "name": "Favio Vazquez",

package/gemini-extension.json

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

@@ -468,50 +468,231 @@ 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>
 
-    IMPORTANT: You MUST do online research BEFORE writing any files. Your training data is stale — verify everything.
+    <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>
 
-    Phase 1 — INVESTIGATE (do this first):
+    <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 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 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 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 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>
+  "
+)
+```
+
+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 agent to complete, then proceed to Step 5c (verification) to confirm files were written correctly.
+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):**
 

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>
   "
 )
 ```
@@ -178,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.
@@ -192,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>
   "
 )
 ```
@@ -237,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,30 +78,38 @@ 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>
   "
 )
 ```

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.1",
+  "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",