learnship 1.9.0

package/learnship/workflows/help.md

@@ -0,0 +1,153 @@
+---
+description: Show all available workflows with descriptions and when to use them
+---
+
+# Help
+
+Show all available workflows, organized by category.
+
+## Start Here
+
+You only need to remember **5 commands** to use learnship effectively:
+
+| Command | When to use |
+|---------|-------------|
+| `/ls` | "Where am I? What's next?" — works for new and returning users |
+| `/next` | Auto-pilot — reads state and runs the right workflow for you |
+| `/new-project` | Starting a brand new project |
+| `/quick "..."` | One-off task with atomic commit, no ceremony |
+| `/help` | This screen — see all 42 commands |
+
+Everything else below is discoverable from `/ls` as you go.
+
+---
+
+## All Workflows
+
+### Core Workflow — build products phase by phase
+
+| Workflow | What it does |
+|----------|-------------|
+| `/new-project` | Full init: questioning → research → requirements → roadmap |
+| `/discuss-phase [N]` | Capture implementation decisions before planning |
+| `/plan-phase [N]` | Research + create + verify plans |
+| `/execute-phase [N]` | Wave-ordered execution of all plans |
+| `/verify-work [N]` | Manual UAT with auto-diagnosis and fix planning |
+| `/complete-milestone` | Archive milestone, tag release, prepare next version |
+| `/audit-milestone` | Pre-release: requirement coverage + stub detection |
+| `/new-milestone [name]` | Start next version cycle after completing a milestone |
+
+### Navigation — know where you are, resume work
+
+| Workflow | What it does |
+|----------|-------------|
+| `/ls` | Status + next step + offer to run it — **start every session here** |
+| `/next` | Auto-pilot: reads state and runs the right workflow automatically |
+| `/progress` | Same as `/ls` — status overview + smart routing |
+| `/resume-work` | Restore full context from last session |
+| `/pause-work` | Save handoff file when stopping mid-phase |
+| `/quick [description]` | Ad-hoc task with full guarantees and atomic commits |
+| `/help` | Show this reference |
+
+### Phase Management — shape the roadmap mid-milestone
+
+| Workflow | What it does |
+|----------|-------------|
+| `/add-phase [description]` | Append new phase to roadmap |
+| `/insert-phase [N] [description]` | Insert urgent work between existing phases |
+| `/remove-phase [N]` | Remove a future phase and renumber |
+| `/research-phase [N]` | Deep research only, no plans yet |
+| `/list-phase-assumptions [N]` | Preview intended approach before planning |
+| `/plan-milestone-gaps` | Create fix phases from audit findings |
+
+### Codebase Intelligence — understand what exists
+
+| Workflow | What it does |
+|----------|-------------|
+| `/map-codebase` | Analyze existing codebase (brownfield entry point) |
+| `/discovery-phase [N]` | Map unfamiliar code area — files, deps, risks — before planning |
+| `/debug [description]` | Systematic triage → diagnose → fix with session state |
+| `/diagnose-issues [N]` | Batch-diagnose all UAT issues — groups by root cause, proposes fix plan |
+| `/execute-plan [N] [id]` | Run a single PLAN.md in isolation (re-run failed plan) |
+| `/validate-phase [N]` | Retroactive test coverage audit for a phase |
+
+### Task Management — capture and act on ideas
+
+| Workflow | What it does |
+|----------|-------------|
+| `/add-todo [description]` | Capture an idea without interrupting flow |
+| `/check-todos` | Review and act on captured todos |
+| `/add-tests [N]` | Generate unit and E2E tests post-execution |
+
+### Decision Intelligence — institutional memory
+
+| Workflow | What it does |
+|----------|-------------|
+| `/decision-log [description]` | Capture a decision with context, alternatives, and rationale |
+| `/knowledge-base` | Aggregate all decisions + lessons into searchable KNOWLEDGE.md |
+| `/knowledge-base search [query]` | Search the project knowledge base |
+
+### Milestone Intelligence — reflect and hand off
+
+| Workflow | What it does |
+|----------|-------------|
+| `/discuss-milestone [version]` | Capture goals and anti-goals before new-milestone |
+| `/milestone-retrospective` | 5-question retrospective after complete-milestone |
+| `/transition` | Write full handoff document for collaborator or fresh session |
+
+### Maintenance — keep the project healthy
+
+| Workflow | What it does |
+|----------|-------------|
+| `/settings` | Interactive config editor for `.planning/config.json` |
+| `/set-profile [quality\|balanced\|budget]` | One-step model profile switch |
+| `/health` | Project health check: stale files, missing artifacts |
+| `/health --repair` | Auto-fix repairable health issues |
+| `/cleanup` | Archive completed milestone phase directories |
+| `/update` | Update the platform itself to the latest version |
+| `/reapply-patches` | Restore local edits after an update |
+| `/sync-upstream-skills` | Pull latest agentic-learning + impeccable from their upstream repos and re-deploy to all platforms |
+
+---
+
+## Quick Reference
+
+**Starting fresh:**
+```
+/new-project
+```
+
+**Standard phase loop:**
+```
+/discuss-phase N → /plan-phase N → /execute-phase N → /verify-work N
+```
+
+**Quick fix:**
+```
+/quick "description of what to do"
+```
+
+**After a break:**
+```
+/ls           (where am I? — offers to run next step)
+/next         (just keep moving — auto-pilot)
+/resume-work  (full context restoration)
+```
+
+**Before releasing:**
+```
+/audit-milestone → /plan-milestone-gaps (if gaps) → /complete-milestone
+```
+
+---
+
+## Configuration
+
+Edit project settings with `/settings` or directly:
+```bash
+cat .planning/config.json
+```
+
+Key settings: `mode` (yolo/interactive), `model_profile` (quality/balanced/budget), `learning_mode` (auto/manual).
+
+See `README.md` for the full configuration reference.

package/learnship/workflows/insert-phase.md

@@ -0,0 +1,106 @@
+---
+description: Insert a new phase between existing phases for urgent work discovered mid-milestone
+---
+
+# Insert Phase
+
+Insert a decimal phase for urgent work discovered mid-milestone. Uses decimal numbering (e.g., `3.1`) to preserve the logical sequence of planned phases without renumbering everything.
+
+**Usage:** `insert-phase [N] [description]`
+
+**When to use:** Urgent bug fix, critical dependency discovered, security patch — work that must happen between two existing phases without waiting.
+
+**Not for:** Regular scope additions → use `add-phase` for those.
+
+## Step 1: Parse Arguments
+
+Extract from arguments:
+- First token: the integer phase number to insert **after** (e.g., `3`)
+- Remaining text: phase description
+
+If either is missing:
+```
+Usage: insert-phase [N] [description]
+Example: insert-phase 3 Fix critical auth vulnerability
+
+[N] = phase to insert after (must be an existing phase)
+```
+
+Validate that the after-phase number is an integer.
+
+## Step 2: Validate
+
+```bash
+test -f .planning/ROADMAP.md && echo "OK" || echo "MISSING"
+```
+
+Check that phase `[N]` exists in ROADMAP.md:
+```bash
+grep -E "^## Phase [N]:" .planning/ROADMAP.md
+```
+
+If phase not found, list available phases and stop.
+
+## Step 3: Calculate Decimal Number
+
+Find existing decimal phases after phase `[N]`:
+```bash
+ls .planning/phases/ 2>/dev/null | grep -E "^[N]\." | sort -V
+```
+
+If none exist → new phase is `[N].1`
+If `[N].1` exists → new phase is `[N].2`, etc.
+
+Generate slug from description (lowercase, hyphens, max 40 chars).
+
+## Step 4: Create Phase Directory
+
+```bash
+mkdir -p ".planning/phases/[N].[M]-[SLUG]"
+```
+
+## Step 5: Update ROADMAP.md
+
+Insert the decimal phase entry immediately after Phase `[N]` in ROADMAP.md:
+
+```markdown
+## Phase [N].[M]: [Description] *(INSERTED — urgent)*
+
+**Goal:** [One sentence — what this urgent work delivers]
+**Status:** [ ] Not started
+**Depends on:** Phase [N]
+**Note:** Inserted between Phase [N] and Phase [N+1]
+
+### Plans
+*Not yet planned — run `plan-phase [N].[M]`*
+```
+
+## Step 6: Update STATE.md
+
+Add to Roadmap Evolution section:
+```markdown
+- Phase [N].[M] inserted after Phase [N]: [description] (URGENT)
+```
+
+Note: Check if Phase [N+1] dependencies are still valid — the inserted phase may need to complete before [N+1] can run.
+
+## Step 7: Commit
+
+```bash
+git add .planning/ROADMAP.md .planning/STATE.md ".planning/phases/[N].[M]-[SLUG]/"
+git commit -m "chore(roadmap): insert urgent phase [N].[M] — [description]"
+```
+
+## Step 8: Confirm
+
+```
+Phase [N].[M] inserted after Phase [N]:
+
+Description: [description]
+Directory: .planning/phases/[N].[M]-[slug]/
+Status: Not planned yet (URGENT)
+
+⚠️  Check Phase [N+1] dependencies — does it still make sense to run after [N].[M]?
+
+▶ Next: plan-phase [N].[M]
+```

package/learnship/workflows/knowledge-base.md

@@ -0,0 +1,168 @@
+---
+description: Aggregate key learnings and decisions across all sessions into a searchable KNOWLEDGE.md
+---
+
+# Knowledge Base
+
+Aggregate key learnings, decisions, and patterns from all sessions into a single searchable `KNOWLEDGE.md`. The knowledge base is the project's institutional memory — it compounds across milestones.
+
+**Usage:** `knowledge-base` — rebuild/update from all sources
+**Usage:** `knowledge-base search [query]` — search the knowledge base
+
+## Step 1: Determine Mode
+
+If `search [query]` argument provided → skip to **Search Mode** at end.
+
+Otherwise → build/update mode.
+
+## Step 2: Locate All Sources
+
+```bash
+# Decisions register
+cat .planning/DECISIONS.md 2>/dev/null
+
+# Debug session resolutions
+ls .planning/debug/resolved/ 2>/dev/null
+
+# Retrospectives
+ls .planning/milestones/*-RETROSPECTIVE.md 2>/dev/null
+
+# Phase research files
+find .planning/ -name "*-RESEARCH.md" | sort
+
+# AGENTS.md regressions
+grep -A 5 "### 20" AGENTS.md 2>/dev/null
+```
+
+## Step 3: Extract Knowledge
+
+From each source, extract structured knowledge items:
+
+**From DECISIONS.md:**
+- Each DEC-XXX entry → Knowledge item: `decision`
+
+**From debug resolved sessions:**
+- Each session's root cause + lesson → Knowledge item: `lesson`
+
+**From retrospectives:**
+- "What worked well" → Knowledge item: `pattern`
+- "What to avoid" → Knowledge item: `anti-pattern`
+- "Carry forward" → Knowledge item: `carry-forward`
+
+**From RESEARCH.md files:**
+- "Don't Hand-Roll" entries → Knowledge item: `library`
+- "Common Pitfalls" entries → Knowledge item: `pitfall`
+
+Deduplicate: if the same concept appears multiple times, merge into one entry with multiple `sources`.
+
+## Step 4: Write / Update KNOWLEDGE.md
+
+Write `.planning/KNOWLEDGE.md`:
+
+```markdown
+---
+updated: [date]
+items: [N]
+---
+
+# Project Knowledge Base
+
+Aggregated learnings from [N] decisions, [M] debug sessions, [K] retrospectives.
+
+---
+
+## Decisions
+
+### DEC-001: [title]
+**Type:** architecture | library | scope | pattern
+**Phase:** [N] | **Date:** [date]
+**Choice:** [what was decided]
+**Rationale:** [why]
+**Still active:** yes | superseded by DEC-XXX
+
+[...repeat for each decision...]
+
+---
+
+## Lessons Learned
+
+### [YYYY-MM-DD]: [title]
+**From:** debug session | retrospective
+**What broke:** [description]
+**Root cause:** [cause]
+**Lesson:** [what to do differently]
+
+[...repeat...]
+
+---
+
+## Patterns That Work
+
+- **[Pattern name]**: [description — what it is and why it works here]
+- **[Pattern name]**: [description]
+
+---
+
+## Anti-Patterns to Avoid
+
+- **[Anti-pattern]**: [what it is] — [why it fails in this project]
+- **[Anti-pattern]**: [description]
+
+---
+
+## Libraries & Tools
+
+| Tool | Use for | Notes |
+|------|---------|-------|
+| [lib] | [purpose] | [any caveats] |
+
+---
+
+## Open Questions
+
+Questions surfaced during work that haven't been fully resolved:
+
+- [question] (from [source])
+```
+
+## Step 5: Commit
+
+```bash
+git add .planning/KNOWLEDGE.md
+git commit -m "docs: update knowledge base ([N] items)"
+```
+
+## Step 6: Confirm
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► KNOWLEDGE BASE UPDATED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Items: [N] total
+  Decisions: [N]
+  Lessons: [N]
+  Patterns: [N]
+  Anti-patterns: [N]
+
+Saved: .planning/KNOWLEDGE.md
+```
+
+---
+
+## Search Mode
+
+If `knowledge-base search [query]` was invoked:
+
+```bash
+grep -i "[query]" .planning/KNOWLEDGE.md 2>/dev/null
+grep -i "[query]" .planning/DECISIONS.md 2>/dev/null
+```
+
+Display matching sections with context. If no results:
+```
+No results for "[query]" in knowledge base.
+
+Try: knowledge-base  (rebuild from all sources first)
+     or search with broader terms
+```

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

@@ -0,0 +1,129 @@
+---
+description: Surface Cascade's intended approach for a phase before planning starts — validate direction early
+---
+
+# List Phase Assumptions
+
+Surface what Cascade intends to do for a phase before committing to a plan. This is **analysis of what Cascade thinks**, not intake of what you want — use `discuss-phase` for that.
+
+**Use when:** You want to validate direction before planning, or you're unsure what approach will be taken.
+
+**Usage:** `list-phase-assumptions [N]`
+
+## Step 1: Validate Phase
+
+Phase number is required:
+```
+Usage: list-phase-assumptions [N]
+Example: list-phase-assumptions 3
+```
+
+Find phase `[N]` in ROADMAP.md:
+```bash
+grep -E "Phase [N]:" .planning/ROADMAP.md
+```
+
+If not found: list available phases and stop.
+
+## Step 2: Load Context
+
+```bash
+cat .planning/ROADMAP.md
+cat .planning/PROJECT.md
+cat .planning/STATE.md
+```
+
+Check for CONTEXT.md (user decisions):
+```bash
+ls ".planning/phases/" 2>/dev/null | grep "^0*[N]-"
+```
+
+If CONTEXT.md exists, read it — it affects assumptions.
+
+## Step 3: Analyze Phase
+
+Based on the phase goal, project context, and codebase, surface assumptions across five dimensions. Be honest about confidence levels.
+
+```
+## My Assumptions for Phase [N]: [Phase Name]
+
+### Technical Approach
+What libraries, frameworks, or patterns I'd use:
+- [Fairly confident:] I'd use [X] because [reason from phase context]
+- [Assuming:] I'd structure this as [Y] because it fits the existing pattern
+- [Unclear:] [Z] could go multiple ways depending on [ambiguity]
+
+### Implementation Order
+What I'd build first, second, third:
+1. [First thing] — because it's foundational
+2. [Second thing] — because it depends on #1
+3. [Third thing] — because it integrates the pieces
+
+### Scope Boundaries
+**In scope:** [What I think this phase covers]
+**Out of scope:** [What I'd defer to later phases]
+**Ambiguous:** [Things that could go either way]
+
+### Risk Areas
+Where I anticipate complexity or challenges:
+- [Tricky thing]: [Why it's hard and what I'd watch out for]
+- [Potential issue]: [What could go wrong]
+
+### Dependencies
+**From prior phases:** [What must exist before this runs]
+**External:** [Third-party dependencies needed]
+**Feeds into:** [What later phases will need from this phase's output]
+
+---
+
+**What do you think?**
+
+Are these assumptions accurate? Tell me:
+- What I got right
+- What I got wrong  
+- What I'm missing
+```
+
+Wait for user response.
+
+## Step 4: Acknowledge Feedback
+
+**If corrections provided:**
+```
+Key corrections noted:
+- [correction 1]
+- [correction 2]
+
+This changes my approach significantly: [summarize updated understanding]
+```
+
+**If assumptions confirmed:**
+```
+Assumptions validated. Ready to plan.
+```
+
+## Step 5: Offer Next Steps
+
+```
+What's next?
+
+1. discuss-phase [N] — you answer my questions to build CONTEXT.md
+2. plan-phase [N] — create plans now (assumptions noted above apply)
+3. Re-examine — I'll analyze again with your corrections
+```
+
+Note: Any corrections discussed here are not automatically captured. Run `discuss-phase [N]` to write them to a CONTEXT.md that planners will read.
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** Offer:
+
+> 💡 **Learning moment:** About to commit to an approach. Log the path not taken:
+>
+> `@agentic-learning either-or` — Record the alternatives considered, the choice made, and expected consequences. When the build goes sideways, this record tells you which assumption failed.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning either-or` to log the approach decisions being made here."*

package/learnship/workflows/ls.md

@@ -0,0 +1,145 @@
+---
+description: Show where you are in the project and what to do next — the fastest way to orient yourself and keep moving
+---
+
+# ls — Project Status
+
+The quickest way to answer "where am I and what do I do next?" Works for new users and returning users alike.
+
+**Usage:** `/ls`
+
+---
+
+## Step 1: Check for Project
+
+```bash
+test -f .planning/PROJECT.md && echo "EXISTS" || echo "MISSING"
+```
+
+**If MISSING** — no project initialized yet. Display:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► WELCOME
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+No project found in this directory.
+
+learnship is a multi-platform agentic engineering system —
+spec-driven phases, context-engineered plans, atomic execution,
+and a learning partner woven into every phase transition.
+
+▶ To start: /new-project
+▶ For a quick one-off task: /quick "description"
+▶ To see all commands: /help
+```
+
+Stop here.
+
+---
+
+## Step 2: Load State
+
+Read 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 for a one-liner summary of what was accomplished.
+
+Check for a `.continue-here.md` handoff:
+
+```bash
+find .planning/phases -name ".continue-here.md" 2>/dev/null
+```
+
+---
+
+## Step 3: Analyze Phase
+
+For the current phase, 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 diagnosed UAT gaps:
+
+```bash
+grep -l "status: diagnosed" .planning/phases/[current_phase_dir]/*-UAT.md 2>/dev/null
+```
+
+---
+
+## Step 4: Display Status
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► [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 phase: [N] — [phase-name]
+  Plans: [done]/[total]   UAT: [status]
+```
+
+---
+
+## Step 5: Route and Offer to Run
+
+Determine the next action (same logic as `progress`):
+
+1. **`.continue-here.md` exists** → mid-plan handoff
+   - Next: `resume-work`
+
+2. **UAT gaps (status: diagnosed)** → fix plans needed
+   - Next: `plan-phase [X]` (gap closure mode)
+
+3. **Plans exist, summaries < plans** → unfinished execution
+   - Next: `execute-phase [X]`
+
+4. **Plans = 0, CONTEXT.md exists** → ready to plan
+   - Next: `plan-phase [X]`
+
+5. **Plans = 0, no CONTEXT.md** → needs discussion
+   - Next: `discuss-phase [X]`
+
+6. **All plans have summaries, more phases remain** → move forward
+   - Next: `discuss-phase [X+1]`
+
+7. **All phases done** → ready to ship
+   - Next: `audit-milestone`
+
+Display clearly, then **ask**:
+
+```
+▶ Next: [workflow name]
+  [one-line reason]
+
+  Run it now? Type "yes" to proceed, or just keep chatting.
+```
+
+If the user says yes (or "go", "do it", "run it", "proceed") — immediately invoke that workflow.
+
+---
+
+## Notes
+
+- `/ls` is an alias for the status + routing logic in `progress`. Use either.
+- For full auto-pilot (no prompt), use `/next` instead.
+- To see all 40+ available commands: `/help`