---
paths: ".claude/plans/**/*.md"
description: Plan file creation, self-containment, and resume procedure
version: "1.0"
created: 2026-05-16
source: Relocated from DevForgeAI.md "Plan File Convention" section
---

# Plan File Creation

Applies when creating or resuming a plan file under `.claude/plans/`.

## Self-Containment

Plans MUST be self-contained: full documentation, reference links, and progress
checkpoints that survive context-window clears. A plan a fresh session cannot resume
from is incomplete.

## Before Creating a New Plan File

1. `Glob(".claude/plans/*.md")` — list all existing plan files.
2. `Grep(pattern="STORY-XXX", path="{plan_file}")` — search each for the story ID.
3. If a match is found, offer to resume the existing plan via `AskUserQuestion`.
4. If no match, create a new plan with the story ID in the filename (e.g., `STORY-NNN-plan.md`).

## Plan Retirement

Plan files referenced in any provenance-chain artifact (epic `plan_file:`, brainstorm
`Feeds Into:`, ADR citations) MUST be archived to `.claude/plans/archive/`, NOT deleted —
deletion permanently breaks the provenance chain. Enforced by `pre-plan-file-rm-guard.sh`
(PreToolUse[Bash], `exit 2`). Full verification and archive procedure:
`.claude/rules/workflow/plan-file-archive.md`.
