/plan-schema

name: plan-schema
description: Plan file (.claude/plans/*-plan.md) reference — sections, per-file format, dependency graph, and converter mappings
allowed-tools: Bash, Read, Write, Edit
argument-hint: "[validate <path>]"

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 descri