learnship 2.2.2 → 2.3.1

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/*' -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.
@@ -696,7 +735,16 @@ Wait for the synthesizer to complete, then proceed to Step 5c (verification) to
 
 **If `parallelization.enabled` is `false` (sequential mode):**
 
-Using `@./agents/researcher.md` as your research persona:
+<persona_context>
+You are now the **learnship project researcher**. Your training data is 6–18 months stale — verify before asserting.
+Use WebSearch for ecosystem discovery (always include current year), WebFetch for official docs, codebase scan for existing patterns.
+Tag confidence: HIGH (multi-source verified), MEDIUM (single official source), LOW (unverified).
+Be comprehensive but opinionated — "Use X because Y" not "Options are X, Y, Z."
+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>
+
+Read `@./agents/project-researcher.md` for the full persona definition.
 
 **Step 5b-pre — Online research (BEFORE writing any files).**
 
@@ -864,7 +912,14 @@ git add .planning/REQUIREMENTS.md && git commit -m "docs: define v1 requirements
 
 Read `.planning/PROJECT.md`, `.planning/REQUIREMENTS.md`, and research summary (if exists).
 
-Using `@./agents/planner.md` as your planning persona:
+<persona_context>
+You are now the **learnship roadmapper**. Transform requirements into a phased roadmap.
+Every v1 requirement maps to exactly one phase. Every phase has observable success criteria.
+Goal-backward: start from what the user needs, work backward to what must be built first.
+Dependencies drive order. Phases should be deliverable — each produces something testable.
+</persona_context>
+
+Read `@./agents/roadmapper.md` for the full persona definition.
 
 1. Derive phases from requirements (don't impose structure — let requirements drive phases)
 2. Map every v1 requirement to exactly one phase
@@ -1023,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/plan-phase.md

@@ -148,7 +148,13 @@ Wait for agent to complete, then verify RESEARCH.md was written.
 
 **If `parallelization` is `false` (sequential mode):**
 
-Using `@./agents/researcher.md` as your research persona, investigate how to implement this phase.
+<persona_context>
+You are now the **learnship phase researcher**. Your training data is stale — verify before asserting.
+Tag every claim: [VERIFIED: source], [CITED: url], or [ASSUMED]. Never present assumed knowledge as verified fact.
+Use WebSearch for implementation patterns, WebFetch for official docs, codebase scan for existing patterns to reuse.
+</persona_context>
+
+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:
 - The CONTEXT.md (user decisions)
@@ -221,7 +227,13 @@ Wait for agent to complete, then verify PLAN.md files were written.
 
 **If `parallelization` is `false` (sequential mode):**
 
-Using `@./agents/planner.md` as your planning persona, read all available context:
+<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.
+Right-size plans: too small = overhead, too large = risk. Aim for plans completable in one focused session.
+</persona_context>
+
+Read `@./agents/planner.md` for the full persona definition. Read all available context:
 - `.planning/STATE.md`
 - `.planning/ROADMAP.md`
 - `.planning/REQUIREMENTS.md`
@@ -287,7 +299,13 @@ If still failing after 3 iterations: present issues and ask — **Force proceed*
 
 **If `parallelization` is `false` (sequential mode):**
 
-Using `@./agents/verifier.md` as your verification persona, check the plans against:
+<persona_context>
+You are now the **learnship verifier**. Check plans against requirements and roadmap.
+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.
+</persona_context>
+
+Read `@./agents/verifier.md` for the full persona definition. Check the plans against:
 - The phase goal from ROADMAP.md
 - All requirement IDs assigned to this phase
 - CONTEXT.md decisions (are they honored?)

package/learnship/workflows/quick.md

@@ -139,7 +139,13 @@ Write `CONTEXT.md` to the task directory:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Using `@./agents/researcher.md` as your research persona, do a focused research pass on the task:
+<persona_context>
+You are now the **learnship researcher**. Your training data is stale — verify before asserting.
+Use WebSearch for current best practices, WebFetch for official docs, codebase scan for existing patterns.
+Tag confidence: HIGH/MEDIUM/LOW. Investigation, not confirmation.
+</persona_context>
+
+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?
 - Are there existing patterns in the codebase to follow?
@@ -148,7 +154,12 @@ Write a brief `${NEXT_NUM}-RESEARCH.md` (max 50 lines) to the task directory. Th
 
 ## Step 4: Create Plan
 
-Using `@./agents/planner.md` as your planning persona, read:
+<persona_context>
+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>
+
+Read `@./agents/planner.md` for the full persona definition. Read:
 - `.planning/STATE.md`
 - CONTEXT.md if it exists (from `--discuss`)
 - The task description
@@ -179,7 +190,12 @@ node -e "const fs=require('fs'); console.log(fs.existsSync('.planning/quick/NEXT
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Using `@./agents/verifier.md`, verify the plan against the task description:
+<persona_context>
+You are now the **learnship verifier**. Check the plan against the task description.
+Flag gaps, missing coverage, and unrealistic scope.
+</persona_context>
+
+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?
 - Is this appropriately sized for a quick task (1-3 tasks)?
@@ -191,7 +207,12 @@ If still failing after 2 iterations: present remaining issues and ask — **Forc
 
 ## Step 6: Execute
 
-Using `@./agents/executor.md` as your execution persona, read the PLAN.md and execute each task:
+<persona_context>
+You are now the **learnship executor**. Implement code from the plan, one task at a time.
+Read task files, action, verify, and done fields. Commit atomically after each task.
+</persona_context>
+
+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
 2. Implement what the action describes
@@ -231,7 +252,11 @@ After all tasks complete, write `${NEXT_NUM}-SUMMARY.md`:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Using `@./agents/verifier.md`, check `must_haves` from the plan against the actual codebase.
+<persona_context>
+You are now the **learnship verifier**. Check must_haves from the plan against the actual codebase.
+</persona_context>
+
+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

@@ -116,7 +116,13 @@ Task(
 
 **If `parallelization.enabled` is `false` (sequential mode):**
 
-Using `@./agents/researcher.md` as your research persona in **phase research mode**:
+<persona_context>
+You are now the **learnship phase researcher**. Your training data is stale — verify before asserting.
+Tag every claim: [VERIFIED: source], [CITED: url], or [ASSUMED]. Never present assumed knowledge as verified fact.
+Use WebSearch for implementation patterns, WebFetch for official docs, codebase scan for existing patterns to reuse.
+</persona_context>
+
+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

@@ -122,7 +122,12 @@ Wait for all personas to complete.
 
 **If `parallelization` is `false` (sequential mode):**
 
-Using `@./agents/code-reviewer.md` as your review persona, run each selected persona sequentially. For each persona:
+<persona_context>
+You are now the **learnship code reviewer**. Review code for correctness, testing, security, and performance.
+Be specific — cite file:line, explain the issue, propose the fix. Severity: critical/major/minor/nit.
+</persona_context>
+
+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
 2. Read the diff through that lens

package/learnship/workflows/secure-phase.md

@@ -126,7 +126,12 @@ Task(
 ```
 
 **If `parallelization.enabled` is `false`:**
-Using `@./agents/security-auditor.md`, check each open threat against the codebase. Update status based on findings.
+<persona_context>
+You are now the **learnship security auditor**. Run STRIDE threat analysis against the codebase.
+Check each open threat. Verify mitigations are implemented correctly. Update status based on findings.
+</persona_context>
+
+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/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

@@ -130,7 +130,12 @@ Task(
 
 **If `parallelization.enabled` is `false` (sequential mode):**
 
-Using `@./agents/verifier.md` as your verification persona, write the missing test files. Rules:
+<persona_context>
+You are now the **learnship verifier**. Write missing test files to close validation gaps.
+Tests must be observable and runnable. Cover the must_haves from each plan. Don't weaken existing tests.
+</persona_context>
+
+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
 - Write tests that actually run (import real modules, not mocks of the implementation)

package/learnship/workflows/verify-work.md

@@ -277,7 +277,12 @@ Task(
 
 **If `parallelization.enabled` is `false` (sequential mode):**
 
-For each issue in the Gaps section, investigate using `@./agents/debugger.md` as your debug persona:
+<persona_context>
+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>
+
+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
 - Do not fix yet — just diagnose
@@ -301,9 +306,18 @@ Display:
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-Using `@./agents/planner.md` as your planning persona, 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 planner**. Create fix plans for diagnosed gaps.
+Each plan covers one logical unit of work. Include gap_closure: true in frontmatter.
+</persona_context>
+
+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>
 
-Verify fix plans (max 3 iterations with `@./agents/verifier.md`) — same loop as `plan-phase`.
+Verify fix plans (max 3 iterations — read `@./agents/verifier.md` for the full persona definition) — same loop as `plan-phase`.
 
 Present when ready:
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "learnship",
-  "version": "2.2.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: spec-driven workflows, integrated learning, and production-grade design.",
+  "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",
     "development",
@@ -27,7 +27,6 @@
     "agents",
     "references",
     "templates",
-    "install.sh",
     "skills",
     "hooks",
     ".claude-plugin",

package/install.sh

@@ -1,254 +0,0 @@
-#!/usr/bin/env bash
-# learnship — Installer
-# Usage:
-#   bash install.sh                    # interactive
-#   bash install.sh --local            # project install (non-interactive)
-#   bash install.sh --global           # global install (non-interactive)
-#   bash install.sh --uninstall --local
-#   bash install.sh --uninstall --global
-
-set -e
-
-REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PLATFORM_NAME="learnship"
-
-# Colors
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-BLUE='\033[0;34m'
-BOLD='\033[1m'
-RESET='\033[0m'
-
-# ─── Helpers ─────────────────────────────────────────────────────────────────
-
-print_header() {
-  echo ""
-  echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
-  echo -e "${BOLD}  ${PLATFORM_NAME}${RESET}"
-  echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
-  echo ""
-}
-
-print_success() { echo -e "${GREEN}✓${RESET} $1"; }
-print_error()   { echo -e "${RED}✗${RESET} $1" >&2; }
-print_info()    { echo -e "${BLUE}→${RESET} $1"; }
-print_warn()    { echo -e "${YELLOW}!${RESET} $1"; }
-
-# ─── Argument Parsing ────────────────────────────────────────────────────────
-
-SCOPE=""
-UNINSTALL=false
-
-for arg in "$@"; do
-  case "$arg" in
-    --local)     SCOPE="local" ;;
-    --global)    SCOPE="global" ;;
-    --uninstall) UNINSTALL=true ;;
-    --help|-h)
-      echo "Usage: bash install.sh [--local|--global] [--uninstall]"
-      echo ""
-      echo "  --local      Install to current project's .windsurf/ directory"
-      echo "  --global     Install to ~/.codeium/windsurf/ (available in all projects)"
-      echo "  --uninstall  Remove the installation"
-      echo ""
-      echo "Run without flags for interactive mode."
-      exit 0
-      ;;
-    *)
-      print_error "Unknown argument: $arg"
-      echo "Run 'bash install.sh --help' for usage."
-      exit 1
-      ;;
-  esac
-done
-
-# ─── Determine Target Directory ──────────────────────────────────────────────
-
-get_target_dir() {
-  local scope="$1"
-  if [[ "$scope" == "global" ]]; then
-    echo "$HOME/.codeium/windsurf"
-  else
-    # When run via npx, pwd() is the npx cache — use LEARNSHIP_INSTALL_CWD
-    # (set by bin/learnship.js from INIT_CWD) to get the user's actual project dir
-    local project_dir="${LEARNSHIP_INSTALL_CWD:-$(pwd)}"
-    echo "${project_dir}/.windsurf"
-  fi
-}
-
-# ─── Interactive Prompt ──────────────────────────────────────────────────────
-
-if [[ -z "$SCOPE" ]]; then
-  print_header
-
-  echo -e "${BOLD}Where would you like to install?${RESET}"
-  echo ""
-  echo "  [1] Project  — installs to ./.windsurf/ (current project only)"
-  echo "  [2] Global   — installs to ~/.codeium/windsurf/ (all Windsurf projects)"
-  echo ""
-  read -p "Choice [1/2]: " choice
-
-  case "$choice" in
-    1|"") SCOPE="local" ;;
-    2)    SCOPE="global" ;;
-    *)
-      print_error "Invalid choice. Run again and enter 1 or 2."
-      exit 1
-      ;;
-  esac
-fi
-
-TARGET_DIR="$(get_target_dir "$SCOPE")"
-
-# ─── Uninstall ───────────────────────────────────────────────────────────────
-
-if [[ "$UNINSTALL" == true ]]; then
-  print_header
-  echo -e "Uninstalling from: ${BOLD}${TARGET_DIR}${RESET}"
-  echo ""
-
-  REMOVED=0
-
-  if [[ -d "${TARGET_DIR}/workflows" ]]; then
-    # Only remove our workflows (non-destructive: checks for our files)
-    for wf in new-project discuss-phase plan-phase execute-phase verify-work quick progress ls next pause-work resume-work complete-milestone; do
-      if [[ -f "${TARGET_DIR}/workflows/${wf}.md" ]]; then
-        rm "${TARGET_DIR}/workflows/${wf}.md"
-        print_info "Removed workflows/${wf}.md"
-        ((REMOVED++)) || true
-      fi
-    done
-  fi
-
-  if [[ -d "${TARGET_DIR}/skills/agentic-learning" ]]; then
-    rm -rf "${TARGET_DIR}/skills/agentic-learning"
-    print_info "Removed skills/agentic-learning/"
-    ((REMOVED++)) || true
-  fi
-
-  if [[ -d "${TARGET_DIR}/skills/impeccable" ]]; then
-    rm -rf "${TARGET_DIR}/skills/impeccable"
-    print_info "Removed skills/impeccable/"
-    ((REMOVED++)) || true
-  fi
-
-  if [[ -d "${TARGET_DIR}/skills/frontend-design" ]]; then
-    rm -rf "${TARGET_DIR}/skills/frontend-design"
-    print_info "Removed skills/frontend-design/ (legacy)"
-    ((REMOVED++)) || true
-  fi
-
-  if [[ $REMOVED -eq 0 ]]; then
-    print_warn "Nothing found to remove at ${TARGET_DIR}"
-  else
-    echo ""
-    print_success "Uninstall complete. Removed ${REMOVED} item(s)."
-  fi
-  exit 0
-fi
-
-# ─── Install ─────────────────────────────────────────────────────────────────
-
-print_header
-echo -e "Installing to: ${BOLD}${TARGET_DIR}${RESET}"
-if [[ "$SCOPE" == "global" ]]; then
-  print_info "Global install — workflows and skills will be available in all Windsurf projects"
-else
-  print_info "Project install — workflows and skills available in this project only"
-fi
-echo ""
-
-# Validate source directory has the required files
-if [[ ! -d "${REPO_DIR}/.windsurf/workflows" ]]; then
-  print_error "Source workflows not found at ${REPO_DIR}/.windsurf/workflows"
-  print_error "Make sure you are running install.sh from the agentic-development repo root."
-  exit 1
-fi
-
-# Create target directories
-mkdir -p "${TARGET_DIR}/workflows"
-mkdir -p "${TARGET_DIR}/skills"
-
-# ── Install Workflows ──────────────────────────────────────────────────────
-
-echo -e "${BOLD}Installing workflows...${RESET}"
-
-WORKFLOW_COUNT=0
-for wf_file in "${REPO_DIR}/.windsurf/workflows/"*.md; do
-  wf_name="$(basename "$wf_file")"
-  dest="${TARGET_DIR}/workflows/${wf_name}"
-  if [[ "$(realpath "$wf_file")" != "$(realpath "$dest" 2>/dev/null)" ]]; then
-    cp "$wf_file" "$dest"
-    print_success "workflows/${wf_name}"
-    ((WORKFLOW_COUNT++)) || true
-  fi
-done
-
-echo ""
-
-# ── Install Skills ─────────────────────────────────────────────────────────
-
-echo -e "${BOLD}Installing skills...${RESET}"
-
-# agentic-learning
-if [[ -d "${REPO_DIR}/.windsurf/skills/agentic-learning" ]]; then
-  mkdir -p "${TARGET_DIR}/skills/agentic-learning"
-  if [[ "$(realpath "${REPO_DIR}/.windsurf/skills/agentic-learning")" != "$(realpath "${TARGET_DIR}/skills/agentic-learning" 2>/dev/null)" ]]; then
-    cp -r "${REPO_DIR}/.windsurf/skills/agentic-learning/"* "${TARGET_DIR}/skills/agentic-learning/"
-  fi
-  print_success "skills/agentic-learning/ (learning partner)"
-else
-  print_warn "skills/agentic-learning/ not found in source — skipping"
-fi
-
-# impeccable (full design skill suite)
-if [[ -d "${REPO_DIR}/.windsurf/skills/impeccable" ]]; then
-  if [[ "$(realpath "${REPO_DIR}/.windsurf/skills/impeccable")" != "$(realpath "${TARGET_DIR}/skills/impeccable" 2>/dev/null)" ]]; then
-    cp -r "${REPO_DIR}/.windsurf/skills/impeccable" "${TARGET_DIR}/skills/impeccable"
-  fi
-  IMPECCABLE_COUNT=$(find "${REPO_DIR}/.windsurf/skills/impeccable" -name "SKILL.md" | wc -l | tr -d ' ')
-  print_success "skills/impeccable/ (${IMPECCABLE_COUNT} design skills — audit, critique, polish, colorize + more)"
-else
-  print_warn "skills/impeccable/ not found in source — skipping"
-fi
-
-echo ""
-
-# ── Done ──────────────────────────────────────────────────────────────────
-
-echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
-echo -e "${GREEN}${BOLD}  Installation complete!${RESET}"
-echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
-echo ""
-echo -e "  ${BOLD}Installed:${RESET} ${WORKFLOW_COUNT} workflows + 2 skill suites (agentic-learning, impeccable)"
-echo -e "  ${BOLD}Location:${RESET}  ${TARGET_DIR}"
-echo ""
-
-if [[ "$SCOPE" == "global" ]]; then
-  echo -e "  ${BOLD}Next steps:${RESET}"
-  echo -e "  • Restart Windsurf (or reload the window) to activate"
-  echo -e "  • Open any project and type ${BOLD}/new-project${RESET} to start"
-else
-  echo -e "  ${BOLD}Next steps:${RESET}"
-  echo -e "  • Workflows are immediately available in this project"
-  echo -e "  • Type ${BOLD}/new-project${RESET} in Cascade to start"
-fi
-
-echo ""
-echo -e "  ${BOLD}Quick reference:${RESET}"
-echo -e "  /ls                   Where am I? What's next? (start every session here)"
-echo -e "  /next                 Auto-pilot — runs the right workflow automatically"
-echo -e "  /new-project          Initialize a new project"
-echo -e "  /discuss-phase [N]    Capture implementation decisions"
-echo -e "  /plan-phase [N]       Create executable plans"
-echo -e "  /execute-phase [N]    Run all plans in a phase"
-echo -e "  /verify-work [N]      Manual acceptance testing"
-echo -e "  /quick [description]  Ad-hoc task with full guarantees"
-echo ""
-echo -e "  ${BOLD}Learning mode:${RESET} Set ${BOLD}learning_mode${RESET} in .planning/config.json"
-echo -e "  ${BOLD}  auto${RESET}   (default) Offered at workflow checkpoints"
-echo -e "  ${BOLD}  manual${RESET} Only when you invoke @agentic-learning"
-echo ""
-echo -e "  See ${BOLD}README.md${RESET} or ${BOLD}https://github.com/FavioVazquez/learnship${RESET} for full documentation."
-echo ""