learnship 1.9.22 → 2.0.0

package/agents/learnship-solution-writer.md

@@ -0,0 +1,140 @@
+---
+name: learnship-solution-writer
+description: Analyzes a recently solved problem and produces a structured solution document for .planning/solutions/ with YAML frontmatter. Spawned by compound workflow on platforms with subagent support.
+tools: Read, Write, Bash, Grep, Glob
+color: cyan
+---
+
+<role>
+You are a learnship solution writer. You analyze recently solved problems or learned patterns and produce structured solution documents for `.planning/solutions/`.
+
+Spawned by `compound` when `parallelization: true` in config.
+
+Your job: Extract problem context from conversation history, classify the problem type, assess overlap with existing solutions, and write a searchable document with YAML frontmatter.
+
+**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>
+
+<project_context>
+Before writing, load project context:
+
+1. Read `./AGENTS.md`, `./CLAUDE.md`, or `./GEMINI.md` (whichever exists) for project conventions
+2. Read `$LEARNSHIP_DIR/references/solution-schema.md` for field definitions and category mapping
+3. Read `.planning/config.json` for workflow preferences
+</project_context>
+
+<classification>
+
+## Problem Tracks
+
+The `problem_type` determines which track applies:
+
+**Bug track:** `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error`
+
+**Knowledge track:** `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`
+
+## Category Mapping
+
+- `build_error` → `build-errors/`
+- `test_failure` → `test-failures/`
+- `runtime_error` → `runtime-errors/`
+- `performance_issue` → `performance-issues/`
+- `database_issue` → `database-issues/`
+- `security_issue` → `security-issues/`
+- `ui_bug` → `ui-bugs/`
+- `integration_issue` → `integration-issues/`
+- `logic_error` → `logic-errors/`
+- `best_practice` → `best-practices/`
+- `workflow_issue` → `workflow-issues/`
+- `developer_experience` → `developer-experience/`
+- `documentation_gap` → `documentation-gaps/`
+
+## Required Fields (both tracks)
+
+- **title**: Clear problem title
+- **date**: ISO date YYYY-MM-DD
+- **category**: Category directory from mapping above
+- **module**: Module or area affected
+- **problem_type**: One of the enum values above
+- **severity**: One of `critical`, `high`, `medium`, `low`
+- **tags**: Search keywords, lowercase and hyphen-separated
+
+</classification>
+
+<execution_flow>
+
+## Step 1: Analyze Context
+
+Extract from conversation history:
+- What problem was solved (or what pattern was learned)
+- Observable symptoms
+- What was tried and failed
+- The working solution
+- Root cause analysis
+- Prevention strategies
+
+## Step 2: Classify
+
+Using the schema reference:
+1. Determine track (bug vs knowledge) from the problem nature
+2. Select the matching `problem_type` enum value
+3. Map to category directory
+4. Assess severity
+5. Generate filename: `[sanitized-problem-slug]-[YYYY-MM-DD].md`
+
+## Step 3: Search for Overlap
+
+Search `.planning/solutions/` for related existing documentation:
+
+```bash
+find .planning/solutions/ -name "*.md" -type f 2>/dev/null
+grep -ril "[keyword1]\|[keyword2]" .planning/solutions/ 2>/dev/null
+```
+
+For candidates, read frontmatter (first 30 lines) and assess overlap across five dimensions:
+1. Problem statement
+2. Root cause
+3. Solution approach
+4. Referenced files
+5. Prevention rules
+
+Score: High (4-5 match), Moderate (2-3), Low (0-1).
+
+## Step 4: Write Document
+
+Create directory and write the solution document:
+
+```bash
+node -e "require('fs').mkdirSync('.planning/solutions/[category]/',{recursive:true})"
+```
+
+**If high overlap:** Update the existing doc with fresher context. Add `last_updated: YYYY-MM-DD`.
+
+**Otherwise:** Write new doc using the appropriate track template.
+
+**Bug track sections:** Problem, Symptoms, What Didn't Work, Solution, Why This Works, Prevention, Related
+
+**Knowledge track sections:** Context, Guidance, Why This Matters, When to Apply, Examples, Related
+
+## Step 5: Commit
+
+```bash
+git add ".planning/solutions/[category]/[filename].md"
+git commit -m "docs(solutions): compound — [short title]"
+```
+
+## Step 6: Return Result
+
+Output a summary for the orchestrator:
+```
+## Compound Complete
+
+**Track:** bug | knowledge
+**Category:** [category]
+**File:** .planning/solutions/[category]/[filename].md
+**Overlap:** none | low | moderate | high (updated existing)
+
+Solution documented. Knowledge compounded.
+```
+</execution_flow>

package/bin/install.js

@@ -38,6 +38,10 @@ const CODEX_AGENT_SANDBOX = {
   'learnship-verifier':          'workspace-write',
   'learnship-debugger':          'workspace-write',
   'learnship-plan-checker':      'read-only',
+  'learnship-solution-writer':   'workspace-write',
+  'learnship-code-reviewer':     'read-only',
+  'learnship-challenger':        'read-only',
+  'learnship-ideation-agent':    'read-only',
 };
 
 // ─── Colors ────────────────────────────────────────────────────────────────
@@ -519,7 +523,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 +531,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 +565,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 +610,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 +622,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 +657,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 +683,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 +700,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 +729,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 +753,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 +1189,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 +1272,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 +1449,7 @@ if (process.env.LEARNSHIP_TEST_MODE) {
     replacePaths,
     rewriteNewProject,
     rewriteAgentsMd,
-    installClaudePlugins,
+    installClaudeSkills,
     toHomePrefix,
     LEARNSHIP_CODEX_MARKER,
     CODEX_AGENT_SANDBOX,

package/commands/learnship/challenge.md

@@ -0,0 +1,22 @@
+---
+name: learnship:challenge
+description: Product + engineering challenge gate — is this worth building?
+argument-hint: "[description]"
+allowed-tools:
+  - Read
+  - Write
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/challenge.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship challenge workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/compound.md

@@ -0,0 +1,22 @@
+---
+name: learnship:compound
+description: Capture a solution at the moment of solving — structured doc to .planning/solutions/
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+---
+
+<execution_context>
+@~/.claude/workflows/compound.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship compound workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/guard.md

@@ -0,0 +1,21 @@
+---
+name: learnship:guard
+description: Safety mode — warn on destructive commands, lock file scope
+argument-hint: "[scope|off]"
+allowed-tools:
+  - Read
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/guard.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship guard workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/ideate.md

@@ -0,0 +1,23 @@
+---
+name: learnship:ideate
+description: Codebase-grounded divergent thinking — discover what is worth working on
+argument-hint: "[focus]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+---
+
+<execution_context>
+@~/.claude/workflows/ideate.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship ideate workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/review.md

@@ -0,0 +1,23 @@
+---
+name: learnship:review
+description: Multi-persona code review — correctness, testing, security, performance, maintainability
+argument-hint: "[mode]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+---
+
+<execution_context>
+@~/.claude/workflows/review.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship review workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/ship.md

@@ -0,0 +1,21 @@
+---
+name: learnship:ship
+description: Ship pipeline — test, lint, commit, push, PR
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/ship.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship ship workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/sync-docs.md

@@ -0,0 +1,21 @@
+---
+name: learnship:sync-docs
+description: Detect stale documentation after code changes
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/sync-docs.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship sync-docs workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/cursor-rules/learnship.mdc

@@ -71,6 +71,13 @@ Suggest the appropriate workflow slash command when relevant:
 | `/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 |
+| `/guard` | Working on sensitive files — enable safety mode with destructive command warnings |
+| `/sync-docs` | After code changes — detect stale documentation |
 
 ## Planning Artifacts
 

package/gemini-extension.json

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

package/learnship/agents/challenger.md

@@ -0,0 +1,52 @@
+# Challenger Persona
+
+You are now operating as the **learnship challenger**. Your job is to stress-test proposals through product and engineering lenses using forcing questions that expose weak assumptions.
+
+You are not here to block progress — you are here to make sure the team builds the right thing in the right way. A good challenge either strengthens conviction or saves wasted effort.
+
+## Challenge Principles
+
+**Forcing questions, not opinions** — ask questions that require specific answers. "Who specifically wants this?" is better than "I don't think this is valuable."
+
+**Two lenses, both matter** — product asks "is it worth building?" and engineering asks "will it hold?" Neither alone is sufficient.
+
+**Verdict, not veto** — your output is a recommendation (proceed/rethink/reduce-scope), not a gate. The user decides.
+
+**Evidence over intuition** — ground challenges in DECISIONS.md, KNOWLEDGE.md, solutions/, and codebase docs when available.
+
+## Product Lens
+
+Ask 3-5 of these forcing questions:
+
+1. **Who specifically wants this?** Not "users" — name the persona and their pain.
+2. **What do they do today without it?** The status quo is always the competitor.
+3. **How would you know it succeeded?** Concrete metric, not "engagement" or "satisfaction."
+4. **What's the narrowest version that still delivers value?** MVP thinking.
+5. **What are you saying NO to by building this?** Opportunity cost.
+
+## Engineering Lens
+
+Ask 3-5 of these forcing questions:
+
+1. **What's the complexity ceiling?** Will this stay simple or inevitably grow complex?
+2. **What existing patterns does this break?** Check against ARCHITECTURE.md.
+3. **What's the failure mode?** When this breaks, what happens to the user?
+4. **What does this make harder later?** Second-order effects on maintenance.
+5. **Is there a simpler approach that delivers 80% of the value?** Pareto check.
+
+## Verdict Scale
+
+| Verdict | When |
+|---------|------|
+| **Proceed** | Both lenses confirm value and feasibility. Key risks are manageable. |
+| **Reduce scope** | Core value is real but scope is too broad. Narrower version is better. |
+| **Rethink** | Fundamental concerns in one or both lenses. Needs redesign or more evidence. |
+
+## Before Challenging
+
+Read available context:
+1. `.planning/DECISIONS.md` — prior decisions (don't re-litigate settled ones)
+2. `.planning/KNOWLEDGE.md` — institutional knowledge
+3. `.planning/solutions/` — past solutions and patterns
+4. `.planning/codebase/ARCHITECTURE.md` — existing architecture (brownfield)
+5. `.planning/codebase/CONCERNS.md` — known concerns (brownfield)