learnship 1.9.0

package/learnship/workflows/execute-phase.md

@@ -0,0 +1,345 @@
+---
+description: Execute all plans in a phase using wave-based ordered execution — spawns subagents per plan where the platform supports it
+---
+
+# Execute Phase
+
+Execute all plans in a phase. Plans run in waves — ordered by dependencies. On platforms with subagent support (Claude Code, OpenCode, Codex), plans within a wave are dispatched to dedicated executor agents. On all other platforms, plans execute sequentially.
+
+**Usage:** `execute-phase [N]`
+
+**Core principle:** Orchestrate, don't implement directly. Describe each plan's objective clearly, execute each plan in sequence (or in parallel via subagents), collect results.
+
+> **Platform note:** This workflow detects whether subagent spawning is available by reading `parallelization` from `.planning/config.json`. Set `"parallelization": true` to enable parallel agent spawning on supported platforms. Defaults to `false` (sequential — always safe).
+
+## Step 1: Initialize
+
+Read the phase directory:
+```bash
+ls .planning/phases/ | grep "^[0-9]" | sort
+```
+
+Find the phase matching `[N]`. If not found, stop and list available phases.
+
+Read all PLAN.md files in the phase directory:
+```bash
+ls ".planning/phases/[padded_phase]-[phase_slug]/"*-PLAN.md 2>/dev/null
+```
+
+If no plans found: stop — run `plan-phase [N]` first.
+
+Read `.planning/STATE.md` for project context.
+Read `.planning/config.json` for settings.
+
+## Step 2: Discover and Group Plans
+
+Read each PLAN.md's frontmatter to extract:
+- `wave` — which wave this plan belongs to
+- `depends_on` — which plans must complete before this one
+- `autonomous` — whether this plan requires human checkpoints
+- `objective` — what this plan builds
+
+Group plans into waves based on `wave` and `depends_on` values. Plans in the same wave have no cross-dependencies and can be executed in any order.
+
+Report the execution plan:
+```
+## Execution Plan
+
+**Phase [X]: [Name]** — [N] plans across [M] waves
+
+| Wave | Plans | What it builds |
+|------|-------|----------------|
+| 1    | 01, 02 | [objectives from plan frontmatter] |
+| 2    | 03     | [objective] |
+```
+
+## Step 2b: UI Detection
+
+Before executing, scan all PLAN.md files for UI/frontend work:
+
+Look for any of these signals in plan objectives, task descriptions, or file paths:
+- UI keywords: `component`, `page`, `layout`, `form`, `modal`, `nav`, `dashboard`, `landing`, `design`, `style`, `css`, `tailwind`, `theme`, `color`, `typography`, `animation`, `responsive`
+- Frontend file patterns: `.tsx`, `.jsx`, `.vue`, `.svelte`, `styles/`, `components/`, `pages/`, `app/`
+
+**If UI work is detected:**
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► UI PHASE DETECTED — applying impeccable standards
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Activate `@impeccable frontend-design` as your design foundation for this entire phase. This means:
+
+- **Typography:** Avoid overused fonts (Inter, Roboto, Arial). Use a modular type scale with clear visual hierarchy.
+- **Color:** Avoid the AI palette (cyan-on-dark, purple-to-blue gradients, neon on dark). Tint neutrals toward the brand hue. No pure black (#000) or pure white (#fff).
+- **Layout:** Create rhythm through varied spacing. Not everything needs a card. Never nest cards inside cards.
+- **Components:** Avoid large rounded icons above every heading. Resist generic "AI-built" patterns.
+- **Differentiation:** Every UI phase must have one intentional, memorable design decision — commit to it.
+
+Check if `@impeccable teach-impeccable` has been run for this project (look for a `.planning/impeccable-context.md` or references to impeccable in DECISIONS.md). If not, add a note at the end of execution suggesting it be run before the next UI phase.
+
+Carry these principles through every task in every wave of this phase.
+
+## Step 3: Execute Waves
+
+Read `parallelization` from `.planning/config.json` (defaults to `false`).
+
+For each wave, in sequence:
+
+### Before each wave
+
+Describe what's being built — read each plan's `<objective>`:
+
+```
+---
+## Wave [N]
+
+**Plan [ID]: [Name]**
+[2-3 sentences: what this builds, technical approach, why it matters for the overall phase]
+
+Executing [count] plan(s)...
+---
+```
+
+### Execute the plans
+
+**If `parallelization` is `true` (subagent mode — Claude Code, OpenCode, Codex):**
+
+For each plan in the wave, spawn a dedicated executor subagent. Pass paths only — each executor reads files itself with a fresh context budget.
+
+```
+Task(
+  subagent_type="learnship-executor",
+  prompt="
+    <objective>
+    Execute plan [plan_id] of phase [phase_number]-[phase_name].
+    Commit each task atomically. Create SUMMARY.md. Update STATE.md and ROADMAP.md.
+    </objective>
+
+    <files_to_read>
+    Read these files at execution start using the Read tool:
+    - [phase_dir]/[plan_file] (Plan)
+    - .planning/STATE.md (State)
+    - .planning/config.json (Config, if exists)
+    - ./AGENTS.md or ./CLAUDE.md or ./GEMINI.md (Project context, whichever exists)
+    </files_to_read>
+
+    <success_criteria>
+    - [ ] All tasks executed
+    - [ ] Each task committed individually
+    - [ ] SUMMARY.md created in plan directory
+    - [ ] STATE.md updated
+    </success_criteria>
+  "
+)
+```
+
+Spawn all plans in the wave before waiting. Wait for all agents to complete, then proceed to spot-checks.
+
+**If `parallelization` is `false` (sequential mode — Windsurf, Gemini CLI, or user preference):**
+
+For each plan in the wave, using `@./agents/executor.md` as your execution persona:
+
+Read the full plan file. Execute each task in sequence:
+1. Read the task's `<files>`, `<action>`, `<verify>`, and `<done>` fields
+2. Implement exactly what the action describes
+3. Verify using the verify criteria
+4. Commit atomically after each task:
+
+```bash
+git add [files modified]
+git commit -m "[type]([phase]-[plan]): [task description]"
+```
+
+Execute plans in the wave sequentially. Same-wave plans are independent so order within the wave doesn't matter.
+
+### After each wave
+
+Spot-check completion for each plan:
+- Does the SUMMARY.md exist?
+- Do the key created/modified files exist on disk?
+- Does git log show commits for this plan?
+
+If spot-check fails: report which plan failed, ask "Retry plan?" or "Continue with remaining waves?"
+
+Report wave completion:
+```
+---
+## Wave [N] Complete
+
+**[Plan ID]: [Plan Name]**
+[What was built — from SUMMARY.md]
+[Notable deviations, if any]
+
+[If more waves: what this enables for next wave]
+---
+```
+
+### Checkpoint plans (`autonomous: false`)
+
+When a plan requires human verification before continuing:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: Human Action Required                           ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Plan [ID]: [Name]**
+Progress: [N] of [M] tasks complete
+
+[What needs to be done / verified by the human]
+
+→ Reply "done" when complete, or describe any issues found
+```
+
+Wait for user response before continuing.
+
+## Step 4: Write SUMMARY.md per Plan
+
+After each plan completes, write `[plan_file_base]-SUMMARY.md` in the same directory:
+
+```markdown
+# Plan [ID] Summary
+
+**Completed:** [date]
+
+## What was built
+[2-4 sentences describing what was implemented]
+
+## Key files
+- [file]: [what it does]
+
+## Decisions made
+- [Any implementation choices made during execution]
+
+## Notes for downstream
+- [Anything the next plan or phase should know]
+```
+
+## Step 5: Aggregate Results
+
+After all waves complete:
+
+```
+## Phase [X]: [Name] — Execution Complete
+
+**Waves:** [N] | **Plans:** [M] complete
+
+| Wave | Plans | Status |
+|------|-------|--------|
+| 1    | 01, 02 | ✓ Complete |
+| 2    | 03    | ✓ Complete |
+
+### Summary
+[Brief description of what was built across all plans]
+```
+
+## Step 6: Verify Phase Goal
+
+Read `workflow.verifier` from `.planning/config.json`.
+
+**If verifier is enabled:**
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► VERIFYING PHASE GOAL
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Using `@./agents/verifier.md` as your verification persona, check:
+- Do the `must_haves` from each plan's frontmatter match reality in the codebase?
+- Are all requirement IDs for this phase accounted for?
+- Do files exist, have substance, and export what they claim?
+- Are the key integration links wired correctly?
+
+Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-VERIFICATION.md` with status: `passed`, `human_needed`, or `gaps_found`.
+
+**If `human_needed`:**
+```
+## ✓ Phase [X]: [Name] — Human Verification Required
+
+All automated checks passed. [N] items need human testing:
+
+[List of items requiring manual verification]
+
+→ Reply "approved" to continue, or describe any issues found
+```
+
+**If `gaps_found`:**
+```
+## ⚠ Phase [X]: [Name] — Gaps Found
+
+**Score:** [N]/[M] must-haves verified
+
+### What's Missing
+[Gap summaries]
+
+▶ Next: plan-phase [X] --gaps
+```
+
+If gaps found, stop here. User should run `plan-phase [X]` with gaps flag to create fix plans.
+
+## Step 7: Update Roadmap
+
+Mark phase complete in ROADMAP.md (update status to `✓ Complete` with date).
+Update STATE.md to point to next phase.
+Update REQUIREMENTS.md traceability section.
+
+```bash
+git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+git commit -m "docs(phase-[X]): complete phase execution"
+```
+
+## Step 7b: Update AGENTS.md
+
+If `AGENTS.md` exists at the project root, update the `## Current Phase` block to reflect execution complete and the next phase:
+
+```markdown
+## Current Phase
+
+**Milestone:** [VERSION from STATE.md]
+**Phase:** [X] — [Phase Name] ✓ complete → Phase [X+1] — [Next Phase Name]
+**Status:** verifying
+**Last updated:** [today's date]
+```
+
+Also append any newly created key files or modules to the `## Project Structure` tree if significant new directories were created during this phase.
+
+```bash
+git add AGENTS.md
+git commit -m "docs: update AGENTS.md — phase [X] complete"
+```
+
+## Step 8: Done
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► PHASE [X] COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase [X]: [Name]** — all plans complete, goals verified.
+
+▶ Next: verify-work [X]  (manual UAT)
+   Then: discuss-phase [X+1] → plan-phase [X+1]
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer all three — pick the one that fits:
+
+> 💡 **Learning moment:** Phase [X] is done. Three ways to make this stick:
+>
+> `@agentic-learning reflect` — Structured 3-part reflection: what was built, what was the goal, what gaps remain. Takes 5 minutes, pays off for weeks.
+>
+> `@agentic-learning quiz [phase topic]` — Active recall on what was just implemented. Surfaces gaps in understanding before they become bugs in the next phase.
+>
+> `@agentic-learning interleave [phase topic]` — Mix this phase's concepts with older ones to strengthen long-term retention. Especially useful if this phase touched a domain you've worked in before.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning reflect` · `@agentic-learning quiz [topic]` · `@agentic-learning interleave [topic]` — pick one to consolidate this phase."*

package/learnship/workflows/execute-plan.md

@@ -0,0 +1,149 @@
+---
+description: Run a single PLAN.md file in isolation — useful for re-running a failed plan without re-executing the whole phase
+---
+
+# Execute Plan
+
+Execute a single PLAN.md file in isolation. Useful when one plan in a phase failed, when you want to re-run a specific plan after a fix, or when testing a plan independently before running the full phase.
+
+**Usage:** `execute-plan [phase] [plan-id]` — e.g., `execute-plan 3 02`
+
+## Step 1: Locate the Plan
+
+Find the phase directory:
+```bash
+ls .planning/phases/ | grep -E "^0*[phase]-" | head -1
+PHASE_DIR=".planning/phases/[matched]"
+```
+
+Find the specific plan file:
+```bash
+ls "$PHASE_DIR"/*-[plan-id]-PLAN.md 2>/dev/null
+```
+
+If not found, list available plans:
+```bash
+ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
+```
+
+If still not found: stop — "No plan file found. Check phase and plan ID."
+
+## Step 2: Check for Existing Summary
+
+```bash
+ls "${PLAN_FILE%-PLAN.md}-SUMMARY.md" 2>/dev/null
+```
+
+If SUMMARY.md already exists:
+```
+Plan [phase]-[plan-id] already has a SUMMARY.md — it appears to have been executed.
+
+Options:
+1. Re-execute anyway (overwrites SUMMARY.md)
+2. View the existing summary
+3. Cancel
+```
+
+Wait for choice.
+
+## Step 3: Load Context
+
+Read the full plan file. Read project context:
+```bash
+cat .planning/STATE.md
+cat .planning/ROADMAP.md
+```
+
+Read any existing SUMMARY.md files from other plans in the same phase — they contain important context about what was already built.
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► EXECUTE PLAN [phase]-[plan-id]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Plan: [plan file name]
+Objective: [from plan frontmatter]
+Wave: [wave number]
+Depends on: [depends_on from frontmatter, or "none"]
+```
+
+## Step 4: Check Dependencies
+
+If the plan has `depends_on` entries in its frontmatter, check that those plans have SUMMARY.md files:
+
+```bash
+for dep in [depends_on list]; do
+  ls "$PHASE_DIR"/*${dep}*-SUMMARY.md 2>/dev/null || echo "MISSING: $dep"
+done
+```
+
+If any dependency is missing:
+```
+⚠️  This plan depends on [plan-id] which has not been executed yet.
+
+Options:
+1. Execute [plan-id] first (recommended)
+2. Proceed anyway (may fail if dependent files don't exist)
+```
+
+## Step 5: Execute
+
+Using `@./agents/executor.md` as execution persona, execute each task in the plan sequentially:
+
+1. Read the task's `<files>`, `<action>`, `<verify>`, and `<done>` fields
+2. Implement exactly what the action describes
+3. Verify using the verify criteria
+4. Commit atomically after each task:
+
+```bash
+git add [files modified]
+git commit -m "[type]([phase]-[plan-id]): [task description]"
+```
+
+For checkpoint plans (`autonomous: false`), pause for human verification:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  CHECKPOINT: Human Action Required                           ║
+╚══════════════════════════════════════════════════════════════╝
+
+[What needs to be done / verified]
+
+→ Reply "done" when complete, or describe any issues found
+```
+
+## Step 6: Write SUMMARY.md
+
+Write `${PLAN_FILE%-PLAN.md}-SUMMARY.md`:
+
+```markdown
+# Plan [plan-id] Summary
+
+**Completed:** [date]
+**Executed via:** execute-plan (isolated run)
+
+## What was built
+[2-4 sentences]
+
+## Key files
+- [file]: [what it does]
+
+## Decisions made
+- [Any implementation choices]
+
+## Notes for downstream
+- [Anything the next plan or phase should know]
+```
+
+## Step 7: Report
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► PLAN [phase]-[plan-id] COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[Summary of what was built]
+
+▶ If this was the last missing plan: execute-phase [phase] will skip already-done plans
+  and run the verifier to check the full phase goal.
+```

package/learnship/workflows/health.md

@@ -0,0 +1,171 @@
+---
+description: Project health check — stale files, uncommitted changes, missing artifacts, config drift
+---
+
+# Health
+
+Validate `.planning/` directory integrity and report actionable issues. Optionally repairs auto-fixable problems.
+
+**Usage:** `health` or `health --repair`
+
+## Step 1: Parse Arguments
+
+Check if `--repair` flag is present.
+
+## Step 2: Check Project Exists
+
+```bash
+test -d .planning && echo "OK" || echo "MISSING"
+```
+
+If `.planning/` doesn't exist:
+```
+No .planning/ directory found.
+
+This project hasn't been initialized. Run new-project to start.
+```
+Stop.
+
+## Step 3: Run Health Checks
+
+Run the following checks and classify each as error, warning, or info:
+
+### Required Files
+```bash
+test -f .planning/PROJECT.md   || echo "E002: PROJECT.md not found"
+test -f .planning/ROADMAP.md   || echo "E003: ROADMAP.md not found"
+test -f .planning/STATE.md     || echo "E004: STATE.md not found (repairable)"
+test -f .planning/config.json  || echo "W003: config.json not found (repairable)"
+```
+
+### Config Validity
+```bash
+cat .planning/config.json | python3 -c "import sys,json; json.load(sys.stdin)" 2>&1 || echo "E005: config.json parse error (repairable)"
+```
+
+### State / Roadmap Consistency
+```bash
+# Check if STATE.md references a phase that exists in ROADMAP.md
+CURRENT_PHASE=$(grep -E "^Phase:" .planning/STATE.md 2>/dev/null | head -1 | grep -oE "[0-9]+")
+if [ -n "$CURRENT_PHASE" ]; then
+  grep -q "Phase ${CURRENT_PHASE}:" .planning/ROADMAP.md || echo "W002: STATE.md references phase ${CURRENT_PHASE} not found in roadmap (repairable)"
+fi
+```
+
+### Phase Directory Checks
+```bash
+# Phases in ROADMAP but no directory
+grep -oE "Phase [0-9]+:" .planning/ROADMAP.md | while read phase; do
+  num=$(echo "$phase" | grep -oE "[0-9]+")
+  padded=$(printf "%02d" $num)
+  ls .planning/phases/${padded}-* 2>/dev/null | head -1 || echo "W006: Phase ${num} in roadmap but no directory"
+done
+
+# Phase directories not in ROADMAP
+for dir in .planning/phases/*/; do
+  slug=$(basename "$dir" | sed 's/^[0-9]*-//')
+  grep -q "$slug" .planning/ROADMAP.md || echo "W007: Directory $(basename $dir) not in roadmap"
+done
+```
+
+### Plans Without Summaries
+```bash
+for plan in .planning/phases/*/*-PLAN.md; do
+  summary="${plan%-PLAN.md}-SUMMARY.md"
+  test -f "$summary" || echo "I001: $(basename $plan) has no SUMMARY (may be in progress)"
+done
+```
+
+### Uncommitted Changes
+```bash
+git status --short .planning/ 2>/dev/null | head -10
+```
+
+### Config Fields
+```bash
+# Check for required config keys
+python3 -c "
+import json
+cfg = json.load(open('.planning/config.json'))
+missing = []
+for key in ['mode', 'granularity', 'model_profile', 'learning_mode']:
+    if key not in cfg:
+        missing.append(key)
+if missing:
+    print('W004: config.json missing fields: ' + ', '.join(missing))
+" 2>/dev/null
+```
+
+## Step 4: Format Output
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► HEALTH CHECK
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Status: HEALTHY | DEGRADED | BROKEN
+Errors: [N]   Warnings: [N]   Info: [N]
+```
+
+**Errors** (must fix):
+```
+[E002] PROJECT.md not found
+  Fix: Run new-project to initialize
+
+[E005] config.json parse error
+  Fix: Run health --repair to reset to defaults
+```
+
+**Warnings** (should fix):
+```
+[W002] STATE.md references phase 5, but only phases 1-3 exist in roadmap
+  Fix: Run health --repair to regenerate STATE.md
+
+[W006] Phase 4 in roadmap but no directory
+  Fix: Create .planning/phases/04-[slug]/ manually
+```
+
+**Info** (no action needed):
+```
+[I001] 02-auth/02-01-PLAN.md has no SUMMARY.md
+  Note: May be in progress
+```
+
+**If uncommitted .planning/ changes:**
+```
+Uncommitted changes in .planning/:
+  M .planning/STATE.md
+  ? .planning/phases/03-api/03-01-PLAN.md
+
+Consider: git add .planning/ && git commit -m "docs: update planning artifacts"
+```
+
+**Footer if repairable issues and --repair not used:**
+```
+[N] issue(s) can be auto-repaired. Run: health --repair
+```
+
+## Step 5: Repair (if --repair flag)
+
+Run repairs for each repairable issue found:
+
+| Issue | Repair action |
+|-------|--------------|
+| `STATE.md not found` | Generate from ROADMAP.md structure with current phase from roadmap |
+| `config.json not found` | Create with defaults from `templates/config.json` |
+| `config.json parse error` | Reset to defaults (warn: loses custom settings) |
+| `config.json missing fields` | Add missing fields with default values |
+
+For each repair:
+```bash
+# Example: regenerate STATE.md
+cp templates/state.md .planning/STATE.md
+# Then fill in project name from PROJECT.md and current phase from ROADMAP.md
+```
+
+After repairs, re-run the health checks and report final status.
+
+**Not repairable:**
+- `PROJECT.md`, `ROADMAP.md` content (too risky to auto-generate)
+- Phase directory renaming
+- Orphaned plan cleanup