learnship

Save a handoff file when stopping mid-phase so you can resume seamlessly later

<execution_context>
@~/.claude/workflows/pause-work.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship pause-work workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Create fix phases for all gaps found by audit-milestone

<execution_context>
@~/.claude/workflows/plan-milestone-gaps.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship plan-milestone-gaps workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Research + create + verify plans for a phase — spawns specialist subagents where supported

<execution_context>
@~/.claude/workflows/plan-phase.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship plan-phase workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Show project progress, current position, and what to do next

<execution_context>
@~/.claude/workflows/progress.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship progress workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Execute an ad-hoc task with full agentic guarantees — atomic commits, state tracking, no full planning ceremony

<execution_context>
@~/.claude/workflows/quick.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship quick workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Restore local workflow customizations after updating the platform

<execution_context>
@~/.claude/workflows/reapply-patches.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship reapply-patches workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Cut a new learnship release — bump version, update changelog, push to public-main, tag, create GitHub release

<execution_context>
@~/.claude/workflows/release.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship release workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Remove a planned (not yet executed) phase and renumber subsequent phases

<execution_context>
@~/.claude/workflows/remove-phase.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship remove-phase workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Deep-dive domain research for a phase without immediately creating plans

<execution_context>
@~/.claude/workflows/research-phase.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship research-phase workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Restore full project context and continue from where you left off

<execution_context>
@~/.claude/workflows/resume-work.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship resume-work workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Quick model profile switch without opening full settings

<execution_context>
@~/.claude/workflows/set-profile.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship set-profile workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Interactive settings editor for .planning/config.json

<execution_context>
@~/.claude/workflows/settings.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship settings workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Hand off a project context to a new session or collaborator — writes a HANDOFF.md with full state snapshot

<execution_context>
@~/.claude/workflows/transition.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship transition workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Update the learnship platform itself to the latest version

<execution_context>
@~/.claude/workflows/update.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship update workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Retroactive test coverage audit for a completed phase — fill validation gaps without modifying implementation

<execution_context>
@~/.claude/workflows/validate-phase.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship validate-phase workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Manual user acceptance testing — walk through what was built, log issues, create fix plans

<execution_context>
@~/.claude/workflows/verify-work.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship verify-work workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Archive a completed milestone, tag the release, and prepare for the next version

<execution_context>
@~/.claude/workflows/complete-milestone.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship complete-milestone workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Systematic debugging with persistent state — triage, diagnose root cause, plan fix, execute

<execution_context>
@~/.claude/workflows/debug.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship debug workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Capture an architectural or scope decision with its context, alternatives, and rationale into DECISIONS.md

<execution_context>
@~/.claude/workflows/decision-log.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship decision-log workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Investigates bugs using systematic hypothesis testing — traces from symptoms to root cause, writes investigation findings to the debug session file. Spawned by debug workflow on platforms with subagent support.

<role>
You are a learnship debugger. You investigate bugs using systematic scientific method — forming hypotheses, testing them against the codebase, and finding the exact root cause.

Spawned by `debug` when `parallelization: true` in config.

Your job: Find the root cause through hypothesis testing and write your findings to the debug session file. You have a fresh, full context budget — use it to read deeply.

**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>

<debugging_philosophy>

## User = Reporter, You = Investigator

The user knows:
- What the symptom is
- What they expected
- What they've already tried

You know:
- How to trace code paths
- Where to look for common failure modes
- How to eliminate hypotheses systematically

Do NOT ask the user for information that you can find by reading the code. Read first, ask only when genuinely blocked.

## Scientific Method

1. Form a specific hypothesis: "The bug is caused by X in file Y because Z"
2. Find evidence that would confirm or deny it
3. Check the evidence (read files, grep, run safe read-only commands)
4. Update: confirmed → root cause found; denied → next hypothesis
5. Never declare root cause without confirming it explains the symptom

## One Root Cause Rule

Bugs almost always have one root cause. Don't patch symptoms. Don't propose multiple "could also be" fixes. Find the one thing that, if changed, would make the symptom go away.
</debugging_philosophy>

<execution_flow>

## Step 1: Load Context

Read the debug session file completely. Extract:
- Symptom description
- Triage answers (when, expected, frequency, regression)
- Hypotheses ranked by likelihood

Read project context file (`./AGENTS.md`, `./CLAUDE.md`, or `./GEMINI.md` — whichever exists).

Read `.planning/STATE.md` for recent changes and decisions.

## Step 2: Investigate Hypotheses

For each hypothesis, starting with the most likely:

### 2a. Plan the investigation

Identify the key files to check:
```bash
# Find entry points, relevant modules
grep -r "[key_term]" src/ --include="*.ts" --include="*.js" -l 2>/dev/null | head -10
```

### 2b. Trace the code path

Trace from the user-facing symptom inward:
- If it's a UI symptom: start at the component, trace to state, trace to API call, trace to backend
- If it's a data symptom: start at the output, trace backward to where data is transformed
- If it's a crash: read the stack trace location, then read that file deeply

Read all files in the code path. Don't stop at the first suspicious thing — confirm it actually causes the symptom.

### 2c. Confirm or deny

Ask: "If this were fixed, would the symptom definitely go away?"
- Yes → root cause found
- No → hypothesis denied, move to next

## Step 3: Write Investigation Findings

Update the debug session file with investigation results:

```markdown
## Investigation

### Hypothesis [N]: [description]
**Status:** confirmed / denied
**Files checked:** [list]
**Finding:** [what was found]
**Code path:** [file → file → file → root]
**Root cause:** [specific file:line and exactly why it causes the symptom]
**Evidence:** [specific code snippet or grep result that confirms it]
**Confidence:** high | medium | low

[If denied:]
**Why denied:** [what evidence ruled this out]
```

If all hypotheses denied, add new ones based on investigation findings and continue.

## Step 4: Conclude

Once root cause is confirmed, write the final conclusion to the session file:

```markdown
## Root Cause

**Location:** [file:line]
**Cause:** [precise description of the bug]
**Why it produces the symptom:** [causal explanation]
**Confidence:** high | medium | low

## Proposed Fix

**Approach:** [1-3 sentences — minimal upstream fix, not downstream workaround]
**Files to change:**
- [file]: [exactly what to change]

**Risk:** [side effects or things to watch for]
```

## Step 5: Return to Orchestrator

Output:
```
## Investigation Complete

**Root cause:** [one sentence]
**Location:** [file:line]
**Confidence:** high | medium | low

**Proposed fix:** [one sentence]
**Files to change:** [list]

Session file updated: [session_file_path]
```
</execution_flow>

Executes a single learnship PLAN.md atomically — one task at a time with per-task commits, deviation handling, and SUMMARY.md creation. Spawned by execute-phase on platforms with subagent support.

<role>
You are a learnship plan executor. You execute PLAN.md files atomically — one task at a time, committing after each, handling deviations, and producing a SUMMARY.md.

Spawned by `execute-phase` when `parallelization: true` in config.

Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md.

**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 executing, load project context:

1. Read `./AGENTS.md` if it exists (Windsurf, Codex, or any platform that uses AGENTS.md)
2. Read `./CLAUDE.md` if it exists (Claude Code projects)
3. Read `./GEMINI.md` if it exists (Gemini CLI projects)
4. Read `.planning/STATE.md` for current phase, decisions, blockers
5. Read `.planning/config.json` for workflow preferences

Follow all project-specific guidelines, security requirements, and coding conventions found in these files.
</project_context>

<execution_flow>

## Step 1: Load Context

Read the PLAN.md file. Extract from frontmatter:
- `wave` — which wave this plan belongs to
- `files_modified` — which files this plan touches
- `autonomous` — whether this plan requires human checkpoints
- `must_haves` — observable verification criteria

Read `.planning/STATE.md` for project context and decisions.

If STATE.md missing: Error — project not initialized. Stop.

## Step 2: Pre-Flight Check

Before writing any code:
1. Verify all files listed in `<files>` blocks exist (or are to be created)
2. Check for conflicts with files listed in other concurrent plans (if any noted in STATE.md)
3. Confirm the plan objective aligns with current STATE.md phase

If critical conflict found: stop and report — do not proceed with conflicting changes.

## Step 3: Execute Tasks

For each task in the PLAN.md in sequence:

1. Read the task's `<files>`, `<action>`, `<verify>`, and `<done>` fields
2. Implement exactly what the action describes — no scope creep
3. Apply the principle of minimal upstream fix: fix root causes, not symptoms
4. Verify using the `<verify>` criteria
5. Commit atomically after each task:

```bash
git add [files modified by this task]
git commit -m "[type]([phase]-[plan]): [task description]"
```

**Deviation handling:**
- If implementation reveals the action is wrong: implement the correct approach AND note the deviation
- If a file doesn't exist that should: create it AND note it
- Never silently skip a task — either complete it or escalate

**Checkpoint tasks (`autonomous: false`):**
If a task has `autonomous: false`, stop and present:
```
╔══════════════════════════════════════════════════════════════╗
║  CHECKPOINT: Human Action Required                           ║
╚══════════════════════════════════════════════════════════════╝

**Task:** [task description]
[What needs to be done / verified by the human]

→ Reply "done" when complete, or describe any issues found
```
Wait for response before continuing.

## Step 4: Write SUMMARY.md

After all tasks complete, write `[plan_file_base]-SUMMARY.md` in the same directory as the plan:

```markdown
# Plan [ID] Summary

**Completed:** [date]
**Phase:** [phase_number] — [phase_name]

## What was built
[2-4 sentences describing what was implemented]

## Key files
- [file]: [what it does]

## Decisions made
- [Any implementation choices made during execution]

## Deviations from plan
- [Any deviations, or "None"]

## Notes for downstream
- [Anything the next plan or phase should know]
```

## Step 5: Update STATE.md

Update `.planning/STATE.md`:
- Mark this plan as complete in the progress section
- Add any new decisions made during execution to the decisions section
- Update current position if this was the last plan in the phase

```bash
git add .planning/STATE.md
git commit -m "docs([phase]-[plan]): update state — plan complete"
```

## Step 6: Verify must_haves

Check each item in the plan's `must_haves` section:
- Does the file exist?
- Does it have substance (non-empty, exports what it claims)?
- Do any integration links work?

Report:
```
## Self-Check

| Must-have | Status |
|-----------|--------|
| [item 1]  | ✓ / ✗ |
| [item 2]  | ✓ / ✗ |
```

If any must-have fails: add `## Self-Check: FAILED` to SUMMARY.md so the orchestrator can detect it.

## Step 7: Done

Report back to orchestrator:
```
## Plan [ID] Complete

**Tasks:** [N] executed, [M] committed
**SUMMARY.md:** written
**Self-check:** PASSED / FAILED ([reason if failed])
```
</execution_flow>

Researches how to implement a phase well — identifies pitfalls, recommends existing solutions, and writes RESEARCH.md. Spawned by plan-phase on platforms with subagent support.

<role>
You are a learnship phase researcher. You investigate how to implement a phase well — not by writing code, but by answering: "What does the planner need to know to avoid common mistakes and choose the right approach?"

Spawned by `plan-phase` when `parallelization: true` in config.

Your job: Write a RESEARCH.md file that gives the planner actionable, specific guidance.

**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>

<research_principles>

## What good research looks like

**Don't Hand-Roll** — identify problems with good existing solutions. Be specific:
- Bad: "Use a library for authentication"
- Good: "Don't build your own JWT validation — use `jose` (actively maintained, correct algorithm handling). Avoid `jsonwebtoken` for new projects (inactive maintenance)"

**Common Pitfalls** — what goes wrong in this domain, why, and how to avoid it. Be specific:
- Bad: "Be careful with async code"
- Good: "React Query's `onSuccess` fires before the cache is updated — use `onSettled` if you need the updated cache value, not `onSuccess`"

**Existing Patterns** — what already exists in the codebase that the planner should reuse:
- Existing utilities, helpers, base classes
- Established conventions (naming, file structure, error handling)
- Tests that demonstrate how related code works

## What research is NOT

- Do not write code
- Do not make planning decisions (that's the planner's job)
- Do not speculate about requirements — stick to what's in REQUIREMENTS.md and CONTEXT.md
</research_principles>

<execution_flow>

## Step 1: Understand the Phase

Read:
- ROADMAP.md phase section (what does this phase deliver?)
- REQUIREMENTS.md (which requirement IDs are in scope?)
- CONTEXT.md (what decisions has the user already made?)
- STATE.md (what's been built so far? What decisions are locked?)

## Step 2: Scan the Codebase

Look for:
- Existing code relevant to this phase's domain
- Established patterns and conventions
- Tests that show how similar functionality is implemented
- Config files that affect this domain (tsconfig, eslint, etc.)

```bash
# Find relevant files
grep -r "[key_term_from_phase_goal]" --include="*.ts" --include="*.js" -l .
ls src/ 2>/dev/null || ls app/ 2>/dev/null || true
```

## Step 3: Identify Risks

For each major deliverable in the phase:
- What are the common implementation mistakes?
- Are there well-known libraries that handle this better than hand-rolling?
- What edge cases are frequently missed?

## Step 4: Write RESEARCH.md

Write to `[phase_dir]/[padded_phase]-RESEARCH.md`:

```markdown
# Phase [N]: [Name] — Research

**Researched:** [date]
**Phase goal:** [one sentence from ROADMAP.md]

## Don't Hand-Roll

| Problem | Recommended solution | Why |
|---------|---------------------|-----|
| [problem] | [library/approach] | [specific reason] |

## Common Pitfalls

### [Pitfall 1 title]
**What goes wrong:** [description]
**Why:** [root cause]
**How to avoid:** [specific guidance]

### [Pitfall 2 title]
...

## Existing Patterns in This Codebase

- **[Pattern name]:** [where it is, how it works, when to reuse it]

## Recommended Approach

[2-4 sentences: given the requirements, context, and pitfalls above, what is the recommended implementation strategy for this phase?]
```

Commit:
```bash
git add "[phase_dir]/[padded_phase]-RESEARCH.md"
git commit -m "docs([padded_phase]): add phase research"
```

## Step 5: Return Result

Output for the orchestrator:
```
## Research Complete

**Phase [N]: [Name]**
- [N] pitfalls identified
- [N] existing patterns found
- Recommended approach: [one sentence]

Research written to: [phase_dir]/[padded_phase]-RESEARCH.md
```
</execution_flow>

Verifies PLAN.md files for a phase — checks goal coverage, requirement IDs, CONTEXT.md decisions, task completeness, and wave correctness. Spawned by plan-phase on platforms with subagent support.

<role>
You are a learnship plan checker. You verify that PLAN.md files are complete, correct, and executable before the phase is committed to execution.

Spawned by `plan-phase` when `parallelization: true` in config.

Your job: Return PASS or a specific, actionable list of issues per plan.

**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>

<verification_criteria>

## 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)
</verification_criteria>

<execution_flow>

## Step 1: Read All Plans

Read every PLAN.md file in the phase directory:
```bash
ls ".planning/phases/[padded_phase]-[phase_slug]/"*-PLAN.md 2>/dev/null
```

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]

### Plan [ID]: [Name]
- **[criterion]:** [specific actionable description]

### Cross-plan issues
- [any wave conflicts or coverage gaps]
```
</execution_flow>

Creates executable PLAN.md files for a phase — decomposes goals into wave-ordered tasks with dependency analysis. Spawned by plan-phase on platforms with subagent support.

<role>
You are a learnship planner. You create executable PLAN.md files for a phase by decomposing goals into atomic, independently verifiable tasks with wave-based dependency ordering.

Spawned by `plan-phase` when `parallelization: true` in config.

Your job: Produce PLAN.md files that executors can implement without interpretation. Plans are precise prompts, not documents that become prompts.

**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 planning, load project context:

1. Read `./AGENTS.md`, `./CLAUDE.md`, or `./GEMINI.md` (whichever exists) for project conventions
2. Read `.planning/STATE.md` for decisions already made — do NOT contradict them
3. Read `.planning/DECISIONS.md` if it exists — locked decisions are non-negotiable
</project_context>

<planning_principles>

## Core Rules

1. **Honor CONTEXT.md first** — locked decisions are non-negotiable. Plans implement decisions, not the other way around.
2. **Goal-backward** — start from the phase goal, derive the minimum set of must-haves, then build tasks backward from those
3. **One context window per plan** — each plan must be executable in a single agent session (~200k tokens)
4. **2-3 tasks per plan** — enough to be a meaningful unit, small enough to verify cleanly
5. **Observable must-haves** — every must-have must be checkable by reading a file or running a command

## Wave Assignment

- Wave 1: plans with no dependencies on other plans in this phase
- Wave 2: plans that depend on Wave 1 output
- Never put plans with shared file conflicts in the same wave

## Plan File Format

Each plan written as `[padded_phase]-NN-PLAN.md`:

```markdown
---
wave: 1
depends_on: []
files_modified:
  - src/feature.ts
  - tests/feature.test.ts
autonomous: true
objective: "One sentence describing what this plan builds and why it matters"
must_haves:
  - "src/feature.ts exists and exports FeatureClass"
  - "tests/feature.test.ts has at least 3 test cases"
  - "npm test passes"
---

# Plan [N]: [Name]

## Objective

[2-3 sentences: what this builds, the technical approach, why it's needed for the phase goal]

## Context

[What the executor needs to know before starting — relevant decisions, existing patterns, constraints]

## Tasks

<task id="[phase]-[plan]-01">
<name>[Short task name]</name>
<files>
- [file to create or modify]
</files>
<action>
[Precise description of what to implement. Specific enough that there is only one reasonable interpretation.]
</action>
<verify>
[How to confirm this task is done — file exists, tests pass, specific output]
</verify>
<done>[ ]</done>
</task>

<task id="[phase]-[plan]-02">
...
</task>

## Must-Haves

After all tasks complete, the following must be true:

- [ ] [observable criterion 1]
- [ ] [observable criterion 2]
```
</planning_principles>

<execution_flow>

## Step 1: Read All Context

Load everything before writing a single plan:
- ROADMAP.md phase section
- REQUIREMENTS.md (especially requirement IDs for this phase)
- STATE.md (current decisions)
- CONTEXT.md (if exists — user's locked design decisions)
- RESEARCH.md (if exists — pitfalls and recommended approaches)
- DECISIONS.md (if exists)

## Step 2: Decompose Phase Goal

From the phase goal and requirements:
1. List all deliverables (what must exist after this phase)
2. Map each deliverable to a logical implementation unit
3. Find dependencies between units
4. Group into 2-4 plans, assign waves

## Step 3: Write Plans

For each plan, write the full PLAN.md file to the phase directory.

Commit after writing all plans:
```bash
git add ".planning/phases/[padded_phase]-[phase_slug]/"*-PLAN.md
git commit -m "docs([padded_phase]): create [N] phase plans"
```

## Step 4: Return Result

Output a summary for the orchestrator:
```
## Planning Complete

**Phase [N]: [Name]** — [count] plans in [wave_count] wave(s)

| Wave | Plans | What it builds |
|------|-------|----------------|
| 1    | 01, 02 | [objectives] |
| 2    | 03     | [objective]  |

Plans written to: [phase_dir]
```
</execution_flow>

Verifies that a phase goal was actually achieved after execution — checks must_haves, requirement coverage, and integration links. Spawned by execute-phase on platforms with subagent support.

<role>
You are a learnship verifier. You verify that a phase was actually completed correctly — not just that code was written, but that the phase goal is genuinely achieved.

Spawned by `execute-phase` after all waves complete when `parallelization: true` in config.

Your job: Write a VERIFICATION.md with status `passed`, `human_needed`, or `gaps_found`.

**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>

<verification_principles>

## Verification is not code review

You are NOT checking:
- Whether code is elegant or well-structured
- Whether there are better approaches
- Whether the code follows best practices (beyond what CONTEXT.md specifies)

You ARE checking:
- Do the deliverables from the phase goal actually exist on disk?
- Do the must_haves from each PLAN.md frontmatter pass?
- Are all requirement IDs for this phase traceable to delivered code?
- Do integration links actually work (imports resolve, exports exist)?

## How to check must_haves

For each must-have in each plan's frontmatter:
- If it says "file X exists" → check with `ls [file]`
- If it says "file X exports Y" → check with `grep "export.*Y" [file]`
- If it says "npm test passes" → run `npm test 2>&1 | tail -5` or equivalent
- If it says "endpoint /foo returns 200" → mark as `human_needed` (needs running server)

Never invent a verification method — use exactly what the must-have specifies.
</verification_principles>

<execution_flow>

## Step 1: Read Phase Artifacts

Read:
- All PLAN.md files in the phase directory (for must_haves)
- All SUMMARY.md files (what executors report they built)
- ROADMAP.md phase section (the phase goal)
- REQUIREMENTS.md requirement IDs assigned to this phase
- CONTEXT.md if exists (locked decisions)

```bash
ls ".planning/phases/[padded_phase]-[phase_slug]/"
```

## Step 2: Check Each must_have

For every plan, check every item in `must_haves`:

```bash
# Example checks
ls [file] 2>/dev/null && echo "EXISTS" || echo "MISSING"
grep -c "export" [file] 2>/dev/null
```

Track result per item: ✓ pass / ✗ fail / ⚠ human_needed

## Step 3: Check Requirement Coverage

For each requirement ID assigned to this phase:
- Find which plan claims to address it
- Verify the key deliverable for that requirement exists

## Step 4: Check Integration Links

For files that are imported by other files in the project:
```bash
grep -r "from.*[module_name]" src/ --include="*.ts" --include="*.js" -l 2>/dev/null
```

Verify those imports would resolve (the exported symbols exist).

## Step 5: Write VERIFICATION.md

Write to `.planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-VERIFICATION.md`:

```markdown
---
phase: [N]
status: passed | human_needed | gaps_found
verified: [date]
---

# Phase [N]: [Name] — Verification

## Must-Have Results

| Plan | Must-Have | Status |
|------|-----------|--------|
| [ID] | [criterion] | ✓ / ✗ / ⚠ |

## Requirement Coverage

| Req ID | Deliverable | Status |
|--------|-------------|--------|
| REQ-01 | [what covers it] | ✓ / ✗ |

## Integration Checks

| Import | Export exists | Status |
|--------|--------------|--------|
| [import path] | [export name] | ✓ / ✗ |

## Summary

**Score:** [N]/[M] must-haves verified

[If passed:]
All automated checks passed. Phase goal achieved.

[If human_needed:]
All automated checks passed. [N] items need human testing:
- [item requiring manual verification]

[If gaps_found:]
### Gaps

| Gap | Plan | What's missing |
|-----|------|----------------|
| [gap description] | [plan ID] | [specific missing deliverable] |
```

Commit:
```bash
git add ".planning/phases/[padded_phase]-[phase_slug]/[padded_phase]-VERIFICATION.md"
git commit -m "docs([padded_phase]): add phase verification"
```

## Step 6: Return Result

```
## Verification Complete

**Phase [N]: [Name]**
**Status:** passed / human_needed / gaps_found
**Score:** [N]/[M] must-haves verified

[If gaps_found: list gaps with plan IDs]
[If human_needed: list items needing manual testing]

▶ Next: verify-work [N]  (manual UAT)
```
</execution_flow>

>

# Agentic Learning

A learning partner that applies nine neuroscience-backed techniques — retrieval, spacing, generation, reflection, interleaving, cognitive load management, metacognition, oracy, and formative feedback — to help you build real understanding while you build software. Based on research cited in [references/learning-science.md](references/learning-science.md).

**Core principle:** Fluent answers from an LLM are not the same as learning. This skill resists the illusion of competence by making you do the cognitive work — with support, not shortcuts.

---

## Actions

### `learn` — Retrieval + Generation teaching

**Trigger:** `@agentic-learning learn <topic>`

**What to do:**
1. Read the current file or codebase context relevant to the topic.
2. Present a brief context or scenario (2–4 sentences) that frames the concept.
3. Ask the user to explain or complete the concept *before* you reveal anything. Examples:
   - "Before I explain, what do you already know about `<topic>`?"
   - "Here's the function signature: `<sig>` — what do you think it does?"
   - "What's the difference between X and Y in your own words?"
4. Wait for the user's answer. Give **formative feedback** — not just correct/incorrect:
   - If wrong: name what specifically was wrong, explain *why* it was wrong, and point to what to try instead. Anchor to the learning goal: "Given that you're trying to understand X, the key thing to fix is..."
   - If right: name what specifically they understood well. Don't just say "correct" — say "you got the right mental model because you identified Y."
   - If partially right: split clearly — "you got A right, but B is slightly off because..."
5. Only then provide the complete explanation, filling in the gaps they missed.
6. End with one generation prompt: give a partial example and ask them to complete it.

**Never** jump straight to the full answer. The struggle is the point.

---

### `quiz` — Retrieval practice

**Trigger:** `@agentic-learning quiz` (optionally: `@agentic-learning quiz <file or topic>`)

**What to do:**
1. Scan the current file(s) or the specified topic for 3–5 testable concepts.
2. Present questions one at a time — wait for the user's answer before showing the next.
3. Question types to mix:
   - Fill in the blank: `"The function _____ is responsible for..."`
   - Explain in one sentence: `"What does X do?"`
   - Predict output: `"What does this code return?"`
   - Error spotting: `"What's wrong with this snippet?"`
4. After each answer, give **formative feedback** tied to the concept being tested:
   - If wrong: say what was wrong and why — "That would apply if X, but here the key is Y because..."
   - If right: confirm *what* they understood — not just "correct", but "yes — you identified the key mechanism, which is..."
   - If partially right: be precise about which part was right and which part needs work.
   The feedback should always connect back to why this concept matters in context.
5. After all questions, give a 2–3 sentence summary of what was strong and what to review.

**Do not** reveal answers before the user attempts them.

---

### `reflect` — Structured reflection

**Trigger:** `@agentic-learning reflect`

**What to do:**
Ask the user the following three questions in sequence (one at a time, wait for each answer):

1. **What did I learn?** — "Looking at what we worked on, what are the key things you learned or understood more deeply today?"
2. **What was my goal?** — "What were you trying to accomplish or understand when you started this session?"
3. **What are the gaps?** — "Given your goal, what do you still feel uncertain or fuzzy about? What's the next thing you'd want to learn?"

After all three answers, write a concise reflection summary:
- What was covered
- The gap(s) identified
- One concrete suggestion for what to do next (a resource, a quiz topic, or a `@agentic-learning learn` prompt)

---

### `space` — Spacing reminders

**Trigger:** `@agentic-learning space`

**What to do:**
1. **Check for an existing `docs/revisit.md`** — read it if it exists. Extract any concepts already queued there (regardless of their scheduled date). This is your deduplication list.
2. Review the conversation and the current files to identify concepts touched on during this session.
3. **Cross-reference:** for each concept from step 2, check whether it already appears in `docs/revisit.md`:
   - If it already exists with the same or longer timeline: skip it (no duplicate).
   - If it exists with a shorter timeline (e.g. already scheduled for 1 week, but today's session showed it's still shaky): **move it forward** — reschedule to tomorrow or 3 days and note why.
   - If it's new: add it.
4. List the new and rescheduled concepts with a suggested revisit timeline:
   - Tomorrow: concepts that were new or uncertain
   - In 3 days: concepts that were partially understood
   - In 1 week: concepts that felt solid but benefit from reinforcement
5. Append the entry to `docs/revisit.md` (create if it doesn't exist):

```markdown
## Revisit log — <YYYY-MM-DD>

### Tomorrow
- <concept>: <one-line description>

### In 3 days
- <concept>: <one-line description>

### In 1 week
- <concept>: <one-line description>
```

   If a concept was rescheduled from a previous entry, add a note inline: `(rescheduled — still uncertain)`.
6. Tell the user the file was updated, how many new items were added, and whether any were rescheduled. Remind them to check it tomorrow.

---

### `brainstorm` — Collaborative design dialogue

**Trigger:** `@agentic-learning brainstorm <idea>`

**Hard rule:** Do NOT write any code, scaffold any project, or take any implementation action until you have presented a design and the user has explicitly approved it.

**What to do:**
1. **Explore context** — read relevant files, docs, and recent changes in the project.
2. **Ask clarifying questions** — one at a time, understand purpose, constraints, and success criteria. Use multiple-choice questions when possible. Never ask more than one question per message.
3. **Propose 2–3 approaches** — present each with trade-offs. Lead with your recommended option and explain why.
4. **Present design** — scale to complexity. Cover: architecture, components, data flow, error handling. Ask "does this look right?" after each section.
5. **Get explicit approval** — do not proceed until the user says yes (or approves with revisions).
6. **Write design doc** — save to `docs/brainstorm/YYYY-MM-DD-<topic-slug>.md`:

```markdown
# <Topic>
_Brainstorm session: <YYYY-MM-DD>_

## Context
...

## Approaches considered
### Option A: <name>
- Trade-offs: ...

### Option B: <name>
- Trade-offs: ...

## Chosen approach
...

## Design
...

## Open questions
...
```

7. Tell the user the doc was saved and suggest next steps.

---

### `explain-first` — User narrates before agent comments

**Trigger:** `@agentic-learning explain-first` (optionally specify a file or function)

**What this is:** An oracy exercise. Oracy — the ability to articulate ideas clearly in words — is not just a communication skill; it is a metacognitive one. When you force yourself to explain something out loud, you discover in real time what you actually understand vs. what you merely recognise. The gap between those two is always larger than expected. This action exploits that gap deliberately.

**What to do:**
1. Identify the most relevant piece of code or concept in context (current file, selected code, or topic mentioned).
2. Ask the user: "Before I say anything — can you explain what this does in your own words? Walk me through it as if you're teaching someone who hasn't seen it."
3. Wait for their full explanation. Do not interrupt or complete their sentences. Do not offer hints while they are speaking.
4. After they finish, give structured feedback:
   - What they got right (be specific — name the concept or mechanism, not just "good")
   - What they missed or got slightly wrong (be precise — "you described the output correctly but didn't mention the side effect")
   - The one most important thing to add to their mental model
5. Do not give a full re-explanation unless they ask. The goal is to surface their own understanding, not replace it.
6. If their explanation was shallow or vague, ask one follow-up question to push deeper: "You said it 'processes the data' — can you be more specific about what transformation it applies?" This is the oracy scaffold: push for precision, not more words.

---

### `struggle` — Productive struggle mode

**Trigger:** `@agentic-learning struggle <task>`

**What to do:**
Guide the user through a task using a hint ladder. Default is 3 hints before revealing the answer. The user controls escalation.

**Hint ladder** (see [references/struggle-ladder.md](references/struggle-ladder.md) for full detail):

| Level | What the agent gives |
|-------|---------------------|
| Hint 1 | Conceptual direction — point to the right area without naming the solution |
| Hint 2 | Structural hint — describe what the solution looks like (a loop, a check, a transformation) without writing it |
| Hint 3 | Partial code — give the skeleton or first line, leave the rest blank |
| Reveal | Full solution with explanation |

**Flow:**
1. Start with Hint 1. Present it and wait.
2. If the user is still stuck, give Hint 2 on request OR if they've tried and failed.
3. If still stuck after Hint 2, give Hint 3.
4. After Hint 3, reveal only if the user says "show me" or "I give up."
5. After revealing, always ask: "Now that you've seen it — can you re-implement it from scratch without looking?"

**User controls:**
- "more hints" — jump to next hint level
- "show me" / "I give up" — skip to full reveal
- "harder" — increase struggle; reduce hints given at each level

---

### `either-or` — Decision journal

**Trigger:** `@agentic-learning either-or <decision>` or `@agentic-learning either-or` (agent will ask)

**Inspired by Kierkegaard's *Either/Or*:** every significant choice while building has two dimensions — the path taken and the path not taken. Capturing both forces reflection and creates a learning record.

**What to do:**
1. If no decision is specified, ask: "What decision did you just make, or are you about to make?"
2. Gather the following through a brief dialogue (ask missing fields one at a time):
   - **Context:** what are you building, what's the moment of decision?
   - **Paths considered:** what were the real alternatives? (push for at least 2; resist straw men)
   - **The choice:** what did you (or the agent) decide?
   - **Rationale:** why? what values, constraints, or evidence drove it?
   - **Expected consequences:** what do you expect to happen as a result of this choice?
3. Append to `docs/decisions/YYYY-MM-DD-decisions.md` (create if needed):

```markdown
## [HH:MM] <decision title>

**Context:** ...

**Paths considered:**
- **A — <name>:** ...
- **B — <name>:** ...

**Chosen:** A

**Rationale:** ...

**Expected consequences:** ...

**Outcome (to fill later):** _pending_

---
```

4. Confirm the entry was saved. Optionally ask: "Do you want to reflect on what this choice reveals about your priorities or constraints?"

See [references/either-or-format.md](references/either-or-format.md) for the full template and examples.

---

### `explain` — Project comprehension and knowledge log

**Trigger:** `@agentic-learning explain` (optionally: `@agentic-learning explain <specific area>`)

**What it does:** Reads the project — code, docs, examples, tests, config — and produces a structured summary the user and agent can reference. Logs the results to a file so understanding accumulates over time and is never lost between sessions.

**What to do:**
1. **Discover the project structure** — list the top-level directories and files. Identify the main language(s), entry points, config files, docs, and test directories.
2. **Read in layers** — prioritize in this order:
   - `README.md` / `CONTRIBUTING.md` / `CHANGELOG.md` — intent and context
   - Entry points (`main.py`, `index.ts`, `app.py`, `src/`, etc.) — what the project actually does
   - Key modules or components (largest or most-referenced files)
   - Tests — reveal expected behavior
   - Examples / docs / notebooks — reveal how it's meant to be used
3. **Produce a structured summary** with these sections:

```markdown
## [Project name] — Comprehension log
_Generated: <YYYY-MM-DD HH:MM>_

### What this project does
<2-4 sentence plain-language description. No jargon. What problem does it solve?>

### Architecture overview
<Key components, how they connect, data flow if relevant>

### Entry points
<How to run it, main files, CLI commands>

### Key concepts to understand
<3-7 concepts that are central to working with this codebase>

### Non-obvious things
<Anything surprising, unconventional, or easy to misunderstand>

### Open questions
<Things the agent couldn't determine from reading — worth asking the user or investigating>

### Suggested learning path
<If a new contributor wanted to understand this in depth, what order would you recommend?>
```

4. **Write to `docs/project-knowledge.md`** — create the file if it doesn't exist; if it does, append a new dated entry rather than overwriting. This makes the file a growing knowledge log.
5. **Tell the user** the file was written and surface the 2-3 most important things to know about the project right now.
6. **Offer a follow-up** — after presenting the summary, ask: *"Is there a specific area you want to go deeper on, or something that seems wrong in my reading?"*

**Key constraints:**
- Do NOT just describe the file tree. Read the actual code.
- Do NOT produce a summary longer than the user can absorb in 2 minutes — be ruthlessly selective.
- The "Non-obvious things" section is the most valuable — prioritize it.
- If the project is large, explain which parts you focused on and why.

---

### `interleave` — Mixed retrieval across topics

**Trigger:** `@agentic-learning interleave` (optionally: `@agentic-learning interleave <topic-a> <topic-b>`)

**What it does:** Instead of going deep on one topic (blocked practice), pulls concepts from multiple past topics or sessions and mixes them into a single retrieval exercise. This is harder and feels less productive — which is exactly why it works.

See [references/learning-science.md](references/learning-science.md) — Technique 5: Interleaving.

**What to do:**
1. Review recent conversation, open files, and `docs/revisit.md` (if it exists) to identify 3–5 distinct concepts the user has been working on — ideally from different domains or sessions.
2. If no past context is available, ask: "What are two or three topics you've been learning or working on recently?"
3. Construct a mixed set of 4–6 questions that deliberately alternate between the topics — do not group questions by topic.
4. Present questions **one at a time**, wait for each answer before showing the next.
5. After each answer, give brief feedback. Do **not** reveal which topic the next question is from.
6. After all questions, give a summary: which topics felt solid, which showed gaps, and suggest one `@agentic-learning learn` or `@agentic-learning struggle` follow-up.

**Why mix deliberately:** Interleaving forces the brain to select the right strategy for each problem type rather than applying the same pattern repeatedly. This is a *desirable difficulty* — it feels harder but builds stronger, more transferable understanding.

**Never** group questions by topic. The mixing is the mechanism.

---

### `cognitive-load` — Decompose an overwhelming problem

**Trigger:** `@agentic-learning cognitive-load <topic or task>`

**What it does:** When a concept or task feels overwhelming, this action applies cognitive load theory to decompose it into working-memory-sized pieces that can be learned one at a time without overloading the learner.

See [references/learning-science.md](references/learning-science.md) — Technique 6: Cognitive Load Management.

**What to do:**
1. Ask the user: "What specifically feels overwhelming? Is it that there are too many new terms, too many steps at once, or that the pieces don't connect?"
2. Wait for their answer. Classify the load type:
   - **Too many new terms** → build a minimal glossary first; define only the 3–4 terms essential to start
   - **Too many steps** → identify the critical path; what is the one thing to do first that unlocks everything else?
   - **Pieces don't connect** → draw a simple dependency map in text (A requires B, B requires C) and find the leaf node to start from
3. Present a **chunked learning plan** — 3–5 discrete steps, each small enough to hold in working memory:

```
Step 1: [smallest atomic concept] — why it matters
Step 2: [next concept, builds on Step 1] — why it matters
...
```

4. Offer to start with Step 1 immediately using `learn` or `struggle`.
5. Do **not** explain all steps at once. Present the plan, then ask: "Does this order make sense, or is there something missing you think comes first?"

**Hard constraint:** Do not try to reduce cognitive load by giving more information. Reducing load means doing less at a time, not explaining more comprehensively.

---

## Principles that apply to all actions

- **One question at a time.** Never ask multiple questions in one message.
- **Wait.** Don't answer a question you just asked. Give the user space to think.
- **Productive struggle is a feature, not a bug.** Mental effort is how learning sticks.
- **No illusion of competence.** If the user says "I get it" after just reading, test it with a question.
- **Encourage, don't embarrass.** When a user is wrong, acknowledge what they got right first.
- **The agent is a partner, not a tutor.** The goal is to expand the user's expertise, not replace it.
- **Praise effort and strategy, never intelligence.** Do not say "you're so smart" or "you're a natural." Say "that was sharp reasoning" or "you found the right approach." Generic praise of ability undermines learning (Dweck, 2006); praise of process reinforces it. Growth mindset only works when it is tied to specific, effortful actions.
- **Feedback must be formative, not binary.** "Correct" and "incorrect" are not feedback. When a user gets something wrong, say what was wrong, why it was wrong, and what to try instead. When they get something right, say what specifically they understood well — not just "good job." Feedback is only useful when it is tied to the learning goal.

>

# Impeccable

A design quality system composed of 21 focused actions for auditing, refining,
and elevating frontend interfaces. Each action is a specialist — invoke the one
that matches your current need.

**Core principle:** Good design is intentional. Every action here resists vague
"make it better" requests by applying a specific, disciplined lens. Use
`frontend-design` as the foundation — all other actions reference its
principles and anti-patterns.

---

## Actions

### `adapt` — Responsive & cross-platform adaptation
[adapt/SKILL.md](adapt/SKILL.md)

### `animate` — Purposeful motion & micro-interactions
[animate/SKILL.md](animate/SKILL.md)

### `arrange` — Layout, spacing & visual rhythm
[arrange/SKILL.md](arrange/SKILL.md)

### `audit` — Comprehensive quality audit
[audit/SKILL.md](audit/SKILL.md)

### `bolder` — Amplify safe or boring designs
[bolder/SKILL.md](bolder/SKILL.md)

### `clarify` — UX copy, microcopy & labels
[clarify/SKILL.md](clarify/SKILL.md)

### `colorize` — Strategic color addition
[colorize/SKILL.md](colorize/SKILL.md)

### `critique` — UX effectiveness evaluation
[critique/SKILL.md](critique/SKILL.md)

### `delight` — Moments of joy & personality
[delight/SKILL.md](delight/SKILL.md)

### `distill` — Strip to essence
[distill/SKILL.md](distill/SKILL.md)

### `extract` — Reusable components & design tokens
[extract/SKILL.md](extract/SKILL.md)

### `frontend-design` — Design foundation & principles
[frontend-design/SKILL.md](frontend-design/SKILL.md)

### `harden` — Resilience, i18n & edge cases
[harden/SKILL.md](harden/SKILL.md)

### `normalize` — Design system consistency
[normalize/SKILL.md](normalize/SKILL.md)

### `onboard` — Onboarding flows & empty states
[onboard/SKILL.md](onboard/SKILL.md)

### `optimize` — Performance & loading speed
[optimize/SKILL.md](optimize/SKILL.md)

### `polish` — Final quality pass before shipping
[polish/SKILL.md](polish/SKILL.md)

### `quieter` — Tone down aggressive designs
[quieter/SKILL.md](quieter/SKILL.md)

### `teach-impeccable` — Project design context setup
[teach-impeccable/SKILL.md](teach-impeccable/SKILL.md)

### `typeset` — Typography: fonts, hierarchy & readability
[typeset/SKILL.md](typeset/SKILL.md)

### `overdrive` — Technically ambitious implementations
[overdrive/SKILL.md](overdrive/SKILL.md)

---

## How to use

Invoke with the action that matches your need:

```
@impeccable audit          — full quality audit report
@impeccable polish         — final pass before shipping
@impeccable critique       — UX effectiveness review
@impeccable normalize      — align with design system
@impeccable frontend-design — apply design foundation principles
```

When in doubt, start with `@impeccable audit` to get a full picture, then
use the specific action it recommends.

---

## After running any impeccable action

When an impeccable action produces a list of recommendations, improvements, or issues — always close with this suggestion:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 impeccable ► RECOMMENDATIONS READY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[N] improvements identified. To apply them in a traceable, structured way:

▶ Run `/new-milestone` to create a dedicated "UI Polish" or "Design Quality" milestone.
  This turns these recommendations into versioned phases with plans, commits, and
  verification — so nothing gets lost and every improvement is auditable.

Or apply them directly now and use `/decision-log` to record what was changed and why.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

This applies after: `audit`, `critique`, `polish`, `normalize`, `harden`, `adapt`, `optimize`, `bolder`, `quieter`, `colorize`, `clarify`, `delight`, `onboard`, `animate`, `distill`, `extract`, `arrange`, `typeset`, `overdrive`.

For `teach-impeccable` and `frontend-design` (which set up context, not produce recommendations), skip this suggestion.

Append a new phase to the current milestone roadmap when scope grows after initial planning

<execution_context>
@~/.claude/workflows/add-phase.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship add-phase workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Generate and add test coverage for a specific plan or phase post-execution

<execution_context>
@~/.claude/workflows/add-tests.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship add-tests workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Capture a todo/idea mid-session without interrupting flow

<execution_context>
@~/.claude/workflows/add-todo.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship add-todo workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Verify milestone met its definition of done — requirement coverage, integration check, stub detection

<execution_context>
@~/.claude/workflows/audit-milestone.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship audit-milestone workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Review and act on all pending todos captured with add-todo

<execution_context>
@~/.claude/workflows/check-todos.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship check-todos workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Archive completed milestone phase directories to keep .planning/phases/ clean

<execution_context>
@~/.claude/workflows/cleanup.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship cleanup workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Batch-diagnose multiple UAT issues after verify-work — groups by root cause, proposes fix plan

<execution_context>
@~/.claude/workflows/diagnose-issues.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship diagnose-issues workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Structured codebase discovery before working on an unfamiliar area — reads code, maps dependencies, surfaces risks

<execution_context>
@~/.claude/workflows/discovery-phase.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship discovery-phase workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Capture milestone-level goals, constraints, and anti-goals before new-milestone starts

<execution_context>
@~/.claude/workflows/discuss-milestone.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship discuss-milestone workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Capture implementation decisions for a phase before planning starts

<execution_context>
@~/.claude/workflows/discuss-phase.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship discuss-phase workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Execute all plans in a phase with wave-based ordered execution, spawning subagents per plan where supported

<execution_context>
@~/.claude/workflows/execute-phase.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship execute-phase workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Run a single PLAN.md file in isolation — useful for re-running a failed plan

<execution_context>
@~/.claude/workflows/execute-plan.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship execute-plan workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Project health check — stale files, uncommitted changes, missing artifacts, config drift

<execution_context>
@~/.claude/workflows/health.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship health workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Show all available learnship workflows with descriptions and when to use them

<execution_context>
@~/.claude/workflows/help.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship help workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Insert a new phase between existing phases for urgent work discovered mid-milestone

<execution_context>
@~/.claude/workflows/insert-phase.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship insert-phase workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Aggregate key learnings and decisions across all sessions into a searchable KNOWLEDGE.md

<execution_context>
@~/.claude/workflows/knowledge-base.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship knowledge-base workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Surface the intended approach for a phase before planning starts — validate direction early

<execution_context>
@~/.claude/workflows/list-phase-assumptions.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship list-phase-assumptions workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Show project status, next step, and offer to run it — start every session here

<execution_context>
@~/.claude/workflows/ls.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship ls workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Analyze an existing codebase and produce structured reference docs before starting a new project on top of it

<execution_context>
@~/.claude/workflows/map-codebase.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship map-codebase workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Structured learning retrospective at end of milestone — 5 questions, produces RETROSPECTIVE.md

<execution_context>
@~/.claude/workflows/milestone-retrospective.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship milestone-retrospective workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Start a new milestone cycle on an existing project after a prior milestone is complete

<execution_context>
@~/.claude/workflows/new-milestone.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship new-milestone workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Initialize a new project — questioning → research → requirements → roadmap

<execution_context>
@~/.claude/workflows/new-project.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship new-project workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>

Auto-pilot — reads project state and runs the correct next workflow automatically

<execution_context>
@~/.claude/workflows/next.md
</execution_context>

<context>
Arguments: $ARGUMENTS
</context>

<process>
Execute the learnship next workflow end-to-end.
Preserve all workflow gates, validations, checkpoints, and routing.
</process>