refactor(plan-commands): Move schema and examples out of commands/

- Move SCHEMA.md to docs/src/context/plan/schema.md
- Move examples/ to tests/plans/
- Update references in create.md, review.md, refine.md
- Symlinks in commands/ ARE followed for discovery (tested)

Files outside commands/ don't appear in slash command autocomplete.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: aRustyDev

context/commands/context/plan/create.md

@@ -1,12 +1,12 @@
 ---
 description: Create a new plan document with proper structure for multi-phase work
-argument-hint: <plan-name> [--phases N] [--location .claude|.plans]
+argument-hint: <plan-name> [--phases N] [--location .claude|.plans] [--minimal]
 allowed-tools: Read, Write, Bash(mkdir:*), Bash(ls:*), AskUserQuestion
 ---
 
 # Create Plan
 
-Create a structured plan document for multi-phase work with proper organization.
+Create a structured plan document for multi-phase work with proper organization. Generated plans comply with the schema defined in `docs/src/context/plan/schema.md`.
 
 ## Arguments
 
@@ -15,12 +15,13 @@ Create a structured plan document for multi-phase work with proper organization.
 - `--location` - Where to create the plan:
   - `.claude` (default): `.claude/plans/<plan-name>/`
   - `.plans`: `.plans/<plan-name>/`
+- `--minimal` - Skip interactive questions, use placeholder values
 
 ## Output
 
 ```text
 <location>/<plan-name>/
-├── index.md           # Plan overview and status
+├── PLAN.md            # Unified plan (schema-compliant)
 └── phase/
     ├── 1-<name>.md    # Phase documents
     ├── 2-<name>.md
@@ -35,54 +36,76 @@ Create a structured plan document for multi-phase work with proper organization.
 2. Validate format: `^[a-z][a-z0-9-]{0,46}[a-z0-9]$`
 3. Parse `--phases` (default: 3)
 4. Parse `--location` (default: `.claude`)
-5. Determine target path
-6. Check if plan exists — ask to overwrite or rename
+5. Parse `--minimal` flag (default: false)
+6. Determine target path
+7. Check if plan exists — ask to overwrite or rename
 
 ### Step 2: Gather Plan Information
 
+Skip this step if `--minimal` flag is set (use placeholders instead).
+
 Use AskUserQuestion to collect:
 
 1. **Plan Title**: Human-readable title
-2. **Objective**: What does this plan accomplish? (2-3 sentences)
-3. **Success Criteria**: How do we know it's done? (3-5 bullet points)
-4. **Phase Names**: Name for each phase (or use defaults)
+2. **Objectives**: What does this plan accomplish? (Ask for 2-3 measurable objectives)
+   - Prompt: "List 2-3 objectives. For each, include how you will measure success. Example: 'Reduce API latency to <100ms (measured via p95 metrics)'"
+3. **Current State Metrics**: What is the current state?
+   - Prompt: "List 1-3 metrics with current values and target values. Example: 'API latency: Current=350ms, Target=100ms'"
+4. **Phase Names**: Name for each phase (or use defaults like "Setup", "Implementation", "Validation")
+5. **Key Risks**: What could go wrong?
+   - Prompt: "List 1-2 potential risks and how you would mitigate them."
 
 ### Step 3: Create Directory Structure
 
 ```bash
 mkdir -p "<location>/<plan-name>/phase"
 ```
 
-### Step 4: Generate Index
+### Step 4: Generate PLAN.md
 
-Write `index.md`:
+Write `PLAN.md`:
 
 ```markdown
 # <Plan Title>
 
-## Objective
+**Created:** <YYYY-MM-DD>
+**Updated:** <YYYY-MM-DD>
+**Owner:** <user or team>
 
-<objective from user>
+## Objectives
 
-## Status
+| # | Objective | Measurable | Success Metric |
+|---|-----------|------------|----------------|
+| 1 | <objective 1> | Yes | <how to measure> |
+| 2 | <objective 2> | Yes | <how to measure> |
 
-| Phase | Name | Status | Notes |
-|-------|------|--------|-------|
-| 1 | <phase-1-name> | pending | |
-| 2 | <phase-2-name> | pending | |
-| ... | ... | ... | |
+## Current State
 
-## Success Criteria
-
-- [ ] <criterion 1>
-- [ ] <criterion 2>
-- [ ] <criterion 3>
+| Metric | Current | Target | Gap |
+|--------|---------|--------|-----|
+| <metric 1> | <current value> | <target value> | <delta> |
+| <metric 2> | <current value> | <target value> | <delta> |
 
 ## Phases
 
-1. [<Phase 1 Name>](./phase/1-<slug>.md)
-2. [<Phase 2 Name>](./phase/2-<slug>.md)
-...
+| ID | Name | Status | Dependencies | Success Criteria |
+|----|------|--------|--------------|------------------|
+| phase-1 | <phase-1-name> | pending | - | <summary> |
+| phase-2 | <phase-2-name> | pending | phase-1 | <summary> |
+| phase-3 | <phase-3-name> | pending | phase-2 | <summary> |
+
+### Phase Details
+
+1. [Phase 1: <Phase 1 Name>](./phase/1-<slug>.md)
+2. [Phase 2: <Phase 2 Name>](./phase/2-<slug>.md)
+3. [Phase 3: <Phase 3 Name>](./phase/3-<slug>.md)
+
+## Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| <risk 1> | Medium | Medium | <mitigation strategy> |
+| <risk 2> | Low | High | <mitigation strategy> |
 
 ## Timeline
 
@@ -92,11 +115,9 @@ Write `index.md`:
 | Phase 1 complete | | |
 | All phases complete | | |
 
-## Risks
+## Rollback Strategy
 
-| Risk | Likelihood | Impact | Mitigation |
-|------|------------|--------|------------|
-| | | | |
+<describe how to revert changes if needed>
 
 ## Notes
 
@@ -110,37 +131,71 @@ For each phase, write `phase/N-<slug>.md`:
 ```markdown
 # Phase N: <Phase Name>
 
+**ID:** `phase-N`
+**Dependencies:** <phase-ids or None>
+**Status:** pending
+**Effort:** <estimate or TBD>
+
 ## Objective
 
-<What this phase accomplishes>
+<What this phase accomplishes - 1-2 sentences>
+
+## Success Criteria
 
-## Prerequisites
+- [ ] <measurable criterion 1>
+- [ ] <measurable criterion 2>
+- [ ] <measurable criterion 3>
 
-- [ ] <dependency from previous phase>
+## Deliverables
+
+| Deliverable | Location | Format |
+|-------------|----------|--------|
+| <deliverable 1> | `<file path>` | <type> |
+| <deliverable 2> | `<file path>` | <type> |
+
+## Files
+
+**Create:**
+- `<path/to/new/file>` (or "None" if no files to create)
+
+**Modify:**
+- `<path/to/existing/file>` (or "None" if no files to modify)
 
 ## Tasks
 
 - [ ] Task 1
 - [ ] Task 2
 - [ ] Task 3
 
-## Deliverables
+## Notes
 
-| Deliverable | Status | Location |
-|-------------|--------|----------|
-| | pending | |
+<phase-specific notes>
+```
 
-## Acceptance Criteria
+### Step 6: Validate Output
 
-- [ ] <criterion 1>
-- [ ] <criterion 2>
+Before reporting, validate the generated plan against the schema:
 
-## Notes
+1. **PLAN.md Validation:**
+   - [ ] Has `## Objectives` section with table containing `Measurable` column
+   - [ ] Has `## Current State` section with `Current`, `Target`, `Gap` columns
+   - [ ] Has `## Phases` section with `ID`, `Dependencies`, `Status` columns
+   - [ ] Has `## Risks` section with `Mitigation` column
+   - [ ] At least 1 objective, 1 metric, 1 phase, 1 risk
 
-<phase-specific notes>
-```
+2. **Phase Document Validation (for each phase):**
+   - [ ] Has metadata block with `**ID:**`, `**Dependencies:**`, `**Status:**`
+   - [ ] Has `## Objective` section (non-empty)
+   - [ ] Has `## Success Criteria` as checklist with 2+ items
+   - [ ] Has `## Deliverables` table with `Location` column
+   - [ ] Has `## Files` section with `**Create:**` and/or `**Modify:**` subsections
+
+3. **Record validation result:**
+   - `PASS` - All required elements present
+   - `WARN` - Optional elements missing (still valid)
+   - `FAIL` - Required elements missing (should not happen with this command)
 
-### Step 6: Report
+### Step 7: Report
 
 ```text
 ## Plan Created
@@ -150,13 +205,20 @@ For each phase, write `phase/N-<slug>.md`:
 | Plan | <plan-name> |
 | Location | <path> |
 | Phases | N |
+| Schema | PASS |
 
 **Files created:**
-- <path>/index.md
+- <path>/PLAN.md
 - <path>/phase/1-<name>.md
 - <path>/phase/2-<name>.md
 ...
 
+**Schema validation:**
+- PLAN.md: PASS (all required sections present)
+- Phase 1: PASS
+- Phase 2: PASS
+...
+
 **Next steps:**
 1. Review and refine phase details
 2. Run `/context:plan:review <path>` to check for gaps
@@ -174,6 +236,9 @@ For each phase, write `phase/N-<slug>.md`:
 
 # Create in .plans/ directory
 /context:plan:create feature-rollout --location .plans
+
+# Quick scaffolding without interactive questions
+/context:plan:create quick-fix --minimal
 ```
 
 ## Plan Status Values
@@ -184,9 +249,26 @@ For each phase, write `phase/N-<slug>.md`:
 | `in-progress` | Currently being worked |
 | `blocked` | Waiting on dependency |
 | `complete` | Finished and verified |
-| `deferred` | Postponed |
+| `skipped` | Intentionally skipped |
+
+## Placeholder Values (for --minimal mode)
+
+When `--minimal` is used, populate with these placeholders:
+
+| Field | Placeholder |
+|-------|-------------|
+| Objectives | "Define objective (make measurable)" |
+| Current State Metric | "Metric TBD" |
+| Current/Target Values | "TBD" |
+| Gap | "-" |
+| Risk | "None identified" |
+| Mitigation | "N/A" |
+| Phase Names | "Setup", "Implementation", "Validation" |
+| Deliverables | "TBD" |
+| Files Create/Modify | "None" |
 
 ## Related Commands
 
-- `/context:plan:review` - Review plan for gaps
+- `/context:plan:review` - Review plan for gaps and schema compliance
+- `/context:plan:refine` - Refine plan with AI assistance
 - `/string-beads` - Convert plan to beads issues