learnship 1.9.24 → 2.0.0

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

package/learnship/workflows/challenge.md

@@ -0,0 +1,189 @@
+---
+description: Product + engineering challenge gate — is this worth building?
+---
+
+# Challenge
+
+Product and engineering challenge gate. Asks forcing questions to determine whether a proposed feature, project, or milestone is worth building — before investing in planning and execution.
+
+Two lenses:
+- **Product lens:** "Is this worth building?" — demand, specificity, alternatives, user impact
+- **Engineering lens:** "Will it hold?" — complexity, maintainability, scalability, risk
+
+**Usage:** `challenge` — challenge the current milestone or phase
+**Usage:** `challenge [description]` — challenge a specific idea or proposal
+
+## Step 1: Gather Context
+
+Read available project context:
+
+```bash
+cat .planning/DECISIONS.md 2>/dev/null
+cat .planning/KNOWLEDGE.md 2>/dev/null
+ls .planning/solutions/ 2>/dev/null
+```
+
+**Brownfield enhancement:** If `.planning/codebase/` exists, also read:
+```bash
+cat .planning/codebase/ARCHITECTURE.md 2>/dev/null
+cat .planning/codebase/CONCERNS.md 2>/dev/null
+```
+
+If a description argument was provided, use it as the proposal to challenge.
+
+If no argument: read `.planning/ROADMAP.md` and `.planning/STATE.md` to identify the current or next milestone/phase as the proposal.
+
+## Step 2: Product Challenge
+
+Read `parallelization` from `.planning/config.json` (defaults to `false`).
+
+**If `parallelization` is `true` (subagent mode):**
+
+```
+Task(
+  subagent_type="learnship-challenger",
+  prompt="
+    <objective>
+    Run the PRODUCT lens challenge on this proposal:
+    [proposal description]
+
+    Ask 3-5 forcing questions from the product perspective:
+    1. Who specifically wants this? (not 'users' — name the persona and their pain)
+    2. What do they do today without it? (status quo is always the competitor)
+    3. How would you know it succeeded? (concrete metric, not 'engagement')
+    4. What's the narrowest version that still delivers value?
+    5. What are you saying NO to by building this?
+
+    Read DECISIONS.md and KNOWLEDGE.md for context on prior decisions.
+    If ARCHITECTURE.md and CONCERNS.md exist, validate against existing architecture.
+
+    Return: answers to each question + verdict (proceed/rethink/reduce-scope)
+    </objective>
+
+    <files_to_read>
+    - .planning/DECISIONS.md (if exists)
+    - .planning/KNOWLEDGE.md (if exists)
+    - .planning/codebase/ARCHITECTURE.md (if exists)
+    - .planning/codebase/CONCERNS.md (if exists)
+    </files_to_read>
+  "
+)
+```
+
+**If `parallelization` is `false` (sequential mode):**
+
+Using `@./agents/challenger.md` as your challenge persona, ask the 3-5 product forcing questions and answer them based on available context.
+
+## Step 3: Engineering Challenge
+
+**If `parallelization` is `true`:**
+
+```
+Task(
+  subagent_type="learnship-challenger",
+  prompt="
+    <objective>
+    Run the ENGINEERING lens challenge on this proposal:
+    [proposal description]
+
+    Ask 3-5 forcing questions from the engineering perspective:
+    1. What's the complexity ceiling? (will this stay simple or inevitably grow complex?)
+    2. What existing patterns does this break? (check ARCHITECTURE.md)
+    3. What's the failure mode? (when this breaks, what happens to the user?)
+    4. What does this make harder later? (second-order effects on maintenance)
+    5. Is there a simpler approach that delivers 80% of the value?
+
+    Read DECISIONS.md and KNOWLEDGE.md for context on prior decisions.
+    Search .planning/solutions/ for related past issues.
+
+    Return: answers to each question + verdict (proceed/rethink/reduce-scope)
+    </objective>
+
+    <files_to_read>
+    - .planning/DECISIONS.md (if exists)
+    - .planning/KNOWLEDGE.md (if exists)
+    - .planning/codebase/ARCHITECTURE.md (if exists)
+    </files_to_read>
+  "
+)
+```
+
+**If `parallelization` is `false`:**
+
+Using `@./agents/challenger.md`, switch to the engineering lens and ask the 3-5 engineering forcing questions.
+
+## Step 4: Synthesize Verdict
+
+Combine both lenses into a verdict:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ learnship ► CHALLENGE COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Proposal: [description]
+
+## Product Lens
+[summary of product challenge findings]
+
+## Engineering Lens
+[summary of engineering challenge findings]
+
+## Verdict: [PROCEED | RETHINK | REDUCE SCOPE]
+
+[1-3 sentence rationale]
+
+[If RETHINK: specific concerns that need addressing]
+[If REDUCE SCOPE: suggested narrower scope]
+[If PROCEED: key risks to monitor]
+```
+
+Present the verdict using the platform's blocking question tool:
+- **Proceed as planned** → continue to planning
+- **Adjust scope** → describe adjustments, then re-challenge or proceed
+- **Rethink** → go back to ideation or discussion
+
+## Step 5: Record Decision
+
+If the user makes a decision based on the challenge:
+
+```bash
+# Append to DECISIONS.md if it exists
+cat >> .planning/DECISIONS.md << 'EOF'
+
+### DEC-[NNN]: [Challenge verdict — proposal title]
+
+**Date:** [YYYY-MM-DD]
+**Type:** scope
+**Context:** Challenged via `/challenge` — product + engineering lens
+**Decision:** [proceed | reduced scope | rethought]
+**Rationale:** [key reasons from both lenses]
+EOF
+
+git add .planning/DECISIONS.md
+git commit -m "docs: challenge verdict — [proposal title]"
+```
+
+---
+
+## Integration Points
+
+- `/new-project` Step 7: optionally suggest `/challenge` before committing to scope
+- `/discuss-milestone`: suggest `/challenge` for ambitious milestones
+- `/quick --challenge`: flag for quick tasks that warrant a sanity check
+
+---
+
+## Learning Checkpoint
+
+Read `learning_mode` from `.planning/config.json`.
+
+**If `auto`:** After the challenge, offer:
+
+> 💡 **Learning moment:** Challenge gates sharpen product thinking:
+>
+> `@agentic-learning either-or` — Which lens (product vs engineering) surfaced the most important concern? Log the reasoning pattern for future decisions.
+>
+> `@agentic-learning brainstorm [proposal topic]` — If the verdict was "rethink," use collaborative brainstorming to explore alternative approaches.
+
+**If `manual`:** Add quietly: *"Tip: `@agentic-learning either-or` to log which challenge lens was most valuable."*

package/learnship/workflows/complete-milestone.md

@@ -163,6 +163,15 @@ git add AGENTS.md
 git commit -m "docs: update AGENTS.md — milestone [VERSION] complete"
 ```
 
+## Step 7c: Sync Documentation
+
+Suggest running `/sync-docs` before the release tag to catch stale documentation:
+
+```
+💡 Before tagging the release, consider running `/sync-docs` to detect
+any documentation that drifted during this milestone.
+```
+
 ## Step 8: Offer Next Milestone
 
 Ask: "Ready to start the next milestone?"