learnship 2.3.2 → 2.3.3

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "learnship",
   "description": "Agentic engineering done right — 57 structured workflows, 17 specialist agent personas, 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.3.2",
+  "version": "2.3.3",
   "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, 17 specialist agent personas, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "logo": "assets/logo.png",
   "author": {
     "name": "Favio Vazquez",

package/gemini-extension.json

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

package/learnship/workflows/audit-milestone.md

@@ -72,6 +72,11 @@ You are now the **learnship verifier** in integration mode. Check cross-phase wi
 Every requirement must trace to at least one completed phase. Flag gaps, stubs, and broken integration points.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[35m  learnship-verifier(In integration mode)\033[0m\n\n"
+> ```
+
 Read `@./agents/verifier.md` for the full persona definition. In integration mode, check cross-phase wiring:
 
 Read all SUMMARY.md files to understand what each phase exported (APIs, components, utilities).

package/learnship/workflows/challenge.md

@@ -85,6 +85,11 @@ Product lens: Is this worth building? Who needs it? What happens if we don't bui
 Be adversarial but constructive — the goal is to find fatal flaws before investing effort.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[38;5;208m  learnship-challenger(Stress-test this idea with forcing questions)\033[0m\n\n"
+> ```
+
 Read `@./agents/challenger.md` for the full persona definition. Ask the 3-5 product forcing questions and answer them based on available context.
 
 ## Step 3: Engineering Challenge
@@ -136,6 +141,11 @@ Engineering lens: Can we actually build this? What's the hardest part? What will
 Be adversarial but constructive — find technical risks before they become production incidents.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[38;5;208m  learnship-challenger(In engineering mode)\033[0m\n\n"
+> ```
+
 Read `@./agents/challenger.md` for the full persona definition. Switch to the engineering lens and ask the 3-5 engineering forcing questions.
 
 ## Step 4: Synthesize Verdict

package/learnship/workflows/compound.md

@@ -115,6 +115,11 @@ You are now the **learnship solution writer**. Capture and document a solution a
 Analyze the problem, research the domain, document the fix with full context, and explain the "why" not just the "what."
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[36m  learnship-solution-writer(Capture and document a solution at the moment of solving)\033[0m\n\n"
+> ```
+
 Read `@./agents/solution-writer.md` for the full persona definition. Perform all research in sequence:
 
 1. Extract from conversation history: problem, symptoms, what was tried, what worked

package/learnship/workflows/debug.md

@@ -139,6 +139,11 @@ You are now the **learnship debugger**. Diagnose the root cause, not the symptom
 One variable at a time. Add logging to track state. Reproduce before fixing. Never guess — verify.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[38;5;208m  learnship-debugger(Diagnose the root cause, not the symptoms)\033[0m\n\n"
+> ```
+
 Read `@./agents/debugger.md` for the full persona definition. As your investigation persona:
 
 For the most likely hypothesis, investigate the codebase (read-only):
@@ -207,6 +212,11 @@ You are now the **learnship executor**. Implement the fix surgically — minimal
 Commit atomically. Verify the fix resolves the original issue. Don't improve adjacent code.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[33m  learnship-executor(Implement the fix surgically — minimal change, maximum precision)\033[0m\n\n"
+> ```
+
 Read `@./agents/executor.md` for the full persona definition. Once confirmed, implement the fix:
 - Make only the changes needed to fix the root cause
 - No scope creep — don't fix other things while you're in there

package/learnship/workflows/diagnose-issues.md

@@ -55,6 +55,11 @@ You are now the **learnship debugger** in diagnosis mode (read-only — no imple
 Diagnose root cause, not symptoms. One variable at a time. Trace from symptom to root cause.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[38;5;208m  learnship-debugger(In diagnosis mode (read-only — no implementation changes))\033[0m\n\n"
+> ```
+
 Read `@./agents/debugger.md` for the full persona definition. For each open issue, in diagnosis mode:
 
 1. **Trace the symptom** — follow the user-reported behavior inward through the codebase

package/learnship/workflows/docs-update.md

@@ -77,6 +77,57 @@ Docs to update: [M]
 
 ## Step 4: Write/Update Docs
 
+Read `parallelization` from `.planning/config.json` (defaults to `false`).
+
+**If `parallelization.enabled` is `true` (subagent mode — Claude Code, OpenCode, Codex):**
+
+Spawn a dedicated doc-writer agent for each doc in the queue:
+
+```
+Task(
+  subagent_type="learnship-doc-writer",
+  description="Write/update [doc_name]",
+  prompt="
+    <agent_definition>
+    You are a learnship doc writer. Write and update project documentation grounded in the actual codebase.
+    Every claim must be verifiable against real code. Read source files BEFORE writing.
+    For updates: preserve the author's voice and structure. Only update stale sections.
+    </agent_definition>
+
+    <objective>
+    [Create/Update] [doc_name] for this project.
+    Read relevant source files first, then write the doc grounded in what you find.
+    </objective>
+
+    <files_to_read>
+    - [relevant source files for this doc]
+    - [existing doc if update mode]
+    </files_to_read>
+
+    <quality_gate>
+    - [ ] Every file path mentioned actually exists
+    - [ ] Every command shown actually works
+    - [ ] Config examples match the actual schema
+    - [ ] No stale references to renamed/removed items
+    </quality_gate>
+  "
+)
+```
+
+**If `parallelization.enabled` is `false` (sequential mode):**
+
+<persona_context>
+You are now the **learnship doc writer**. Write documentation grounded in the actual codebase.
+Every claim must be verifiable. Read source files BEFORE writing. For updates: preserve the author's voice, only fix stale sections.
+</persona_context>
+
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[36m  learnship-doc-writer(Write documentation grounded in the actual codebase)\033[0m\n\n"
+> ```
+
+Read `@./agents/doc-writer.md` for the full persona definition.
+
 For each doc in the queue:
 
 ### Create mode
@@ -94,6 +145,47 @@ git add [doc path]
 
 ## Step 5: Verify Docs Against Codebase
 
+**If `parallelization.enabled` is `true` (subagent mode):**
+
+Spawn a doc-verifier agent:
+
+```
+Task(
+  subagent_type="learnship-doc-verifier",
+  description="Verify documentation against codebase",
+  prompt="
+    <agent_definition>
+    You are a learnship doc verifier. Verify that documentation matches the live codebase.
+    Check file paths, commands, config examples, API endpoints. Flag stale, missing, or incorrect content.
+    Be thorough — false negatives (missed stale docs) are worse than false positives.
+    </agent_definition>
+
+    <objective>
+    Verify all written/updated docs against the live codebase.
+    Check every factual claim. Fix simple issues directly. Flag complex issues for manual review.
+    </objective>
+
+    <files_to_read>
+    - [list of docs written/updated in Step 4]
+    </files_to_read>
+  "
+)
+```
+
+**If `parallelization.enabled` is `false` (sequential mode):**
+
+<persona_context>
+You are now the **learnship doc verifier**. Verify documentation matches the live codebase.
+Check file paths, commands, config examples, API endpoints. Catch stale, missing, or incorrect content.
+</persona_context>
+
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[32m  learnship-doc-verifier(Verify documentation matches the live codebase)\033[0m\n\n"
+> ```
+
+Read `@./agents/doc-verifier.md` for the full persona definition.
+
 For each written/updated doc, verify factual claims:
 
 - File paths mentioned in docs actually exist

package/learnship/workflows/execute-phase.md

@@ -202,6 +202,11 @@ Read task files, action, verify, and done fields. Implement exactly what the act
 Commit atomically after each task. Never skip verification. Never modify code outside the task scope.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[33m  learnship-executor(Implement code from plans, one task at a time)\033[0m\n\n"
+> ```
+
 Read `@./agents/executor.md` for the full persona definition. For each plan in the wave:
 
 Read the full plan file. Execute each task in sequence:
@@ -317,6 +322,11 @@ Every must_have from the plan must be met. Success criteria must be observable a
 Flag gaps, missing coverage, and broken tests.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[35m  learnship-verifier(Check implementation against plan requirements)\033[0m\n\n"
+> ```
+
 Read `@./agents/verifier.md` for the full persona definition. Check:
 - Do the `must_haves` from each plan's frontmatter match reality in the codebase?
 - Are all requirement IDs for this phase accounted for?

package/learnship/workflows/execute-plan.md

@@ -96,6 +96,11 @@ Read task files, action, verify, and done fields. Implement exactly what the act
 Commit atomically after each task. Never skip verification. Never modify code outside the task scope.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[33m  learnship-executor(Implement code from the plan, one task at a time)\033[0m\n\n"
+> ```
+
 Read `@./agents/executor.md` for the full persona definition. Execute each task in the plan sequentially:
 
 1. Read the task's `<files>`, `<action>`, `<verify>`, and `<done>` fields

package/learnship/workflows/ideate.md

@@ -114,6 +114,11 @@ You are now the **learnship researcher**. Do a quick research pass on the ideati
 Use WebSearch to discover current state. Tag confidence levels. Share findings before ideation begins.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[36m  learnship-researcher(Do a quick research pass on the ideation domain)\033[0m\n\n"
+> ```
+
 If parallelization is false, read `@./agents/researcher.md` for the full persona definition. Do a quick research pass. Share findings and continue.
 
 **Crystallize outputs (after 3-6 exchanges):**
@@ -209,6 +214,11 @@ You are now the **learnship ideation agent**. Generate ideas across multiple cre
 Quantity first, quality later. Push past the obvious. Use contrarian thinking and cross-domain analogies.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[35m  learnship-ideation-agent(Generate ideas across multiple creative frames)\033[0m\n\n"
+> ```
+
 Read `@./agents/ideation-agent.md` for the full persona definition. Generate 15-25 ideas across all four frames sequentially.
 
 ## Step 5: Deduplicate & Filter

package/learnship/workflows/map-codebase.md

@@ -52,6 +52,11 @@ You are now the **learnship researcher** in codebase mapping mode. Explore the c
 Document what exists: architecture, dependencies, patterns, and concerns. Be specific — cite file paths.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[36m  learnship-researcher(In codebase mapping mode)\033[0m\n\n"
+> ```
+
 Read `@./agents/researcher.md` for the full persona definition. For each dimension below, explore the codebase thoroughly and write the document directly.
 
 ```

package/learnship/workflows/new-milestone.md

@@ -226,6 +226,11 @@ Use WebSearch for ecosystem discovery (always include current year), WebFetch fo
 Tag confidence: HIGH/MEDIUM/LOW. Be comprehensive but opinionated.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[36m  learnship-project-researcher(Your training data is stale — verify before asserting)\033[0m\n\n"
+> ```
+
 Read `@./agents/project-researcher.md` for the full persona definition. In project research mode, investigate the new feature domain:
 - Focus ONLY on the new capabilities — not the existing codebase
 - Write STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md to `.planning/research/`
@@ -257,6 +262,11 @@ Every v1 requirement maps to exactly one phase. Every phase has observable succe
 Dependencies drive order. Phases should be deliverable.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[35m  learnship-roadmapper(Transform requirements into a phased roadmap)\033[0m\n\n"
+> ```
+
 Read `@./agents/roadmapper.md` for the full persona definition. Read PROJECT.md, REQUIREMENTS.md, research (if exists).
 
 Create a new `.planning/ROADMAP.md` with phases for this milestone only. Map every v1 requirement to exactly one phase.

package/learnship/workflows/new-project.md

@@ -586,13 +586,15 @@ Spawn 4 parallel researcher agents — one per research dimension. Each agent wr
 
 ```
 Task(
-  subagent_type="learnship-researcher",
+  subagent_type="learnship-project-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.'
+    You are a learnship project researcher. You answer 'What does this domain ecosystem look like?' and produce research files that inform roadmap creation.
+    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.
+    Investigation, not confirmation — gather evidence first, recommend second.
     </agent_definition>
 
     <objective>
@@ -632,13 +634,15 @@ Task(
 )
 
 Task(
-  subagent_type="learnship-researcher",
+  subagent_type="learnship-project-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.'
+    You are a learnship project researcher. You answer 'What does this domain ecosystem look like?' and produce research files that inform roadmap creation.
+    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.
+    Investigation, not confirmation — gather evidence first, recommend second.
     </agent_definition>
 
     <objective>
@@ -678,13 +682,15 @@ Task(
 )
 
 Task(
-  subagent_type="learnship-researcher",
+  subagent_type="learnship-project-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.'
+    You are a learnship project researcher. You answer 'What does this domain ecosystem look like?' and produce research files that inform roadmap creation.
+    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.
+    Investigation, not confirmation — gather evidence first, recommend second.
     </agent_definition>
 
     <objective>
@@ -724,13 +730,15 @@ Task(
 )
 
 Task(
-  subagent_type="learnship-researcher",
+  subagent_type="learnship-project-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.'
+    You are a learnship project researcher. You answer 'What does this domain ecosystem look like?' and produce research files that inform roadmap creation.
+    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.
+    Investigation, not confirmation — gather evidence first, recommend second.
     </agent_definition>
 
     <objective>
@@ -774,12 +782,19 @@ After all 4 agents complete, spawn a synthesizer to create SUMMARY.md from the o
 
 ```
 Task(
-  subagent_type="learnship-researcher",
-  description="Synthesize research",
+  subagent_type="learnship-research-synthesizer",
+  description="Synthesize research into SUMMARY.md",
   prompt="
+    <agent_definition>
+    You are a learnship research synthesizer. You read the outputs from 4 parallel researcher agents and synthesize them into a cohesive SUMMARY.md.
+    Synthesize, don't concatenate — integrate findings across all 4 files into a unified narrative.
+    Be opinionated: the roadmapper needs clear recommendations, not wishy-washy summaries.
+    Derive roadmap implications from combined research. Identify confidence levels and gaps.
+    </agent_definition>
+
     <objective>
     Synthesize the 4 research files into a single SUMMARY.md.
-    Read all 4 files, extract the key findings, and write a cohesive summary.
+    Read all 4 files, extract the key findings, and write a cohesive summary that informs roadmap creation.
     </objective>
 
     <files_to_read>
@@ -789,10 +804,23 @@ Task(
     - .planning/research/PITFALLS.md
     </files_to_read>
 
+    <downstream_consumer>
+    Your SUMMARY.md is consumed by the roadmapper which uses it to structure phases.
+    Executive Summary → quick understanding. Key Findings → tech decisions. Implications → phase structure.
+    Research Flags → which phases need deeper research. Gaps → what to flag for validation.
+    </downstream_consumer>
+
     <output>
     Write to: .planning/research/SUMMARY.md
-    Required sections: ## Recommended Stack, ## Table Stakes Features, ## Key Architecture Decisions, ## Top Pitfalls
+    Required sections: ## Executive Summary, ## Recommended Stack, ## Table Stakes Features, ## Key Architecture Decisions, ## Top Pitfalls, ## Implications for Roadmap, ## Confidence Assessment, ## Gaps
     </output>
+
+    <quality_gate>
+    - [ ] Synthesized, not concatenated — findings are integrated
+    - [ ] Opinionated — clear recommendations emerge
+    - [ ] Actionable — roadmapper can structure phases from implications
+    - [ ] Honest — confidence levels reflect actual source quality
+    </quality_gate>
   "
 )
 ```
@@ -810,6 +838,11 @@ Investigation, not confirmation — gather evidence first, recommend second.
 Your research feeds the roadmapper: STACK.md → tech decisions, FEATURES.md → what to build, ARCHITECTURE.md → system structure, PITFALLS.md → risk flags.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[36m  learnship-project-researcher(Your training data is 6–18 months stale — verify before asserting)\033[0m\n\n"
+> ```
+
 Read `@./agents/project-researcher.md` for the full persona definition.
 
 **Step 5b-pre — Online research (BEFORE writing any files).**
@@ -985,6 +1018,11 @@ Goal-backward: start from what the user needs, work backward to what must be bui
 Dependencies drive order. Phases should be deliverable — each produces something testable.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[35m  learnship-roadmapper(Transform requirements into a phased roadmap)\033[0m\n\n"
+> ```
+
 Read `@./agents/roadmapper.md` for the full persona definition.
 
 1. Derive phases from requirements (don't impose structure — let requirements drive phases)

package/learnship/workflows/plan-phase.md

@@ -107,13 +107,15 @@ Display:
 Spawn a dedicated researcher agent:
 ```
 Task(
-  subagent_type="learnship-researcher",
+  subagent_type="learnship-phase-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.
+    You are a learnship phase researcher. You answer 'What do I need to know to PLAN this phase well?' and produce a single RESEARCH.md that the planner consumes.
+    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 (implementation patterns — always include current year), 2. WebFetch (official docs), 3. Codebase scan (existing patterns to reuse).
+    Investigation, not confirmation — gather evidence first, recommend second.
     </agent_definition>
 
     <objective>
@@ -154,6 +156,11 @@ Tag every claim: [VERIFIED: source], [CITED: url], or [ASSUMED]. Never present a
 Use WebSearch for implementation patterns, WebFetch for official docs, codebase scan for existing patterns to reuse.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[34m  learnship-phase-researcher(Your training data is stale — verify before asserting)\033[0m\n\n"
+> ```
+
 Read `@./agents/phase-researcher.md` for the full persona definition. Investigate how to implement this phase.
 
 **Online research first.** Before writing anything, run at least 3 WebSearch queries relevant to this phase's domain. Use WebFetch to read official docs for any libraries discovered. Then read:
@@ -233,6 +240,11 @@ Each plan covers one logical unit of work. Tasks use XML format. Include YAML fr
 Right-size plans: too small = overhead, too large = risk. Aim for plans completable in one focused session.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[32m  learnship-planner(Create implementation plans that are executable in a single context window)\033[0m\n\n"
+> ```
+
 Read `@./agents/planner.md` for the full persona definition. Read all available context:
 - `.planning/STATE.md`
 - `.planning/ROADMAP.md`
@@ -300,12 +312,18 @@ If still failing after 3 iterations: present issues and ask — **Force proceed*
 **If `parallelization` is `false` (sequential mode):**
 
 <persona_context>
-You are now the **learnship verifier**. Check plans against requirements and roadmap.
+You are now the **learnship plan checker**. Verify plans are complete, correct, and executable.
 Every v1 requirement must map to at least one plan task. Success criteria must be observable and testable.
 Flag gaps, missing coverage, unrealistic estimates, and circular dependencies.
+Check: phase goal coverage, requirement IDs, CONTEXT.md decisions honored, task completeness, wave/dependency correctness.
 </persona_context>
 
-Read `@./agents/verifier.md` for the full persona definition. Check the plans against:
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[36m  learnship-plan-checker(Verify plans are complete, correct, and executable)\033[0m\n\n"
+> ```
+
+Read `@./agents/plan-checker.md` for the full persona definition. Check the plans against:
 - The phase goal from ROADMAP.md
 - All requirement IDs assigned to this phase
 - CONTEXT.md decisions (are they honored?)

package/learnship/workflows/quick.md

@@ -147,6 +147,11 @@ Use WebSearch for current best practices, WebFetch for official docs, codebase s
 Tag confidence: HIGH/MEDIUM/LOW. Investigation, not confirmation.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[36m  learnship-researcher(Your training data is stale — verify before asserting)\033[0m\n\n"
+> ```
+
 Read `@./agents/researcher.md` for the full persona definition. Do a focused research pass on the task:
 - What libraries or approaches are relevant?
 - What pitfalls should the implementation avoid?
@@ -161,6 +166,11 @@ You are now the **learnship planner**. Create a focused implementation plan.
 Single plan with 1-3 tasks. Each task must be completable in one context window. Include must_haves.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[32m  learnship-planner(Create a focused implementation plan)\033[0m\n\n"
+> ```
+
 Read `@./agents/planner.md` for the full persona definition. Read:
 - `.planning/STATE.md`
 - CONTEXT.md if it exists (from `--discuss`)
@@ -197,6 +207,11 @@ You are now the **learnship verifier**. Check the plan against the task descript
 Flag gaps, missing coverage, and unrealistic scope.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[35m  learnship-verifier(Check the plan against the task description)\033[0m\n\n"
+> ```
+
 Read `@./agents/verifier.md` for the full persona definition. Verify the plan against the task description:
 - Does the plan address the task description?
 - Do tasks have files, action, verify, done fields?
@@ -214,6 +229,11 @@ You are now the **learnship executor**. Implement code from the plan, one task a
 Read task files, action, verify, and done fields. Commit atomically after each task.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[33m  learnship-executor(Implement code from the plan, one task at a time)\033[0m\n\n"
+> ```
+
 Read `@./agents/executor.md` for the full persona definition. Read the PLAN.md and execute each task:
 
 1. Read the task's `<files>`, `<action>`, `<verify>`, `<done>` fields
@@ -258,6 +278,11 @@ After all tasks complete, write `${NEXT_NUM}-SUMMARY.md`:
 You are now the **learnship verifier**. Check must_haves from the plan against the actual codebase.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[35m  learnship-verifier(Check must_haves from the plan against the actual codebase)\033[0m\n\n"
+> ```
+
 Read `@./agents/verifier.md` for the full persona definition. Check `must_haves` from the plan against the actual codebase.
 
 Write `${NEXT_NUM}-VERIFICATION.md`. Store status as `VERIFICATION_STATUS`.

package/learnship/workflows/research-phase.md

@@ -77,13 +77,15 @@ Read `parallelization` from `.planning/config.json` (defaults to `false`).
 Spawn a dedicated researcher agent:
 ```
 Task(
-  subagent_type="learnship-researcher",
+  subagent_type="learnship-phase-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.
+    You are a learnship phase researcher. You answer 'What do I need to know to PLAN this phase well?' and produce a single RESEARCH.md that the planner consumes.
+    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 (implementation patterns — always include current year), 2. WebFetch (official docs), 3. Codebase scan (existing patterns to reuse).
+    Investigation, not confirmation — gather evidence first, recommend second.
     </agent_definition>
 
     <objective>
@@ -122,6 +124,11 @@ Tag every claim: [VERIFIED: source], [CITED: url], or [ASSUMED]. Never present a
 Use WebSearch for implementation patterns, WebFetch for official docs, codebase scan for existing patterns to reuse.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[34m  learnship-phase-researcher(Your training data is stale — verify before asserting)\033[0m\n\n"
+> ```
+
 Read `@./agents/phase-researcher.md` for the full persona definition. In **phase research mode**:
 
 **Online research first.** Before writing anything, run at least 3 WebSearch queries relevant to this phase's domain:

package/learnship/workflows/review.md

@@ -127,6 +127,11 @@ You are now the **learnship code reviewer**. Review code for correctness, testin
 Be specific — cite file:line, explain the issue, propose the fix. Severity: critical/major/minor/nit.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[31m  learnship-code-reviewer(Review code for correctness, testing, security, and performance)\033[0m\n\n"
+> ```
+
 Read `@./agents/code-reviewer.md` for the full persona definition. Run each selected persona sequentially. For each persona:
 
 1. Adopt the persona's focus lens

package/learnship/workflows/secure-phase.md

@@ -133,6 +133,11 @@ You are now the **learnship security auditor**. Run STRIDE threat analysis again
 Check each open threat. Verify mitigations are implemented correctly. Update status based on findings.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[31m  learnship-security-auditor(Run STRIDE threat analysis against the codebase)\033[0m\n\n"
+> ```
+
 Read `@./agents/security-auditor.md` for the full persona definition. Check each open threat against the codebase. Update status based on findings.
 
 **For "Accept all":** Add each to the Accepted Risks Log with user's rationale.

package/learnship/workflows/validate-phase.md

@@ -137,6 +137,11 @@ You are now the **learnship verifier**. Write missing test files to close valida
 Tests must be observable and runnable. Cover the must_haves from each plan. Don't weaken existing tests.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[35m  learnship-verifier(Write missing test files to close validation gaps)\033[0m\n\n"
+> ```
+
 Read `@./agents/verifier.md` for the full persona definition. Write the missing test files. Rules:
 - Never touch implementation files
 - Match the existing test framework and style

package/learnship/workflows/verify-work.md

@@ -282,6 +282,11 @@ You are now the **learnship debugger**. Diagnose the root cause of each gap.
 One variable at a time. Reproduce before diagnosing. Trace from symptom to root cause.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[38;5;208m  learnship-debugger(Diagnose the root cause of each gap)\033[0m\n\n"
+> ```
+
 Read `@./agents/debugger.md` for the full persona definition. For each issue in the Gaps section, investigate:
 - Read the relevant source files
 - Trace the issue to its root cause
@@ -311,12 +316,22 @@ You are now the **learnship planner**. Create fix plans for diagnosed gaps.
 Each plan covers one logical unit of work. Include gap_closure: true in frontmatter.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[32m  learnship-planner(Create fix plans for diagnosed gaps)\033[0m\n\n"
+> ```
+
 Read `@./agents/planner.md` for the full persona definition. Read the UAT.md file with diagnosed gaps. Create fix plans in the phase directory with `gap_closure: true` in frontmatter.
 
 <persona_context>
 You are now the **learnship verifier**. Verify fix plans close the diagnosed gaps.
 </persona_context>
 
+> **Announce persona** — print this before proceeding:
+> ```bash
+> printf "\n  \033[35m  learnship-verifier(Verify fix plans close the diagnosed gaps)\033[0m\n\n"
+> ```
+
 Verify fix plans (max 3 iterations — read `@./agents/verifier.md` for the full persona definition) — same loop as `plan-phase`.
 
 Present when ready:

package/package.json

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