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

| Creator | Pattern | Example | |---------|---------|---------| | /plan-creator | {feature-slug}-{hash5}-plan.md | oauth2-authentication-a3f9e-plan.md | | /bug-plan-creator | bug-plan-creator-{identifier}-{hash5}-plan.md | bug-plan-creator-auth-null-pointer-4k2m7-plan.md | | /code-quality-plan-creator | code-quality-{filename}-{hash5}-plan.md | code-quality-auth_service-3m8k5-plan.md |

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

Required Sections

Every plan must have these sections in order:

| Section | Purpose | Converter Use | |---------|---------|---------------| | ## Summary | 2-3 sentence executive summary | name and description fields | | ## Files | Canonical list of files to edit/create | Task/bead count | | ## Code Context | Raw investigation findings with file:line refs | Copied into task descriptions | | ## External Context | API docs, library references, best practices | Copied into task descriptions | | ## Architectural Narrative | Architecture, approach, requirements, constraints | Requirements → acceptanceCriteria | | ## Implementation Plan | Per-file instructions with full code | Task/bead description body | | ## Dependency Graph | Phase table mapping files to execution order | dependsOn (prd.json) / bd dep add (beads) | | ## Exit Criteria | Test commands and success conditions | acceptanceCriteria / bead exit criteria |

Additional Sections by Plan Type

| Plan Type | Extra Sections | |-----------|---------------| | Bug plan | ## Error Analysis (Original Error, Root Cause, Code Path), ## Investigation Findings (Evidence, Hypothesis Testing, Root Cause Location) | | Code quality plan | ## LSP Analysis Summary (Symbols Found, Reference Analysis) |

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):

| Subsection | Content | |------------|---------| | ### Task | Detailed task description | | ### Architecture | Current system architecture with file:line references | | ### Selected Context | Relevant files and what they provide | | ### Relationships | Component dependencies and data flow | | ### External Context | Key documentation findings | | ### Implementation Notes | Patterns, edge cases, specific guidance | | ### Ambiguities | Open questions or decisions made | | ### Requirements | Numbered acceptance criteria — ALL must be satisfied | | ### Constraints | Hard technical constraints | | ### Selected Approach | Single chosen approach with rationale (see below) |

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):

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

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

[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