learnship 1.9.0

package/bin/learnship.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// learnship — npx installer
+// Usage: npx learnship [--local|--global] [--uninstall]
+
+const { execSync, spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const args = process.argv.slice(2);
+const hasLocal = args.includes('--local');
+const hasGlobal = args.includes('--global');
+const hasUninstall = args.includes('--uninstall');
+const hasHelp = args.includes('--help') || args.includes('-h');
+
+if (hasHelp) {
+  console.log(`
+learnship — Learn as you build. Build with intent.
+
+Usage:
+  npx github:FavioVazquez/learnship                  # interactive install
+  npx github:FavioVazquez/learnship --local          # install to current project (.windsurf/)
+  npx github:FavioVazquez/learnship --global         # install to all Windsurf projects (~/.codeium/windsurf/)
+  npx github:FavioVazquez/learnship --uninstall --local
+  npx github:FavioVazquez/learnship --uninstall --global
+
+After installing, open Windsurf and type /new-project to start.
+  `);
+  process.exit(0);
+}
+
+// Resolve the install.sh path (bundled alongside this script)
+const repoRoot = path.resolve(__dirname, '..');
+const installScript = path.join(repoRoot, 'install.sh');
+
+if (!fs.existsSync(installScript)) {
+  console.error('Error: install.sh not found. The package may be incomplete.');
+  process.exit(1);
+}
+
+// Build args to forward to install.sh
+const forwardArgs = [];
+if (hasLocal) forwardArgs.push('--local');
+if (hasGlobal) forwardArgs.push('--global');
+if (hasUninstall) forwardArgs.push('--uninstall');
+
+const result = spawnSync('bash', [installScript, ...forwardArgs], {
+  stdio: 'inherit',
+  cwd: repoRoot,
+  env: {
+    ...process.env,
+    LEARNSHIP_INSTALL_CWD: process.env.INIT_CWD || process.cwd(),
+  },
+});
+
+process.exit(result.status ?? 0);

package/commands/learnship/add-phase.md

@@ -0,0 +1,22 @@
+---
+name: learnship:add-phase
+description: Append a new phase to the current milestone roadmap when scope grows after initial planning
+argument-hint: "[description]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/add-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship add-phase workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/add-tests.md

@@ -0,0 +1,24 @@
+---
+name: learnship:add-tests
+description: Generate and add test coverage for a specific plan or phase post-execution
+argument-hint: "[N]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Edit
+  - Task
+---
+
+<execution_context>
+@~/.claude/workflows/add-tests.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship add-tests workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/add-todo.md

@@ -0,0 +1,21 @@
+---
+name: learnship:add-todo
+description: Capture a todo/idea mid-session without interrupting flow
+argument-hint: "[description]"
+allowed-tools:
+  - Read
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/add-todo.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship add-todo workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/audit-milestone.md

@@ -0,0 +1,21 @@
+---
+name: learnship:audit-milestone
+description: Verify milestone met its definition of done — requirement coverage, integration check, stub detection
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/audit-milestone.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship audit-milestone workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/check-todos.md

@@ -0,0 +1,22 @@
+---
+name: learnship:check-todos
+description: Review and act on all pending todos captured with add-todo
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/check-todos.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship check-todos workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/cleanup.md

@@ -0,0 +1,22 @@
+---
+name: learnship:cleanup
+description: Archive completed milestone phase directories to keep .planning/phases/ clean
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/cleanup.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship cleanup workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/complete-milestone.md

@@ -0,0 +1,22 @@
+---
+name: learnship:complete-milestone
+description: Archive a completed milestone, tag the release, and prepare for the next version
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/complete-milestone.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship complete-milestone workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/debug.md

@@ -0,0 +1,27 @@
+---
+name: learnship:debug
+description: Systematic debugging with persistent state — triage, diagnose root cause, plan fix, execute
+argument-hint: "[description]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/debug.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship debug workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/decision-log.md

@@ -0,0 +1,22 @@
+---
+name: learnship:decision-log
+description: Capture an architectural or scope decision with its context, alternatives, and rationale into DECISIONS.md
+argument-hint: "[description]"
+allowed-tools:
+  - Read
+  - Write
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/decision-log.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship decision-log workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/diagnose-issues.md

@@ -0,0 +1,23 @@
+---
+name: learnship:diagnose-issues
+description: Batch-diagnose multiple UAT issues after verify-work — groups by root cause, proposes fix plan
+argument-hint: "[N]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+---
+
+<execution_context>
+@~/.claude/workflows/diagnose-issues.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship diagnose-issues workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/discovery-phase.md

@@ -0,0 +1,24 @@
+---
+name: learnship:discovery-phase
+description: Structured codebase discovery before working on an unfamiliar area — reads code, maps dependencies, surfaces risks
+argument-hint: "[N]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+---
+
+<execution_context>
+@~/.claude/workflows/discovery-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship discovery-phase workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/discuss-milestone.md

@@ -0,0 +1,23 @@
+---
+name: learnship:discuss-milestone
+description: Capture milestone-level goals, constraints, and anti-goals before new-milestone starts
+argument-hint: "[version]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/discuss-milestone.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship discuss-milestone workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/discuss-phase.md

@@ -0,0 +1,23 @@
+---
+name: learnship:discuss-phase
+description: Capture implementation decisions for a phase before planning starts
+argument-hint: "[N]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/discuss-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship discuss-phase workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/execute-phase.md

@@ -0,0 +1,27 @@
+---
+name: learnship:execute-phase
+description: Execute all plans in a phase with wave-based ordered execution, spawning subagents per plan where supported
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/execute-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship execute-phase workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/execute-plan.md

@@ -0,0 +1,26 @@
+---
+name: learnship:execute-plan
+description: Run a single PLAN.md file in isolation — useful for re-running a failed plan
+argument-hint: "<phase-number> <plan-id>"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Task
+---
+
+<execution_context>
+@~/.claude/workflows/execute-plan.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship execute-plan workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/health.md

@@ -0,0 +1,20 @@
+---
+name: learnship:health
+description: Project health check — stale files, uncommitted changes, missing artifacts, config drift
+allowed-tools:
+  - Read
+  - Bash
+---
+
+<execution_context>
+@~/.claude/workflows/health.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship health workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/help.md

@@ -0,0 +1,19 @@
+---
+name: learnship:help
+description: Show all available learnship workflows with descriptions and when to use them
+allowed-tools:
+  - Read
+---
+
+<execution_context>
+@~/.claude/workflows/help.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship help workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/insert-phase.md

@@ -0,0 +1,22 @@
+---
+name: learnship:insert-phase
+description: Insert a new phase between existing phases for urgent work discovered mid-milestone
+argument-hint: "[N] [description]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/insert-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship insert-phase workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/knowledge-base.md

@@ -0,0 +1,21 @@
+---
+name: learnship:knowledge-base
+description: Aggregate key learnings and decisions across all sessions into a searchable KNOWLEDGE.md
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+---
+
+<execution_context>
+@~/.claude/workflows/knowledge-base.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship knowledge-base workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/list-phase-assumptions.md

@@ -0,0 +1,21 @@
+---
+name: learnship:list-phase-assumptions
+description: Surface the intended approach for a phase before planning starts — validate direction early
+argument-hint: "[N]"
+allowed-tools:
+  - Read
+  - Bash
+---
+
+<execution_context>
+@~/.claude/workflows/list-phase-assumptions.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship list-phase-assumptions workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/ls.md

@@ -0,0 +1,20 @@
+---
+name: learnship:ls
+description: Show project status, next step, and offer to run it — start every session here
+allowed-tools:
+  - Read
+  - Bash
+---
+
+<execution_context>
+@~/.claude/workflows/ls.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship ls workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/map-codebase.md

@@ -0,0 +1,23 @@
+---
+name: learnship:map-codebase
+description: Analyze an existing codebase and produce structured reference docs before starting a new project on top of it
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+---
+
+<execution_context>
+@~/.claude/workflows/map-codebase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship map-codebase workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/milestone-retrospective.md

@@ -0,0 +1,21 @@
+---
+name: learnship:milestone-retrospective
+description: Structured learning retrospective at end of milestone — 5 questions, produces RETROSPECTIVE.md
+allowed-tools:
+  - Read
+  - Write
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/milestone-retrospective.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship milestone-retrospective workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/new-milestone.md

@@ -0,0 +1,23 @@
+---
+name: learnship:new-milestone
+description: Start a new milestone cycle on an existing project after a prior milestone is complete
+argument-hint: "[name]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/new-milestone.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship new-milestone workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/new-project.md

@@ -0,0 +1,24 @@
+---
+name: learnship:new-project
+description: Initialize a new project — questioning → research → requirements → roadmap
+argument-hint: "[--auto]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Task
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/new-project.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship new-project workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>

package/commands/learnship/next.md

@@ -0,0 +1,22 @@
+---
+name: learnship:next
+description: Auto-pilot — reads project state and runs the correct next workflow automatically
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+---
+
+<execution_context>
+@~/.claude/workflows/next.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS
+</context>
+
+<process>
+Execute the learnship next workflow end-to-end.
+Preserve all workflow gates, validations, checkpoints, and routing.
+</process>