learnship 1.9.22 → 2.0.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "learnship",
-  "description": "Agentic engineering done right — 42 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system. Works with Claude Code, Windsurf, Cursor, Gemini CLI, OpenCode, and Codex.",
-  "version": "1.9.22",
+  "description": "Agentic engineering done right — 49 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system. Works with Claude Code, Windsurf, Cursor, Gemini CLI, OpenCode, and Codex.",
+  "version": "2.0.0",
   "author": {
     "name": "Favio Vazquez",
     "email": "favio.vazquezp@gmail.com"

package/.cursor-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "learnship",
   "displayName": "learnship",
-  "description": "Agentic engineering done right — 42 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
-  "version": "1.9.22",
+  "description": "Agentic engineering done right — 49 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
+  "version": "2.0.0",
   "logo": "assets/logo.png",
   "author": {
     "name": "Favio Vazquez",

package/README.md

@@ -10,7 +10,7 @@
   <a href="https://github.com/FavioVazquez/learnship/stargazers"><img src="https://img.shields.io/github/stars/FavioVazquez/learnship?style=flat&color=f59e0b" alt="Stars"></a>
   <a href="https://www.npmjs.com/package/learnship"><img src="https://img.shields.io/npm/v/learnship?color=cb3837&label=npm" alt="npm"></a>
   <img src="https://img.shields.io/badge/platforms-6-0ea5e9" alt="6 platforms">
-  <img src="https://img.shields.io/badge/workflows-42-3b82f6" alt="42 workflows">
+  <img src="https://img.shields.io/badge/workflows-49-3b82f6" alt="49 workflows">
 </p>
 
 <p align="center">
@@ -36,7 +36,8 @@ Every serious AI coding tool (Claude Code, Cursor, Manus, Devin) converges on th
 learnship gives you that harness as a portable, open-source layer that runs inside Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, or Codex CLI and adds three things your agent doesn't have by default:
 
 - **Persistent memory.** `/new-project` generates an `AGENTS.md` at your project root. Windsurf, Claude Code, and Cursor load it automatically every session; on other platforms the workflows reference it explicitly. No more repeating yourself.
-- **Structured process.** A repeatable phase loop (Discuss → Plan → Execute → Verify) with spec-driven plans, wave-ordered execution, and UAT-driven verification. The harness controls what context reaches the agent at each step.
+- **Structured process.** A repeatable phase loop (Discuss → Plan → Execute → Verify → Review → Ship → Compound) with spec-driven plans, wave-ordered execution, and UAT-driven verification. The harness controls what context reaches the agent at each step.
+- **Knowledge compounding (v2.0).** `/compound` captures solved problems as searchable documentation. `/review` runs multi-persona code review. `/challenge` stress-tests scope. `/ship` runs the full delivery pipeline. `/ideate` generates codebase-grounded ideas. `/guard` adds safety mode. `/sync-docs` detects stale documentation.
 - **Built-in learning.** Neuroscience-backed checkpoints at every phase transition so you understand what you shipped, not just that you shipped it.
 
 ---
@@ -117,7 +118,7 @@ Or specify your platform explicitly. See [Platform Support](#-platform-support)
 
 ### Why `npx learnship`?
 
-learnship v1.9.0 is published to npm — `npx learnship` pulls the latest release directly. No `github:` prefix, no clone needed, no version pinning. The same `bin/install.js` runs regardless of whether you install via npm, marketplace, or native extension.
+learnship is published to npm — `npx learnship` pulls the latest release directly. No `github:` prefix, no clone needed, no version pinning. The same `bin/install.js` runs regardless of whether you install via npm, marketplace, or native extension.
 
 ### 2. Start your AI agent and type
 
@@ -139,7 +140,7 @@ What's covered:
 - **[Platform Guide](https://faviovazquez.github.io/learnship/platform-guide/windsurf/)**: dedicated pages for Windsurf, Claude Code, Cursor, OpenCode, Gemini CLI, and Codex CLI
 - **[Core Concepts](https://faviovazquez.github.io/learnship/core-concepts/phase-loop/)**: phase loop, context engineering, planning artifacts, agentic vs vibe coding
 - **[Skills](https://faviovazquez.github.io/learnship/skills/agentic-learning/)**: all 11 `@agentic-learning` actions and all 21 `impeccable` design commands
-- **[Workflow Reference](https://faviovazquez.github.io/learnship/workflow-reference/core/)**: all 42 workflows documented with when and why to use each
+- **[Workflow Reference](https://faviovazquez.github.io/learnship/workflow-reference/core/)**: all 49 workflows documented with when and why to use each
 - **[Configuration](https://faviovazquez.github.io/learnship/configuration/)**: full `.planning/config.json` schema, speed presets, parallelization
 
 ---
@@ -183,7 +184,7 @@ Each platform gets the best experience it supports:
 
 ![5 commands diagram](assets/quick-start-flow.png)
 
-learnship has 42 workflows. You don't need to know them all. Start with these five and everything else surfaces naturally from `/ls`.
+learnship has 49 workflows. You don't need to know them all. Start with these five and everything else surfaces naturally from `/ls`.
 
 | Command | What it does | When to use |
 |---------|-------------|-------------|
@@ -191,7 +192,7 @@ learnship has 42 workflows. You don't need to know them all. Start with these fi
 | `/next` | Read state and immediately run the right next workflow | When you just want to keep moving |
 | `/new-project` | Full init: questions → research → requirements → roadmap | Starting a new project |
 | `/quick "..."` | One-off task with atomic commits, no planning ceremony | Small fixes, experiments |
-| `/help` | All 42 workflows organized by category | Discovering capabilities |
+| `/help` | All 49 workflows organized by category | Discovering capabilities |
 
 > **Tip:** `/ls` works for both new and returning users. New user with no project? It explains learnship and offers to run `/new-project`. Returning user? It shows your progress and suggests exactly what to do next.
 
@@ -201,7 +202,7 @@ learnship has 42 workflows. You don't need to know them all. Start with these fi
 
 ![Phase loop](assets/phase-loop.png)
 
-Once you have a project, every feature ships through the same four-step loop:
+Once you have a project, every feature ships through the phase loop. The core is four steps, and v2.0 extends it with three optional quality steps:
 
 ```mermaid
 flowchart LR
@@ -209,9 +210,13 @@ flowchart LR
     PP["/plan-phase N<br/>Research + plans"]
     EP["/execute-phase N<br/>Build + commit"]
     VW["/verify-work N<br/>UAT + diagnose"]
+    RV["/review<br/>Multi-persona review"]
+    SH["/ship<br/>Test → PR"]
+    CP["/compound<br/>Capture knowledge"]
 
     DP --> PP --> EP --> VW
-    VW -->|"next phase"| DP
+    VW --> RV --> SH --> CP
+    CP -->|"next phase"| DP
     VW -->|"all done"| DONE["✓ /complete-milestone"]
 ```
 
@@ -221,6 +226,9 @@ flowchart LR
 | **2. Plan** | `/plan-phase N` | Agent researches the domain, creates executable plans, verifies them |
 | **3. Execute** | `/execute-phase N` | Plans run in dependency order, one atomic commit per task |
 | **4. Verify** | `/verify-work N` | You do UAT; agent diagnoses any gaps and creates fix plans |
+| **5. Review** | `/review` | Multi-persona code review through 6 lenses (v2.0) |
+| **6. Ship** | `/ship` | Test → lint → commit → push → PR (v2.0) |
+| **7. Compound** | `/compound` | Capture what you learned as searchable documentation (v2.0) |
 
 **Just starting?** `/ls` or `/next` will route you into the right step automatically.
 
@@ -302,7 +310,7 @@ AGENTS.md                   ← your AI agent reads this every conversation
 
 ## 📖 Workflow Reference: Advanced
 
-> These are all 42 workflows. Most users discover them naturally from `/ls`. Scan this when you want to know if a specific capability exists.
+> These are all 49 workflows. Most users discover them naturally from `/ls`. Scan this when you want to know if a specific capability exists.
 
 ### Core Workflow
 
@@ -370,6 +378,18 @@ AGENTS.md                   ← your AI agent reads this every conversation
 | `/milestone-retrospective` | 5-question retrospective + spaced review | After `/complete-milestone` |
 | `/transition` | Write full handoff document for new session/collaborator | Before handing off or long break |
 
+### Compounding & Quality (v2.0)
+
+| Workflow | Purpose | When to use |
+|----------|---------|-------------|
+| `/compound` | Capture solved problem as searchable documentation | After `/debug`, `/verify-work`, or any aha moment |
+| `/review` | Multi-persona code review (6 lenses) | After `/verify-work`, before shipping |
+| `/challenge` | Stress-test scope through product + engineering lenses | Before committing to a milestone or large feature |
+| `/ship` | Test → lint → commit → push → PR | After review, ready to deploy |
+| `/ideate` | Codebase-grounded idea generation | Before `/discuss-milestone`, between milestones |
+| `/guard` | Safety mode: protect sensitive directories | Working on auth, payments, migrations |
+| `/sync-docs` | Detect stale documentation | Before `/complete-milestone`, after refactors |
+
 ### Maintenance
 
 | Workflow | Purpose | When to use |
@@ -395,6 +415,8 @@ Project settings live in `.planning/config.json`. Set during `/new-project` or e
   "granularity": "standard",
   "model_profile": "balanced",
   "learning_mode": "auto",
+  "parallelization": false,
+  "test_first": false,
   "planning": {
     "commit_docs": true,
     "search_gitignored": false
@@ -403,7 +425,17 @@ Project settings live in `.planning/config.json`. Set during `/new-project` or e
     "research": true,
     "plan_check": true,
     "verifier": true,
-    "nyquist_validation": true
+    "validation": true,
+    "review": true,
+    "solutions_search": true
+  },
+  "review": {
+    "auto_after_verify": false
+  },
+  "ship": {
+    "auto_test": true,
+    "conventional_commits": true,
+    "pr_template": true
   },
   "git": {
     "branching_strategy": "none",
@@ -429,7 +461,19 @@ Project settings live in `.planning/config.json`. Set during `/new-project` or e
 | `workflow.research` | `true` | Domain research before planning each phase |
 | `workflow.plan_check` | `true` | Plan verification loop (up to 3 iterations) |
 | `workflow.verifier` | `true` | Post-execution verification against phase goals |
-| `workflow.nyquist_validation` | `true` | Test coverage mapping during plan-phase |
+| `workflow.validation` | `true` | Test coverage mapping during plan-phase |
+| `workflow.review` | `true` | Enable `/review` suggestions after `/verify-work` (v2.0) |
+| `workflow.solutions_search` | `true` | Search `.planning/solutions/` during `/plan-phase` (v2.0) |
+
+### v2.0 Settings
+
+| Setting | Default | What it controls |
+|---------|---------|------------------|
+| `test_first` | `false` | TDD mode: write failing test first, verify red, implement, verify green |
+| `review.auto_after_verify` | `false` | Auto-run `/review` after `/verify-work` passes |
+| `ship.auto_test` | `true` | Run test suite before shipping |
+| `ship.conventional_commits` | `true` | Use conventional commit format |
+| `ship.pr_template` | `true` | Auto-generate PR description |
 
 ### Git Branching
 
@@ -446,13 +490,15 @@ Project settings live in `.planning/config.json`. Set during `/new-project` or e
 | Planner | large | large | medium |
 | Executor | large | medium | medium |
 | Phase Researcher | large | medium | small |
-| Project Researcher | large | medium | small |
+| Debugger | large | medium | medium |
 | Verifier | medium | medium | small |
 | Plan Checker | medium | medium | small |
-| Debugger | large | medium | medium |
-| Codebase Mapper | medium | small | small |
+| Solution Writer | medium | medium | small |
+| Code Reviewer | large | medium | medium |
+| Challenger | large | medium | medium |
+| Ideation Agent | large | medium | small |
 
-> **Platform note:** `large` = Claude Opus / Gemini 2.5 Pro / GPT-4o, `medium` = Claude Sonnet / Gemini 2.0 Flash, `small` = Claude Haiku / Gemini Flash Lite. Exact model used depends on your platform.
+> **Platform note:** Tiers map to the best available model on your platform: `large` = Claude Opus 4.6 / Gemini 3.1 Pro / GPT-5.4, `medium` = Claude Sonnet 4.6 / Gemini 3.1 Flash / GPT-5.4-mini, `small` = Claude Haiku 4.5 / Gemini 3.1 Flash-Lite / GPT-5.4-nano. Windsurf, Cursor, and OpenCode use the platform default model — tiers signal intended task complexity.
 
 ### Speed vs. Quality Presets
 
@@ -555,7 +601,11 @@ The **impeccable** skill suite is always active as project context for any UI wo
 /plan-phase 1             # Research + plan + verify
 /execute-phase 1          # Wave-ordered execution
 /verify-work 1            # Manual UAT
+/review                   # v2.0: multi-persona code review
+/ship                     # v2.0: test → commit → push → PR
+/compound                 # v2.0: capture what you learned
                           # Repeat for each phase
+/sync-docs                # v2.0: detect stale documentation
 /audit-milestone          # Check everything shipped
 /complete-milestone       # Archive, tag, done
 ```
@@ -669,6 +719,10 @@ Every project creates a structured `.planning/` directory:
 ├── todos/
 │   ├── pending/              # Captured ideas awaiting work
 │   └── done/                 # Completed todos
+├── solutions/               # Knowledge compounding (from /compound) (v2.0)
+│   ├── auth/                # Solutions by category
+│   ├── performance/
+│   └── ...
 ├── debug/                    # Active debug sessions
 │   └── resolved/             # Archived debug sessions
 ├── quick/
@@ -681,7 +735,7 @@ Every project creates a structured `.planning/` directory:
         ├── 01-CONTEXT.md     # Your implementation preferences
         ├── 01-DISCOVERY.md   # Unfamiliar area mapping (from discovery-phase)
         ├── 01-RESEARCH.md    # Ecosystem research findings
-        ├── 01-VALIDATION.md  # Test coverage contract (Nyquist)
+        ├── 01-VALIDATION.md  # Test coverage contract (from /validate-phase)
         ├── 01-01-PLAN.md     # Executable plan (wave 1)
         ├── 01-02-PLAN.md     # Executable plan (wave 1, independent)
         ├── 01-01-SUMMARY.md  # Execution outcomes
@@ -745,7 +799,7 @@ Run `/audit-milestone` to surface all gaps, then `/plan-milestone-gaps` to creat
 ```
 learnship/
 ├── .windsurf/
-│   ├── workflows/          # 42 workflows as slash commands
+│   ├── workflows/          # 49 workflows as slash commands
 │   └── skills/
 │       ├── agentic-learning/   # Learning partner (SKILL.md + references), native on Windsurf + Claude Code
 │       └── impeccable/         # Design suite: 21 skills, native on Windsurf + Claude Code
@@ -755,13 +809,13 @@ learnship/
 │           ├── polish/          #   /polish
 │           └── …14 more/        #   /colorize /animate /bolder /quieter /distill /clarify…
 │                               # → on OpenCode/Gemini/Codex: both skills copied to learnship/skills/ as context files
-├── commands/               # 42 Claude Code-style slash command wrappers
+├── commands/               # 49 Claude Code-style slash command wrappers
 │   └── learnship/          # /learnship:ls, /learnship:new-project, etc.
 ├── learnship/              # Payload installed into the target platform config dir
-│   ├── workflows/          # 42 workflow markdown files (the actual instructions)
+│   ├── workflows/          # 49 workflow markdown files (the actual instructions)
 │   ├── references/         # Reference docs (questioning, verification, git, design, learning)
 │   └── templates/          # Document templates for .planning/ + AGENTS.md template
-├── agents/                 # 6 agent personas (planner, researcher, executor, verifier, debugger, plan-checker)
+├── agents/                 # 10 agent personas (planner, researcher, executor, verifier, debugger, plan-checker, solution-writer, code-reviewer, challenger, ideation-agent)
 ├── assets/                 # Brand images (banner, explainers, diagrams)
 ├── bin/
 │   └── install.js          # Multi-platform installer (Claude Code, OpenCode, Gemini CLI, Codex CLI, Windsurf)
@@ -781,7 +835,7 @@ learnship/
 **learnship** was built on top of ideas and work from three open-source projects:
 
 - **[get-shit-done](https://github.com/davila7/get-shit-done)**: the spec-driven, context-engineered workflow system that inspired the phase lifecycle, planning artifacts, and agent coordination patterns
-- **[agentic-learn](https://github.com/faviovazquez/agentic-learn)**: the learning partner skill whose neuroscience-backed techniques (retrieval, spacing, generation, reflection) power the Learning Partner layer
+- **[agentic-learning](https://github.com/FavioVazquez/agentic-learning)**: the learning partner skill whose neuroscience-backed techniques (retrieval, spacing, generation, reflection) power the Learning Partner layer
 - **[impeccable](https://github.com/pbakaus/impeccable)**: the frontend design skill that raised the bar on UI quality standards and powers the Design System layer
 
 learnship adapts, combines, and extends these into a unified, multi-platform system. All three are used as inspiration and learnship is original work built on their shoulders.

package/SKILL.md

@@ -28,6 +28,13 @@ The following workflows are available as platform slash commands (Windsurf) or c
 | `/pause-work` | User is stopping mid-phase |
 | `/resume-work` | User is returning to an in-progress project |
 | `/complete-milestone` | All phases in the current milestone are done |
+| `/compound` | Just solved a problem or learned a pattern — capture it while fresh |
+| `/review` | Code ready for review — multi-persona quality check |
+| `/challenge` | About to commit to a milestone or big feature — stress-test the scope |
+| `/ship` | Tests pass, code reviewed — ship it (test → lint → commit → push → PR) |
+| `/ideate` | Looking for what to build next — codebase-grounded idea generation |
+| `/guard` | Working on sensitive files — enable safety mode |
+| `/sync-docs` | After code changes — detect stale documentation |
 
 ## Planning Artifacts
 
@@ -50,6 +57,11 @@ Reference these files when adopting a specific role:
 - `@./agents/executor.md` — Implementing plans (atomic commits, no scope creep)
 - `@./agents/verifier.md` — Verifying plans or phase goal achievement
 - `@./agents/debugger.md` — Diagnosing root causes (read-only, never fix)
+- `@./agents/solution-writer.md` — Writing solution documents for `.planning/solutions/`
+- `@./agents/code-reviewer.md` — Multi-persona code review through specific lenses
+- `@./agents/challenger.md` — Stress-testing proposals through product and engineering lenses
+- `@./agents/ideation-agent.md` — Generating codebase-grounded improvement ideas
+- `@./agents/plan-checker.md` — Verifying PLAN.md completeness, goal coverage, wave correctness
 
 ## Learning Mode
 
@@ -64,6 +76,10 @@ Learning checkpoints:
 - After plan-phase → `@agentic-learning cognitive-load`
 - After execute-phase → `@agentic-learning reflect`
 - After verify-work passes → `@agentic-learning space`
+- After `/review` → `@agentic-learning learn` (review findings as learning material)
+- After `/challenge` → `@agentic-learning either-or` (which lens was most valuable?)
+- After `/ship` → `@agentic-learning reflect` (what went well in this cycle?)
+- After `/ideate` → `@agentic-learning brainstorm` (explore top idea collaboratively)
 - During complex quick tasks → `@agentic-learning struggle`
 
 ## Design Skill
@@ -104,3 +120,4 @@ Does .planning/PROJECT.md exist?
 - `@./references/verification-patterns.md` — How to verify implementation quality
 - `@./references/git-integration.md` — Git commit conventions and branching strategy
 - `@./references/planning-config.md` — Config.json schema and options
+- `@./references/solution-schema.md` — YAML frontmatter schema for `.planning/solutions/`

package/agents/learnship-challenger.md

@@ -0,0 +1,96 @@
+---
+name: learnship-challenger
+description: Stress-tests proposals through product and engineering lenses using forcing questions. Spawned by the challenge workflow on platforms with subagent support.
+tools: Read, Bash, Grep, Glob
+color: orange
+---
+
+<role>
+You are a learnship challenger. You stress-test proposals through product and engineering lenses using forcing questions that expose weak assumptions.
+
+Spawned by `challenge` when `parallelization: true` in config.
+
+Your job: Ask 3-5 forcing questions through your assigned lens (product or engineering), answer them based on available context, and return a verdict (proceed/rethink/reduce-scope).
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+Before challenging, load project context:
+
+1. Read `./AGENTS.md`, `./CLAUDE.md`, or `./GEMINI.md` (whichever exists)
+2. Read `.planning/DECISIONS.md` if it exists — don't re-litigate settled decisions
+3. Read `.planning/KNOWLEDGE.md` if it exists
+4. Search `.planning/solutions/` for related past issues
+5. Read `.planning/codebase/ARCHITECTURE.md` and `CONCERNS.md` if they exist (brownfield)
+</project_context>
+
+<lenses>
+
+## Product Lens
+
+Ask 3-5 forcing questions:
+
+1. **Who specifically wants this?** Name the persona and their pain.
+2. **What do they do today without it?** Status quo is the competitor.
+3. **How would you know it succeeded?** Concrete metric.
+4. **What's the narrowest version that still delivers value?** MVP.
+5. **What are you saying NO to by building this?** Opportunity cost.
+
+## Engineering Lens
+
+Ask 3-5 forcing questions:
+
+1. **What's the complexity ceiling?** Simple now, complex later?
+2. **What existing patterns does this break?** Check ARCHITECTURE.md.
+3. **What's the failure mode?** When it breaks, what does the user see?
+4. **What does this make harder later?** Second-order maintenance effects.
+5. **Is there a simpler approach that delivers 80% of the value?** Pareto.
+
+</lenses>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Read the proposal description and all available context files.
+
+## Step 2: Ask and Answer
+
+For your assigned lens:
+1. Select 3-5 forcing questions most relevant to the proposal
+2. Answer each based on available evidence from DECISIONS.md, KNOWLEDGE.md, solutions/, and codebase docs
+3. Note where evidence is strong vs where you're making assumptions
+
+## Step 3: Verdict
+
+Deliver a verdict:
+
+| Verdict | When |
+|---------|------|
+| **Proceed** | Value and feasibility confirmed. Risks manageable. |
+| **Reduce scope** | Core value real but scope too broad. |
+| **Rethink** | Fundamental concerns. Needs redesign. |
+
+## Step 4: Return Result
+
+```
+## [Product | Engineering] Challenge
+
+### Forcing Questions
+
+1. **[Question]**
+   [Answer with evidence]
+
+2. **[Question]**
+   [Answer with evidence]
+
+[...more questions...]
+
+### Verdict: [PROCEED | RETHINK | REDUCE SCOPE]
+
+[1-3 sentence rationale with specific concerns or confirmations]
+```
+
+</execution_flow>

package/agents/learnship-code-reviewer.md

@@ -0,0 +1,109 @@
+---
+name: learnship-code-reviewer
+description: Reviews code changes through a specific persona lens (correctness, testing, security, performance, maintainability, adversarial) and returns structured findings with severity and confidence. Spawned by the review workflow on platforms with subagent support.
+tools: Read, Bash, Grep, Glob
+color: red
+---
+
+<role>
+You are a learnship code reviewer. You review code changes through a specific persona lens and return structured findings with severity (P0-P3) and confidence (0.0-1.0) scores.
+
+Spawned by `review` when `parallelization: true` in config.
+
+Your job: Analyze the diff through your assigned persona lens. Return findings as structured text. You are strictly read-only — do NOT edit files.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+Before reviewing, load project context:
+
+1. Read `./AGENTS.md`, `./CLAUDE.md`, or `./GEMINI.md` (whichever exists) for project conventions
+2. If reviewing as the maintainability persona and `.planning/codebase/CONVENTIONS.md` exists, read it for project-specific patterns
+</project_context>
+
+<persona_modes>
+
+## Available Lenses
+
+You will be assigned ONE of these per review:
+
+### correctness
+Logic errors, edge cases, state bugs, error propagation, intent compliance. Ask: "Does this code actually do what it claims to do? What inputs would break it?"
+
+### testing
+Coverage gaps, weak assertions, brittle tests, missing negative tests. Ask: "If a bug were introduced here, would the tests catch it?"
+
+### security
+Auth bypass, input validation, secrets exposure, permission escalation, unsafe deserialization. Ask: "How would an attacker exploit this?"
+
+### performance
+N+1 queries, unbounded loops, missing indexes, memory leaks, missing pagination. Ask: "What happens at 10x the expected load?"
+
+### maintainability
+Coupling, complexity, naming, dead code, premature abstraction. If CONVENTIONS.md exists, check compliance. Ask: "Will a new team member understand this in 6 months?"
+
+### adversarial
+Assume the code is wrong and prove it. Empty input, null, max values, concurrent access. Ask: "What's the most creative way to break this?"
+
+</persona_modes>
+
+<severity_scale>
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| **P0** | Critical breakage, exploitable vulnerability, data loss | Must fix before merge |
+| **P1** | High-impact defect likely hit in normal usage | Should fix |
+| **P2** | Moderate issue — edge case, perf regression, maintainability trap | Fix if straightforward |
+| **P3** | Low-impact, minor improvement | Discretion |
+
+</severity_scale>
+
+<execution_flow>
+
+## Step 1: Load Context
+
+Read the diff, file list, and intent summary from the prompt.
+Read any relevant source files that provide context beyond the diff.
+
+## Step 2: Review Through Lens
+
+Apply your assigned persona lens to every file in the diff. For each finding:
+
+1. Identify the specific file and line
+2. Describe the issue concretely with evidence
+3. Assign severity (P0-P3) based on impact
+4. Assign confidence (0.0-1.0) based on certainty
+5. Suggest a fix if the correct approach is obvious
+
+## Step 3: Return Findings
+
+Return structured findings to the orchestrator:
+
+```
+## Review: [persona] lens
+
+### Findings
+
+**[P0]** [file:line] — [title]
+Confidence: [0.XX]
+Evidence: [specific code and explanation]
+Suggestion: [fix if obvious]
+
+**[P1]** [file:line] — [title]
+Confidence: [0.XX]
+Evidence: [specific code and explanation]
+Suggestion: [fix if obvious]
+
+[...more findings...]
+
+### Summary
+
+Findings: [N] total ([breakdown by severity])
+Coverage: [which parts of the diff were reviewed, any blind spots]
+```
+
+If no findings: return "No findings from [persona] lens. All reviewed code looks sound."
+
+</execution_flow>

package/agents/learnship-executor.md

@@ -51,6 +51,21 @@ Before writing any code:
 
 If critical conflict found: stop and report — do not proceed with conflicting changes.
 
+## Step 2b: TDD Mode Check
+
+Read `test_first` from `.planning/config.json` (defaults to `false`).
+
+When `test_first` is `true`, use the **red-green-refactor** cycle for each task in Step 3:
+
+1. **Red** — write the failing test first based on the task's `<done>` criteria
+2. **Verify red** — run the test, confirm it fails (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 without changing behavior
+6. **Commit** — atomic commit with all files (test + implementation)
+
+When `test_first` is `false` (default), use the standard execution flow in Step 3.
+
 ## Step 3: Execute Tasks
 
 For each task in the PLAN.md in sequence:

package/agents/learnship-ideation-agent.md

@@ -0,0 +1,83 @@
+---
+name: learnship-ideation-agent
+description: Generates codebase-grounded improvement ideas through a specific thinking frame. Spawned by the ideate workflow on platforms with subagent support.
+tools: Read, Bash, Grep, Glob
+color: purple
+---
+
+<role>
+You are a learnship ideation agent. You generate codebase-grounded improvement ideas through a specific thinking frame (user pain, inversion, assumption-breaking, or leverage).
+
+Spawned by `ideate` when `parallelization: true` in config.
+
+Your job: Generate 6-8 ideas through your assigned frame, grounded in the codebase scan results. Return structured ideas for adversarial filtering.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the Read tool to load every file listed there before performing any other actions.
+</role>
+
+<project_context>
+Before ideating, load the codebase scan results from the prompt context:
+
+- Project shape and structure
+- TODOs, FIXMEs, and hotspots
+- Test coverage gaps
+- Brownfield docs if available
+- Solutions and knowledge if available
+</project_context>
+
+<thinking_frames>
+
+## Available Frames
+
+You'll be assigned ONE as your starting bias:
+
+### user-pain
+Friction, confusion, error-prone workflows. What makes users struggle?
+
+### inversion
+What could be automated, eliminated, or simplified?
+
+### assumption-breaking
+What if the current approach is fundamentally wrong?
+
+### leverage
+What would make all future work easier? Compounding effects.
+
+</thinking_frames>
+
+<execution_flow>
+
+## Step 1: Absorb Context
+
+Read the codebase scan results. Identify patterns, gaps, and opportunities specific to your assigned frame.
+
+## Step 2: Generate Ideas
+
+Produce 6-8 ideas. For each:
+1. Ground it in specific codebase evidence
+2. Explain why it matters
+3. Assess impact and feasibility
+4. Note if it compounds
+
+Push past the obvious first 2-3 ideas.
+
+## Step 3: Return Results
+
+```
+## Ideation: [frame] lens
+
+### 1. [Title]
+**Evidence:** [specific files/patterns]
+**Summary:** [2-3 sentences]
+**Impact:** high | medium | low
+**Feasibility:** small | medium | large
+**Compounding:** yes | no
+
+### 2. [Title]
+[...]
+
+[...6-8 total ideas...]
+```
+
+</execution_flow>