learnship 1.9.24 → 2.0.0

package/learnship/workflows/compound.md

@@ -0,0 +1,305 @@
+---
+description: Capture a solution at the moment of solving — structured doc to .planning/solutions/
+---
+
+# Compound
+
+Capture a recently solved problem or learned pattern while context is fresh. Creates structured documentation in `.planning/solutions/` with YAML frontmatter for searchability. Each documented solution compounds your team's knowledge — the first time takes research, the next time takes minutes.
+
+**Usage:** `compound` — document the most recent fix or learning
+**Usage:** `compound [brief context]` — provide additional context hint
+
+## Step 1: Choose Mode
+
+Present the user with two options before proceeding. Use the platform's blocking question tool (`AskUserQuestion` in Claude Code, `request_user_input` in Codex, `ask_user` in Gemini, `ask_user_question` in Windsurf). If no question tool is available, present the options and wait for the user's reply.
+
+```
+1. Full (recommended) — the complete compound workflow. Researches,
+   cross-references, and reviews your solution to produce documentation
+   that compounds your project's knowledge.
+
+2. Lightweight — same documentation, single pass. Faster and uses
+   fewer tokens, but won't detect duplicates or cross-reference
+   existing docs. Best for simple fixes or long sessions nearing
+   context limits.
+```
+
+Do NOT pre-select a mode. Do NOT skip this prompt. Wait for the user's choice before proceeding.
+
+---
+
+## Full Mode
+
+### Phase 1: Parallel Research
+
+Read `parallelization` from `.planning/config.json` (defaults to `false`).
+
+**If `parallelization` is `true` (subagent mode — Claude Code, OpenCode, Codex):**
+
+Launch these tasks IN PARALLEL. Each returns text data to the orchestrator — subagents must NOT write any files.
+
+```
+Task(
+  subagent_type="learnship-solution-writer",
+  prompt="
+    <objective>
+    RESEARCH ONLY — do NOT write any files.
+    Analyze conversation history to extract:
+    1. Problem classification (bug vs knowledge track)
+    2. YAML frontmatter skeleton with fields: title, date, category, module,
+       problem_type, component, severity, tags
+    3. Category directory path mapped from problem_type
+    4. Suggested filename: [sanitized-problem-slug]-[YYYY-MM-DD].md
+
+    Bug track problem_types: build_error, test_failure, runtime_error,
+    performance_issue, database_issue, security_issue, ui_bug,
+    integration_issue, logic_error
+
+    Knowledge track problem_types: best_practice, documentation_gap,
+    workflow_issue, developer_experience
+
+    Category mapping:
+    - build_error → build-errors/
+    - test_failure → test-failures/
+    - runtime_error → runtime-errors/
+    - performance_issue → performance-issues/
+    - database_issue → database-issues/
+    - security_issue → security-issues/
+    - ui_bug → ui-bugs/
+    - integration_issue → integration-issues/
+    - logic_error → logic-errors/
+    - best_practice → best-practices/
+    - workflow_issue → workflow-issues/
+    - developer_experience → developer-experience/
+    - documentation_gap → documentation-gaps/
+
+    Return text data only.
+    </objective>
+
+    <files_to_read>
+    - $LEARNSHIP_DIR/references/solution-schema.md
+    </files_to_read>
+  "
+)
+```
+
+Simultaneously, search `.planning/solutions/` for related documentation:
+
+```bash
+# Search for related solutions
+find .planning/solutions/ -name "*.md" -type f 2>/dev/null | head -20
+```
+
+If solutions exist, grep for keyword matches from the current problem:
+```bash
+grep -ril "[keyword1]\|[keyword2]" .planning/solutions/ 2>/dev/null
+```
+
+For each candidate, read the frontmatter (first 30 lines) to assess overlap across five dimensions: problem statement, root cause, solution approach, referenced files, and prevention rules.
+
+Score overlap:
+- **High** (4-5 dimensions match): essentially the same problem solved again
+- **Moderate** (2-3 dimensions match): same area but different angle
+- **Low** (0-1 dimensions match): related but distinct
+
+**If `parallelization` is `false` (sequential mode):**
+
+Using `@./agents/solution-writer.md` as your analysis persona, perform all research in sequence:
+
+1. Extract from conversation history: problem, symptoms, what was tried, what worked
+2. Classify: determine track (bug vs knowledge), problem_type, category, severity
+3. Search `.planning/solutions/` for related docs using grep-first filtering
+4. Assess overlap with existing docs
+5. Suggest filename: `[sanitized-slug]-[YYYY-MM-DD].md`
+
+### Phase 2: Assembly & Write
+
+**WAIT for all Phase 1 research to complete before proceeding.**
+
+Check the overlap assessment:
+
+| Overlap | Action |
+|---------|--------|
+| **High** — existing doc covers the same problem and solution | **Update the existing doc** with fresher context rather than creating a duplicate. Add `last_updated: YYYY-MM-DD` to frontmatter. |
+| **Moderate** — same area but different angle or solution | **Create a new doc**. Note the overlap for future consolidation. |
+| **Low or none** | **Create a new doc** normally. |
+
+Create directory if needed:
+```bash
+node -e "require('fs').mkdirSync('.planning/solutions/[category]/',{recursive:true})"
+```
+
+Write the solution document using the appropriate track template:
+
+**Bug track template:**
+```markdown
+---
+title: [Clear problem title]
+date: [YYYY-MM-DD]
+category: [category directory]
+module: [module or area]
+problem_type: [enum value]
+severity: [critical|high|medium|low]
+tags: [keyword-one, keyword-two]
+---
+
+# [Clear problem title]
+
+## Problem
+[1-2 sentence description of the issue and impact]
+
+## Symptoms
+- [Observable symptom or error]
+
+## What Didn't Work
+- [Attempted fix and why it failed]
+
+## Solution
+[The fix that worked, including code snippets]
+
+## Why This Works
+[Root cause explanation and why the fix addresses it]
+
+## Prevention
+- [Concrete practice, test, or guardrail]
+
+## Related
+- [Related docs or issues, if any]
+```
+
+**Knowledge track template:**
+```markdown
+---
+title: [Clear, descriptive title]
+date: [YYYY-MM-DD]
+category: [category directory]
+module: [module or area]
+problem_type: [enum value]
+severity: [critical|high|medium|low]
+tags: [keyword-one, keyword-two]
+---
+
+# [Clear, descriptive title]
+
+## Context
+[What situation, gap, or friction prompted this guidance]
+
+## Guidance
+[The practice, pattern, or recommendation with code examples]
+
+## Why This Matters
+[Rationale and impact of following or not following this guidance]
+
+## When to Apply
+- [Conditions or situations where this applies]
+
+## Examples
+[Concrete before/after or usage examples]
+
+## Related
+- [Related docs or issues, if any]
+```
+
+### Phase 3: Commit & Confirm
+
+```bash
+git add ".planning/solutions/[category]/[filename].md"
+git commit -m "docs(solutions): compound — [short title]"
+```
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► COMPOUND COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+File created:
+- .planning/solutions/[category]/[filename].md
+
+What's next?
+1. Continue workflow (recommended)
+2. View documentation
+3. Link related documentation
+```
+
+Present the "What's next?" options using the platform's blocking question tool. Wait for the user's selection before proceeding.
+
+**Alternate output (when updating an existing doc due to high overlap):**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► COMPOUND UPDATED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Overlap detected: .planning/solutions/[category]/[existing-file].md
+  Action: Updated existing doc with fresher context
+  Added: last_updated: [YYYY-MM-DD]
+
+File updated:
+- .planning/solutions/[category]/[existing-file].md
+```
+
+---
+
+## Lightweight Mode
+
+Single-pass alternative — same documentation, fewer tokens. No subagents, no cross-referencing, no duplicate detection.
+
+1. **Extract from conversation**: Identify the problem and solution from conversation history
+2. **Classify**: Determine track (bug vs knowledge), category, and filename using the schema from `$LEARNSHIP_DIR/references/solution-schema.md`
+3. **Write minimal doc**: Create `.planning/solutions/[category]/[filename].md` using the appropriate track template with:
+   - YAML frontmatter with track-appropriate fields
+   - Bug track: Problem, solution with key code snippets, one prevention tip
+   - Knowledge track: Context, guidance with key examples, one applicability note
+4. **Skip cross-referencing** to conserve context
+
+```bash
+node -e "require('fs').mkdirSync('.planning/solutions/[category]/',{recursive:true})"
+# Write the file
+git add ".planning/solutions/[category]/[filename].md"
+git commit -m "docs(solutions): compound — [short title] (lightweight)"
+```
+
+**Lightweight output:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► COMPOUND COMPLETE ✓ (lightweight)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+File created:
+- .planning/solutions/[category]/[filename].md
+
+Note: This was created in lightweight mode. For richer documentation
+(cross-references, overlap detection), re-run /compound in a fresh session.
+```
+
+**No subagents are launched. No parallel tasks. One file written.**
+
+---
+
+## The Compounding Philosophy
+
+Each documented solution compounds your project's knowledge:
+
+1. First time you solve a problem → Research (30 min)
+2. Document the solution → `.planning/solutions/` (5 min)
+3. Next time similar issue occurs → Quick lookup (2 min)
+4. Knowledge compounds → Team gets smarter
+
+**Each unit of engineering work should make subsequent units of work easier — not harder.**
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After documenting, offer based on what happened:
+
+> 💡 **Learning moment:** Solution captured. Compound the knowledge further:
+>
+> `@agentic-learning learn [solution domain]` — Active retrieval on the concept you just documented. You explain the root cause first, gaps get filled. This is how fixes become lasting pattern recognition.
+>
+> `@agentic-learning space` — Schedule this concept for spaced revisit. Writes to `docs/revisit.md`. Future sessions start with less decay.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning learn [domain]` · `@agentic-learning space` to turn this solution into a lasting pattern."*

package/learnship/workflows/debug.md

@@ -200,6 +200,13 @@ node -e "require('fs').mkdirSync('.planning/debug/resolved',{recursive:true})"
 mv ".planning/debug/[session-file]" ".planning/debug/resolved/"
 ```
 
+Suggest compounding the solution:
+```
+💡 Compound this fix? Run `/compound` to capture the problem, root cause,
+and solution while context is fresh. Future plan-phase runs will search
+these solutions before planning.
+```
+
 ## Step 9b: Update AGENTS.md Regressions
 
 If `AGENTS.md` exists at the project root, append a regression entry to the `## Regressions` section:

package/learnship/workflows/discuss-milestone.md

@@ -120,6 +120,11 @@ Goals: [N] captured
 Anti-goals: [N] captured
 
 ▶ Next: new-milestone [VERSION]  (will read this context automatically)
+
+💡 For ambitious milestones, consider running `/challenge` first to stress-test
+the scope through product and engineering lenses before committing.
+
+💡 Not sure what to build? Run `/ideate` for codebase-grounded idea generation.
 ```
 
 ---

package/learnship/workflows/execute-phase.md

@@ -82,6 +82,27 @@ Check if `@impeccable teach-impeccable` has been run for this project (look for
 
 Carry these principles through every task in every wave of this phase.
 
+## Step 2c: TDD Mode Check
+
+Read `test_first` from `.planning/config.json` (defaults to `false`).
+
+If `test_first` is `true`:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► TDD MODE ACTIVE — red-green-refactor per task
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+In TDD mode, each executor uses the red-green-refactor cycle:
+1. **Red** — write the failing test first
+2. **Verify red** — confirm the test fails
+3. **Green** — write minimum code to pass
+4. **Verify green** — confirm the test passes
+5. **Refactor** — clean up without changing behavior
+6. **Commit** — atomic commit (test + implementation together)
+
+Both inline (`@./agents/executor.md`) and subagent (`learnship-executor`) executors honor this setting.
+
 ## Step 3: Execute Waves
 
 Read `parallelization` from `.planning/config.json` (defaults to `false`).
@@ -323,7 +344,10 @@ git commit -m "docs: update AGENTS.md — phase [X] complete"
 **Phase [X]: [Name]** — all plans complete, goals verified.
 
 ▶ Next: verify-work [X]  (manual UAT)
+   Then: /review → /ship → /compound
    Then: discuss-phase [X+1] → plan-phase [X+1]
+
+💡 Working on sensitive files? Run `/guard [scope]` to enable safety mode.
 ```
 
 ---

package/learnship/workflows/guard.md

@@ -0,0 +1,164 @@
+---
+description: Safety mode — warn on destructive commands, lock file scope
+---
+
+# Guard
+
+Safety mode for sensitive phases. Warns before destructive commands, locks file scope to prevent accidental changes outside the working area, and persists guard state across sessions.
+
+**Usage:** `guard [scope]` — activate guard mode for a specific scope (directory, file pattern, or phase)
+**Usage:** `guard off` — deactivate guard mode
+
+## Step 1: Parse Arguments
+
+If argument is `off` → deactivate guard mode (Step 6).
+
+Otherwise, interpret the scope:
+- **Directory path** (e.g., `src/auth/`) → guard all files under that path
+- **File pattern** (e.g., `*.migration`) → guard files matching the pattern
+- **Phase number** (e.g., `3`) → guard files modified by that phase's plans
+- **No argument** → guard the current phase's file scope
+
+## Step 2: Determine File Scope
+
+**If a directory or pattern was provided:** Use it directly.
+
+**If a phase number was provided:**
+```bash
+# Extract files_modified from all plans in the phase
+grep -h "files_modified" .planning/phases/[padded_phase]-*/*-PLAN.md -A 50 2>/dev/null | grep "^ *-" | sed 's/^ *- //'
+```
+
+**If no argument — auto-detect from current phase:**
+```bash
+# Read current phase from STATE.md
+cat .planning/STATE.md 2>/dev/null | grep -i "phase"
+
+# Get files from current phase plans
+grep -rh "files_modified" .planning/phases/$(ls .planning/phases/ | sort | tail -1)/*-PLAN.md -A 50 2>/dev/null | grep "^ *-" | sed 's/^ *- //'
+```
+
+**Brownfield enhancement:** If `.planning/codebase/CONCERNS.md` exists, read it and auto-suggest guard scope for files flagged as high-risk:
+```bash
+cat .planning/codebase/CONCERNS.md 2>/dev/null | grep -i "risk\|sensitive\|critical\|production"
+```
+
+## Step 3: Activate Guard
+
+Write guard state to `.planning/guard-state.md`:
+
+```markdown
+---
+active: true
+activated: [ISO timestamp]
+scope: [description of what's guarded]
+---
+
+# Guard Mode Active
+
+## Protected Scope
+
+[list of files/directories/patterns being guarded]
+
+## Destructive Command Warnings
+
+The following commands will trigger a warning before execution:
+- `rm`, `rm -rf`, `git reset --hard`, `git clean -fd`
+- `DROP TABLE`, `DELETE FROM`, `TRUNCATE`
+- `git push --force`, `git rebase` (on shared branches)
+- Any write to files outside the guarded scope
+
+## Session Log
+
+- [timestamp]: Guard activated — scope: [scope description]
+```
+
+```bash
+git add .planning/guard-state.md
+git commit -m "docs: activate guard mode — scope: [description]"
+```
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► GUARD MODE ACTIVE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Protected scope:
+[list of guarded files/dirs]
+
+Warnings will trigger for:
+- Destructive commands (rm -rf, git reset --hard, DROP TABLE)
+- Writes outside guarded scope
+- Force pushes and rebases on shared branches
+
+▶ Run: guard off  — to deactivate
+```
+
+## Step 4: Guard Behavior (While Active)
+
+When guard mode is active (`.planning/guard-state.md` exists with `active: true`):
+
+**Before any file write:** Check if the target file is within the guarded scope.
+- **Inside scope** → proceed normally
+- **Outside scope** → warn: "⚠ Guard: This file is outside the guarded scope ([scope]). Proceed anyway?"
+
+**Before destructive commands:** Always warn:
+```
+⚠ Guard: Destructive command detected: [command]
+This will [description of what it does].
+Proceed? (yes/no)
+```
+
+**Log all guard events** to the Session Log in `guard-state.md`.
+
+## Step 5: Persistent State
+
+Guard mode persists across sessions via `.planning/guard-state.md`. Any workflow that reads `.planning/config.json` should also check for active guard state:
+
+```bash
+# Check if guard is active
+grep -q "active: true" .planning/guard-state.md 2>/dev/null && echo "GUARD_ACTIVE"
+```
+
+## Step 6: Deactivate
+
+When `guard off` is invoked:
+
+Update `.planning/guard-state.md`:
+```markdown
+---
+active: false
+activated: [original timestamp]
+deactivated: [ISO timestamp]
+scope: [original scope]
+---
+```
+
+```bash
+git add .planning/guard-state.md
+git commit -m "docs: deactivate guard mode"
+```
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► GUARD MODE DEACTIVATED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Guard was active for: [duration]
+Events logged: [N]
+```
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After activating guard, offer:
+
+> 💡 **Learning moment:** Safety modes reflect risk awareness:
+>
+> `@agentic-learning either-or` — When should you use guard mode vs just being careful? Log the decision criteria for future reference.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning either-or` to log when guard mode is worth the overhead."*

package/learnship/workflows/help.md

@@ -16,7 +16,7 @@ You only need to remember **5 commands** to use learnship effectively:
 | `/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 |
+| `/help` | This screen — see all 49 commands |
 
 Everything else below is discoverable from `/ls` as you go.
 
@@ -79,6 +79,18 @@ Everything else below is discoverable from `/ls` as you go.
 | `/check-todos` | Review and act on captured todos |
 | `/add-tests [N]` | Generate unit and E2E tests post-execution |
 
+### Compounding & Quality — capture, review, ship
+
+| Workflow | What it does |
+|----------|-------------|
+| `/compound` | Capture a solution while context is fresh → `.planning/solutions/` |
+| `/review [mode]` | Multi-persona code review (correctness, testing, security, performance, maintainability) |
+| `/challenge [description]` | Product + engineering challenge gate — is this worth building? |
+| `/ship` | Ship pipeline: test → lint → commit → push → PR |
+| `/ideate [focus]` | Codebase-grounded divergent thinking — discover what to work on |
+| `/guard [scope\|off]` | Safety mode — warn on destructive commands, lock file scope |
+| `/sync-docs` | Detect stale documentation after code changes |
+
 ### Decision Intelligence — institutional memory
 
 | Workflow | What it does |
@@ -119,7 +131,7 @@ Everything else below is discoverable from `/ls` as you go.
 
 **Standard phase loop:**
 ```
-/discuss-phase N → /plan-phase N → /execute-phase N → /verify-work N
+/discuss-phase N → /plan-phase N → /execute-phase N → /verify-work N → /review → /ship → /compound
 ```
 
 **Quick fix:**