plan-schema

Plan file schema reference for architectural plans created by /plan-creator, /bug-plan-creator, and /code-quality-plan-creator. Use this when creating, editing, or reviewing .claude/plans/*-plan.md files.

When to Use

Invoke /plan-schema before manually editing any plan file. Invoke /plan-schema validate <path> to check an existing plan.

Core Concepts

Plans are markdown files in .claude/plans/ that specify HOW to implement a feature, fix, or improvement. They are consumed by:

• /plan-loop and /plan-swarm — execute plans directly
• /tasks-converter — converts to prd.json for /tasks-loop, /tasks-swarm, or RalphTUI
• /beads-converter — converts to beads for /beads-loop, /beads-swarm, or RalphTUI

Conversion Pipeline

Plans are the intermediate representation between creators and executors:

/plan-creator (or /bug-plan-creator, /code-quality-plan-creator)
    ↓ writes
.claude/plans/{slug}-{hash5}-plan.md
    ↓ consumed by (choose one)
    ├─ /plan-loop or /plan-swarm        → executes plan directly
    ├─ /tasks-converter <plan-path>     → .claude/prd/<slug>.json
    │       ↓ executed by
    │       /tasks-loop or /tasks-swarm or ralph-tui
    └─ /beads-converter <plan-path>     → .beads/ (bd CLI issues)
            ↓ executed by
            /beads-loop or /beads-swarm or ralph-tui

Direct execution (/plan-loop, /plan-swarm) reads the plan file and implements each file entry in dependency order. No intermediate format needed.

Converted execution (/tasks-converter, /beads-converter) transforms the plan into prd.json or beads. Each task/bead gets a 100% self-contained description — the executor agent receives only the task description, never the source plan. All code, requirements, and verification commands are copied verbatim from the plan.

File Naming

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

Slug: kebab-case, concise. Hash: 5-char lowercase alphanumeric.

Required Sections

Every plan must have these sections in order:

Additional Sections by Plan Type

Section Details

Summary

## Summary

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

Files

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

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

## External Context

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

Architectural Narrative

Contains these subsections (all required):

Selected Approach format:

### Selected Approach

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

Bug plans use ### Fix Strategy instead of ### Selected Approach (same format).

Implementation Plan

Per-file instructions. Each file gets its own subsection:

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

Migration Pattern (for edits — show before/after):

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

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

Dependencies: [File paths from this plan that must exist first] Provides: [Exports other plan files depend on]

### Dependency Graph

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

```markdown
## Dependency Graph

> Converters use this to build `dependsOn` (prd.json) or `depends_on` (beads).
> 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` |

Rules:

• Phase 1 = files with no dependencies on other plan files
• Phase N+1 = files whose deps are ALL in phases <= N
• Same phase = parallel (no inter-dependencies)
• Dependency = real code dependency (imports, extends, uses)
• Every file from ## Files must appear in this table

Exit Criteria

## 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 .

Success Conditions

• All tests pass (exit code 0)
• No linting errors (exit code 0)
• No type errors (exit code 0)
• All requirements satisfied
• All files implemented

Verification Script

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

## Converter Mapping

How converters translate plan sections into task/bead fields:

| Plan Section | prd.json Field | Beads (`bd`) Fie