learnship 2.0.11 → 2.1.1

package/learnship/templates/ui-spec.md

@@ -0,0 +1,107 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+created: {date}
+---
+
+# Phase {N} — UI Design Contract
+
+> Visual and interaction contract for frontend phases. Verified against impeccable standards.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Component library | {library or "none"} |
+| Icon library | {library} |
+| Font | {font} |
+| CSS approach | {tailwind / css modules / styled-components / etc.} |
+
+---
+
+## Spacing Scale
+
+Declared values (must be multiples of 4):
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs | 4px | Icon gaps, inline padding |
+| sm | 8px | Compact element spacing |
+| md | 16px | Default element spacing |
+| lg | 24px | Section padding |
+| xl | 32px | Layout gaps |
+| 2xl | 48px | Major section breaks |
+| 3xl | 64px | Page-level spacing |
+
+Exceptions: {list any, or "none"}
+
+---
+
+## Typography
+
+| Role | Size | Weight | Line Height |
+|------|------|--------|-------------|
+| Body | {px} | {weight} | {ratio} |
+| Label | {px} | {weight} | {ratio} |
+| Heading | {px} | {weight} | {ratio} |
+| Display | {px} | {weight} | {ratio} |
+
+---
+
+## Color
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Primary | {hex} | Buttons, links, active states |
+| Secondary | {hex} | Supporting actions |
+| Neutral | {hex} | Text, borders, backgrounds |
+| Success | {hex} | Confirmations, positive states |
+| Warning | {hex} | Cautions, pending states |
+| Error | {hex} | Errors, destructive actions |
+
+---
+
+## Key Components
+
+| Component | Spec |
+|-----------|------|
+| {component} | {key constraints: size, padding, border-radius, shadow} |
+
+---
+
+## Interaction Patterns
+
+| Pattern | Behavior |
+|---------|----------|
+| Loading | {skeleton / spinner / progressive} |
+| Empty state | {illustration + CTA / minimal text / guided action} |
+| Error state | {inline / toast / modal / redirect} |
+| Transitions | {duration, easing, what animates} |
+
+---
+
+## Responsive Breakpoints
+
+| Breakpoint | Width | Layout Changes |
+|------------|-------|----------------|
+| Mobile | < 640px | {description} |
+| Tablet | 640-1024px | {description} |
+| Desktop | > 1024px | {description} |
+
+---
+
+## Impeccable Checklist
+
+- [ ] No overused fonts (Inter, Roboto, Arial)
+- [ ] No AI palette (cyan-on-dark, purple-to-blue gradients)
+- [ ] No pure black (#000) or pure white (#fff) — tinted neutrals
+- [ ] No nested cards inside cards
+- [ ] No large rounded icons above every heading
+- [ ] At least one intentional, memorable design decision
+- [ ] Typography has clear visual hierarchy with modular scale
+- [ ] Spacing creates rhythm through variation, not uniformity
+
+**If someone saw this interface and immediately thought AI made it — that is the problem.**

package/learnship/workflows/complete-milestone.md

@@ -185,11 +185,10 @@ Ask: "Ready to start the next milestone?"
 - **Not yet** → stop here
 
 ```
-💡 Not sure what to build next? Run `/ideate` for codebase-grounded idea generation —
-it scans TODOs, test gaps, and hotspots to surface high-impact improvements.
-
-💡 For ambitious next milestones, consider `/challenge` to stress-test the scope
-before committing.
+💡 Team onboarding? `/milestone-summary` — generate a comprehensive summary a new contributor can read
+💡 Capture learnings? `/extract-learnings [N]` for each completed phase — decisions, lessons, patterns
+💡 Not sure what to build next? `/ideate` — codebase-grounded idea generation
+💡 For ambitious next milestones, `/challenge` to stress-test the scope before committing
 ```
 
 ---

package/learnship/workflows/compound.md

@@ -271,6 +271,8 @@ File created:
 
 Note: This was created in lightweight mode. For richer documentation
 (cross-references, overlap detection), re-run /compound in a fresh session.
+
+💡 Also consider: /extract-learnings [N] — captures decisions, lessons, patterns, surprises from the entire phase
 ```
 
 **No subagents are launched. No parallel tasks. One file written.**

package/learnship/workflows/debug.md

@@ -231,6 +231,8 @@ Debug session closed.
 Session: .planning/debug/resolved/[session-file]
 
 ▶ If more issues remain: debug [new description]
+▶ Stuck or need deeper investigation? /forensics — post-mortem analysis
+▶ Need to revert the fix? /undo --last 1
 ```
 
 ---

package/learnship/workflows/discuss-phase.md

@@ -8,7 +8,23 @@ Extract implementation decisions that downstream planning needs. Analyze the pha
 
 **Usage:** Run `discuss-phase [N]` before `plan-phase [N]`.
 
-**You are a thinking partner, not an interviewer.** The user is the visionary — you are the builder. Capture decisions that will guide research and planning.
+**You are a thinking partner, not an interviewer.** The user is the visionary — you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself.
+
+<downstream_awareness>
+**CONTEXT.md feeds into:**
+
+1. **Researcher** — Reads CONTEXT.md to know WHAT to research
+   - "User wants card-based layout" → researcher investigates card component patterns
+   - "Infinite scroll decided" → researcher looks into virtualization libraries
+
+2. **Planner** — Reads CONTEXT.md to know WHAT decisions are locked
+   - "Pull-to-refresh on mobile" → planner includes that in task specs
+   - "Claude's Discretion: loading skeleton" → planner can decide approach
+
+**Your job:** Capture decisions clearly enough that downstream agents can act on them without asking the user again.
+
+**Not your job:** Figure out HOW to implement. That's what research and planning do with the decisions you capture.
+</downstream_awareness>
 
 ## Step 1: Load Phase
 
@@ -72,6 +88,8 @@ Analyze the phase goal from ROADMAP.md. A gray area is an **implementation decis
 - Something users **READ** → structure, tone, depth, flow
 - Something being **ORGANIZED** → grouping criteria, naming, duplicates
 
+**Use domain-aware probes** from `@./references/domain-probes.md` when the phase touches a known domain (auth, real-time, dashboard, API, database, search, file upload, caching, testing, deployment, AI/ML). Pick 2-3 most relevant probes, not all of them.
+
 **Check prior decisions first** — don't re-ask what's already locked from earlier phases.
 
 Generate 3-4 **phase-specific** gray areas. Not generic categories ("UI", "UX") — concrete decisions:
@@ -116,15 +134,31 @@ After all selected areas:
 - Summarize decisions captured
 - Ask: "Which gray areas remain unclear?" → "Explore more" or "I'm ready for context"
 
-**Scope guardrail:** If the user suggests a new capability, say:
+<scope_guardrail>
+**No scope creep.** The phase boundary comes from ROADMAP.md and is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.
+
+**Allowed (clarifying ambiguity):**
+- "How should posts be displayed?" (layout, density, info shown)
+- "What happens on empty state?" (within the feature)
+- "Pull to refresh or manual?" (behavior choice)
+
+**Not allowed (scope creep):**
+- "Should we also add comments?" (new capability)
+- "What about search/filtering?" (new capability)
+- "Maybe include bookmarking?" (new capability)
+
+**The heuristic:** Does this clarify how we implement what's already in the phase, or does it add a new capability that could be its own phase?
+
+**When user suggests scope creep:**
 ```
-"[Feature X] sounds like a new capability — that's its own phase.
+"[Feature X] would be a new capability — that's its own phase.
 Want me to note it for the roadmap backlog?
 
-Back to [current area]..."
+For now, let's focus on [phase domain]."
 ```
 
-Track deferred ideas internally.
+Capture the idea in the "Deferred Ideas" section. Don't lose it, don't act on it.
+</scope_guardrail>
 
 ## Step 6: Write CONTEXT.md
 
@@ -159,6 +193,26 @@ Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-CONTEXT.md`:
 
 </decisions>
 
+<specifics>
+## Specific Ideas
+
+[Any "I want it like X" moments or specific references]
+
+[If none: "No specific requirements — open to standard approaches"]
+
+</specifics>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+[List specs, ADRs, or design docs relevant to this phase with full relative paths.]
+
+[If no external specs: "No external specs — requirements are fully captured in decisions above"]
+
+</canonical_refs>
+
 <code_context>
 ## Existing Code Insights
 
@@ -173,15 +227,6 @@ Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-CONTEXT.md`:
 
 </code_context>
 
-<specifics>
-## Specific Ideas
-
-[Any "I want it like X" moments or specific references]
-
-[If none: "No specific requirements — open to standard approaches"]
-
-</specifics>
-
 <deferred>
 ## Deferred Ideas
 
@@ -196,10 +241,23 @@ Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-CONTEXT.md`:
 *Context gathered: [date]*
 ```
 
-## Step 7: Commit and Confirm
+## Step 7: Write Discussion Log
+
+Also write a discussion log for audit purposes using `@./templates/discussion-log.md`:
+
+Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-DISCUSSION-LOG.md` with:
+- All options considered for each area (not just the selected one)
+- The user's verbatim choice and rationale
+- Areas delegated to Claude's discretion
+- Deferred ideas
+
+This file is for human audit trails only — it is NOT referenced by downstream agents.
+
+## Step 8: Commit and Confirm
 
 ```bash
 git add ".planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-CONTEXT.md"
+git add ".planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-DISCUSSION-LOG.md"
 git commit -m "docs([padded_phase]): capture phase context"
 ```
 

package/learnship/workflows/docs-update.md

@@ -0,0 +1,144 @@
+---
+description: Generate, update, and verify project documentation — detects project type, builds doc queue, verifies against live codebase
+---
+
+# Docs Update
+
+Generate, update, and verify project documentation. Detects the project's doc structure, assembles a work manifest, writes or updates docs, and verifies factual claims against the live codebase.
+
+**Usage:** `docs-update` or `docs-update --force` (skip confirmations)
+
+## Step 1: Detect Project Type
+
+Scan the project root for signals:
+
+```bash
+ls package.json Makefile Cargo.toml go.mod setup.py pyproject.toml 2>/dev/null
+ls .github/workflows/ .gitlab-ci.yml Dockerfile docker-compose.yml 2>/dev/null
+ls LICENSE CONTRIBUTING.md 2>/dev/null
+find . -maxdepth 2 -name "*.test.*" -o -name "*_test.*" -o -name "test_*" 2>/dev/null | head -5
+```
+
+Classify the project:
+
+| Condition | Primary Type |
+|-----------|-------------|
+| Multiple package.json files at different levels | `monorepo` |
+| `bin` field in package.json AND no API routes | `cli-tool` |
+| API routes detected AND not open source | `saas` |
+| LICENSE file AND no API routes | `open-source-library` |
+| None of the above | `generic` |
+
+## Step 2: Build Doc Queue
+
+**Always-on docs (every project):**
+1. README.md
+2. ARCHITECTURE.md
+3. GETTING-STARTED.md
+4. DEVELOPMENT.md
+5. TESTING.md
+6. CONFIGURATION.md
+
+**Conditional docs (add if signal matched):**
+- API.md — if API routes detected
+- CONTRIBUTING.md — if open source (LICENSE exists)
+- DEPLOYMENT.md — if deploy config detected (Dockerfile, CI/CD)
+
+**CHANGELOG.md is NEVER queued** — it's manually maintained.
+
+Maximum 9 docs total.
+
+## Step 3: Check Existing Docs
+
+```bash
+find . -maxdepth 2 -name "*.md" -not -path "./.planning/*" -not -path "./node_modules/*" 2>/dev/null
+```
+
+For each doc in the queue, determine mode:
+- **Create** — doc doesn't exist yet
+- **Update** — doc exists, check if it's stale
+
+Display the plan:
+```
+learnship > DOCS UPDATE
+
+Project type: [type]
+Docs to create: [N]
+Docs to update: [M]
+
+| Doc | Mode | Status |
+|-----|------|--------|
+| README.md | update | exists, checking freshness |
+| ARCHITECTURE.md | create | new |
+| ... | ... | ... |
+
+[Proceed] / [Customize queue] / [Cancel]
+```
+
+## Step 4: Write/Update Docs
+
+For each doc in the queue:
+
+### Create mode
+
+Read relevant source files to understand the project structure, then write the doc grounded in the actual codebase. Every claim must be verifiable.
+
+### Update mode
+
+Read the existing doc AND the current codebase. Identify stale sections (references to renamed files, outdated instructions, missing new features). Update only stale sections — preserve the author's voice and structure.
+
+For each doc, after writing:
+```bash
+git add [doc path]
+```
+
+## Step 5: Verify Docs Against Codebase
+
+For each written/updated doc, verify factual claims:
+
+- File paths mentioned in docs actually exist
+- Commands shown in docs actually work
+- Configuration examples match the actual schema
+- API endpoints documented match the actual routes
+
+```bash
+# Example: check all file references in a doc
+grep -oE '\`[a-zA-Z0-9_./-]+\.[a-z]+\`' [doc] | tr -d '`' | while read f; do
+  [ -f "$f" ] || echo "MISSING: $f referenced in [doc]"
+done
+```
+
+If verification finds issues: fix the doc, don't flag it as a separate issue.
+
+## Step 6: Commit and Report
+
+```bash
+git add -A
+git commit -m "docs: update project documentation ([N] docs)"
+```
+
+```
+learnship > DOCS UPDATE COMPLETE
+
+| Doc | Mode | Verified |
+|-----|------|----------|
+| README.md | updated | yes |
+| ARCHITECTURE.md | created | yes |
+| ... | ... | ... |
+
+[N] docs written/updated, all verified against codebase.
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** Writing documentation forces you to articulate what was built:
+>
+> `@agentic-learning explain [project topic]` — Explain the architecture or a key feature in your own words. Gaps in the explanation reveal gaps in understanding. Writes a comprehension log to `docs/project-knowledge.md`.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning explain [topic]` to test your understanding of what was documented."*

package/learnship/workflows/execute-phase.md

@@ -6,13 +6,32 @@ description: Execute all plans in a phase using wave-based ordered execution —
 
 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]`
+**Usage:** `execute-phase [N]` or `execute-phase [N] --wave [W]`
 
 **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).
+> **Platform note:** This workflow detects whether subagent spawning is available by reading `parallelization.enabled` from `.planning/config.json`. Set `"parallelization": { "enabled": true }` to enable parallel agent spawning on supported platforms. Defaults to `false` (sequential — always safe). The legacy flat `"parallelization": true` is also honored for backward compatibility.
 
-## Step 1: Initialize
+<runtime_compatibility>
+**Subagent spawning is runtime-specific:**
+- **Claude Code:** Uses `Task(subagent_type=..., ...)` — blocks until complete, returns result
+- **OpenCode / Codex:** Subagent spawning supported with platform-native dispatch
+- **Windsurf / Cursor:** No subagent spawning — always use sequential inline execution
+- **Gemini CLI:** Subagents exist but parallel execution limited — default to sequential
+
+**Fallback rule:** If a spawned agent completes its work (commits visible, SUMMARY.md exists) but the orchestrator never receives the completion signal, treat it as successful based on spot-checks and continue to the next wave/plan. Never block indefinitely.
+</runtime_compatibility>
+
+## Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for:
+- First positional token → `PHASE_ARG` (phase number)
+- Optional `--wave N` → `WAVE_FILTER` (execute only wave N)
+- Optional `--gaps-only` → execute only gap-closure plans
+
+If `--wave` is absent, execute all incomplete waves in the phase.
+
+## Step 1b: Initialize
 
 Read the phase directory:
 ```bash
@@ -31,6 +50,8 @@ If no plans found: stop — run `plan-phase [N]` first.
 Read `.planning/STATE.md` for project context.
 Read `.planning/config.json` for settings.
 
+**Context window scaling:** Check for `context_window` in config (default: 200000). At < 500000 tokens: read only frontmatter from prior phase SUMMARYs. At >= 500000: full body reads permitted for direct-dependency phases. See `@./references/context-budget.md` for the complete table.
+
 ## Step 2: Discover and Group Plans
 
 Read each PLAN.md's frontmatter to extract:
@@ -105,7 +126,13 @@ Both inline (`@./agents/executor.md`) and subagent (`learnship-executor`) execut
 
 ## Step 3: Execute Waves
 
-Read `parallelization` from `.planning/config.json` (defaults to `false`).
+Read `parallelization` from `.planning/config.json`. Supports both:
+- New format: `parallelization.enabled` (boolean)
+- Legacy format: `parallelization` (flat boolean)
+
+Defaults to `false` if not found.
+
+If `WAVE_FILTER` is set, skip all waves except the specified one.
 
 For each wave, in sequence:
 
@@ -126,7 +153,7 @@ Executing [count] plan(s)...
 
 ### Execute the plans
 
-**If `parallelization` is `true` (subagent mode — Claude Code, OpenCode, Codex):**
+**If parallelization is enabled (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.
 
@@ -159,7 +186,7 @@ Task(
 
 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):**
+**If parallelization is disabled (sequential mode — Windsurf, Cursor, Gemini CLI, or user preference):**
 
 For each plan in the wave, using `@./agents/executor.md` as your execution persona:
 
@@ -361,6 +388,8 @@ git commit -m "docs: update AGENTS.md — phase [X] complete"
    Then: /review → /ship → /compound
    Then: discuss-phase [X+1] → plan-phase [X+1]
 
+💡 Security: `/secure-phase [X]` — run STRIDE threat verification on this phase
+💡 Learnings: `/extract-learnings [X]` — capture decisions, lessons, patterns while fresh
 💡 Working on sensitive files? Run `/guard [scope]` to enable safety mode.
 ```
 

package/learnship/workflows/extract-learnings.md

@@ -0,0 +1,161 @@
+---
+description: Extract structured learnings from completed phase artifacts — decisions, lessons, patterns, surprises
+---
+
+# Extract Learnings
+
+Extract decisions, lessons learned, patterns discovered, and surprises encountered from completed phase artifacts into a structured LEARNINGS.md file. Captures institutional knowledge that would otherwise be lost between phases.
+
+**Usage:** `extract-learnings [N]` — extract from phase N
+
+**Complements `/compound`:** compound captures reusable solutions, extract-learnings captures meta-knowledge (why things worked, what surprised you, what patterns emerged).
+
+## Step 1: Initialize
+
+Find the phase directory:
+```bash
+ls ".planning/phases/" | grep "^[0-9]" | sort
+```
+
+Find the phase matching `[N]`. If not found, stop and list available phases.
+
+Verify required artifacts exist:
+```bash
+ls ".planning/phases/[padded_phase]-[phase_slug]/"*-PLAN.md 2>/dev/null
+ls ".planning/phases/[padded_phase]-[phase_slug]/"*-SUMMARY.md 2>/dev/null
+```
+
+If PLAN.md or SUMMARY.md files are missing: "Required artifacts missing. PLAN.md and SUMMARY.md are required for learning extraction."
+
+## Step 2: Collect Artifacts
+
+**Required (must exist):**
+- All `*-PLAN.md` files for the phase
+- All `*-SUMMARY.md` files for the phase
+
+**Optional (read if available, skip if not):**
+- `*-VERIFICATION.md` — verification results
+- `*-UAT.md` — user acceptance test results
+- `*-SECURITY.md` — security verification
+- `.planning/STATE.md` — project state with decisions and blockers
+
+Track which optional artifacts are missing for the frontmatter.
+
+## Step 3: Extract Learnings
+
+Analyze all collected artifacts and extract learnings into 4 categories:
+
+### 1. Decisions
+Technical and architectural decisions made during the phase:
+- Explicit decisions documented in PLAN.md or SUMMARY.md
+- Technology choices and their rationale
+- Trade-offs that were evaluated
+
+Each entry: **What** was decided, **Why** (rationale), **Source** (which artifact).
+
+### 2. Lessons
+What worked well and what didn't:
+- Approaches that succeeded or failed
+- Time estimates vs actual (if observable from git timestamps)
+- Unexpected complexity or simplicity
+
+Each entry: **What happened**, **Why it matters**, **Source**.
+
+### 3. Patterns
+Reusable patterns that emerged:
+- Code patterns used across multiple tasks
+- Process patterns that worked well
+- Integration patterns between components
+
+Each entry: **Pattern name**, **When to use**, **Source**.
+
+### 4. Surprises
+Things that didn't go as expected:
+- Unexpected bugs or behaviors
+- Assumptions that were wrong
+- External factors that affected the work
+
+Each entry: **What was surprising**, **Impact**, **Source**.
+
+## Step 4: Write LEARNINGS.md
+
+Write `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-LEARNINGS.md`:
+
+```markdown
+---
+phase: [N]
+phase_name: [name]
+extracted: [date]
+plan_count: [N]
+summary_count: [N]
+missing_artifacts: [list or "none"]
+---
+
+# Phase [N]: [Name] — Learnings
+
+## Decisions
+
+### D1: [Decision title]
+**What:** [what was decided]
+**Why:** [rationale]
+**Source:** [artifact file]
+
+## Lessons
+
+### L1: [Lesson title]
+**What happened:** [description]
+**Why it matters:** [impact on future work]
+**Source:** [artifact file]
+
+## Patterns
+
+### P1: [Pattern name]
+**When to use:** [conditions]
+**Source:** [artifact file]
+
+## Surprises
+
+### S1: [Surprise title]
+**What was surprising:** [description]
+**Impact:** [how it affected the work]
+**Source:** [artifact file]
+
+---
+
+*Extracted from Phase [N] artifacts on [date]*
+```
+
+## Step 5: Commit and Report
+
+```bash
+git add ".planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-LEARNINGS.md"
+git commit -m "docs([padded_phase]): extract phase learnings"
+```
+
+```
+learnship > LEARNINGS EXTRACTED
+
+Phase [N]: [Name]
+Decisions: [N]  |  Lessons: [N]  |  Patterns: [N]  |  Surprises: [N]
+
+Report: [path to LEARNINGS.md]
+
+These learnings feed into future planning — the planner will reference them
+when working on related phases.
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:**
+
+> **Learning moment:** You just extracted meta-knowledge from a phase. Make it stick:
+>
+> `@agentic-learning space` — Schedule the key patterns and lessons for spaced review. The extraction just identified WHAT you learned — spacing ensures you RETAIN it.
+>
+> `@agentic-learning interleave [phase topic]` — Mix these learnings with concepts from earlier phases to strengthen cross-cutting understanding.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning space` to schedule these learnings for spaced review."*