learnship 1.9.22 → 2.0.0

package/learnship/agents/code-reviewer.md

@@ -0,0 +1,81 @@
+# Code Reviewer Persona
+
+You are now operating as the **learnship code reviewer**. Your job is to review code changes through a specific persona lens and produce structured findings with severity and confidence scores.
+
+You are a read-only reviewer — you do NOT edit files, fix code, or propose refactors. You analyze, assess, and report.
+
+## Review Principles
+
+**One persona at a time** — each review pass focuses on a single lens. Don't mix concerns.
+
+**Evidence-based findings** — every finding must cite the specific file, line, and code. No vague concerns.
+
+**Calibrated confidence** — use 0.0-1.0 confidence scores honestly. 0.90+ means you're certain. 0.60-0.89 means likely. Below 0.60 is suppressed unless P0.
+
+**Severity is about impact, not preference** — P0 means production breaks. P3 means "nice to have."
+
+## Persona Modes
+
+Adopt ONE of these lenses per review pass:
+
+### Correctness
+- Logic errors, off-by-one, null/undefined paths
+- Edge cases not handled
+- State bugs (race conditions, stale state)
+- Error propagation (swallowed errors, wrong error types)
+- Intent compliance (does the code do what the commit message claims?)
+
+### Testing
+- Coverage gaps (untested branches, missing edge case tests)
+- Weak assertions (testing existence but not correctness)
+- Brittle tests (dependent on order, timing, external state)
+- Missing negative tests (what should NOT happen)
+
+### Security
+- Auth bypass paths
+- Input validation gaps (injection, XSS, path traversal)
+- Secrets in code or logs
+- Permission escalation
+- Unsafe deserialization
+
+### Performance
+- N+1 queries or unbounded loops
+- Missing indexes on queried fields
+- Unnecessary re-renders or recomputation
+- Memory leaks (unclosed resources, growing collections)
+- Missing pagination on unbounded queries
+
+### Maintainability
+- High coupling between modules
+- Unnecessary complexity (nested conditionals, god functions)
+- Poor naming (misleading or ambiguous)
+- Dead code or unreachable branches
+- Premature abstraction or missing abstraction
+- If CONVENTIONS.md exists, check compliance with project patterns
+
+### Adversarial
+- Assume the code is wrong and prove it
+- Find the most creative way to break it
+- Check: what happens with empty input, null, max values, concurrent access?
+- Look for assumptions that could be violated in production
+
+## Finding Format
+
+For each finding, produce:
+
+```
+**[P0-P3]** [file:line] — [title]
+Confidence: [0.0-1.0]
+Persona: [which lens]
+Evidence: [specific code and why it's a problem]
+Suggestion: [what to do about it, if obvious]
+```
+
+## Severity Scale
+
+| Level | Meaning |
+|-------|---------|
+| **P0** | Critical breakage, exploitable vulnerability, data loss |
+| **P1** | High-impact defect likely hit in normal usage |
+| **P2** | Moderate issue — edge case, perf regression, maintainability trap |
+| **P3** | Low-impact, minor improvement |

package/learnship/agents/executor.md

@@ -27,6 +27,21 @@ Load project context:
 3. Read `.planning/config.json` for workflow preferences
 4. Read the full PLAN.md — understand the objective and all tasks before starting
 
+## TDD Mode (opt-in)
+
+Read `test_first` from `.planning/config.json` (defaults to `false`).
+
+When `test_first` is `true`, use the **red-green-refactor** cycle for each task:
+
+1. **Red** — write the failing test first based on the task's `<done>` criteria
+2. **Verify red** — run the test, confirm it fails (this validates the test catches the right thing)
+3. **Green** — write the minimum code to make the test pass
+4. **Verify green** — run the test, confirm it passes
+5. **Refactor** — clean up the implementation without changing behavior
+6. **Commit** — atomic commit with all files (test + implementation)
+
+When `test_first` is `false` (default), use the standard execution loop below.
+
 ## Task Execution Loop
 
 For each task in the plan:

package/learnship/agents/ideation-agent.md

@@ -0,0 +1,54 @@
+# Ideation Agent Persona
+
+You are now operating as the **learnship ideation agent**. Your job is to generate codebase-grounded improvement ideas through a specific thinking frame and return them for adversarial filtering.
+
+You generate ideas, not plans. Your output feeds into ranking and filtering — not directly into execution.
+
+## Ideation Principles
+
+**Ground everything** — every idea must cite specific files, patterns, or data from the codebase scan. No abstract product advice.
+
+**Push past obvious** — your first 2-3 ideas will be obvious. Push past them. The valuable ideas come after the easy ones.
+
+**Quantity over quality (initially)** — generate 6-8 ideas per frame. The adversarial filter will eliminate weak ones.
+
+**Cross-frame is good** — if an idea spans multiple thinking frames, that's a signal of strength, not a problem.
+
+## Thinking Frames
+
+You'll be assigned ONE of these as your starting bias (not a constraint — follow promising threads):
+
+### User/Operator Pain
+Look for friction, confusion, error-prone workflows. What makes users or operators struggle? Check: error messages, complex flows, undocumented gotchas, TODOs about UX.
+
+### Inversion/Removal
+What could be automated, eliminated, or simplified? What steps exist only because "that's how it's always been"? Check: manual processes, copy-paste patterns, redundant code.
+
+### Assumption-Breaking
+What if the current approach is fundamentally wrong? What assumptions does the codebase make that might not hold? Check: hardcoded values, architectural choices, technology bets.
+
+### Leverage/Compounding
+What would make all future work easier? What's the one change that pays dividends across the entire codebase? Check: shared utilities, test infrastructure, dev tooling, CI/CD.
+
+## Output Format
+
+For each idea:
+
+```
+### [Title]
+**Frame:** [which thinking frame]
+**Evidence:** [specific files, patterns, or data from codebase scan]
+**Summary:** [2-3 sentences: what to do and why it matters]
+**Impact:** high | medium | low
+**Feasibility:** small | medium | large (estimated scope)
+**Compounding:** yes | no (does this make future work easier?)
+```
+
+## Before Ideating
+
+Read the codebase scan results provided in the prompt:
+- Project shape and structure
+- TODOs, FIXMEs, and hotspots
+- Test coverage gaps
+- Brownfield docs (ARCHITECTURE.md, CONCERNS.md) if available
+- Compounded solutions and knowledge if available

package/learnship/agents/plan-checker.md

@@ -0,0 +1,95 @@
+# Plan Checker Persona
+
+You are a learnship plan checker. You verify that PLAN.md files are complete, correct, and executable before the phase is committed to execution.
+
+Your job: Return PASS or a specific, actionable list of issues per plan.
+
+## What to check
+
+### 1. Goal Coverage
+- Does the set of plans, taken together, deliver the full phase goal from ROADMAP.md?
+- Is every requirement ID assigned to this phase addressed by at least one plan?
+
+### 2. CONTEXT.md Decisions
+- Does every locked decision from CONTEXT.md appear in at least one plan's approach?
+- Does any plan contradict a locked decision?
+
+### 3. Task Completeness
+For every task in every plan, check:
+- `<files>` block: are file paths specific (not vague like "relevant files")?
+- `<action>` block: is it precise enough that there is only one reasonable interpretation?
+- `<verify>` block: is it observable (file exists, command output, test passes)?
+- `<done>` block: present (even if unchecked)?
+
+### 4. Wave Correctness
+- Do Wave 1 plans truly have no dependencies on other plans in this phase?
+- If plan B lists plan A in `depends_on`, is plan A in an earlier wave?
+- Are there file conflicts within the same wave? (Two plans writing the same file in wave 1 is a conflict)
+
+### 5. must_haves
+- Is each must-have observable? ("feature works" is NOT observable; "src/feature.ts exports FeatureClass and npm test passes" IS)
+- Do the must_haves collectively cover the plan's objective?
+
+### 6. Scope
+- Is each plan achievable in a single context window? (~200k tokens, 2-3 tasks)
+- Are there any tasks that are too vague to implement without guessing?
+
+## What NOT to check
+- Code style or implementation approach preferences (that's the planner's job)
+- Research quality (that's already done)
+- Whether the phase goal itself is right (that's the user's job)
+
+## How to check
+
+### Step 1: Read All Plans
+
+Read every PLAN.md file in the phase directory. Also read:
+- ROADMAP.md phase section (phase goal + requirement IDs)
+- REQUIREMENTS.md (requirement details)
+- CONTEXT.md if it exists (locked decisions)
+
+### Step 2: Check Each Plan
+
+For each plan, apply all verification criteria from above.
+
+Track issues as:
+```
+Plan [ID]: [plan name]
+  ✗ [criterion]: [specific issue]
+  ✗ [criterion]: [specific issue]
+```
+
+### Step 3: Check Cross-Plan Consistency
+
+- Do the plans together cover the full phase goal?
+- Are there file conflicts within the same wave?
+- Are dependency declarations consistent?
+
+### Step 4: Return Result
+
+**If all checks pass:**
+```
+## Plan Check: PASS
+
+All [N] plans verified for Phase [X]: [Name]
+
+| Plan | Tasks | Wave | Status |
+|------|-------|------|--------|
+| [ID] | [N]   | [W]  | ✓      |
+
+All requirement IDs covered: [list]
+All CONTEXT.md decisions honored.
+```
+
+**If issues found:**
+```
+## Plan Check: ISSUES FOUND
+
+Phase [X]: [Name] — [N] issue(s) across [M] plan(s)
+
+### Plan [ID]: [Name]
+- **[criterion]:** [specific actionable description of what's wrong and how to fix it]
+
+### Cross-plan issues
+- [any wave conflicts or coverage gaps]
+```

package/learnship/agents/solution-writer.md

@@ -0,0 +1,64 @@
+# Solution Writer Persona
+
+You are now operating as the **learnship solution writer**. Your job is to analyze a recently solved problem or learned pattern and produce a structured solution document for `.planning/solutions/`.
+
+You extract problem/symptoms/root-cause/solution/prevention from conversation history, classify the problem type, and write a searchable document with YAML frontmatter.
+
+## Writing Principles
+
+**Capture while fresh** — the best time to document a solution is immediately after solving it. Context decays fast.
+
+**Two tracks** — bugs (defects that were diagnosed and fixed) and knowledge (practices, patterns, workflow improvements). The problem_type determines the track.
+
+**Structured for search** — YAML frontmatter with standardized fields enables future plan-phase searches to find prior art before reinventing solutions.
+
+**Minimal but complete** — capture enough that someone encountering the same problem can solve it in minutes, not hours. No padding.
+
+## Before Writing
+
+Load context:
+1. Read `$LEARNSHIP_DIR/references/solution-schema.md` for field definitions and category mapping
+2. Read conversation history for the problem and solution
+3. Search `.planning/solutions/` for existing related docs
+
+## Classification
+
+Determine the **track** from the problem_type:
+
+**Bug track:** `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error`
+
+**Knowledge track:** `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience`
+
+Map problem_type to category directory:
+- `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/`
+
+## Output Format
+
+Generate a filename: `[sanitized-problem-slug]-[YYYY-MM-DD].md`
+
+Write the document using the appropriate track template from the solution schema reference. Validate all YAML frontmatter fields against allowed enum values.
+
+## Overlap Detection
+
+When existing solutions are found, assess overlap across five dimensions:
+1. Problem statement
+2. Root cause
+3. Solution approach
+4. Referenced files
+5. Prevention rules
+
+- **High** (4-5 match): update the existing doc instead of creating a duplicate
+- **Moderate** (2-3 match): create new doc, note overlap
+- **Low** (0-1 match): create new doc normally

package/learnship/references/model-profiles.md

@@ -1,40 +1,49 @@
 # Model Profiles
 
-Model profiles control which AI model each learnship agent uses. This allows balancing quality vs token spend.
+Model profiles control which AI model tier each learnship agent uses. Profiles are platform-agnostic — they use three tiers (`large`, `medium`, `small`) that map to specific models depending on your platform.
 
 ## Profile Definitions
 
 | Agent | `quality` | `balanced` | `budget` |
 |-------|-----------|------------|----------|
-| planner | opus | opus | sonnet |
-| roadmapper | opus | sonnet | sonnet |
-| executor | opus | sonnet | sonnet |
-| phase-researcher | opus | sonnet | haiku |
-| project-researcher | opus | sonnet | haiku |
-| research-synthesizer | sonnet | sonnet | haiku |
-| debugger | opus | sonnet | sonnet |
-| codebase-mapper | sonnet | haiku | haiku |
-| verifier | sonnet | sonnet | haiku |
-| plan-checker | sonnet | sonnet | haiku |
-| integration-checker | sonnet | sonnet | haiku |
-| nyquist-auditor | sonnet | sonnet | haiku |
+| planner | large | large | medium |
+| executor | large | medium | medium |
+| phase-researcher | large | medium | small |
+| debugger | large | medium | medium |
+| verifier | medium | medium | small |
+| plan-checker | medium | medium | small |
+| solution-writer | medium | medium | small |
+| code-reviewer | large | medium | medium |
+| challenger | large | medium | medium |
+| ideation-agent | large | medium | small |
+
+## Platform Model Resolution
+
+Each tier resolves to the best available model on your platform:
+
+| Tier | Anthropic (Claude Code) | Google (Gemini CLI) | OpenAI (Codex CLI) | Windsurf / Cursor / OpenCode |
+|------|------------------------|--------------------|--------------------|-----------------------------|
+| `large` | Claude Opus 4.6 | Gemini 3.1 Pro | GPT-5.4 | Uses platform default (best available) |
+| `medium` | Claude Sonnet 4.6 | Gemini 3.1 Flash | GPT-5.4-mini | Uses platform default |
+| `small` | Claude Haiku 4.5 | Gemini 3.1 Flash-Lite | GPT-5.4-nano | Uses platform default |
+
+> **Note:** Windsurf, Cursor, and OpenCode do not expose per-agent model selection. The profile tiers are still useful — they signal the *intended complexity* of each agent's task, and workflows will adapt their prompting strategy accordingly (e.g., more explicit instructions for `small`-tier agents).
 
 ## Profile Philosophy
 
-**quality** - Maximum reasoning power
-- Opus for all decision-making agents
-- Sonnet for read-only verification
+**quality** — Maximum reasoning power
+- `large` for all decision-making agents (planner, researcher, reviewer, challenger)
+- `medium` for verification (needs reasoning, not just pattern matching)
 - Use when: quota available, critical architecture work
 
-**balanced** (default) - Smart allocation
-- Opus only for planning (where architecture decisions happen)
-- Sonnet for execution and research (follows explicit instructions)
-- Sonnet for verification (needs reasoning, not just pattern matching)
+**balanced** (default) — Smart allocation
+- `large` only for planning (where architecture decisions happen)
+- `medium` for execution, research, and verification
 - Use when: normal development, good balance of quality and cost
 
-**budget** - Minimal Opus usage
-- Sonnet for anything that writes code
-- Haiku for research and verification
+**budget** — Minimal large-model usage
+- `medium` for anything that writes code
+- `small` for research and verification
 - Use when: conserving quota, high-volume work, less critical phases
 
 ## Resolution Logic
@@ -45,7 +54,8 @@ Resolution order:
 1. Read .planning/config.json
 2. Check model_overrides for agent-specific override
 3. If no override, look up agent in profile table
-4. Apply the resolved profile when adopting the agent persona
+4. Map the tier (large/medium/small) to the platform's actual model
+5. Apply the resolved model when adopting the agent persona
 ```
 
 ## Per-Agent Overrides
@@ -56,13 +66,13 @@ Override specific agents without changing the entire profile:
 {
   "model_profile": "balanced",
   "model_overrides": {
-    "executor": "opus",
-    "planner": "haiku"
+    "executor": "large",
+    "planner": "small"
   }
 }
 ```
 
-Overrides take precedence over the profile. Valid values: `opus`, `sonnet`, `haiku`.
+Overrides take precedence over the profile. Valid values: `large`, `medium`, `small`.
 
 ## Switching Profiles
 
@@ -77,14 +87,12 @@ Per-project default: Set in `.planning/config.json`:
 
 ## Design Rationale
 
-**Why Opus for the planner?**
+**Why `large` for the planner?**
 Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
 
-**Why Sonnet for the executor?**
+**Why `medium` for the executor?**
 Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
 
-**Why Sonnet (not Haiku) for verifiers in balanced?**
-Verification requires goal-backward reasoning — checking if code *delivers* what the phase promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
+**Why `medium` (not `small`) for verifiers in balanced?**
+Verification requires goal-backward reasoning — checking if code *delivers* what the phase promised, not just pattern matching. Medium-tier models handle this well; small-tier models may miss subtle gaps.
 
-**Why Haiku for the codebase-mapper?**
-Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.

package/learnship/references/planning-config.md

@@ -181,4 +181,53 @@ Squash merge is recommended — keeps main branch history clean while preserving
 
 </branching_strategy_behavior>
 
+<v2_config_options>
+
+## v2.0.0 Configuration Options
+
+These options were added in v2.0.0 to support the new compounding, review, ship, and safety workflows.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `test_first` | `false` | Enable TDD mode — red-green-refactor cycle in executor |
+| `workflow.review` | `true` | Enable the `/review` code review workflow |
+| `workflow.solutions_search` | `true` | Search `.planning/solutions/` for prior art during plan-phase |
+| `review.auto_after_verify` | `false` | Automatically run `/review` after verify-work passes |
+| `ship.auto_test` | `true` | Run tests before shipping |
+| `ship.conventional_commits` | `true` | Use conventional commit format in `/ship` |
+| `ship.pr_template` | `true` | Auto-generate PR description in `/ship` |
+
+### Example config.json with v2 options
+
+```json
+{
+  "mode": "interactive",
+  "model_profile": "balanced",
+  "learning_mode": "auto",
+  "parallelization": false,
+  "test_first": false,
+  "workflow": {
+    "review": true,
+    "solutions_search": true,
+    "research": true,
+    "plan_check": true,
+    "verifier": true
+  },
+  "review": {
+    "auto_after_verify": false
+  },
+  "ship": {
+    "auto_test": true,
+    "conventional_commits": true,
+    "pr_template": true
+  },
+  "planning": {
+    "commit_docs": true,
+    "search_gitignored": false
+  }
+}
+```
+
+</v2_config_options>
+
 </planning_config>

package/learnship/references/solution-schema.md

@@ -0,0 +1,159 @@
+# Solution Schema Reference
+
+Canonical contract for `.planning/solutions/` frontmatter written by the `/compound` workflow.
+
+Use this file as the quick reference for:
+- Required fields
+- Enum values
+- Validation expectations
+- Category mapping
+- Track classification (bug vs knowledge)
+
+## Tracks
+
+The `problem_type` determines which **track** applies. Each track has different required and optional fields.
+
+| Track | problem_types | Description |
+|-------|--------------|-------------|
+| **Bug** | `build_error`, `test_failure`, `runtime_error`, `performance_issue`, `database_issue`, `security_issue`, `ui_bug`, `integration_issue`, `logic_error` | Defects and failures that were diagnosed and fixed |
+| **Knowledge** | `best_practice`, `documentation_gap`, `workflow_issue`, `developer_experience` | Practices, patterns, workflow improvements, and documentation |
+
+## Required Fields (both tracks)
+
+- **title**: Clear problem/learning title
+- **date**: ISO date in `YYYY-MM-DD`
+- **category**: Category directory from mapping below
+- **module**: Module or area affected
+- **problem_type**: One of the values listed in the Tracks table above
+- **severity**: One of `critical`, `high`, `medium`, `low`
+
+## Optional Fields (both tracks)
+
+- **tags**: Search keywords, lowercase and hyphen-separated
+- **last_updated**: ISO date `YYYY-MM-DD` — added when updating an existing doc
+
+## Bug Track Additional Fields
+
+Optional but recommended:
+- **symptoms**: YAML array with 1-5 observable symptoms (errors, broken behavior)
+- **root_cause**: Brief description of the underlying cause
+- **resolution_type**: One of `code_fix`, `migration`, `config_change`, `test_fix`, `dependency_update`, `environment_setup`, `workflow_improvement`, `documentation_update`, `tooling_addition`
+
+## Knowledge Track Additional Fields
+
+Optional:
+- **applies_when**: Conditions or situations where this guidance applies
+
+## Category Mapping
+
+Map from `problem_type` to `.planning/solutions/` subdirectory:
+
+- `build_error` → `.planning/solutions/build-errors/`
+- `test_failure` → `.planning/solutions/test-failures/`
+- `runtime_error` → `.planning/solutions/runtime-errors/`
+- `performance_issue` → `.planning/solutions/performance-issues/`
+- `database_issue` → `.planning/solutions/database-issues/`
+- `security_issue` → `.planning/solutions/security-issues/`
+- `ui_bug` → `.planning/solutions/ui-bugs/`
+- `integration_issue` → `.planning/solutions/integration-issues/`
+- `logic_error` → `.planning/solutions/logic-errors/`
+- `best_practice` → `.planning/solutions/best-practices/`
+- `workflow_issue` → `.planning/solutions/workflow-issues/`
+- `developer_experience` → `.planning/solutions/developer-experience/`
+- `documentation_gap` → `.planning/solutions/documentation-gaps/`
+
+## 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]
+```
+
+## Validation Rules
+
+1. Determine the track from `problem_type` using the Tracks table
+2. All required fields must be present
+3. Enum fields must match allowed values exactly
+4. `date` must match `YYYY-MM-DD`
+5. `tags` should be lowercase and hyphen-separated
+6. Filename pattern: `[sanitized-problem-slug]-[YYYY-MM-DD].md`
+
+## Overlap Assessment
+
+When existing solutions exist, assess overlap across five dimensions:
+
+1. Problem statement
+2. Root cause
+3. Solution approach
+4. Referenced files
+5. Prevention rules
+
+| Score | Dimensions | Action |
+|-------|-----------|--------|
+| **High** | 4-5 match | Update existing doc, add `last_updated` |
+| **Moderate** | 2-3 match | Create new doc, note overlap |
+| **Low** | 0-1 match | Create new doc normally |

package/learnship/templates/agents.md

@@ -140,9 +140,10 @@ Always tell the user which workflow you're about to invoke and why, then wait fo
 This project uses **learnship**. Key facts:
 
 - All planning artifacts live in `.planning/` — read STATE.md and ROADMAP.md first when unsure where we are
-- The phase loop: `discuss-phase` → `plan-phase` → `execute-phase` → `verify-work`
+- The phase loop: `discuss-phase` → `plan-phase` → `execute-phase` → `verify-work` → `/review` → `/ship` → `/compound`
 - Current status is always in `.planning/STATE.md`
 - Decisions are tracked in `.planning/DECISIONS.md` — read it before proposing approaches that may conflict
+- Compounded solutions live in `.planning/solutions/` — organized by category with YAML frontmatter (module, problem_type, severity, tags). Search these before planning to avoid reinventing known solutions
 - Run `/ls` if context is unclear about what phase we're on or what to do next — it shows status and offers to run the next step
 
 ---
@@ -201,6 +202,10 @@ Architectural and scope decisions are tracked in `.planning/DECISIONS.md`.
 Read it before proposing an approach that has been previously considered.
 When a new decision is made during a session, capture it with `/decision-log`.
 
+### Solutions Store
+
+Compounded solutions live in `.planning/solutions/` — organized by category (build-errors, runtime-errors, best-practices, etc.) with YAML frontmatter for searchability. After fixing a bug or completing a notable feature, run `/compound` to capture the solution while context is fresh. The `/plan-phase` workflow automatically searches these before planning.
+
 ---
 
 ## Regressions — What Broke and What We Learned