learnship 2.0.10 → 2.1.0

package/learnship/templates/security.md

@@ -0,0 +1,61 @@
+---
+phase: {N}
+slug: {phase-slug}
+status: draft
+threats_open: 0
+created: {date}
+---
+
+# Phase {N} — Security
+
+> Per-phase security contract: threat register, accepted risks, and audit trail.
+
+---
+
+## Trust Boundaries
+
+| Boundary | Description | Data Crossing |
+|----------|-------------|---------------|
+| {boundary} | {description} | {data type / sensitivity} |
+
+---
+
+## Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation | Status |
+|-----------|----------|-----------|-------------|------------|--------|
+| T-{N}-01 | {STRIDE category} | {component} | {mitigate / accept / transfer} | {control or reference} | open |
+
+*Status: open · closed*
+*Disposition: mitigate (implementation required) · accept (documented risk) · transfer (third-party)*
+*STRIDE categories: Spoofing · Tampering · Repudiation · Information Disclosure · Denial of Service · Elevation of Privilege*
+
+---
+
+## Accepted Risks Log
+
+| Risk ID | Threat Ref | Rationale | Accepted By | Date |
+|---------|------------|-----------|-------------|------|
+
+*Accepted risks do not resurface in future audit runs.*
+
+*If none: "No accepted risks."*
+
+---
+
+## Security Audit Trail
+
+| Audit Date | Threats Total | Closed | Open | Run By |
+|------------|---------------|--------|------|--------|
+| {YYYY-MM-DD} | {N} | {N} | {N} | {name / agent} |
+
+---
+
+## Sign-Off
+
+- [ ] All threats have a disposition (mitigate / accept / transfer)
+- [ ] Accepted risks documented in Accepted Risks Log
+- [ ] `threats_open: 0` confirmed
+- [ ] `status: verified` set in frontmatter
+
+**Approval:** {pending / verified YYYY-MM-DD}

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:
 
@@ -337,8 +364,14 @@ node -e "const fs=require('fs');if(!fs.existsSync('AGENTS.md')){process.exit(0);
 
 > If verification fails, restore the missing sections from `@./templates/agents.md` before committing.
 
+**Sync platform-native copies (if they exist):**
+
+```bash
+node -e "const fs=require('fs');const copies=[['CLAUDE.md','Claude Code'],['GEMINI.md','Gemini CLI']];if(!fs.existsSync('AGENTS.md'))process.exit(0);copies.forEach(([f,p])=>{if(fs.existsSync(f)){fs.copyFileSync('AGENTS.md',f);console.log('Synced AGENTS.md → '+f+' ('+p+')');}});"
+```
+
 ```bash
-git add AGENTS.md
+git add AGENTS.md CLAUDE.md GEMINI.md 2>/dev/null
 git commit -m "docs: update AGENTS.md — phase [X] complete"
 ```
 
@@ -355,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.
 ```