learnship 1.9.0

package/learnship/workflows/plan-milestone-gaps.md

@@ -0,0 +1,160 @@
+---
+description: Create fix phases for all gaps found by audit-milestone
+---
+
+# Plan Milestone Gaps
+
+Create all phases needed to close gaps identified by `audit-milestone`. One workflow creates all fix phases — no need to run `add-phase` per gap.
+
+**Use after:** `audit-milestone` reports `gaps_found`.
+
+## Step 1: Load Audit Results
+
+Find the most recent audit file:
+```bash
+ls -t .planning/*-MILESTONE-AUDIT.md 2>/dev/null | head -1
+```
+
+If no audit file exists or status is `passed`:
+```
+No gaps found. Run audit-milestone first, or all gaps are already closed.
+```
+Stop.
+
+Read the audit file and extract structured gaps:
+- `gaps.requirements` — unsatisfied requirement IDs
+- `gaps.integration` — broken cross-phase connections
+- `gaps.flows` — broken E2E user flows
+- `gaps.stubs` — stub/placeholder locations
+
+## Step 2: Prioritize Gaps
+
+Read `.planning/REQUIREMENTS.md` to get priority for each requirement gap:
+
+| Priority | Treatment |
+|----------|-----------|
+| `must` / required | Always include — blocks milestone |
+| `should` / recommended | Include by default |
+| `nice-to-have` / optional | Ask user: include now or defer to next milestone? |
+
+For integration and flow gaps: infer priority from the affected requirements.
+
+If there are nice-to-have gaps, ask:
+```
+[N] optional gap(s) found. Include in fix phases or defer to next milestone?
+
+- [gap description]
+- [gap description]
+
+Include (recommended) / Defer all / Choose individually
+```
+
+## Step 3: Group Gaps into Phases
+
+Cluster related gaps into logical fix phases:
+
+**Grouping rules:**
+- Same affected source phase → combine into one fix phase
+- Same subsystem (auth, API, UI, data layer) → combine
+- Dependency order: fix broken exports before fixing callers
+- Keep phases focused: 2-4 tasks each
+
+Example:
+```
+Gap: REQ AUTH-02 unsatisfied (session not persisting)
+Gap: Integration Phase 1→3 (auth token not passed to API calls)
+Gap: Flow "User stays logged in" broken
+
+→ Fix Phase: "Wire Auth Session"
+  Tasks: persist session, pass token in API calls, handle expiry
+```
+
+## Step 4: Determine Phase Numbers
+
+Find the highest existing phase number:
+```bash
+ls .planning/phases/ | grep -E "^[0-9]" | sort -V | tail -1
+```
+
+Gap closure phases continue from the highest existing phase + 1.
+
+## Step 5: Present Gap Closure Plan
+
+```
+## Gap Closure Plan
+
+Milestone: [VERSION]
+Gaps to close: [N] requirements, [M] integration, [K] flows
+
+### Proposed Fix Phases
+
+**Phase [N]: [Name]**
+Closes:
+- [REQ-ID]: [description]
+- Integration: [from phase] → [to phase]
+Tasks: [count]
+
+**Phase [N+1]: [Name]**
+Closes:
+- [REQ-ID]: [description]
+Tasks: [count]
+
+---
+
+Create these [X] fix phase(s)? (yes / adjust)
+```
+
+Wait for confirmation.
+
+## Step 6: Update ROADMAP.md
+
+Append each gap closure phase to the current milestone section:
+
+```markdown
+## Phase [N]: [Name] *(gap closure)*
+
+**Goal:** [what user can do after this phase]
+**Closes:** [REQ-IDs and integration gaps being addressed]
+**Status:** [ ] Not started
+**Depends on:** [prior phase]
+```
+
+## Step 7: Update REQUIREMENTS.md
+
+For each unsatisfied requirement being addressed:
+- Update the Phase column to the new gap closure phase number
+- Reset status to `Pending`
+- Change `[x]` back to `[ ]` if it was incorrectly marked complete
+- Update the coverage count at top of REQUIREMENTS.md
+
+## Step 8: Create Phase Directories
+
+```bash
+for each gap closure phase:
+  mkdir -p ".planning/phases/[NN]-[slug]"
+done
+```
+
+## Step 9: Commit
+
+```bash
+git add .planning/ROADMAP.md .planning/REQUIREMENTS.md .planning/phases/
+git commit -m "docs(roadmap): add gap closure phases [N]-[M] for [VERSION] audit"
+```
+
+## Step 10: Present Next Steps
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► GAP CLOSURE PHASES CREATED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phases added: [N] through [M]
+Gaps addressed: [X] requirements, [Y] integration, [Z] flows
+
+▶ Next: plan-phase [N]  (first gap closure phase)
+
+After all gap phases are complete:
+  audit-milestone   — re-audit to verify all gaps closed
+  complete-milestone — archive when audit passes
+```

package/learnship/workflows/plan-phase.md

@@ -0,0 +1,288 @@
+---
+description: Research + create + verify plans for a phase — spawns specialist subagents where supported
+---
+
+# Plan Phase
+
+Create executable plans for a roadmap phase. Default flow: Research → Plan → Verify → Done.
+
+On platforms with subagent support (Claude Code, OpenCode, Codex), each stage spawns a dedicated specialist agent with its own full context budget. On all other platforms, all stages run sequentially in the same context.
+
+**Usage:** `plan-phase [N]` — optionally add `--skip-research` or `--skip-verify`
+
+> **Platform note:** Read `parallelization` from `.planning/config.json`. When `true`, researcher/planner/checker each run as a spawned subagent. When `false` (default), all stages run inline using agent persona files.
+
+## Step 1: Initialize
+
+Read `.planning/ROADMAP.md` and find the requested phase. If no phase number provided, detect the next unplanned phase.
+
+If phase not found: stop and show available phases.
+
+Read config:
+```bash
+cat .planning/config.json
+```
+
+Create the phase directory if it doesn't exist:
+```bash
+mkdir -p ".planning/phases/[padded_phase]-[phase_slug]"
+```
+
+Check what already exists:
+```bash
+ls ".planning/phases/[padded_phase]-[phase_slug]/" 2>/dev/null
+```
+
+## Step 1b: Load Decisions Register
+
+If `.planning/DECISIONS.md` exists, read it:
+```bash
+cat .planning/DECISIONS.md 2>/dev/null
+```
+
+Surface any decisions relevant to this phase — the planner must not contradict active decisions without explicit user instruction.
+
+## Step 2: Load CONTEXT.md
+
+Check if a CONTEXT.md exists for this phase.
+
+**If no CONTEXT.md:**
+Ask: "No CONTEXT.md found for Phase [X]. Plans will use research and requirements only — your design preferences won't be included."
+- **Continue without context** → proceed
+- **Run discuss-phase first** → stop, suggest running `discuss-phase [X]` first
+
+**If CONTEXT.md exists:** Load it and confirm: "Using phase context from: [path]"
+
+## Step 3: Research Phase
+
+**Skip if:** `--skip-research` flag, or `workflow.research` is `false` in config, or RESEARCH.md already exists (unless `--research` flag forces re-research).
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► RESEARCHING PHASE [X]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**If `parallelization` is `true` (subagent mode):**
+
+Spawn a dedicated researcher agent:
+```
+Task(
+  subagent_type="learnship-phase-researcher",
+  prompt="
+    <objective>
+    Research how to implement Phase [phase_number]: [phase_name].
+    Answer: 'What do I need to know to PLAN this phase well?'
+    Write RESEARCH.md to [phase_dir]/[padded_phase]-RESEARCH.md.
+    </objective>
+
+    <files_to_read>
+    - [context_path] (user decisions, if exists)
+    - .planning/REQUIREMENTS.md
+    - .planning/STATE.md
+    </files_to_read>
+  "
+)
+```
+
+Wait for agent to complete, then verify RESEARCH.md was written.
+
+**If `parallelization` is `false` (sequential mode):**
+
+Using `@./agents/researcher.md` as your research persona, investigate how to implement this phase. Read:
+- The CONTEXT.md (user decisions)
+- `.planning/REQUIREMENTS.md` (which requirements this phase covers)
+- `.planning/STATE.md` (project history and decisions)
+- Existing codebase for relevant patterns
+
+Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-RESEARCH.md` with two key sections:
+- **Don't Hand-Roll** — problems with good existing solutions ("Don't build your own JWT — use jose")
+- **Common Pitfalls** — what goes wrong, why, how to avoid it
+
+## Step 4: Check Existing Plans
+
+```bash
+ls ".planning/phases/[padded_phase]-[phase_slug]/"*-PLAN.md 2>/dev/null
+```
+
+If plans already exist, ask: "Phase [X] already has [N] plan(s)."
+- **Add more plans** → continue to planning
+- **View existing** → show plans, then ask
+- **Replan from scratch** → delete existing plans, continue
+
+## Step 5: Create Plans
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► PLANNING PHASE [X]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**If `parallelization` is `true` (subagent mode):**
+
+Spawn a dedicated planner agent:
+```
+Task(
+  subagent_type="learnship-planner",
+  prompt="
+    <objective>
+    Create 2-4 executable PLAN.md files for Phase [phase_number]: [phase_name].
+    Write plans to [phase_dir]/[padded_phase]-NN-PLAN.md.
+    </objective>
+
+    <files_to_read>
+    - .planning/STATE.md
+    - .planning/ROADMAP.md
+    - .planning/REQUIREMENTS.md
+    - [context_path] (if exists)
+    - [research_path] (if exists)
+    - $LEARNSHIP_DIR/templates/plan.md
+    </files_to_read>
+  "
+)
+```
+
+Wait for agent to complete, then verify PLAN.md files were written.
+
+**If `parallelization` is `false` (sequential mode):**
+
+Using `@./agents/planner.md` as your planning persona, read all available context:
+- `.planning/STATE.md`
+- `.planning/ROADMAP.md`
+- `.planning/REQUIREMENTS.md`
+- CONTEXT.md (if exists)
+- RESEARCH.md (if exists)
+
+Create 2-4 PLAN.md files in the phase directory. Each plan:
+- Covers a single logical unit of work executable in one context window
+- Has YAML frontmatter: `wave`, `depends_on`, `files_modified`, `autonomous`
+- Contains tasks in XML format (see `$LEARNSHIP_DIR/templates/plan.md`)
+- Has `must_haves` section with observable verification criteria
+
+**Wave assignment:**
+- Plans with no dependencies → Wave 1 (independent, execute in any order)
+- Plans depending on Wave 1 → Wave 2
+- Plans with cross-plan file conflicts → same wave or sequential
+
+**Name plans:** `[padded_phase]-01-PLAN.md`, `[padded_phase]-02-PLAN.md`, etc.
+
+## Step 6: Verify Plans
+
+**Skip if:** `--skip-verify` flag, or `workflow.plan_check` is `false` in config.
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► VERIFYING PLANS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**If `parallelization` is `true` (subagent mode):**
+
+Spawn a plan-checker agent:
+```
+Task(
+  subagent_type="learnship-plan-checker",
+  prompt="
+    <objective>
+    Verify all PLAN.md files in [phase_dir] for Phase [phase_number]: [phase_name].
+    Check: phase goal coverage, requirement IDs, CONTEXT.md decisions, task completeness, wave correctness.
+    Return: PASS or list of specific issues per plan.
+    </objective>
+
+    <files_to_read>
+    - [phase_dir]/*-PLAN.md (all plans)
+    - .planning/ROADMAP.md
+    - .planning/REQUIREMENTS.md
+    - [context_path] (if exists)
+    </files_to_read>
+  "
+)
+```
+
+If issues returned: revise affected plans, re-spawn checker. Max 3 iterations.
+If still failing after 3 iterations: present issues and ask — **Force proceed** / **Provide guidance and retry** / **Abandon**.
+
+**If `parallelization` is `false` (sequential mode):**
+
+Using `@./agents/verifier.md` as your verification persona, check the plans against:
+- The phase goal from ROADMAP.md
+- All requirement IDs assigned to this phase
+- CONTEXT.md decisions (are they honored?)
+- Task completeness (files, action, verify, done fields)
+- Wave/dependency correctness
+
+**Verification loop (max 3 iterations):**
+
+If issues found:
+1. List the issues clearly
+2. Revise the affected plans to fix them
+3. Re-verify
+4. If still failing after 3 iterations: present remaining issues and ask — **Force proceed** / **Provide guidance and retry** / **Abandon**
+
+If verification passes: proceed.
+
+## Step 7: Commit Plans
+
+```bash
+git add ".planning/phases/[padded_phase]-[phase_slug]/"
+git commit -m "docs([padded_phase]): create phase plans"
+```
+
+## Step 7b: Update AGENTS.md
+
+If `AGENTS.md` exists at the project root, update the `## Current Phase` block:
+
+```markdown
+## Current Phase
+
+**Milestone:** [VERSION from STATE.md]
+**Phase:** [N] — [Phase Name]
+**Status:** planning
+**Last updated:** [today's date]
+```
+
+```bash
+git add AGENTS.md
+git commit -m "docs: update AGENTS.md — planning phase [N]"
+```
+
+## Step 8: Present Status
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► PHASE [X] PLANNED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase [X]: [Name]** — [N] plan(s) in [M] wave(s)
+
+| Wave | Plans | What it builds |
+|------|-------|----------------|
+| 1    | 01, 02 | [objectives] |
+| 2    | 03     | [objective]  |
+
+Research: [Completed | Used existing | Skipped]
+Verification: [Passed | Passed with override | Skipped]
+
+▶ Next: execute-phase [X]
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer based on context:
+
+> 💡 **Learning moment:** Plans are ready. Before you execute, make sure the domain is solid:
+>
+> `@agentic-learning explain-first [phase topic]` — Explain the approach back in your own words before touching code. Gaps in the explanation reveal gaps in the mental model — before they become bugs.
+>
+> `@agentic-learning cognitive-load [topic]` — If the scope feels overwhelming, decompose it into working-memory-sized steps first.
+>
+> `@agentic-learning quiz [phase topic]` — Quick active recall on the domain concepts this phase covers. Especially useful if the research surfaced unfamiliar territory.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning explain-first [topic]` to validate your mental model before executing."*

package/learnship/workflows/progress.md

@@ -0,0 +1,118 @@
+---
+description: Show project progress, current position, and what to do next
+---
+
+# Progress
+
+Check where you are in the project, what's been done, and what comes next.
+
+## Step 1: Check for Planning Structure
+
+```bash
+test -f .planning/PROJECT.md && echo "EXISTS" || echo "MISSING"
+```
+
+If `.planning/` doesn't exist: stop — run `new-project` to initialize.
+
+## Step 2: Load Context
+
+Read the key state files:
+```bash
+cat .planning/STATE.md
+cat .planning/ROADMAP.md
+```
+
+Find the 2-3 most recent SUMMARY.md files:
+```bash
+find .planning -name "*-SUMMARY.md" -type f 2>/dev/null | xargs ls -t 2>/dev/null | head -3
+```
+
+Read each to extract what was recently accomplished (one-liner per plan).
+
+## Step 3: Analyze Phase Status
+
+For the current phase directory, count:
+```bash
+ls ".planning/phases/[current_phase_dir]/"*-PLAN.md 2>/dev/null | wc -l
+ls ".planning/phases/[current_phase_dir]/"*-SUMMARY.md 2>/dev/null | wc -l
+ls ".planning/phases/[current_phase_dir]/"*-UAT.md 2>/dev/null | wc -l
+```
+
+Check for UAT files with gaps (issues found during testing):
+```bash
+grep -l "status: diagnosed" .planning/phases/[current_phase_dir]/*-UAT.md 2>/dev/null
+```
+
+Check for a `.continue-here.md` handoff file:
+```bash
+find .planning/phases -name ".continue-here.md" 2>/dev/null
+```
+
+## Step 4: Report Status
+
+Calculate overall progress: count completed phases / total phases.
+
+Display:
+```
+# [Project Name]
+
+**Progress:** [████████░░] [X]% — Phase [N] of [total]
+
+## Recent Work
+- [Phase, Plan]: [what was accomplished — 1 line]
+- [Phase, Plan]: [what was accomplished — 1 line]
+
+## Current Position
+Phase [N] of [total]: [phase-name]
+Status: [planned | in-progress | complete]
+Context: [✓ CONTEXT.md exists | — not yet]
+
+## Key Decisions
+- [Key decision from STATE.md]
+
+## Blockers / Concerns
+- [Any blockers from STATE.md, or "None"]
+```
+
+## Step 5: Route to Next Action
+
+**Check conditions in order:**
+
+1. **`.continue-here.md` exists** → mid-plan handoff found
+   ```
+   ⚠️  Handoff detected: .planning/phases/[phase]/.continue-here.md
+   ▶ Next: resume-work
+   ```
+
+2. **UAT gaps exist (status: diagnosed)** → fix plans needed
+   ```
+   ⚠️  UAT Gaps Found in Phase [X]
+   ▶ Next: plan-phase [X] (gap closure mode)
+   ```
+
+3. **Plans exist but summaries < plans** → unfinished execution
+   ```
+   ## ▶ Next Up
+   **Phase [X]-[plan]: [Plan Name]** — [objective]
+   ▶ Next: execute-phase [X]
+   ```
+
+4. **Plans = 0** → phase not yet planned
+   - If CONTEXT.md exists: `▶ Next: plan-phase [X]`
+   - If no CONTEXT.md: `▶ Next: discuss-phase [X]` (recommended) or `plan-phase [X]`
+
+5. **Summaries = plans AND plans > 0** → phase complete
+   - If more phases remain: `▶ Next: discuss-phase [X+1]`
+   - If all phases done: `▶ Next: audit-milestone`
+
+After presenting the recommended next step, ask:
+
+```
+▶ Next: [workflow-name] [args if any]
+
+  Run it now? Type "yes" to proceed, or just keep chatting.
+```
+
+If the user responds with "yes", "go", "do it", "run it", or "proceed" — immediately invoke that workflow.
+
+For full auto-pilot with no prompt, use `/next` instead.