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

package/README.md

@@ -38,7 +38,7 @@
 npx learnship
 ```
 
-**Works on Mac, Windows, and Linux.** Requires Node.js ≥ 18 and Git. The installer auto-detects your platform.
+**Works on Mac, Windows, and Linux.** Requires Node.js ≥ 22 and Git. The installer auto-detects your platform.
 
 ```bash
 npx learnship --global   # all projects
@@ -521,7 +521,7 @@ Project settings live in `.planning/config.json`. Set during `/new-project` or e
 
 | Setting | Options | Default | What it controls |
 |---------|---------|---------|-----------------|
-| `mode` | `yolo`, `interactive` | `yolo` | `yolo` auto-approves steps; `interactive` confirms at each decision |
+| `mode` | `auto`, `interactive` | `auto` | `auto` auto-approves steps; `interactive` confirms at each decision |
 | `granularity` | `coarse`, `standard`, `fine` | `standard` | Phase size: 3-5 / 5-8 / 8-12 phases |
 | `model_profile` | `quality`, `balanced`, `budget` | `balanced` | Agent model tier (see table below) |
 | `learning_mode` | `auto`, `manual` | `auto` | `auto` offers learning at checkpoints; `manual` requires explicit invocation |
@@ -579,8 +579,8 @@ Project settings live in `.planning/config.json`. Set during `/new-project` or e
 
 | Scenario | `mode` | `granularity` | `model_profile` | Research | Plan Check | Verifier |
 |----------|--------|--------------|----------------|----------|------------|---------|
-| Prototyping | `yolo` | `coarse` | `budget` | off | off | off |
-| Normal dev | `yolo` | `standard` | `balanced` | on | on | on |
+| Prototyping | `auto` | `coarse` | `budget` | off | off | off |
+| Normal dev | `auto` | `standard` | `balanced` | on | on | on |
 | Production | `interactive` | `fine` | `quality` | on | on | on |
 
 ---
@@ -896,7 +896,7 @@ learnship/
 ├── bin/
 │   └── install.js          # Multi-platform installer (Claude Code, OpenCode, Gemini CLI, Codex CLI, Windsurf)
 ├── tests/
-│   └── validate_multiplatform.sh  # 511+ check test suite (5 suites, 6 platforms)
+│   └── run_all.sh               # 15 test suites, 1200+ checks across 6 platforms
 ├── SKILL.md                # Meta-skill: platform context loaded by Cascade / AI agents
 ├── install.sh              # Shell installer wrapper
 ├── package.json            # npm package (npx learnship)

package/bin/install.js

@@ -503,11 +503,18 @@ function verifyInstalled(dirPath, description) {
   return true;
 }
 
+// Internal-only workflows that should never be installed to user projects.
+// These are used to maintain the learnship repo itself.
+const INTERNAL_ONLY_WORKFLOWS = new Set([
+  'sync-upstream-skills.md',
+]);
+
 /** Recursively copy dir, replacing path references in .md files */
 function copyDir(srcDir, destDir, pathPrefix, platform) {
   if (fs.existsSync(destDir)) fs.rmSync(destDir, { recursive: true });
   fs.mkdirSync(destDir, { recursive: true });
   for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    if (INTERNAL_ONLY_WORKFLOWS.has(entry.name)) continue;
     const src = path.join(srcDir, entry.name);
     const dest = path.join(destDir, entry.name);
     if (entry.isDirectory()) {
@@ -1503,6 +1510,7 @@ function install(platform, isGlobal) {
     let count = 0;
     for (const f of fs.readdirSync(path.join(learnshipSrc, 'workflows'))) {
       if (!f.endsWith('.md')) continue;
+      if (INTERNAL_ONLY_WORKFLOWS.has(f)) continue;
       let c = fs.readFileSync(path.join(learnshipSrc, 'workflows', f), 'utf8');
       c = replacePaths(c, pathPrefix, platform);
       if (f === 'new-project.md') c = rewriteNewProject(c, platform);

package/cursor-rules/learnship.mdc

@@ -64,32 +64,42 @@ Suggest the appropriate workflow slash command when relevant:
 | Workflow | When to suggest |
 |----------|----------------|
 | `/new-project` | User wants to start a new project from scratch |
+| `/new-milestone` | Start a new milestone cycle on an existing project |
 | `/discuss-phase [N]` | Before planning a phase — capture user's implementation vision |
+| `/discuss-milestone` | Capture milestone-level goals before `/new-milestone` |
 | `/plan-phase [N]` | After discussing a phase — create executable plans |
 | `/execute-phase [N]` | Plans exist and are ready to run |
 | `/verify-work [N]` | Phase execution complete — user acceptance testing |
+| `/review` | Code ready for review — multi-persona quality check |
+| `/ship` | Tests pass, code reviewed — ship it (test → lint → commit → push → PR) |
+| `/complete-milestone` | All phases in the current milestone are done |
 | `/ls` | User asks "where are we?", "what's next?", or starts a new session |
 | `/next` | User wants to keep moving without deciding what to do |
-| `/quick [task]` | Small ad-hoc task that doesn't need full phase ceremony |
 | `/progress` | Status overview and routing |
+| `/quick [task]` | Small ad-hoc task that doesn't need full phase ceremony |
+| `/debug [symptom]` | Bug report — systematic hypothesis-driven debugging |
+| `/map-codebase` | Analyze existing codebase structure before planning (brownfield projects) |
+| `/ideate` | Codebase-grounded idea generation (`--explore` for Socratic mode) |
+| `/challenge` | Stress-test a proposal with product + engineering forcing questions |
+| `/settings` | Change project configuration after setup |
+| `/health` | Project health check — stale files, uncommitted changes, config drift |
+| `/compound` | Just solved a problem or learned a pattern — capture it while fresh |
 | `/pause-work` | User is stopping mid-phase |
 | `/resume-work` | User is returning to an in-progress project |
-| `/complete-milestone` | All phases in the current milestone are done |
-| `/compound` | Just solved a problem or learned a pattern — capture it while fresh |
-| `/review` | Code ready for review — multi-persona quality check |
-| `/challenge` | About to commit to a milestone or big feature — stress-test the scope |
-| `/ship` | Tests pass, code reviewed — ship it (test → lint → commit → push → PR) |
-| `/ideate` | Looking for what to build next — codebase-grounded idea generation (add `--explore` for Socratic mode) |
-| `/guard` | Working on sensitive files — enable safety mode with destructive command warnings |
-| `/sync-docs` | After code changes — detect stale documentation |
-| `/forensics` | Something went wrong — post-mortem investigation (read-only) |
-| `/undo` | Need to revert commits safely — preserves git history |
+| `/guard` | Working on sensitive files — enable safety mode |
 | `/note [text]` | Quick idea capture — zero friction, no questions |
 | `/session-report` | End of session — generate summary for stakeholders |
 | `/secure-phase [N]` | After execution — per-phase STRIDE security verification |
+| `/validate-phase [N]` | Retroactive test coverage audit for a completed phase |
+| `/diagnose-issues` | Batch-diagnose multiple UAT issues after `/verify-work` |
 | `/docs-update` | Generate or update project documentation |
+| `/sync-docs` | After code changes — detect stale documentation |
 | `/extract-learnings [N]` | After phase completion — structured learning extraction |
 | `/milestone-summary` | Generate comprehensive milestone summary for team onboarding |
+| `/forensics` | Something went wrong — post-mortem investigation (read-only) |
+| `/undo` | Need to revert commits safely — preserves git history |
+| `/knowledge-base` | Aggregate learnings across sessions into searchable KNOWLEDGE.md |
+| `/transition` | Hand off project context to a new session or collaborator |
 
 ## Planning Artifacts
 
@@ -150,15 +160,36 @@ Set `"parallelization": { "enabled": true|false }` in `.planning/config.json` ba
 
 ## Structured Questions
 
-When workflows include `AskUserQuestion()` blocks, **Cursor has no native structured question tool**. Present each question as a numbered text list with descriptions and ask the user to reply with their choice number or label. Example:
+When workflows include `AskUserQuestion()` blocks, **Cursor has no native structured question tool**. Present each question as a numbered text list with descriptions and ask the user to reply with their choice number or label. Present questions in rounds (Round 1: core settings, Round 2: workflow agents, Round 3: pipeline & git, Round 4: parallelization). **Wait for the user's reply after EACH round before showing the next.** Do NOT present all questions at once.
 
+Example:
 ```
 **Working Style**
 How do you want to work?
-1. YOLO (Recommended) — Auto-approve steps, just execute
+1. Auto (Recommended) — Auto-approve steps, just execute
 2. Interactive — Confirm at each step
 ```
 
+## Config Schema
+
+After all configuration rounds are answered, write `.planning/config.json` with this EXACT schema. Map user answers to these keys — do NOT invent keys like `working_style`, `model_tier`, `platform`, `milestone`, or `phases`:
+
+- Working Style → `"mode"`: `"auto"` or `"interactive"`
+- Granularity → `"granularity"`: `"coarse"`, `"standard"`, or `"fine"`
+- Learning Partner → `"learning_mode"`: `"auto"` or `"manual"`
+- AI Models → `"model_profile"`: `"balanced"`, `"quality"`, or `"budget"`
+- Research → `"workflow.research"`: `true` or `false`
+- Plan Check → `"workflow.plan_check"`: `true` or `false`
+- Verifier → `"workflow.verifier"`: `true` or `false`
+- Review → `"workflow.review"`: `true` or `false`
+- TDD → `"test_first"`: `true` or `false`
+- Ship Pipeline → `"ship.auto_test"`, `"ship.conventional_commits"`, `"ship.pr_template"`
+- Git Tracking → `"planning.commit_docs"`: `true` or `false`
+- Commit Mode → `"planning.commit_mode"`: `"auto"` or `"manual"`
+- Parallel Execution → `"parallelization.enabled"`: `true` or `false`
+
+Run the config verification gate after writing — it must print `CONFIG_VALID`.
+
 ## Learning Mode
 
 Read `learning_mode` from `.planning/config.json` (default: "auto"):

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.3.1",
+  "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/references/planning-config.md

@@ -229,7 +229,7 @@ The `parallelization` field is now an object. Legacy flat `"parallelization": tr
 
 ### Gates Section
 
-Controls which confirmation prompts are shown during workflows. Set to `false` to skip specific confirmations (useful for experienced users in yolo mode).
+Controls which confirmation prompts are shown during workflows. Set to `false` to skip specific confirmations (useful for experienced users in auto mode).
 
 | Option | Default | Description |
 |--------|---------|-------------|

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
@@ -181,6 +191,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 ## Step 5: Record Decision
 
 If the user makes a decision based on the challenge:

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

@@ -64,6 +64,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 Then ask as follow-ups (one at a time):
 - "What did you expect to happen?"
 - "What have you already tried?"
@@ -137,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):
@@ -205,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
@@ -127,6 +132,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 ## Step 6: Create Fix Plans
 
 For each fix group, write a PLAN.md in the phase directory:

package/learnship/workflows/discuss-milestone.md

@@ -49,6 +49,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 ## Step 2: Discuss Goals
 
 Ask openly: **"What do you want this milestone to achieve?"**

package/learnship/workflows/discuss-phase.md

@@ -73,6 +73,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 If "Skip" → exit workflow.
 
 If no CONTEXT.md exists but plans already exist for this phase:
@@ -91,6 +93,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 ## Step 3: Scout Codebase
 
 Do a lightweight scan to inform the discussion. Look for:
@@ -164,6 +168,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 If "All clear" → skip to Step 6.
 
 **For each selected area, discuss:**
@@ -186,6 +192,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 3. After 4 questions, ask: "More questions about [area], or move to next?"
 4. If more → ask 4 more, then check again
 
@@ -207,6 +215,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 <scope_guardrail>
 **No scope creep.** The phase boundary comes from ROADMAP.md and is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.
 

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/help.md

@@ -178,6 +178,6 @@ Edit project settings with `/settings` or directly:
 cat .planning/config.json
 ```
 
-Key settings: `mode` (yolo/interactive), `model_profile` (quality/balanced/budget), `learning_mode` (auto/manual).
+Key settings: `mode` (auto/interactive), `model_profile` (quality/balanced/budget), `learning_mode` (auto/manual).
 
 See `README.md` for the full configuration reference.

package/learnship/workflows/ideate.md

@@ -89,6 +89,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 If yes: read `parallelization` from `.planning/config.json`. If `parallelization.enabled` is true, spawn a researcher agent:
 ```
 Task(
@@ -112,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):**
@@ -207,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/list-phase-assumptions.md

@@ -119,6 +119,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 Note: Any corrections discussed here are not automatically captured. Run `discuss-phase [N]` to write them to a CONTEXT.md that planners will read.
 
 ---

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

@@ -121,10 +121,14 @@ Note the tech stack, key directories, and any README content internally. Use thi
 
 ## Step 2: Configuration
 
-Present configuration questions using structured question rounds. Use your platform's interactive question tool, or numbered text lists if unavailable.
+> **🔴 MANDATORY INTERACTIVE QUESTIONS — You MUST present each round as a blocking question using `AskUserQuestion` (or your platform's equivalent: `ask_user_question` on Windsurf, `ask_user` on Gemini, `request_user_input` on Codex). Each round is a SEPARATE blocking call. Do NOT combine all rounds into one. Do NOT render questions as plain text or markdown lists — you MUST use the interactive question tool so the user clicks options. Wait for the user's reply after EACH round before showing the next round.**
+>
+> **🛑 FORBIDDEN:** Do NOT present all questions at once as a text wall. Do NOT skip any question. Do NOT invent answers. Do NOT proceed to the config.json write step until ALL 4 rounds have been answered by the user.
 
 **Round 1 — Core settings (4 questions):**
 
+> Present these 4 questions as a SINGLE blocking `AskUserQuestion` call. STOP and wait for the user's reply before proceeding to Round 2.
+
 ```
 AskUserQuestion([
   {
@@ -132,7 +136,7 @@ AskUserQuestion([
     question: "How do you want to work?",
     multiSelect: false,
     options: [
-      { label: "YOLO (Recommended)", description: "Auto-approve steps, just execute" },
+      { label: "Auto (Recommended)", description: "Auto-approve steps, just execute" },
       { label: "Interactive", description: "Confirm at each step" }
     ]
   },
@@ -168,8 +172,12 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's Round 1 reply before continuing.
+
 **Round 2 — Workflow agents (5 questions):**
 
+> Present these 5 questions as a SINGLE blocking `AskUserQuestion` call. STOP and wait for the user's reply before proceeding to Round 3.
+
 ```
 AskUserQuestion([
   {
@@ -220,8 +228,12 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's Round 2 reply before continuing.
+
 **Round 3 — Pipeline & git (4 questions):**
 
+> Present these 4 questions as a SINGLE blocking `AskUserQuestion` call. STOP and wait for the user's reply before proceeding to Round 4.
+
 ```
 AskUserQuestion([
   {
@@ -264,13 +276,35 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's Round 3 reply before continuing.
+
 <!-- LEARNSHIP_PARALLEL_BLOCK -->
 
+> 🛑 STOP. Wait for the user's Round 4 reply (parallelization) before continuing.
+
+**Now create `.planning/config.json`** — use EXACTLY this schema. Map the user's answers to these keys. Do NOT invent keys. Do NOT use flat keys like `working_style`, `model_tier`, `platform`, `milestone`, or `phases` — those are WRONG.
+
+**Key mapping from questions to config:**
+- Working Style → `"mode"`: `"auto"` or `"interactive"`
+- Granularity → `"granularity"`: `"coarse"`, `"standard"`, or `"fine"`
+- Learning Partner → `"learning_mode"`: `"auto"` or `"manual"`
+- AI Models → `"model_profile"`: `"balanced"`, `"quality"`, or `"budget"`
+- Research → `"workflow.research"`: `true` or `false`
+- Plan Check → `"workflow.plan_check"`: `true` or `false`
+- Verifier → `"workflow.verifier"`: `true` or `false`
+- Review → `"workflow.review"`: `true` or `false`
+- Solutions Search → `"workflow.solutions_search"`: `true` or `false`
+- TDD → `"test_first"`: `true` or `false`
+- Ship Pipeline → `"ship.auto_test"`, `"ship.conventional_commits"`, `"ship.pr_template"`: each `true` or `false`
+- Git Tracking → `"planning.commit_docs"`: `true` or `false`
+- Commit Mode → `"planning.commit_mode"`: `"auto"` or `"manual"`
+- Parallel Execution → `"parallelization.enabled"`: `true` or `false`
+
 Create `.planning/config.json` with all settings:
 
 ```json
 {
-  "mode": "yolo|interactive",
+  "mode": "auto|interactive",
   "granularity": "coarse|standard|fine",
   "model_profile": "quality|balanced|budget",
   "learning_mode": "auto|manual",
@@ -332,6 +366,38 @@ Create `.planning/config.json` with all settings:
 
 **Note:** The `parallelization` field is now an object (not a flat boolean). Legacy flat `"parallelization": true` is still honored for backward compatibility. The `gates` and `safety` sections use sensible defaults — only ask users about them if they specifically want to customize.
 
+**Verify config.json was written correctly:**
+
+```bash
+node -e "
+const fs=require('fs');
+try{
+  const c=JSON.parse(fs.readFileSync('.planning/config.json','utf8'));
+  const errs=[];
+  if(!['auto','interactive'].includes(c.mode)) errs.push('mode must be auto|interactive, got: '+c.mode);
+  if(!['coarse','standard','fine'].includes(c.granularity)) errs.push('granularity must be coarse|standard|fine');
+  if(!['quality','balanced','budget'].includes(c.model_profile)) errs.push('model_profile must be quality|balanced|budget');
+  if(!['auto','manual'].includes(c.learning_mode)) errs.push('learning_mode must be auto|manual');
+  if(typeof c.test_first!=='boolean') errs.push('test_first must be boolean');
+  if(!c.planning||!['auto','manual'].includes(c.planning.commit_mode)) errs.push('planning.commit_mode must be auto|manual');
+  if(!c.workflow||typeof c.workflow.research!=='boolean') errs.push('workflow.research must be boolean');
+  if(!c.workflow||typeof c.workflow.plan_check!=='boolean') errs.push('workflow.plan_check must be boolean');
+  if(!c.workflow||typeof c.workflow.verifier!=='boolean') errs.push('workflow.verifier must be boolean');
+  if(!c.workflow||typeof c.workflow.review!=='boolean') errs.push('workflow.review must be boolean');
+  if(!c.parallelization||typeof c.parallelization.enabled!=='boolean') errs.push('parallelization.enabled must be boolean');
+  if(!c.ship||typeof c.ship.auto_test!=='boolean') errs.push('ship.auto_test must be boolean');
+  const bad=['working_style','model_tier','platform','milestone','phases','commit_mode'];
+  for(const k of bad){if(k in c)errs.push('FORBIDDEN top-level key: '+k+' — use the nested schema');}
+  if(errs.length){console.log('CONFIG_INVALID');errs.forEach(e=>console.log('  - '+e));}
+  else console.log('CONFIG_VALID');
+}catch(e){console.log('CONFIG_MISSING_OR_CORRUPT: '+e.message);}
+"
+```
+
+**If `CONFIG_INVALID` or `CONFIG_MISSING_OR_CORRUPT`:** The config file is wrong. Fix it to match the schema above exactly, then re-run the verification. Do NOT proceed until it passes.
+
+**If `CONFIG_VALID`:** Continue.
+
 If `planning.commit_docs` is false, add `.planning/` to `.gitignore`:
 ```bash
 echo ".planning/" >> .gitignore
@@ -520,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>
@@ -566,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>
@@ -612,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>
@@ -658,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>
@@ -708,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>
@@ -723,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>
   "
 )
 ```
@@ -744,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).**
@@ -919,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

@@ -91,6 +91,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 If "All clear" → skip to Step 4.
 
 For each selected area, ask 1-2 focused questions with concrete options using structured questions. Max 2 questions per area — keep it lightweight.
@@ -145,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?
@@ -159,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`)
@@ -195,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?
@@ -212,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
@@ -256,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

@@ -94,6 +94,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 ## Step 5: Resolve Open Threats
 
 Read `parallelization` from `.planning/config.json` (defaults to `false`).
@@ -131,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.
@@ -152,6 +159,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 ## Step 6: Write SECURITY.md
 
 Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-SECURITY.md` using `@./templates/security.md`:

package/learnship/workflows/settings.md

@@ -18,7 +18,7 @@ If missing, create from template:
 ```bash
 cp templates/config.json .planning/config.json 2>/dev/null || cat > .planning/config.json << 'EOF'
 {
-  "mode": "interactive",
+  "mode": "auto",
   "granularity": "standard",
   "model_profile": "balanced",
   "learning_mode": "auto",
@@ -117,7 +117,7 @@ AskUserQuestion([
     question: "Working style?",
     multiSelect: false,
     options: [
-      { label: "YOLO", description: "Auto-approve steps, just execute" },
+      { label: "Auto", description: "Auto-approve steps, just execute" },
       { label: "Interactive", description: "Confirm at each step, more control" }
     ]
   },
@@ -143,6 +143,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 **Round 2 — Workflow agents (6 questions):**
 
 ```
@@ -204,6 +206,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 **Round 3 — Pipeline & git (4 questions):**
 
 ```
@@ -249,6 +253,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 ## Step 5: Save Config
 
 After user types "done", read the current config, apply all changes, and write the complete updated JSON. Preserve any fields not shown in the menu (gates, hooks, etc.) — never drop fields the user didn't modify.

package/learnship/workflows/validate-phase.md

@@ -97,6 +97,8 @@ AskUserQuestion([
 ])
 ```
 
+> 🛑 STOP. Wait for the user's reply before continuing.
+
 **If "Fill all gaps":**
 
 Read `parallelization` from `.planning/config.json` (defaults to `false`).
@@ -135,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.1",
+  "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",
@@ -56,6 +56,6 @@
     "test": "bash tests/run_all.sh"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0.0"
   }
 }

package/references/planning-config.md

@@ -229,7 +229,7 @@ The `parallelization` field is now an object. Legacy flat `"parallelization": tr
 
 ### Gates Section
 
-Controls which confirmation prompts are shown during workflows. Set to `false` to skip specific confirmations (useful for experienced users in yolo mode).
+Controls which confirmation prompts are shown during workflows. Set to `false` to skip specific confirmations (useful for experienced users in auto mode).
 
 | Option | Default | Description |
 |--------|---------|-------------|

package/templates/config.json

@@ -1,5 +1,5 @@
 {
-  "mode": "interactive",
+  "mode": "auto",
   "granularity": "standard",
   "context": "dev",
   "model_profile": "balanced",