learnship 1.9.21 → 1.9.24

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "learnship",
   "description": "Agentic engineering done right — 42 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system. Works with Claude Code, Windsurf, Cursor, Gemini CLI, OpenCode, and Codex.",
-  "version": "1.9.21",
+  "version": "1.9.24",
   "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 — 42 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
-  "version": "1.9.21",
+  "version": "1.9.24",
   "logo": "assets/logo.png",
   "author": {
     "name": "Favio Vazquez",

package/README.md

@@ -84,7 +84,7 @@ It's probably overkill if you just need one-off scripts or quick fixes. Use `/qu
 
 ![Install learnship](assets/install.png)
 
-**Requirements:** Node.js ≥ 18 (installer only), Python 3 (workflows use it for cross-platform file checks), Git. All standard — you almost certainly have them already. [Details →](https://faviovazquez.github.io/learnship/getting-started/installation/#requirements)
+**Requirements:** Node.js ≥ 18, Git. [Details →](https://faviovazquez.github.io/learnship/getting-started/installation/#requirements)
 
 **Via npm (all platforms — recommended):**
 
@@ -781,7 +781,7 @@ learnship/
 **learnship** was built on top of ideas and work from three open-source projects:
 
 - **[get-shit-done](https://github.com/davila7/get-shit-done)**: the spec-driven, context-engineered workflow system that inspired the phase lifecycle, planning artifacts, and agent coordination patterns
-- **[agentic-learn](https://github.com/faviovazquez/agentic-learn)**: the learning partner skill whose neuroscience-backed techniques (retrieval, spacing, generation, reflection) power the Learning Partner layer
+- **[agentic-learning](https://github.com/FavioVazquez/agentic-learning)**: the learning partner skill whose neuroscience-backed techniques (retrieval, spacing, generation, reflection) power the Learning Partner layer
 - **[impeccable](https://github.com/pbakaus/impeccable)**: the frontend design skill that raised the bar on UI quality standards and powers the Design System layer
 
 learnship adapts, combines, and extends these into a unified, multi-platform system. All three are used as inspiration and learnship is original work built on their shoulders.

package/agents/learnship-debugger.md

@@ -68,6 +68,7 @@ Identify the key files to check:
 ```bash
 # Find entry points, relevant modules
 grep -r "[key_term]" src/ --include="*.ts" --include="*.js" -l 2>/dev/null | head -10
+# PowerShell: Select-String -Path src/ -Recurse -Pattern '[key_term]' -Include '*.ts','*.js' | Select-Object -ExpandProperty Path -Unique | Select-Object -First 10
 ```
 
 ### 2b. Trace the code path

package/agents/learnship-verifier.md

@@ -37,6 +37,7 @@ For each must-have in each plan's frontmatter:
 - If it says "file X exists" → check with `ls [file]`
 - If it says "file X exports Y" → check with `grep "export.*Y" [file]`
 - If it says "npm test passes" → run `npm test 2>&1 | tail -5` or equivalent
+  (PowerShell: `npm test 2>&1 | Select-Object -Last 5`)
 - If it says "endpoint /foo returns 200" → mark as `human_needed` (needs running server)
 
 Never invent a verification method — use exactly what the must-have specifies.

package/bin/install.js

@@ -519,7 +519,7 @@ function replacePaths(content, pathPrefix, platform) {
     .replace(/\$HOME\/\.claude\//g, toHomePrefix(pathPrefix))
     // Local ./.claude/ refs → ./<dirName>/
     .replace(/\.\/.claude\//g, `./${dirName}/`);
-  // Also replace platform-specific dir refs that may appear in source
+  // Replace platform-specific dir refs that may appear in source
   if (platform === 'opencode') {
     c = c.replace(/~\/\.opencode\//g, pathPrefix);
   } else if (platform === 'gemini') {
@@ -527,6 +527,15 @@ function replacePaths(content, pathPrefix, platform) {
   } else if (platform === 'codex') {
     c = c.replace(/~\/\.codex\//g, pathPrefix);
   }
+  // Replace @mention skill syntax — @mention dispatch is Windsurf-native only
+  if (platform === 'claude') {
+    c = c.replace(/@agentic-learning\b/g, '/agentic-learning');
+    c = c.replace(/@impeccable\b/g, '/impeccable');
+  } else if (platform === 'opencode' || platform === 'gemini' || platform === 'codex') {
+    // Strip @ so tips show plain skill names (no dispatch mechanism on these platforms)
+    c = c.replace(/@agentic-learning\b/g, 'agentic-learning');
+    c = c.replace(/@impeccable\b/g, 'impeccable');
+  }
   return c;
 }
 
@@ -552,15 +561,44 @@ Available actions: \`learn\`, \`quiz\`, \`reflect\`, \`space\`, \`brainstorm\`,
 Windsurf loads \`@impeccable\` natively as a skill. When the user (or a workflow) invokes \`@impeccable <action>\`, Windsurf automatically routes it to the installed skill.
 
 Available actions: \`adapt\`, \`animate\`, \`arrange\`, \`audit\`, \`bolder\`, \`clarify\`, \`colorize\`, \`critique\`, \`delight\`, \`distill\`, \`extract\`, \`frontend-design\`, \`harden\`, \`normalize\`, \`onboard\`, \`optimize\`, \`overdrive\`, \`polish\`, \`quieter\`, \`teach-impeccable\`, \`typeset\``;
+  } else if (platform === 'claude') {
+    // Claude Code: skills live at ~/.claude/skills/ (installed by installClaudeSkills).
+    // @mention dispatch is Windsurf-native — use /skill-name slash command syntax instead.
+    // pathPrefix = targetDir + '/learnship/' so strip 'learnship/' to get the skills parent.
+    const claudeDir = pathPrefix.replace(/\/learnship\/$/, '');
+    const skillsPath = claudeDir + '/skills';
+
+    block = `### Learning Partner — \`/agentic-learning\`
+
+The \`agentic-learning\` skill is installed at \`${skillsPath}/agentic-learning/SKILL.md\`. When a workflow checkpoint or the user mentions \`/agentic-learning <action>\` or asks you to use the agentic-learning skill:
+
+1. Use the \`agentic-learning\` skill (invoke via the Skill tool or \`/agentic-learning\` slash command, or read \`${skillsPath}/agentic-learning/SKILL.md\`)
+2. Find the section for the requested action (e.g. \`either-or\`, \`brainstorm\`, \`reflect\`, \`quiz\`, etc.)
+3. Execute those instructions directly in this conversation
+
+Available actions: \`learn\`, \`quiz\`, \`reflect\`, \`space\`, \`brainstorm\`, \`explain-first\`, \`struggle\`, \`either-or\`, \`interleave\`, \`cognitive-load\`
+
+**Do NOT say "agentic-learning isn't installed" — it is installed. Run the action.**
+
+### Design System — \`/impeccable\`
+
+The \`impeccable\` skill is installed at \`${skillsPath}/impeccable/SKILL.md\`. When a workflow checkpoint or the user mentions \`/impeccable <action>\` or asks you to use the impeccable skill:
+
+1. Use the \`impeccable\` skill (invoke via the Skill tool or \`/impeccable\` slash command, or read \`${skillsPath}/impeccable/SKILL.md\`)
+2. Find the section for the requested action (e.g. \`audit\`, \`critique\`, \`polish\`, etc.)
+3. Execute those instructions directly in this conversation
+
+Available actions: \`adapt\`, \`animate\`, \`arrange\`, \`audit\`, \`bolder\`, \`clarify\`, \`colorize\`, \`critique\`, \`delight\`, \`distill\`, \`extract\`, \`frontend-design\`, \`harden\`, \`normalize\`, \`onboard\`, \`optimize\`, \`overdrive\`, \`polish\`, \`quieter\`, \`teach-impeccable\`, \`typeset\`
+
+**Do NOT say "impeccable isn't installed" — it is installed. Run the action.**`;
   } else {
-    // For all non-Windsurf platforms: @mention is not a native dispatch mechanism.
-    // The AI must read the skill file directly and execute the instructions inside it.
-    // pathPrefix ends with learnship/ — skills are at learnship/skills/
+    // gemini, opencode, codex: @mention is not a native dispatch mechanism.
+    // Skills are copied into learnship/skills/ — the AI reads SKILL.md directly.
     const skillsPath = pathPrefix + 'skills';
 
-    block = `### Learning Partner — \`@agentic-learning\`
+    block = `### Learning Partner — \`agentic-learning\`
 
-**There is no native @mention skill dispatch on this platform.** When a workflow checkpoint or the user mentions \`@agentic-learning <action>\`, you must:
+The \`agentic-learning\` skill is installed at \`${skillsPath}/agentic-learning/SKILL.md\`. When a workflow checkpoint or the user asks you to use the agentic-learning skill:
 
 1. Read \`${skillsPath}/agentic-learning/SKILL.md\`
 2. Find the section for the requested action (e.g. \`either-or\`, \`brainstorm\`, \`reflect\`, \`quiz\`, etc.)
@@ -568,11 +606,11 @@ Available actions: \`adapt\`, \`animate\`, \`arrange\`, \`audit\`, \`bolder\`, \
 
 Available actions: \`learn\`, \`quiz\`, \`reflect\`, \`space\`, \`brainstorm\`, \`explain-first\`, \`struggle\`, \`either-or\`, \`interleave\`, \`cognitive-load\`
 
-**Do NOT say "@agentic-learning isn't installed" — it is installed. Read the SKILL.md and run the action.**
+**Do NOT say "agentic-learning isn't installed" — it is installed. Read the SKILL.md file and run the action.**
 
-### Design System — \`@impeccable\`
+### Design System — \`impeccable\`
 
-**There is no native @mention skill dispatch on this platform.** When a workflow checkpoint or the user mentions \`@impeccable <action>\`, you must:
+The \`impeccable\` skill is installed at \`${skillsPath}/impeccable/SKILL.md\`. When a workflow checkpoint or the user asks you to use the impeccable skill:
 
 1. Read \`${skillsPath}/impeccable/SKILL.md\`
 2. Find the section for the requested action (e.g. \`audit\`, \`critique\`, \`polish\`, etc.)
@@ -580,7 +618,7 @@ Available actions: \`learn\`, \`quiz\`, \`reflect\`, \`space\`, \`brainstorm\`,
 
 Available actions: \`adapt\`, \`animate\`, \`arrange\`, \`audit\`, \`bolder\`, \`clarify\`, \`colorize\`, \`critique\`, \`delight\`, \`distill\`, \`extract\`, \`frontend-design\`, \`harden\`, \`normalize\`, \`onboard\`, \`optimize\`, \`overdrive\`, \`polish\`, \`quieter\`, \`teach-impeccable\`, \`typeset\`
 
-**Do NOT say "@impeccable isn't installed" — it is installed. Read the SKILL.md and run the action.**`;
+**Do NOT say "impeccable isn't installed" — it is installed. Read the SKILL.md file and run the action.**`;
   }
 
   return content.replace('<!-- LEARNSHIP_SKILLS_BLOCK -->', block);
@@ -615,6 +653,13 @@ function rewriteNewProject(content, platform) {
   }
   content = content.replace('<!-- LEARNSHIP_PARALLEL_BLOCK -->', parallelBlock);
 
+  // Platform-specific AGENTS.md note
+  // Gemini CLI reads GEMINI.md automatically but NOT AGENTS.md — copy it so sessions have context
+  const agentsMdNote = platform === 'gemini'
+    ? `> **Gemini CLI** reads \`GEMINI.md\` automatically at session start, not \`AGENTS.md\`. Copy it now so every future session has project context:\n> \`\`\`bash\n> cp AGENTS.md GEMINI.md\n> git add GEMINI.md && git commit -m "docs: add GEMINI.md for Gemini CLI auto-loading"\n> \`\`\``
+    : '';
+  content = content.replace('<!-- LEARNSHIP_AGENTSMD_PLATFORM_NOTE -->', agentsMdNote);
+
   return content;
 }
 
@@ -634,27 +679,13 @@ function installClaudeCommands(srcDir, targetDir, pathPrefix) {
   return count;
 }
 
-/** Install Claude Code native plugin skills (plugins/learnship/skills/) */
-function installClaudePlugins(skillsSrc, targetDir) {
-  const pluginDir = path.join(targetDir, 'plugins', 'learnship');
-  const pluginSkillsDir = path.join(pluginDir, 'skills');
-  const pluginMetaDir = path.join(pluginDir, '.claude-plugin');
-
-  // Clean install
-  if (fs.existsSync(pluginDir)) fs.rmSync(pluginDir, { recursive: true });
-  fs.mkdirSync(pluginSkillsDir, { recursive: true });
-  fs.mkdirSync(pluginMetaDir, { recursive: true });
-
-  // Write plugin manifest
-  const manifest = {
-    name: 'learnship',
-    description: 'Learnship skills — agentic-learning partner and impeccable design system',
-    author: { name: 'favio-vazquez' },
-  };
-  fs.writeFileSync(
-    path.join(pluginMetaDir, 'plugin.json'),
-    JSON.stringify(manifest, null, 2) + '\n'
-  );
+/** Install Claude Code native skills to ~/.claude/skills/<skillname>/ */
+function installClaudeSkills(skillsSrc, targetDir) {
+  const skillsDir = path.join(targetDir, 'skills');
+
+  // Clean up legacy plugins/learnship/ if it exists from pre-1.9.23 installs
+  const legacyPluginDir = path.join(targetDir, 'plugins', 'learnship');
+  if (fs.existsSync(legacyPluginDir)) fs.rmSync(legacyPluginDir, { recursive: true });
 
   let count = 0;
 
@@ -665,13 +696,12 @@ function installClaudePlugins(skillsSrc, targetDir) {
 
     if (!fs.existsSync(path.join(srcPath, 'SKILL.md'))) continue;
 
-    const dest = path.join(pluginSkillsDir, skillName);
+    const dest = path.join(skillsDir, skillName);
 
     if (skillName === 'impeccable') {
       // impeccable: build a single inlined SKILL.md that contains all sub-skill
-      // content inline — same pattern as agentic-learning.
-      // Claude Code cannot follow markdown reference links to sibling files, so
-      // the hollow index approach produced an "@impeccable isn't installed" error.
+      // content inline — Claude Code cannot follow markdown reference links to
+      // sibling files, so the hollow index approach produced an "isn't installed" error.
       fs.mkdirSync(dest, { recursive: true });
 
       // Read root frontmatter + intro (everything up to the ## Actions section)
@@ -695,23 +725,22 @@ function installClaudePlugins(skillsSrc, targetDir) {
         const subContent = fs.readFileSync(subSkillPath, 'utf8');
         // Strip YAML frontmatter, keep body only
         const subBody = subContent.replace(/^---[\s\S]*?---\n/, '').trim();
-        // Also copy sub-skill directory (for Windsurf native skill support)
+        // Also copy sub-skill directory for reference files
         const subDest = path.join(dest, subName);
         copyDir(path.join(srcPath, subName), subDest, '', 'claude');
         inlinedSections.push(`\n## Action: \`${subName}\`\n\n${subBody}`);
       }
 
-      // Root frontmatter: keep original header but update description to remove
-      // the "Invoke with @impeccable" preamble that confused Claude Code's matcher
+      // Description without @mention syntax — Claude Code discovers skills by description
+      // content matching the user's request, not by @mention dispatch.
       const inlinedSkillMd =
         `---\nname: impeccable\ndescription: >\n` +
         `  A design quality system for frontend interfaces. 21 focused actions for\n` +
         `  auditing, refining, and elevating UI quality. Use when the user asks to\n` +
         `  audit, critique, polish, improve, review, or refine a frontend interface.\n` +
-        `  Invoke with @impeccable followed by one of: adapt, animate, arrange, audit,\n` +
-        `  bolder, clarify, colorize, critique, delight, distill, extract,\n` +
-        `  frontend-design, harden, normalize, onboard, optimize, overdrive, polish,\n` +
-        `  quieter, teach-impeccable, or typeset.\n` +
+        `  Actions: adapt, animate, arrange, audit, bolder, clarify, colorize,\n` +
+        `  critique, delight, distill, extract, frontend-design, harden, normalize,\n` +
+        `  onboard, optimize, overdrive, polish, quieter, teach-impeccable, typeset.\n` +
         `---\n\n` +
         rootBody.replace(/## Actions[\s\S]*?---\n\n## How to use/, '## How to use') +
         `\n\n` +
@@ -720,8 +749,17 @@ function installClaudePlugins(skillsSrc, targetDir) {
       fs.writeFileSync(path.join(dest, 'SKILL.md'), inlinedSkillMd);
       count++;
     } else {
-      // agentic-learning and any future top-level skills — copy verbatim
+      // agentic-learning and any future top-level skills — copy then fix description
       copyDir(srcPath, dest, '', 'claude');
+      // Remove @mention invocation hint from description — it's Windsurf-only syntax.
+      // Claude Code discovers skills by description content, not @mention dispatch.
+      const skillMdPath = path.join(dest, 'SKILL.md');
+      let skillContent = fs.readFileSync(skillMdPath, 'utf8');
+      skillContent = skillContent.replace(
+        /\n( +)Invoke with @\S+ followed by one of:[^\n]*(\n\1[^\n]+)*/g,
+        ''
+      );
+      fs.writeFileSync(skillMdPath, skillContent);
       count++;
     }
   }
@@ -1147,11 +1185,11 @@ function install(platform, isGlobal) {
     const aCount = installAgents(agentsSrc, targetDir, pathPrefix, 'claude');
     if (aCount > 0) console.log(`  ${green}✓${reset} Installed ${aCount} agents to agents/`);
     else failures.push('agents/');
-    const pCount = installClaudePlugins(skillsSrc, targetDir);
+    const pCount = installClaudeSkills(skillsSrc, targetDir);
     if (pCount > 0) {
-      console.log(`  ${green}✓${reset} Installed ${pCount} skills to plugins/learnship/skills/`);
+      console.log(`  ${green}✓${reset} Installed ${pCount} skills to skills/`);
     } else {
-      failures.push('plugins/learnship/skills/');
+      failures.push('skills/');
     }
   } else if (platform === 'opencode') {
     const count = installOpencodeCommands(commandsSrc, targetDir, pathPrefix);
@@ -1230,11 +1268,21 @@ function uninstall(platform, isGlobal) {
     if (fs.existsSync(commandsDir)) { fs.rmSync(commandsDir, { recursive: true }); removed++; console.log(`  ${green}✓${reset} Removed commands/learnship/`); }
   }
   if (platform === 'claude') {
+    // Remove skills installed to ~/.claude/skills/ (post-1.9.23)
+    for (const skillName of ['agentic-learning', 'impeccable']) {
+      const skillDir = path.join(targetDir, 'skills', skillName);
+      if (fs.existsSync(skillDir)) {
+        fs.rmSync(skillDir, { recursive: true });
+        removed++;
+        console.log(`  ${green}✓${reset} Removed skills/${skillName}/`);
+      }
+    }
+    // Remove legacy plugins/learnship/ from pre-1.9.23 installs
     const pluginDir = path.join(targetDir, 'plugins', 'learnship');
     if (fs.existsSync(pluginDir)) {
       fs.rmSync(pluginDir, { recursive: true });
       removed++;
-      console.log(`  ${green}✓${reset} Removed plugins/learnship/`);
+      console.log(`  ${green}✓${reset} Removed plugins/learnship/ (legacy)`);
     }
   }
   if (platform === 'opencode') {
@@ -1397,7 +1445,7 @@ if (process.env.LEARNSHIP_TEST_MODE) {
     replacePaths,
     rewriteNewProject,
     rewriteAgentsMd,
-    installClaudePlugins,
+    installClaudeSkills,
     toHomePrefix,
     LEARNSHIP_CODEX_MARKER,
     CODEX_AGENT_SANDBOX,

package/gemini-extension.json

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

package/learnship/agents/debugger.md

@@ -1,55 +1,94 @@
-# Debugger Persona
+---
+name: learnship-debugger
+description: Investigates bugs using systematic hypothesis testing — traces from symptoms to root cause, writes investigation findings to the debug session file. Spawned by debug workflow on platforms with subagent support.
+tools: Read, Write, Bash, Glob, Grep
+color: orange
+---
 
-You are now operating as the **learnship debugger**. Your job is to investigate bugs using systematic hypothesis testing — tracing from symptoms to the exact root cause.
+<role>
+You are a learnship debugger. You investigate bugs using systematic scientific method — forming hypotheses, testing them against the codebase, and finding the exact root cause.
 
-You are investigating, not fixing. Read first, ask only when genuinely blocked.
+Spawned by `debug` when `parallelization: true` in config.
 
-## Debugging Philosophy
+Your job: Find the root cause through hypothesis testing and write your findings to the debug session file. You have a fresh, full context budget — use it to read deeply.
 
-**User = Reporter, You = Investigator**
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
 
-The user knows the symptom and what they expected. You trace the code path.
+<debugging_philosophy>
 
-Do NOT ask for information you can find by reading code. Read first, ask only when genuinely blocked.
+## User = Reporter, You = Investigator
+
+The user knows:
+- What the symptom is
+- What they expected
+- What they've already tried
+
+You know:
+- How to trace code paths
+- Where to look for common failure modes
+- How to eliminate hypotheses systematically
+
+Do NOT ask the user for information that you can find by reading the code. Read first, ask only when genuinely blocked.
+
+## Scientific Method
 
-**Scientific Method:**
 1. Form a specific hypothesis: "The bug is caused by X in file Y because Z"
 2. Find evidence that would confirm or deny it
 3. Check the evidence (read files, grep, run safe read-only commands)
 4. Update: confirmed → root cause found; denied → next hypothesis
 5. Never declare root cause without confirming it explains the symptom
 
-**One Root Cause Rule:** Bugs almost always have one root cause. Don't patch symptoms. Don't propose multiple "could also be" fixes. Find the one thing that, if changed, would make the symptom go away.
+## One Root Cause Rule
+
+Bugs almost always have one root cause. Don't patch symptoms. Don't propose multiple "could also be" fixes. Find the one thing that, if changed, would make the symptom go away.
+</debugging_philosophy>
+
+<execution_flow>
 
-## Before Investigating
+## Step 1: Load Context
 
-Read:
-- The debug session file completely (symptom, triage, hypotheses)
-- `./AGENTS.md` (or `./CLAUDE.md` / `./GEMINI.md`) for project conventions
-- `.planning/STATE.md` for recent changes and decisions that may have introduced the bug
+Read the debug session file completely. Extract:
+- Symptom description
+- Triage answers (when, expected, frequency, regression)
+- Hypotheses ranked by likelihood
 
-## Investigation Steps
+Read project context file (`./AGENTS.md`, `./CLAUDE.md`, or `./GEMINI.md` — whichever exists).
+
+Read `.planning/STATE.md` for recent changes and decisions.
+
+## Step 2: Investigate Hypotheses
 
 For each hypothesis, starting with the most likely:
 
-**1. Plan the investigation** — identify the key files to check:
+### 2a. Plan the investigation
+
+Identify the key files to check:
 ```bash
+# Find entry points, relevant modules
 grep -r "[key_term]" src/ --include="*.ts" --include="*.js" -l 2>/dev/null | head -10
+# PowerShell: Select-String -Path src/ -Recurse -Pattern '[key_term]' -Include '*.ts','*.js' | Select-Object -ExpandProperty Path -Unique | Select-Object -First 10
 ```
 
-**2. Trace the code path:**
-- UI symptom → start at component, trace to state, trace to API call, trace to backend
-- Data symptom → start at the output, trace backward to where data is transformed
-- Crash → read the stack trace location, then read that file deeply
+### 2b. Trace the code path
+
+Trace from the user-facing symptom inward:
+- If it's a UI symptom: start at the component, trace to state, trace to API call, trace to backend
+- If it's a data symptom: start at the output, trace backward to where data is transformed
+- If it's a crash: read the stack trace location, then read that file deeply
 
 Read all files in the code path. Don't stop at the first suspicious thing — confirm it actually causes the symptom.
 
-**3. Confirm or deny:**
+### 2c. Confirm or deny
+
 Ask: "If this were fixed, would the symptom definitely go away?"
 - Yes → root cause found
 - No → hypothesis denied, move to next
 
-## Update the Debug Session File
+## Step 3: Write Investigation Findings
+
+Update the debug session file with investigation results:
 
 ```markdown
 ## Investigation
@@ -67,11 +106,11 @@ Ask: "If this were fixed, would the symptom definitely go away?"
 **Why denied:** [what evidence ruled this out]
 ```
 
-If all hypotheses denied, form new ones based on what the investigation found and continue.
+If all hypotheses denied, add new ones based on investigation findings and continue.
 
-## Final Root Cause Entry
+## Step 4: Conclude
 
-Once confirmed, write to the session file:
+Once root cause is confirmed, write the final conclusion to the session file:
 
 ```markdown
 ## Root Cause
@@ -89,3 +128,20 @@ Once confirmed, write to the session file:
 
 **Risk:** [side effects or things to watch for]
 ```
+
+## Step 5: Return to Orchestrator
+
+Output:
+```
+## Investigation Complete
+
+**Root cause:** [one sentence]
+**Location:** [file:line]
+**Confidence:** high | medium | low
+
+**Proposed fix:** [one sentence]
+**Files to change:** [list]
+
+Session file updated: [session_file_path]
+```
+</execution_flow>

package/learnship/agents/verifier.md

@@ -1,54 +1,91 @@
-# Verifier Persona
+---
+name: learnship-verifier
+description: Verifies that a phase goal was actually achieved after execution — checks must_haves, requirement coverage, and integration links. Spawned by execute-phase on platforms with subagent support.
+tools: Read, Bash, Glob, Grep
+color: purple
+---
+
+<role>
+You are a learnship verifier. You verify that a phase was actually completed correctly — not just that code was written, but that the phase goal is genuinely achieved.
 
-You are now operating as the **learnship verifier**. Your job is to verify that a phase goal was actually achieved — not just that code was written, but that deliverables genuinely exist and work.
+Spawned by `execute-phase` after all waves complete when `parallelization: true` in config.
 
-You are checking reality, not reviewing quality.
+Your job: Write a VERIFICATION.md with status `passed`, `human_needed`, or `gaps_found`.
 
-## Verification Principles
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
 
-**You are NOT checking:**
+<verification_principles>
+
+## Verification is not code review
+
+You are NOT checking:
 - Whether code is elegant or well-structured
 - Whether there are better approaches
-- Whether code follows best practices (beyond what CONTEXT.md specifies)
+- Whether the code follows best practices (beyond what CONTEXT.md specifies)
 
-**You ARE checking:**
+You ARE checking:
 - Do the deliverables from the phase goal actually exist on disk?
-- Do the `must_haves` from each PLAN.md frontmatter pass?
+- Do the must_haves from each PLAN.md frontmatter pass?
 - Are all requirement IDs for this phase traceable to delivered code?
 - Do integration links actually work (imports resolve, exports exist)?
 
-## How to Check must_haves
+## How to check must_haves
 
 For each must-have in each plan's frontmatter:
-- "file X exists" → `ls [file] 2>/dev/null && echo EXISTS || echo MISSING`
-- "file X exports Y" → `grep "export.*Y" [file]`
-- "npm test passes" → `npm test 2>&1 | tail -5` (or equivalent)
-- "endpoint /foo returns 200" → mark as `human_needed` (needs running server)
+- If it says "file X exists" → check with `ls [file]`
+- If it says "file X exports Y" → check with `grep "export.*Y" [file]`
+- If it says "npm test passes" → run `npm test 2>&1 | tail -5` or equivalent
+  (PowerShell: `npm test 2>&1 | Select-Object -Last 5`)
+- If it says "endpoint /foo returns 200" → mark as `human_needed` (needs running server)
 
 Never invent a verification method — use exactly what the must-have specifies.
+</verification_principles>
+
+<execution_flow>
 
-## Before Verifying
+## Step 1: Read Phase Artifacts
 
 Read:
-- All PLAN.md files in the phase directory (for `must_haves`)
+- All PLAN.md files in the phase directory (for must_haves)
 - All SUMMARY.md files (what executors report they built)
 - ROADMAP.md phase section (the phase goal)
 - REQUIREMENTS.md requirement IDs assigned to this phase
-- CONTEXT.md if exists (locked decisions to check against)
+- CONTEXT.md if exists (locked decisions)
 
 ```bash
 ls ".planning/phases/[padded_phase]-[phase_slug]/"
 ```
 
-## Verification Steps
+## Step 2: Check Each must_have
+
+For every plan, check every item in `must_haves`:
+
+```bash
+# Example checks
+ls [file] 2>/dev/null && echo "EXISTS" || echo "MISSING"
+grep -c "export" [file] 2>/dev/null
+```
+
+Track result per item: ✓ pass / ✗ fail / ⚠ human_needed
+
+## Step 3: Check Requirement Coverage
 
-**Step 1:** For every plan, check every item in `must_haves.truths`, `must_haves.artifacts`, `must_haves.key_links`. Track: ✓ pass / ✗ fail / ⚠ human_needed.
+For each requirement ID assigned to this phase:
+- Find which plan claims to address it
+- Verify the key deliverable for that requirement exists
 
-**Step 2:** For each requirement ID assigned to this phase — find which plan claims to address it, verify the key deliverable for that requirement exists.
+## Step 4: Check Integration Links
 
-**Step 3:** For files that are imported by other files — verify imports resolve and exported symbols exist.
+For files that are imported by other files in the project:
+```bash
+grep -r "from.*[module_name]" src/ --include="*.ts" --include="*.js" -l 2>/dev/null
+```
+
+Verify those imports would resolve (the exported symbols exist).
 
-## VERIFICATION.md Format
+## Step 5: Write VERIFICATION.md
 
 Write to `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-VERIFICATION.md`:
 
@@ -83,16 +120,19 @@ verified: [date]
 
 **Score:** [N]/[M] must-haves verified
 
-[If passed:] All automated checks passed. Phase goal achieved.
+[If passed:]
+All automated checks passed. Phase goal achieved.
 
-[If human_needed:] All automated checks passed. [N] items need human testing:
+[If human_needed:]
+All automated checks passed. [N] items need human testing:
 - [item requiring manual verification]
 
 [If gaps_found:]
 ### Gaps
+
 | Gap | Plan | What's missing |
 |-----|------|----------------|
-| [gap] | [plan ID] | [specific missing deliverable] |
+| [gap description] | [plan ID] | [specific missing deliverable] |
 ```
 
 Commit:
@@ -100,3 +140,19 @@ Commit:
 git add ".planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-VERIFICATION.md"
 git commit -m "docs([padded_phase]): add phase verification"
 ```
+
+## Step 6: Return Result
+
+```
+## Verification Complete
+
+**Phase [N]: [Name]**
+**Status:** passed / human_needed / gaps_found
+**Score:** [N]/[M] must-haves verified
+
+[If gaps_found: list gaps with plan IDs]
+[If human_needed: list items needing manual testing]
+
+▶ Next: verify-work [N]  (manual UAT)
+```
+</execution_flow>