learnship 2.3.2 → 2.3.4

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "learnship",
   "description": "Agentic engineering done right — 57 structured workflows, 17 specialist agent personas, persistent memory across sessions, integrated learning partner, and impeccable UI design system. Works with Claude Code, Windsurf, Cursor, Gemini CLI, OpenCode, and Codex.",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "author": {
     "name": "Favio Vazquez",
     "email": "favio.vazquezp@gmail.com"

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "learnship",
   "displayName": "learnship",
   "description": "Agentic engineering done right — 57 structured workflows, 17 specialist agent personas, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "logo": "assets/logo.png",
   "author": {
     "name": "Favio Vazquez",

package/README.md

@@ -121,7 +121,7 @@ Every feature ships through a 7-step loop:
 ```mermaid
 flowchart LR
     DP["/discuss-phase N<br/>Capture decisions"]
-    PP["/plan-phase N<br/>Research + plans"]
+    PP["/plan-phase N<br/>Vertical slice plans"]
     EP["/execute-phase N<br/>Build + commit"]
     VW["/verify-work N<br/>UAT + diagnose"]
     RV["/review<br/>Multi-persona review"]
@@ -136,8 +136,8 @@ flowchart LR
 
 | Step | Command | What happens |
 |------|---------|-------------|
-| **1. Discuss** | `/discuss-phase N` | You and the agent align on implementation decisions before any code |
-| **2. Plan** | `/plan-phase N` | Agent researches the domain, creates executable plans, verifies them |
+| **1. Discuss** | `/discuss-phase N` | You and the agent align on implementation decisions before any code. Add `--deep` for extended deep questioning that walks every branch (v2.3.4) |
+| **2. Plan** | `/plan-phase N` | Agent researches the domain, creates vertical slice plans (tracer bullets), verifies them — including horizontal slice detection (v2.3.4) |
 | **3. Execute** | `/execute-phase N` | Plans run in dependency order, one atomic commit per task |
 | **4. Verify** | `/verify-work N` | You do UAT; agent diagnoses any gaps and creates fix plans |
 | **5. Review** | `/review` | Multi-persona code review through 6 lenses (v2.0) |
@@ -252,6 +252,14 @@ It's probably overkill for one-off scripts. Use `/quick` for that.
 
 ## 🆕 What's New
 
+### What's new in v2.3.4
+
+v2.3.4 adds two planning quality features:
+
+**Deep questioning mode** (`--deep` flag or `workflow.discuss_mode: "deep"` in config): Both `/discuss-phase` and `/new-project` now support extended questioning that walks every decision branch until shared understanding is reached. Each question includes a recommended answer. Standard mode (4 focused exchanges) remains the default.
+
+**Vertical slice planning** (enforced in `plan-phase`): Plans are now required to be tracer bullets — thin vertical slices through all integration layers (data → logic → API → UI → test) for one demoable user-facing behavior. The plan-checker flags any plan that covers only one architectural layer across all features. Single-layer phases (migrations, style passes) use `single_layer_justified: true` in the plan frontmatter.
+
 ### What's new in v2.3
 
 v2.3 adds 5 new agent personas, Windsurf-native persona adoption via `model_decision` rules, and inline `<persona_context>` blocks across all 18 persona-aware workflows:
@@ -294,7 +302,7 @@ v2.1 adds 8 new workflows, 5 new references, 3 new templates, and 2 new agents:
 | **Session** | `/note` — zero-friction capture · `/session-report` — stakeholder summaries |
 | **Learning** | `/extract-learnings` — decisions, lessons, patterns, surprises · `/milestone-summary` — team onboarding |
 
-Enhanced: `/discuss-phase` (scope guardrails + domain probes), `/execute-phase` (`--wave` flag + context scaling), `/quick` (`--research --validate --full` composable flags), `/ideate` (`--explore` Socratic mode).
+Enhanced: `/discuss-phase` (scope guardrails + domain probes + `--deep` extended questioning v2.3.4), `/new-project` (`--deep` extended questioning v2.3.4), `/plan-phase` (vertical slice tracer bullets + horizontal slice detection v2.3.4), `/execute-phase` (`--wave` flag + context scaling), `/quick` (`--research --validate --full` composable flags), `/ideate` (`--explore` Socratic mode).
 
 **Optional per-phase:** `/secure-phase N` (STRIDE security), `/extract-learnings N` (meta-knowledge).
 **Recovery:** `/forensics` (post-mortem), `/undo` (safe revert).
@@ -533,13 +541,16 @@ Project settings live in `.planning/config.json`. Set during `/new-project` or e
 ### Workflow Toggles
 
 | Setting | Default | What it controls |
-|---------|---------|-----------------|
+|---------|---------|------------------|
 | `workflow.research` | `true` | Domain research before planning each phase |
-| `workflow.plan_check` | `true` | Plan verification loop (up to 3 iterations) |
+| `workflow.plan_check` | `true` | Plan verification loop (up to 3 iterations), including vertical slice integrity check |
 | `workflow.verifier` | `true` | Post-execution verification against phase goals |
 | `workflow.validation` | `true` | Test coverage mapping during plan-phase |
 | `workflow.review` | `true` | Enable `/review` suggestions after `/verify-work` (v2.0) |
 | `workflow.solutions_search` | `true` | Search `.planning/solutions/` during `/plan-phase` (v2.0) |
+| `workflow.security_enforcement` | `true` | Per-phase STRIDE security verification via `/secure-phase` |
+| `workflow.discuss_mode` | `"discuss"` | Questioning depth: `"discuss"` (4 exchanges) or `"deep"` (extended, walks every branch) (v2.3.4) |
+| `workflow.tdd_mode` | `false` | Instruct planner to apply TDD task ordering to eligible tasks |
 
 ### Review & Ship Settings
 

package/agents/learnship-plan-checker.md

@@ -1,6 +1,6 @@
 ---
 name: learnship-plan-checker
-description: Verifies PLAN.md files for a phase — checks goal coverage, requirement IDs, CONTEXT.md decisions, task completeness, and wave correctness. Spawned by plan-phase on platforms with subagent support.
+description: Verifies PLAN.md files for a phase — checks goal coverage, requirement IDs, CONTEXT.md decisions, task completeness, wave correctness, and vertical slice integrity (each plan must be a demoable tracer bullet). Spawned by plan-phase on platforms with subagent support.
 tools: Read, Bash, Glob, Grep
 color: cyan
 ---
@@ -48,6 +48,11 @@ For every task in every plan, check:
 - Is each plan achievable in a single context window? (~200k tokens, 2-3 tasks)
 - Are there any tasks that are too vague to implement without guessing?
 
+### 7. Vertical Slice (tracer bullet)
+- Does each plan's `objective` describe a **demoable user-facing behavior** delivered end-to-end?
+- Does any plan cover only a single layer (all schema, all API routes, all UI components across the feature)? If yes, flag as **horizontal slice** unless `single_layer_justified: true` is in the frontmatter.
+- The test: "Can someone demo what this plan delivers after it completes, without completing other plans?" If no and `single_layer_justified` is not set → flag it.
+
 ## What NOT to check
 - Code style or implementation approach preferences (that's the planner's job)
 - Research quality (that's already done)

package/agents/learnship-planner.md

@@ -1,6 +1,6 @@
 ---
 name: learnship-planner
-description: Creates executable PLAN.md files for a phase — decomposes goals into wave-ordered tasks with dependency analysis. Spawned by plan-phase on platforms with subagent support.
+description: Creates executable PLAN.md files for a phase — decomposes goals into vertical slice (tracer bullet) tasks with wave-ordered dependency analysis. Each plan delivers one demoable user-facing behavior end-to-end. Spawned by plan-phase on platforms with subagent support.
 tools: Read, Write, Bash, Glob, Grep
 color: green
 ---
@@ -28,11 +28,18 @@ Before planning, load project context:
 
 ## Core Rules
 
-1. **Honor CONTEXT.md first** — locked decisions are non-negotiable. Plans implement decisions, not the other way around.
-2. **Goal-backward** — start from the phase goal, derive the minimum set of must-haves, then build tasks backward from those
-3. **One context window per plan** — each plan must be executable in a single agent session (~200k tokens)
-4. **2-3 tasks per plan** — enough to be a meaningful unit, small enough to verify cleanly
-5. **Observable must-haves** — every must-have must be checkable by reading a file or running a command
+1. **Vertical slices, not horizontal layers** — Each PLAN.md is a **tracer bullet**: a thin vertical slice through all integration layers for one user-facing behavior. A completed plan is demoable without completing other plans. DO NOT create all-schema, all-API, or all-UI plans.
+   ```
+   WRONG: Plan 01 = DB schema   Plan 02 = API routes   Plan 03 = UI
+   RIGHT: Plan 01 = user can log in (schema + route + form + test)
+          Plan 02 = user can reset password (schema + route + form + test)
+   ```
+   Exception: add `single_layer_justified: true` to frontmatter if the phase is legitimately single-layer (migration, style pass).
+2. **Honor CONTEXT.md first** — locked decisions are non-negotiable. Plans implement decisions, not the other way around.
+3. **Goal-backward** — start from the phase goal, derive the minimum set of must-haves, then build tasks backward from those
+4. **One context window per plan** — each plan must be executable in a single agent session (~200k tokens)
+5. **2-3 tasks per plan** — enough to be a meaningful unit, small enough to verify cleanly
+6. **Observable must-haves** — every must-have must be checkable by reading a file or running a command
 
 ## Wave Assignment
 
@@ -52,7 +59,8 @@ files_modified:
   - src/feature.ts
   - tests/feature.test.ts
 autonomous: true
-objective: "One sentence describing what this plan builds and why it matters"
+single_layer_justified: false  # true only for legitimately single-layer phases
+objective: "One sentence describing the demoable user-facing behavior this plan delivers end-to-end"
 must_haves:
   - "src/feature.ts exists and exports FeatureClass"
   - "tests/feature.test.ts has at least 3 test cases"
@@ -113,10 +121,12 @@ Load everything before writing a single plan:
 ## Step 2: Decompose Phase Goal
 
 From the phase goal and requirements:
-1. List all deliverables (what must exist after this phase)
-2. Map each deliverable to a logical implementation unit
-3. Find dependencies between units
-4. Group into 2-4 plans, assign waves
+1. List all user-facing behaviors the phase must deliver (not layers — behaviors)
+2. Each behavior becomes one plan: data schema + logic + API + UI + test
+3. Find dependencies between plans
+4. Group into 2-4 vertical slice plans, assign waves
+
+**Self-check before writing:** For each draft plan, ask: "Can someone demo this plan's deliverable after it completes, without completing other plans?" If no → restructure.
 
 ## Step 3: Write Plans
 

package/bin/install.js

@@ -1438,7 +1438,7 @@ function install(platform, isGlobal) {
     console.log(`  ${yellow}Option 2 (manual):${reset} Copy the rule file into your project:`);
     console.log(`    ${dim}mkdir -p .cursor/rules${reset}`);
     console.log(`    ${dim}cp node_modules/learnship/cursor-rules/learnship.mdc .cursor/rules/${reset}\n`);
-    console.log(`  ${dim}The .mdc rule activates all 42 learnship workflows automatically in every Cursor session.${reset}\n`);
+    console.log(`  ${dim}The .mdc rule activates all 57 learnship workflows automatically in every Cursor session.${reset}\n`);
     return;
   }
 

package/cursor-rules/learnship.mdc

@@ -160,7 +160,7 @@ 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. 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.
+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 — working style, granularity, learning partner, AI models, questioning depth, output profile; 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:
 ```
@@ -178,6 +178,8 @@ After all configuration rounds are answered, write `.planning/config.json` with
 - 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`

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "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/agents/plan-checker.md

@@ -34,6 +34,11 @@ For every task in every plan, check:
 - Is each plan achievable in a single context window? (~200k tokens, 2-3 tasks)
 - Are there any tasks that are too vague to implement without guessing?
 
+### 7. Vertical Slice (tracer bullet)
+- Does each plan's `objective` describe a **demoable user-facing behavior** delivered end-to-end?
+- Does any plan cover only a single layer across the whole feature (all schema, all API endpoints, all UI components)? If yes, flag it as a **horizontal slice** unless `single_layer_justified: true` is set in the frontmatter.
+- The test: "Can someone demo what this plan delivers after it completes, without completing other plans?" If no and `single_layer_justified` is not set → flag it.
+
 ## What NOT to check
 - Code style or implementation approach preferences (that's the planner's job)
 - Research quality (that's already done)

package/learnship/agents/planner.md

@@ -6,6 +6,18 @@ Plans are precise prompts for an executor — not documents that become prompts.
 
 ## Planning Principles
 
+**Vertical slices, not horizontal layers** — Each PLAN.md is a **tracer bullet**: a thin vertical slice that cuts through all integration layers end-to-end for one user-facing behavior. A completed plan is demoable or verifiable on its own. Do NOT create plans that implement a single layer across the whole feature.
+
+```
+WRONG (horizontal):  Plan 01 = all DB schema   Plan 02 = all API   Plan 03 = all UI
+RIGHT  (vertical):   Plan 01 = user can log in (schema + API endpoint + UI form + test)
+                     Plan 02 = user can reset password (schema + API + UI + test)
+```
+
+**Anti-pattern to avoid:** If someone cannot demo what a completed plan delivers without also completing other plans, the plan is too horizontal. Restructure.
+
+**Exception — single-layer phases:** Some phases are legitimately single-layer (e.g., "migrate all DB tables to new schema", "style all existing components"). In this case, add `single_layer_justified: true` to the plan's YAML frontmatter and note the reason in the objective.
+
 **Atomic tasks** — each task should be completable in one logical unit of work and committed independently.
 
 **Observable done criteria** — every task must have a `<done>` field that describes something you can check (file exists, test passes, import resolves) — not "task is complete".
@@ -36,7 +48,8 @@ files_modified:
   - path/to/file.ts
   - path/to/other.ts
 autonomous: true
-objective: "[One sentence: what this plan builds and why it matters for the phase]"
+single_layer_justified: false  # set true only if this phase is legitimately single-layer (e.g., DB migration, style pass)
+objective: "[One sentence describing the demoable user-facing behavior this plan delivers end-to-end]"
 must_haves:
   truths:
     - "File src/auth/token.ts exists and exports `validateToken`"

package/learnship/references/planning-config.md

@@ -210,7 +210,7 @@ New sections and fields added in v2.1.0 for security, parallelization control, g
 | Option | Default | Description |
 |--------|---------|-------------|
 | `workflow.security_enforcement` | `true` | Enable per-phase security verification via `/secure-phase` |
-| `workflow.discuss_mode` | `"discuss"` | Discussion mode for discuss-phase |
+| `workflow.discuss_mode` | `"discuss"` | Discussion depth for `discuss-phase` and `new-project` questioning. `"discuss"` = standard (4 focused exchanges). `"deep"` = extended questioning, walks every decision branch until shared understanding — equivalent to passing `--deep` flag |
 | `workflow.tdd_mode` | `false` | Instruct planner to apply `type: tdd` to eligible tasks |
 
 ### Parallelization Section (replaces flat boolean)

package/learnship/templates/plan.md

@@ -113,6 +113,14 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 - Progress table updated by execute workflow
 - Plan count can be "TBD" initially, refined during planning
 
+**Vertical slice planning (enforced by plan-phase and plan-checker):**
+- Each PLAN.md is a tracer bullet — one user-facing behavior, all layers (data → logic → API → UI → test)
+- A completed plan is demoable without completing other plans
+- Plan descriptions in this roadmap should reflect what users experience, not which layer is being built
+  - ✗ "01-01: Create database schema" — horizontal, not demoable alone
+  - ✓ "01-01: User can register and receive confirmation email" — vertical, demoable
+- Exception: `single_layer_justified: true` in PLAN.md frontmatter for legitimately single-layer phases
+
 **Success criteria:**
 - 2-5 observable behaviors per phase (from user's perspective)
 - Cross-checked against requirements during roadmap creation

package/learnship/workflows/audit-milestone.md

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

package/learnship/workflows/challenge.md

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

package/learnship/workflows/compound.md

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

package/learnship/workflows/debug.md

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

package/learnship/workflows/diagnose-issues.md

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

package/learnship/workflows/discuss-phase.md

@@ -7,6 +7,7 @@ description: Capture implementation decisions for a phase before planning starts
 Extract implementation decisions that downstream planning needs. Analyze the phase to identify gray areas, let the user choose what to discuss, then deep-dive each selected area until satisfied.
 
 **Usage:** Run `discuss-phase [N]` before `plan-phase [N]`.
+**Usage:** Run `discuss-phase [N] --deep` for extended deep questioning — walks every decision branch until shared understanding is reached, with a recommended answer for each question.
 
 **You are a thinking partner, not an interviewer.** The user is the visionary — you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself.
 
@@ -28,6 +29,12 @@ Extract implementation decisions that downstream planning needs. Analyze the pha
 
 ## Step 1: Load Phase
 
+**Detect mode:** Check for `--deep` flag in the command. If not present, check `workflow.discuss_mode` in `.planning/config.json` — if it is `"deep"`, activate deep mode. Otherwise, use standard mode.
+
+```
+DEEP_MODE = "--deep" flag present OR config.workflow.discuss_mode == "deep"
+```
+
 Read `.planning/ROADMAP.md` and find the requested phase number. If not found, stop and show available phases.
 
 Read prior context to avoid re-asking decided questions:
@@ -175,7 +182,7 @@ If "All clear" → skip to Step 6.
 **For each selected area, discuss:**
 
 1. Announce: "Let's talk about [Area]."
-2. Ask focused questions with concrete options using structured questions where possible:
+2. Ask focused questions with concrete options using structured questions where possible. **Always include a recommended answer** — state which option you'd pick and why:
 
 ```
 AskUserQuestion([
@@ -184,7 +191,7 @@ AskUserQuestion([
     question: "[Specific implementation question]",
     multiSelect: false,
     options: [
-      { label: "[Option A] (Recommended)", description: "[Why, with code context if relevant]" },
+      { label: "[Option A] (Recommended)", description: "[Why this is recommended, with code context if relevant]" },
       { label: "[Option B]", description: "[Why]" },
       { label: "[Option C]", description: "[Why]" }
     ]
@@ -194,13 +201,23 @@ AskUserQuestion([
 
 > 🛑 STOP. Wait for the user's reply before continuing.
 
-3. After 4 questions, ask: "More questions about [area], or move to next?"
+**Standard mode** (default):
+3. After 4 questions per area, ask: "More questions about [area], or move to next?"
 4. If more → ask 4 more, then check again
 
+**Deep mode** (`--deep` or `discuss_mode: "deep"`):
+3. After each answer, analyze: what is the single biggest remaining unknown in this area that could change how it's implemented? Ask that next. Provide your recommended answer.
+4. Continue drilling down each decision branch — if an answer opens a sub-branch, follow it. Do NOT move on until the branch is fully resolved.
+5. Only move to the next area when you judge that the current area has no remaining decision branches that would change the implementation.
+6. If you can explore the codebase to answer a question yourself, do so instead of asking the user.
+
+> **Deep mode intent:** Walk the full decision tree. Resolve every fork. The CONTEXT.md produced should leave no ambiguity that downstream agents would need to guess about.
+
 After all selected areas:
 - Summarize decisions captured
 - Present final check:
 
+**Standard mode:**
 ```
 AskUserQuestion([
   {
@@ -215,6 +232,22 @@ AskUserQuestion([
 ])
 ```
 
+**Deep mode:**
+```
+AskUserQuestion([
+  {
+    header: "Shared Understanding Check",
+    question: "I've walked through every decision branch I can identify. Do you feel we've reached shared understanding on how to implement this phase?",
+    multiSelect: false,
+    options: [
+      { label: "Yes — write CONTEXT.md", description: "All key decisions are captured" },
+      { label: "There's still [area] to discuss", description: "Keep going on a specific area" },
+      { label: "Let me add something", description: "I have context to add before you write" }
+    ]
+  }
+])
+```
+
 > 🛑 STOP. Wait for the user's reply before continuing.
 
 <scope_guardrail>
@@ -256,6 +289,7 @@ Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-CONTEXT.md`:
 # Phase [X]: [Name] - Context
 
 **Gathered:** [date]
+**Mode:** [standard | deep]
 **Status:** Ready for planning
 
 <domain>
@@ -368,6 +402,7 @@ Created: .planning/phases/[padded_phase]-[slug]/[padded_phase]-CONTEXT.md
 
 💡 Ambitious scope? `/challenge` — stress-test the approach before planning
 💡 Made important decisions? `/compound` — capture them while context is fresh
+💡 Want to go deeper? Re-run `discuss-phase [X] --deep` for relentless branch-walking until full shared understanding
 ```
 
 ---

package/learnship/workflows/docs-update.md

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

package/learnship/workflows/execute-phase.md

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

package/learnship/workflows/execute-plan.md

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

package/learnship/workflows/ideate.md

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