plan-schema

/plan-creator (or /bug-plan-creator, /code-quality-plan-creator)
    ↓ writes
docs/plans/{slug}-{hash5}-plan.md
    ↓ consumed by (choose one)
    └─ /plan-loop or /plan-swarm        → executes plan directly

docs/plans/{slug}-{hash5}-plan.md

## Summary

[2-3 sentence executive summary of what will be built/fixed and why]

## Files

> **Note**: This is the canonical file list.

### Files to Edit
- `path/to/existing1`
- `path/to/existing2`

### Files to Create
- `path/to/new1`
- `path/to/new2`

## Code Context

[Raw findings from codebase investigation - file:line references, patterns, architecture.
 This section preserves investigation notes for converters to copy into task descriptions.]

## External Context

[API references, library documentation, best practices, installation commands.
 "N/A" if no external research was needed.]

### Selected Approach

**Approach**: [Name]
**Description**: [How it will be implemented]
**Rationale**: [Why this is the best approach]
**Trade-offs Accepted**: [Limitations or compromises]

## Implementation Plan

### path/to/file [edit|create]

**Purpose**: [What this file does]
**TOTAL CHANGES**: [N] (exact count)

**Changes**:
1. [Change description with exact line numbers]
2. [Another change with line numbers]

**Implementation Details**:
- Exact function signatures with types
- Import statements needed
- Integration points with other files

**Reference Implementation** (REQUIRED - FULL code):
```language
// COMPLETE implementation — copy-paste ready
// ALL imports, ALL functions, ALL logic

// BEFORE (current code at line X):
const oldCode = something()

// AFTER (new code):
const newCode = somethingBetter()

**Success Criteria guidelines:**
- Must be task-specific, not generic "tests pass"
- Include the exact command to verify (scoped to this file/feature)
- Should be runnable by the executor to confirm task completion
- Examples:
  - `npm test -- src/auth/middleware.test.ts` (run specific test file)
  - `grep -q "export function validateToken" src/auth/service.ts` (verify export exists)
  - `curl -s localhost:3000/health | jq -e '.status == "ok"'` (verify endpoint works)

### Dependency Graph

Maps files to phased execution order. Source of truth for converter dependency wiring.

```markdown
## Dependency Graph

> Files in the same phase can execute in parallel.

| Phase | File | Action | Depends On |
|-------|------|--------|------------|
| 1 | `src/types/auth.ts` | create | — |
| 1 | `src/config/oauth.ts` | create | — |
| 2 | `src/services/auth.ts` | create | `src/types/auth.ts`, `src/config/oauth.ts` |
| 3 | `src/routes/auth.ts` | edit | `src/services/auth.ts` |

## Exit Criteria

### Test Commands
```bash
[test-command]        # e.g., npm test, pytest, go test ./...
[lint-command]        # e.g., npm run lint, ruff check
[typecheck-command]   # e.g., npm run typecheck, mypy .

[test-command] && [lint-command] && [typecheck-command]

## Banned Anti-Patterns

These phrases are forbidden in plans — replace with exact specifications:

Replace with: exact exceptions, specific line numbers, file:line references, explicit lists, exact import statements, complete signatures with types.

## Validation Checklist

### Structure
- [ ] All required sections exist (Summary, Files, Code Context, External Context, Architectural Narrative, Implementation Plan, Dependency Graph, Exit Criteria)
- [ ] Each per-file entry has: Purpose, Changes (numbered with line numbers), Reference Implementation, Success Criteria, Dependencies, Provides

### Dependencies
- [ ] Every per-file `Dependencies` has a matching `Provides` in another file
- [ ] No circular dependencies
- [ ] Interface signatures are identical everywhere they appear
- [ ] Dependency Graph table includes ALL files from `## Files`
- [ ] Phase assignments match per-file Dependencies
- [ ] Phase 1 files have no dependencies on other plan files

### TDD Compliance
- [ ] Every production file with business logic has a corresponding test file
- [ ] Test files appear in earlier dependency graph phases than production files they test
- [ ] Each test file has specific test cases listed (not vague "add tests")

### Consumer Readiness
- [ ] Each file's instructions are implementable without questions
- [ ] All function signatures include full types
- [ ] All imports listed
- [ ] Line numbers provided for edits
- [ ] Full reference implementation code included (not patterns)

### Per-Task Verification
- [ ] Every per-file entry has a Success Criteria section
- [ ] Success Criteria includes at least one runnable verification command
- [ ] Verification commands are scoped to the specific task (not global test suite)
- [ ] No vague criteria like "tests pass" — must be specific and actionable

### Requirements Coverage
- [ ] Every requirement maps to at least one file change
- [ ] No requirements are orphaned

## Instructions

The user invoked this skill with arguments: `$ARGUMENTS`

Determine mode from the arguments.

### If the arguments start with `validate`:

Extract the path from the arguments (e.g., `/plan-schema validate docs/plans/auth-a3f9e-plan.md`).

Read the plan file and check against the validation checklist:

1. Check all required sections exist
2. Check each per-file entry has required subsections (including Success Criteria)
3. Check Dependency Graph includes all files from `## Files`
4. Check for banned anti-patterns
5. Check Dependencies/Provides consistency
6. Check each Success Criteria has a runnable verification command
7. Report violations with the fix from the schema above

### If no arguments were provided:

Output the quick reference: