learnship 2.3.0 → 2.3.1

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.1",
   "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.1",
   "logo": "assets/logo.png",
   "author": {
     "name": "Favio Vazquez",

package/gemini-extension.json

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

package/learnship/workflows/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,13 +74,47 @@ 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/*' | sort | head -40
-# PowerShell: Get-ChildItem -Recurse -Depth 3 | Where-Object { $_.FullName -notmatch '\.git|node_modules|\.planning|__pycache__|\.venv' } | Select-Object -First 40
+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
+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.
@@ -1039,6 +1078,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "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",