learnship 2.3.0 → 2.3.2

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.0",
+  "version": "2.3.2",
   "author": {
     "name": "Favio Vazquez",
     "email": "favio.vazquezp@gmail.com"

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "learnship",
   "displayName": "learnship",
   "description": "Agentic engineering done right — 57 structured workflows, 17 specialist agent personas, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "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.0",
+  "version": "2.3.2",
   "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/challenge.md

@@ -181,6 +181,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/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?"

package/learnship/workflows/diagnose-issues.md

@@ -127,6 +127,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/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(

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

@@ -6,7 +6,7 @@ description: Analyze an existing codebase and produce structured reference docs
 
 Analyze an existing codebase through structured focused exploration. Produces 7 structured documents in `.planning/codebase/` that feed into `new-project` when adding features to existing code.
 
-**Use before:** `/new-project` on a brownfield (existing) codebase.
+**Use before:** `/new-project` on a brownfield (existing) codebase, or before `/new-milestone` when the codebase has changed significantly.
 
 **Philosophy:** Each agent gets fresh context, explores a specific domain, and writes documents directly. The orchestrator only confirms what was created — it never receives document contents.
 

package/learnship/workflows/new-milestone.md

@@ -100,6 +100,64 @@ If a MILESTONE-CONTEXT.md was consumed, delete it:
 git rm .planning/MILESTONE-CONTEXT.md 2>/dev/null || true
 ```
 
+## Step 6a: Codebase Map Check
+
+Check if the codebase has changed significantly since the last map:
+
+```bash
+node -e "
+const fs=require('fs');
+const hasCbMap=fs.existsSync('.planning/codebase');
+if(!hasCbMap){console.log('NO_MAP');}
+else{
+  const mapFiles=fs.readdirSync('.planning/codebase').filter(f=>f.endsWith('.md'));
+  const mapAge=mapFiles.length>0?Math.max(...mapFiles.map(f=>fs.statSync('.planning/codebase/'+f).mtimeMs)):0;
+  const daysSinceMap=Math.floor((Date.now()-mapAge)/(1000*60*60*24));
+  console.log('HAS_MAP');console.log('map_files: '+mapFiles.length);console.log('days_since_update: '+daysSinceMap);
+}
+"
+```
+
+**If `NO_MAP`:** Offer codebase mapping:
+
+```
+AskUserQuestion([
+  {
+    header: "Codebase Map",
+    question: "No codebase map found. The codebase may have evolved since the last milestone. Want to map it before planning new features?",
+    multiSelect: false,
+    options: [
+      { label: "Map codebase (Recommended)", description: "Run /map-codebase to analyze current architecture, then return here" },
+      { label: "Skip", description: "Continue without mapping — I know the current state" }
+    ]
+  }
+])
+```
+
+- **Map codebase:** Tell the user: "Run `/map-codebase` first, then come back to `/new-milestone`." Then **STOP. Exit this workflow.**
+- **Skip:** Continue to Step 6b.
+
+**If `HAS_MAP` and `days_since_update` > 30:** Offer to refresh:
+
+```
+AskUserQuestion([
+  {
+    header: "Stale Codebase Map",
+    question: "Your codebase map is [N] days old. Want to refresh it before planning new features?",
+    multiSelect: false,
+    options: [
+      { label: "Refresh map", description: "Run /map-codebase to update, then return here" },
+      { label: "Use existing map", description: "Current map is close enough" }
+    ]
+  }
+])
+```
+
+- **Refresh map:** Tell the user: "Run `/map-codebase` first, then come back to `/new-milestone`." Then **STOP. Exit this workflow.**
+- **Use existing map:** Continue to Step 6b.
+
+**If `HAS_MAP` and `days_since_update` <= 30:** Continue silently to Step 6b.
+
 ## Step 6b: Config Review
 
 Check if the project config has all v2 keys:

package/learnship/workflows/new-project.md

@@ -40,13 +40,18 @@ node -e "const fs=require('fs'); console.log(fs.existsSync('.planning/PROJECT.md
 ```bash
 node -e "
 const fs=require('fs'),path=require('path');
-function walk(dir,skip){let n=0;try{for(const e of fs.readdirSync(dir,{withFileTypes:true})){const f=path.join(dir,e.name);if(skip.some(s=>f.includes(s)))continue;n+=e.isDirectory()?walk(f,skip):1;}}catch(e){}return n;}
-const n=walk('.',['/.git/','node_modules','.planning','__pycache__','.venv']);
-console.log(n>2?'HAS_CODE':'BLANK');console.log(n+' files');
+const skip=new Set(['.git','node_modules','.planning','__pycache__','.venv','.windsurf','.claude','.cursor','.codex','.gemini','.opencode','.config']);
+const codeExt=new Set(['.ts','.js','.py','.go','.rs','.swift','.java','.kt','.c','.cpp','.h','.cs','.rb','.php','.dart','.scala','.lua','.r','.R','.zig','.ex','.exs','.clj']);
+const pkgFiles=['package.json','requirements.txt','Cargo.toml','go.mod','Package.swift','build.gradle','pom.xml','Gemfile','composer.json','pubspec.yaml','CMakeLists.txt','Makefile','mix.exs'];
+function hasCode(dir,depth){if(depth>3)return false;try{for(const e of fs.readdirSync(dir,{withFileTypes:true})){if(e.isFile()&&codeExt.has(path.extname(e.name)))return true;if(e.isDirectory()&&!skip.has(e.name)&&hasCode(path.join(dir,e.name),depth+1))return true;}}catch{}return false;}
+const hasPkg=pkgFiles.some(f=>fs.existsSync(f));
+const hasCodeFiles=hasCode('.',0);
+const hasCbMap=fs.existsSync('.planning/codebase');
+if(hasCodeFiles||hasPkg){console.log('HAS_CODE');console.log('has_package: '+(hasPkg?'yes':'no'));console.log('has_codebase_map: '+(hasCbMap?'yes':'no'));console.log('needs_map: '+(!hasCbMap?'yes':'no'));}else{console.log('BLANK');}
 "
 ```
 
-**If HAS_CODE:** Note this internally as `EXISTING_CODEBASE = true`. You will scan the codebase briefly in Step 1b before questioning. Do NOT use existing code as an excuse to skip or shorten the questioning ceremony — the ceremony exists precisely because you need the user's intent, not just their code.
+**If HAS_CODE:** Note this internally as `EXISTING_CODEBASE = true`. Also record `needs_map` (true if `.planning/codebase/` doesn't exist yet). You will offer codebase mapping in Step 1b before questioning. Do NOT use existing code as an excuse to skip or shorten the questioning ceremony — the ceremony exists precisely because you need the user's intent, not just their code.
 
 Check if git is initialized:
 
@@ -69,23 +74,61 @@ Create the planning directory:
 node -e "require('fs').mkdirSync('.planning/research',{recursive:true})"
 ```
 
-## Step 1b: Existing Codebase Scan (only if EXISTING_CODEBASE = true)
+## Step 1b: Existing Codebase Handling (only if EXISTING_CODEBASE = true)
 
-If `EXISTING_CODEBASE = true`, do a quick structural scan before questioning so your follow-up questions are grounded in reality:
+If `EXISTING_CODEBASE = true`, first check whether a codebase map is needed.
 
+**If `needs_map` is true** (existing code detected but no `.planning/codebase/`):
+
+```
+AskUserQuestion([
+  {
+    header: "Existing Codebase Detected",
+    question: "I detected existing code in this directory. Would you like to map the codebase first? This produces structured reference docs that make the questioning phase sharper.",
+    multiSelect: false,
+    options: [
+      { label: "Map codebase first (Recommended)", description: "Run /map-codebase to analyze architecture, stack, conventions, and concerns — then return here" },
+      { label: "Quick scan only", description: "Do a fast structural scan and continue without full mapping" },
+      { label: "Skip — I know this codebase", description: "Proceed directly to configuration questions" }
+    ]
+  }
+])
+```
+
+> 🛑 STOP. Wait for the user's reply before continuing.
+
+- **Map codebase first:** Tell the user: "Run `/map-codebase` first, then come back to `/new-project` — the codebase map will be available for the questioning phase." Then **STOP. Exit this workflow.** The user will return to `/new-project` after mapping completes.
+- **Quick scan only:** Continue with the quick scan below.
+- **Skip:** Continue directly to Step 2 (configuration).
+
+**If `needs_map` is false** (codebase map already exists): Read the existing map for context and continue with the quick scan below.
+
+**Quick structural scan** (for "Quick scan only" or when map already exists):
+
+```bash
+find . -maxdepth 3 -not -path './.git/*' -not -path './node_modules/*' -not -path './.planning/*' -not -path './__pycache__/*' -not -path './.venv/*' -not -path './.windsurf/*' -not -path './.claude/*' -not -path './.cursor/*' -not -path './.codex/*' -not -path './.gemini/*' -not -path './.opencode/*' | sort | head -40
+# PowerShell: Get-ChildItem -Recurse -Depth 3 | Where-Object { $_.FullName -notmatch '\.git|node_modules|\.planning|__pycache__|\.venv|\.windsurf|\.claude|\.cursor|\.codex|\.gemini|\.opencode' } | Select-Object -First 40
+```
+
+If `.planning/codebase/` exists, also read the summary docs:
 ```bash
-find . -maxdepth 3 -not -path './.git/*' -not -path './node_modules/*' -not -path './.planning/*' -not -path './__pycache__/*' -not -path './.venv/*' | sort | head -40
-# PowerShell: Get-ChildItem -Recurse -Depth 3 | Where-Object { $_.FullName -notmatch '\.git|node_modules|\.planning|__pycache__|\.venv' } | Select-Object -First 40
+cat .planning/codebase/ARCHITECTURE.md 2>/dev/null | head -40
+cat .planning/codebase/STACK.md 2>/dev/null | head -40
+cat .planning/codebase/CONCERNS.md 2>/dev/null | head -20
 ```
 
 Note the tech stack, key directories, and any README content internally. Use this ONLY to ask sharper follow-up questions — never to infer the user's intent or skip ceremony steps.
 
 ## 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([
   {
@@ -93,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" }
     ]
   },
@@ -129,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([
   {
@@ -181,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([
   {
@@ -225,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",
@@ -293,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
@@ -1039,6 +1144,8 @@ After verify-work passes: `/review` for multi-persona code review, `/ship` to te
 
 💡 For ambitious projects, consider running `/challenge` to stress-test the scope through product and engineering lenses before starting Phase 1.
 
+💡 Building on an existing codebase? Run `/ideate` for codebase-grounded idea generation — it scans your code for hotspots and improvement opportunities.
+
 💡 Working near sensitive areas (auth, payments, migrations)? Run `/guard [scope]` to activate safety mode.
 
 > **Platform detected:** `[PLATFORM]` — parallelization is `[true/false]`

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.

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`).
@@ -152,6 +154,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/sync-upstream-skills.md

@@ -223,7 +223,7 @@ node bin/install.js --all
 
 This ensures:
 - **Windsurf** — skills already live in `.windsurf/skills/` (updated in place above)
-- **Claude Code** — `~/.claude/skills/` rebuilt with updated skill content + rewritten `references/` paths
+- **Claude Code** — Claude skills directory rebuilt with updated skill content + rewritten `references/` paths
 - **OpenCode / Gemini CLI / Codex** — `learnship/skills/` context files updated
 
 ---
@@ -256,7 +256,7 @@ impeccable:
 
 All platforms updated (installer re-run):
   Windsurf       ✓ skills updated in place
-  Claude Code    ✓ ~/.claude/skills/ rebuilt
+  Claude Code    ✓ skills directory rebuilt
   Other platforms ✓ learnship/skills/ context files updated
 
 Backup saved at: .windsurf/skills/.upstream-backup-<timestamp>/

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`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "description": "Learn as you build. Build with intent. — A multi-platform agentic engineering system for Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, and Codex: 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",