learnship 2.3.2 → 2.3.4

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

@@ -125,9 +125,9 @@ Note the tech stack, key directories, and any README content internally. Use thi
 >
 > **🛑 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):**
+**Round 1 — Core settings (6 questions):**
 
-> Present these 4 questions as a SINGLE blocking `AskUserQuestion` call. STOP and wait for the user's reply before proceeding to Round 2.
+> Present these 6 questions as a SINGLE blocking `AskUserQuestion` call. STOP and wait for the user's reply before proceeding to Round 2.
 
 ```
 AskUserQuestion([
@@ -168,6 +168,25 @@ AskUserQuestion([
       { label: "Quality", description: "Large-tier models for all agents (highest cost, best results)" },
       { label: "Budget", description: "Medium for code, small for research/verification (lowest cost)" }
     ]
+  },
+  {
+    header: "Questioning Depth",
+    question: "How deep should discuss-phase and new-project question you?",
+    multiSelect: false,
+    options: [
+      { label: "Standard (Recommended)", description: "4 focused exchanges per area — fast and sufficient for most projects" },
+      { label: "Deep", description: "Extended questioning: walks every decision branch until shared understanding is reached. Produces richer CONTEXT.md and PROJECT.md. Good for complex or unfamiliar domains." }
+    ]
+  },
+  {
+    header: "Output Profile",
+    question: "How verbose should agent responses be?",
+    multiSelect: false,
+    options: [
+      { label: "Dev (Recommended)", description: "Concise, action-oriented — code first, brief rationale. Low verbosity." },
+      { label: "Research", description: "Detailed explanations, alternatives, and context. High verbosity." },
+      { label: "Review", description: "Audit-focused — findings, severity, recommendations. Medium verbosity." }
+    ]
   }
 ])
 ```
@@ -289,6 +308,8 @@ AskUserQuestion([
 - Granularity → `"granularity"`: `"coarse"`, `"standard"`, or `"fine"`
 - Learning Partner → `"learning_mode"`: `"auto"` or `"manual"`
 - AI Models → `"model_profile"`: `"balanced"`, `"quality"`, or `"budget"`
+- Questioning Depth → `"workflow.discuss_mode"`: `"discuss"` (Standard) or `"deep"` (Deep)
+- Output Profile → `"context"`: `"dev"` (Dev), `"research"` (Research), or `"review"` (Review)
 - Research → `"workflow.research"`: `true` or `false`
 - Plan Check → `"workflow.plan_check"`: `true` or `false`
 - Verifier → `"workflow.verifier"`: `true` or `false`
@@ -308,6 +329,7 @@ Create `.planning/config.json` with all settings:
   "granularity": "coarse|standard|fine",
   "model_profile": "quality|balanced|budget",
   "learning_mode": "auto|manual",
+  "context": "dev|research|review",
   "test_first": false|true,
   "planning": {
     "commit_docs": true|false,
@@ -322,7 +344,7 @@ Create `.planning/config.json` with all settings:
     "review": true|false,
     "solutions_search": true|false,
     "security_enforcement": true|false,
-    "discuss_mode": "discuss",
+    "discuss_mode": "discuss|deep",
     "tdd_mode": false|true
   },
   "parallelization": {
@@ -380,6 +402,8 @@ try{
   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.context&&!['dev','research','review'].includes(c.context)) errs.push('context must be dev|research|review');
+  if(c.workflow&&c.workflow.discuss_mode&&!['discuss','deep'].includes(c.workflow.discuss_mode)) errs.push('workflow.discuss_mode must be discuss|deep');
   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');
@@ -424,7 +448,25 @@ Display:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-This step is **strictly sequential**. You must complete each numbered exchange fully before moving to the next. Do not batch questions. Do not skip exchanges. Do not proceed to Step 4 until Exchange 4 is complete.
+**Detect questioning mode:** Check for `--deep` flag in the `/new-project` command. If not present, ask the user:
+
+```
+AskUserQuestion([
+  {
+    header: "Questioning Depth",
+    question: "How deep do you want me to go with questions before writing PROJECT.md?",
+    multiSelect: false,
+    options: [
+      { label: "Standard (Recommended)", description: "4 focused exchanges — enough for a sharp PROJECT.md" },
+      { label: "Deep", description: "Grill-me style — I walk every open branch until we reach shared understanding. Takes longer, produces a richer PROJECT.md" }
+    ]
+  }
+])
+```
+
+> 🛑 STOP. Wait for the user's reply. Record mode as `QUESTIONING_MODE = standard | deep`.
+
+This step is **strictly sequential**. You must complete each numbered exchange fully before moving to the next. Do not batch questions. Do not skip exchanges. Do not proceed to Step 4 until the gate check passes.
 
 **Exchange 1 — Opening question:**
 
@@ -465,6 +507,8 @@ Based on all previous answers, ask a third follow-up that clarifies scope, edge
 >
 > If any count is wrong, go back and complete the missing exchanges. Do NOT proceed with fewer than 4 exchanges under any circumstances — even if the user's first answer was extremely detailed.
 
+**If `QUESTIONING_MODE = standard`:**
+
 Verify internally: do you have `ANSWER_1`, `ANSWER_2`, `ANSWER_3`, and `ANSWER_4` recorded? If any is missing, go back and ask it. Only after all four answers are in hand may you ask:
 
 "I think I have a solid picture of what you're building. Ready for me to write PROJECT.md, or is there more you want to cover first?"
@@ -472,6 +516,31 @@ Verify internally: do you have `ANSWER_1`, `ANSWER_2`, `ANSWER_3`, and `ANSWER_4
 - **Write PROJECT.md** → proceed to Step 4
 - **More to cover** → continue asking follow-ups, then re-ask this gate question
 
+**If `QUESTIONING_MODE = deep`:**
+
+After Exchange 4, continue with the extended deep questioning loop:
+- Identify the single biggest remaining unknown that would change the direction, scope, or architecture of PROJECT.md. Ask it. Provide your recommended answer with each question.
+- If an answer opens a new branch (a sub-decision), follow that branch before moving on.
+- If you can explore the codebase to resolve a question yourself, do so instead of asking.
+- Continue until you judge that all major branches are resolved. Then ask:
+
+```
+AskUserQuestion([
+  {
+    header: "Shared Understanding Check",
+    question: "I've walked through every major open question I can identify. Do you feel we have a complete shared picture of what you want to build?",
+    multiSelect: false,
+    options: [
+      { label: "Yes — write PROJECT.md", description: "All key decisions and scope are clear" },
+      { label: "There's still something open", description: "Keep going on a specific area" },
+      { label: "Let me add context", description: "I have something to add before you write" }
+    ]
+  }
+])
+```
+
+> 🛑 STOP. Wait for user reply. If "Yes" → proceed to Step 4. Otherwise continue drilling.
+
 Use the questioning techniques from `@./references/questioning.md` and domain-aware probes from `@./references/domain-probes.md` to shape the follow-up questions. When the user mentions a known domain (auth, real-time, dashboard, API, database, search, file uploads, caching, testing, deployment, AI/ML), use the relevant probes to ask sharper questions.
 
 ## Step 4: Write PROJECT.md
@@ -586,13 +655,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 +703,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 +751,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 +799,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 +851,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 +873,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 +907,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 +1087,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:
@@ -196,14 +203,16 @@ Task(
   prompt="
     <agent_definition>
     You are a learnship planner. Create executable PLAN.md files that an AI agent can follow step-by-step.
-    Each plan covers a single logical unit of work. Tasks use XML format with file, action, verify, done fields.
-    Plans have YAML frontmatter: wave, depends_on, files_modified, autonomous.
+    Each plan is a VERTICAL SLICE (tracer bullet) — a thin end-to-end path through all layers for one user-facing behavior. A completed plan must be demoable or verifiable on its own.
+    DO NOT create plans that cover a single layer across the whole feature (all-schema plan, all-API plan, all-UI plan). Each plan delivers one complete behavior: data + logic + API + UI + test.
+    Exception: add `single_layer_justified: true` to frontmatter only if the phase is legitimately single-layer (e.g., DB migration, style pass).
+    Tasks use XML format with file, action, verify, done fields. Plans have YAML frontmatter: wave, depends_on, files_modified, autonomous, single_layer_justified, objective.
     Be specific — task actions should be concrete instructions, not vague guidance.
     </agent_definition>
 
     <objective>
     Create 2-4 executable PLAN.md files for Phase [phase_number]: [phase_name].
-    Write plans to [phase_dir]/[padded_phase]-NN-PLAN.md.
+    Each plan = one tracer bullet (demoable end-to-end slice). Write plans to [phase_dir]/[padded_phase]-NN-PLAN.md.
     </objective>
 
     <files_to_read>
@@ -229,10 +238,18 @@ Wait for agent to complete, then verify PLAN.md files were written.
 
 <persona_context>
 You are now the **learnship planner**. Create implementation plans that are executable in a single context window.
-Each plan covers one logical unit of work. Tasks use XML format. Include YAML frontmatter with wave, depends_on, files_modified.
+Each plan is a VERTICAL SLICE (tracer bullet) — a thin end-to-end path through all layers for one user-facing behavior. A completed plan must be demoable or verifiable on its own.
+DO NOT create plans that cover a single layer across the whole feature (all-schema plan, all-API plan, all-UI plan). Each plan delivers one complete behavior: data + logic + API + UI + test.
+Exception: add `single_layer_justified: true` to frontmatter only if the phase is legitimately single-layer (e.g., DB migration, style pass).
+Tasks use XML format. Include YAML frontmatter with wave, depends_on, files_modified, autonomous, single_layer_justified, objective.
 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`
@@ -241,11 +258,13 @@ Read `@./agents/planner.md` for the full persona definition. Read all available
 - RESEARCH.md (if exists)
 
 Create 2-4 PLAN.md files in the phase directory. Each plan:
-- Covers a single logical unit of work executable in one context window
-- Has YAML frontmatter: `wave`, `depends_on`, `files_modified`, `autonomous`
+- Is a **vertical slice (tracer bullet)** — delivers one demoable user-facing behavior end-to-end (data → logic → API → UI → test). NOT a horizontal layer.
+- Has YAML frontmatter: `wave`, `depends_on`, `files_modified`, `autonomous`, `single_layer_justified`, `objective`
 - Contains tasks in XML format (see `$LEARNSHIP_DIR/templates/plan.md`)
 - Has `must_haves` section with observable verification criteria
 
+**Vertical slice check before writing:** For each plan you draft, ask: "Can someone demo this plan's deliverable after it completes, without completing other plans?" If the answer is no, restructure into proper vertical slices.
+
 **Wave assignment:**
 - Plans with no dependencies → Wave 1 (independent, execute in any order)
 - Plans depending on Wave 1 → Wave 2
@@ -274,13 +293,14 @@ Task(
   prompt="
     <agent_definition>
     You are a learnship plan checker. Verify plans are complete, correct, and executable.
-    Check: phase goal coverage, requirement IDs, CONTEXT.md decisions honored, task completeness, wave/dependency correctness.
-    Be strict — flag missing requirement IDs, vague task actions, incorrect wave assignments.
+    Check: phase goal coverage, requirement IDs, CONTEXT.md decisions honored, task completeness, wave/dependency correctness, AND vertical slice integrity.
+    Vertical slice check: each plan's objective must describe a demoable user-facing behavior delivered end-to-end. Flag any plan that covers only a single layer (all schema, all API, all UI) unless single_layer_justified: true is set in its frontmatter.
+    Be strict — flag missing requirement IDs, vague task actions, incorrect wave assignments, and horizontal slices.
     </agent_definition>
 
     <objective>
     Verify all PLAN.md files in [phase_dir] for Phase [phase_number]: [phase_name].
-    Check: phase goal coverage, requirement IDs, CONTEXT.md decisions, task completeness, wave correctness.
+    Check: phase goal coverage, requirement IDs, CONTEXT.md decisions, task completeness, wave correctness, vertical slice integrity.
     Return: PASS or list of specific issues per plan.
     </objective>
 
@@ -300,17 +320,25 @@ 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.
+Flag gaps, missing coverage, unrealistic estimates, circular dependencies, AND horizontal slices.
+Vertical slice check: each plan's objective must describe a demoable user-facing behavior delivered end-to-end. Flag any plan that covers only a single layer (all schema, all API, all UI) unless `single_layer_justified: true` is in the frontmatter.
+Check: phase goal coverage, requirement IDs, CONTEXT.md decisions honored, task completeness, wave/dependency correctness, vertical slice integrity.
 </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?)
 - Task completeness (files, action, verify, done fields)
 - Wave/dependency correctness
+- Vertical slice integrity (is each plan's objective a demoable user-facing behavior? flag horizontal-only plans)
 
 **Verification loop (max 3 iterations):**
 

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

@@ -36,7 +36,7 @@ cp templates/config.json .planning/config.json 2>/dev/null || cat > .planning/co
     "review": true,
     "solutions_search": true,
     "security_enforcement": true,
-    "discuss_mode": "discuss",
+    "discuss_mode": "discuss",    // "discuss" (standard 4-exchange) or "deep" (extended questioning, walks every branch until shared understanding)
     "tdd_mode": false
   },
   "parallelization": {

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: