learnship 1.9.20 → 1.9.22

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.20",
+  "version": "1.9.22",
   "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.20",
+  "version": "1.9.22",
   "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):**
 

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/cursor-rules/learnship.mdc

@@ -5,6 +5,54 @@ description: Activate learnship agentic engineering workflows — structured pha
 
 You are working inside a project that uses **learnship** — a multi-platform agentic engineering system for building real products with spec-driven workflows, integrated learning, and impeccable design.
 
+## Mandatory Gate — No Project, No Work
+
+**Before responding to any user message, check:**
+
+```
+Does .planning/PROJECT.md exist?
+```
+
+- **No** → The project has not been initialized. **Do NOT implement anything.** Tell the user:
+
+  > "This project hasn't been set up with learnship yet. Run `/new-project` to initialize it — that takes about 10 minutes and sets up the spec, roadmap, and phase structure before any code gets written.
+  >
+  > This is not optional: working without a spec means building the wrong thing. `/new-project` first."
+
+  Then stop. Do not offer to help with the task. Do not say "but I can also just fix it directly." Wait for the user to run `/new-project`.
+
+- **Yes** → Continue normally. Apply the workflow routing logic.
+
+**This gate applies to ALL messages** — bug reports, feature requests, "quick fixes", detailed specs, anything. The only exception: if the user is currently mid-ceremony in `/new-project` (i.e., they are answering your questions), their messages are workflow answers, not tasks to route.
+
+## New Project Ceremony — /new-project
+
+When the user runs `/new-project`, execute these **9 mandatory steps in order**. Do not skip, defer, or abbreviate any step.
+
+**Checklist (check off as you go):**
+- [ ] Step 1 — Setup & codebase check
+- [ ] Step 1b — Existing codebase scan (if applicable)
+- [ ] Step 2 — Configuration questions
+- [ ] Step 3 — Deep questioning (4 exchanges minimum)
+- [ ] Step 4 — Write and confirm PROJECT.md
+- [ ] Step 5 — Research decision (ask user, wait for answer)
+- [ ] Step 6 — Define requirements (interactive)
+- [ ] Step 7 — Create and approve roadmap
+- [ ] Step 8 — Generate AGENTS.md ← **mandatory, never skip**
+- [ ] Step 9 — Done banner + next step
+
+**Critical gates:**
+
+1. **Exchange 1 answer does NOT skip Exchanges 2–4.** No matter how detailed the user's answer to "What do you want to build?" — it is raw material for follow-ups, not a replacement. You MUST still ask Exchanges 2, 3, and 4.
+
+2. **After Step 4 (PROJECT.md confirmed):** Do NOT write REQUIREMENTS.md or ROADMAP.md. First ask: "Before I write the requirements — do you want me to research the domain ecosystem first?" Wait for reply.
+
+3. **After Step 7 (roadmap approved):** Do NOT display the done banner or suggest next steps. Generate AGENTS.md (Step 8) first.
+
+4. **Step 9 next step is `/discuss-phase 1` — not `/plan-phase`.** The phase loop is: `discuss-phase` → `plan-phase` → `execute-phase` → `verify-work`. `discuss-phase` is mandatory first — it writes the CONTEXT.md that planning depends on.
+
+**Routing protocol suspended during `/new-project`.** Every user message while the ceremony is in progress is an answer to a workflow question, not a task to route.
+
 ## Core Workflows
 
 Suggest the appropriate workflow slash command when relevant:

package/gemini-extension.json

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

package/learnship/references/planning-config.md

@@ -40,7 +40,7 @@ Configuration options for `.planning/` directory behavior.
 
 ```bash
 # Read commit_docs from config.json
-COMMIT_DOCS=$(python3 -c "import json; c=json.load(open('.planning/config.json')); print(c.get('planning',{}).get('commit_docs','true'))" 2>/dev/null || echo 'true')
+COMMIT_DOCS=$(node -e "try{const c=JSON.parse(require('fs').readFileSync('.planning/config.json','utf8'));process.stdout.write(String((c.planning||{}).commit_docs??'true'));}catch(e){process.stdout.write('true');}" 2>/dev/null || echo 'true')
 ```
 
 **Auto-detection:** If `.planning/` is gitignored, treat `commit_docs` as `false` regardless of config.json. This prevents git errors.
@@ -139,7 +139,7 @@ To use uncommitted mode:
 
 Read config directly:
 ```bash
-python3 -c "import json; c=json.load(open('.planning/config.json')); g=c.get('git',{}); print(g.get('branching_strategy','none'), g.get('phase_branch_template','phase-{phase}-{slug}'), g.get('milestone_branch_template','{milestone}-{slug}'))"
+node -e "const c=JSON.parse(require('fs').readFileSync('.planning/config.json','utf8')),g=c.git||{};console.log(g.branching_strategy||'none',g.phase_branch_template||'phase-{phase}-{slug}',g.milestone_branch_template||'{milestone}-{slug}')"
 ```
 
 **Branch creation:**

package/learnship/workflows/add-phase.md

@@ -12,7 +12,7 @@ Append a new integer phase to the end of the current milestone. Use when scope g
 
 Check that a roadmap exists:
 ```bash
-python3 -c "import os; print('OK' if os.path.exists('.planning/ROADMAP.md') else 'MISSING')"
+node -e "const fs=require('fs'); console.log(fs.existsSync('.planning/ROADMAP.md') ? 'OK' : 'MISSING')"
 ```
 
 If missing: stop — run `new-project` first.
@@ -24,11 +24,13 @@ If no description was provided as an argument, ask: "What does this new phase de
 Read `.planning/ROADMAP.md` and find the highest existing integer phase number:
 ```bash
 grep -E "^## Phase [0-9]+" .planning/ROADMAP.md | tail -1
+# PowerShell: Select-String -Path .planning/ROADMAP.md -Pattern '^## Phase \d+' | Select-Object -Last 1
 ```
 
 Also scan the phases directory for any directories that may not be in the roadmap:
 ```bash
 ls .planning/phases/ 2>/dev/null | grep -E "^[0-9]+" | sort -n | tail -3
+# PowerShell: Get-ChildItem .planning/phases/ -ErrorAction SilentlyContinue | Where-Object { $_.Name -match '^[0-9]+' } | Sort-Object Name | Select-Object -Last 3
 ```
 
 Set `NEXT_NUM` = highest found + 1. Pad to 2 digits (01, 02, ..., 10, 11, ...).
@@ -38,7 +40,8 @@ Generate a slug from the description (lowercase, hyphens, max 40 chars).
 ## Step 3: Create Phase Directory
 
 ```bash
-mkdir -p ".planning/phases/${NEXT_NUM}-${SLUG}"
+node -e "require('fs').mkdirSync('.planning/phases/${NEXT_NUM}-${SLUG}',{recursive:true})"
+# PowerShell: New-Item -ItemType Directory -Force -Path ".planning/phases/${NEXT_NUM}-${SLUG}"
 ```
 
 ## Step 4: Update ROADMAP.md

package/learnship/workflows/add-tests.md

@@ -20,6 +20,7 @@ Example: add-tests 3 focus on edge cases in the pricing module
 Find the phase directory:
 ```bash
 ls .planning/phases/ | grep -E "^0*[N]-" | head -1
+# PowerShell: Get-ChildItem .planning/phases/ | Where-Object { $_.Name -match "^0*[N]-" } | Select-Object -First 1 -ExpandProperty Name
 PHASE_DIR=".planning/phases/[matched]"
 ```
 
@@ -45,6 +46,7 @@ Extract the list of files modified by the phase from SUMMARY.md.
 find . \( -name "jest.config.*" -o -name "vitest.config.*" -o -name "pytest.ini" -o -name "pyproject.toml" -o -name "playwright.config.*" \) -not -path "*/node_modules/*" 2>/dev/null
 
 find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*.py" \) -not -path "*/node_modules/*" 2>/dev/null | head -10
+# PowerShell: Get-ChildItem -Recurse | Where-Object { $_.Name -match '\.test\.|spec\.|^test_.*\.py' -and $_.FullName -notmatch 'node_modules' } | Select-Object -First 10
 ```
 
 Identify: test framework, E2E framework (if any), how to run tests, existing test file patterns and locations.

package/learnship/workflows/add-todo.md

@@ -11,7 +11,7 @@ Capture an idea, task, or issue that surfaces during a session. Fast "thought
 ## Step 1: Ensure Directories Exist
 
 ```bash
-mkdir -p .planning/todos/pending .planning/todos/done
+node -e "require('fs').mkdirSync('.planning/todos/pending',{recursive:true});require('fs').mkdirSync('.planning/todos/done',{recursive:true})"
 ```
 
 ## Step 2: Extract Content

package/learnship/workflows/audit-milestone.md

@@ -79,6 +79,7 @@ Check:
 
 ```bash
 grep -rn "TODO\|FIXME\|PLACEHOLDER\|return null\|return undefined" src/ --include="*.ts" --include="*.tsx" --include="*.js" 2>/dev/null | grep -v "node_modules\|\.test\." | head -30
+# PowerShell: Select-String -Path src/ -Recurse -Pattern 'TODO|FIXME|PLACEHOLDER|return null|return undefined' -Include '*.ts','*.tsx','*.js' | Where-Object { $_.Path -notmatch 'node_modules|\.test\.' } | Select-Object -First 30
 ```
 
 ## Step 5: Compile Audit Report

package/learnship/workflows/cleanup.md

@@ -80,7 +80,7 @@ Wait for confirmation. If "no": stop.
 For each milestone and its phase directories:
 
 ```bash
-mkdir -p ".planning/milestones/v[X.Y]-phases"
+node -e "require('fs').mkdirSync('.planning/milestones/v[X.Y]-phases',{recursive:true})"
 mv ".planning/phases/[phase-dir]/" ".planning/milestones/v[X.Y]-phases/"
 ```
 

package/learnship/workflows/complete-milestone.md

@@ -47,6 +47,7 @@ Ask for confirmation:
 Read `.planning/STATE.md` and check for existing version tags:
 ```bash
 git tag --list "v*" | sort -V | tail -5
+# PowerShell: git tag --list "v*" | Sort-Object | Select-Object -Last 5
 ```
 
 Propose the next version (e.g., `v1.0`, `v1.1`, `v2.0`). Ask for confirmation or let user specify.
@@ -55,7 +56,7 @@ Propose the next version (e.g., `v1.0`, `v1.1`, `v2.0`). Ask for confirmation or
 
 Create the milestones archive directory:
 ```bash
-mkdir -p .planning/milestones
+node -e "require('fs').mkdirSync('.planning/milestones',{recursive:true})"
 ```
 
 Archive the roadmap for this milestone:

package/learnship/workflows/debug.md

@@ -11,7 +11,7 @@ Systematic debugging workflow: triage → root cause diagnosis → fix planning
 ## Step 1: Create Debug Session
 
 ```bash
-mkdir -p .planning/debug
+node -e "require('fs').mkdirSync('.planning/debug',{recursive:true})"
 DATE=$(date +%Y%m%d-%H%M)
 ```
 
@@ -196,7 +196,7 @@ Update session file:
 
 Move to resolved:
 ```bash
-mkdir -p .planning/debug/resolved
+node -e "require('fs').mkdirSync('.planning/debug/resolved',{recursive:true})"
 mv ".planning/debug/[session-file]" ".planning/debug/resolved/"
 ```
 

package/learnship/workflows/diagnose-issues.md

@@ -15,6 +15,7 @@ Batch-diagnose all open UAT issues after `verify-work`. Groups issues by root ca
 Find the UAT file for the phase:
 ```bash
 ls ".planning/phases/"*[N]*"/"*-UAT.md 2>/dev/null | head -1
+# PowerShell: Get-ChildItem ".planning/phases/" -Recurse -Filter "*-UAT.md" | Where-Object { $_.FullName -match [N] } | Select-Object -First 1
 ```
 
 If no UAT file found: stop — "Run `verify-work [N]` first to log issues."

package/learnship/workflows/discovery-phase.md

@@ -33,13 +33,16 @@ Search for code related to the target area using key terms from the phase goal:
 ```bash
 # Find files mentioning key terms
 grep -rl "[key term 1]" src/ 2>/dev/null | head -15
+# PowerShell: Select-String -Path src/ -Recurse -Pattern "[key term 1]" | Select-Object -ExpandProperty Path -Unique | Select-Object -First 15
 grep -rl "[key term 2]" src/ 2>/dev/null | head -10
+# PowerShell: Select-String -Path src/ -Recurse -Pattern "[key term 2]" | Select-Object -ExpandProperty Path -Unique | Select-Object -First 10
 
 # Find related directories
 find src/ -type d | grep -i "[key term]" 2>/dev/null
 
 # Find entry points
 grep -rn "export\|module.exports\|def " src/ --include="*.ts" --include="*.js" --include="*.py" 2>/dev/null | grep -i "[key term]" | head -20
+# PowerShell: Select-String -Path src/ -Recurse -Pattern 'export|module.exports|def ' | Where-Object { $_.Line -imatch '[key term]' } | Select-Object -First 20
 ```
 
 Read the 5-8 most relevant files. Focus on interfaces, types, exports, and public API — not implementation details.
@@ -51,6 +54,7 @@ For the relevant files, trace what they depend on and what depends on them:
 **Incoming dependencies** (who calls this code):
 ```bash
 grep -rl "import.*[module name]\|require.*[module name]" src/ 2>/dev/null | head -10
+# PowerShell: Select-String -Path src/ -Recurse -Pattern 'import.*[module name]|require.*[module name]' | Select-Object -ExpandProperty Path -Unique | Select-Object -First 10
 ```
 
 **Outgoing dependencies** (what this code calls):
@@ -80,6 +84,7 @@ Look specifically for:
 ```bash
 # Files with most lines of code in the area
 wc -l $(find src/ -name "*.ts" -o -name "*.py" 2>/dev/null | xargs grep -l "[key term]" 2>/dev/null) | sort -n | tail -10
+# PowerShell: Select-String -Path src/ -Recurse -Pattern '[key term]' -Include '*.ts','*.py' | Select-Object -ExpandProperty Path -Unique | ForEach-Object { (Get-Content $_).Count } | Sort-Object | Select-Object -Last 10
 ```
 
 **Test coverage gaps:**
@@ -90,6 +95,7 @@ find . -name "*.test.*" -o -name "test_*.py" | xargs grep -l "[key term]" 2>/dev
 **TODO/FIXME in the area:**
 ```bash
 grep -rn "TODO\|FIXME\|HACK\|XXX" src/ 2>/dev/null | grep -i "[key term]" | head -10
+# PowerShell: Select-String -Path src/ -Recurse -Pattern 'TODO|FIXME|HACK|XXX' | Where-Object { $_.Line -imatch '[key term]' } | Select-Object -First 10
 ```
 
 **Known issues from DECISIONS.md:**

package/learnship/workflows/discuss-milestone.md

@@ -17,6 +17,7 @@ Read what has already shipped:
 cat .planning/PROJECT.md
 cat .planning/STATE.md
 ls .planning/milestones/ 2>/dev/null | sort -V | tail -3
+# PowerShell: Get-ChildItem .planning/milestones/ -ErrorAction SilentlyContinue | Sort-Object Name | Select-Object -Last 3
 ```
 
 Display the last milestone summary so the conversation starts informed:
@@ -29,7 +30,7 @@ Pending todos: [N] items
 
 Check if a MILESTONE-CONTEXT.md already exists:
 ```bash
-python3 -c "import os; print('EXISTS' if os.path.exists('.planning/MILESTONE-CONTEXT.md') else 'MISSING')"
+node -e "const fs=require('fs'); console.log(fs.existsSync('.planning/MILESTONE-CONTEXT.md') ? 'EXISTS' : 'MISSING')"
 ```
 
 If exists: ask "A milestone context file already exists from a prior discussion. Update it or start fresh?"

package/learnship/workflows/discuss-phase.md

@@ -29,6 +29,7 @@ Extract from prior CONTEXT.md files: locked preferences, patterns the user has e
 If `.planning/DECISIONS.md` exists, read it:
 ```bash
 cat .planning/DECISIONS.md 2>/dev/null | head -80
+# PowerShell: Get-Content .planning/DECISIONS.md -ErrorAction SilentlyContinue | Select-Object -First 80
 ```
 
 Note any decisions that constrain or inform this phase's approach. Surface them during discussion rather than re-asking decided questions.
@@ -129,7 +130,7 @@ Track deferred ideas internally.
 
 Find or create the phase directory:
 ```bash
-mkdir -p ".planning/phases/[padded_phase]-[phase_slug]"
+node -e "require('fs').mkdirSync('.planning/phases/[padded_phase]-[phase_slug]',{recursive:true})"
 ```
 
 Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-CONTEXT.md`: