---
name: formalize-plan
description: Convert a Claude plan file into canonical MASTER_PLAN format
arguments: "[--split]"
---

# /formalize-plan Command

Read the most recent `.claude/plans/*.md` file and reformat it into the canonical MASTER_PLAN structure using `## Steps` with checkboxes.

## Arguments

- `--split` — Split a multi-phase plan into separate numbered `MASTER_PLAN[N].md` files (one per phase)

## Behavior

### Step 1: Find the Most Recent Plan

Use the Glob tool to find all `.claude/plans/*.md` files, then read the most recent one by modification time.

If no plan files exist, tell the user:
> No plan files found in `.claude/plans/`. Enter plan mode first (`/plan`), create a plan, then run `/formalize-plan`.

### Step 2: Read the Canonical Template

Read the template for reference:

```
${CLAUDE_PLUGIN_ROOT}/templates/MASTER_PLAN.md
```

### Step 3: Read and Analyze the Plan

Read the plan file contents. Identify:
- The plan's objective/goal
- Files to be created or modified
- Numbered steps
- Any verification steps mentioned

### Step 4: Determine Output Mode

**If `--split` was passed AND the plan has multiple phases:**
- Determine the next MASTER_PLAN number:
  ```bash
  bash "${CLAUDE_PLUGIN_ROOT}/scripts/next-plan-number.sh"
  ```
- Create one `MASTER_PLAN[N].md` per phase, incrementing N for each

**Otherwise (default):**
- Determine the next number and write a single `MASTER_PLAN[N].md`

### Step 5: Reformat into Canonical Structure

Transform the plan content into the canonical format with `## Steps` using checkboxes:

```markdown
# Master Plan: [Descriptive Title]

## Objective

[1-2 sentence description extracted from the plan]

## Files

| File | Change |
|------|--------|
| `path/to/file` | Description of change |

## Steps

- [ ] **1. [First step title]**
  - Detail or substep
  - Key files: `path/to/file`

- [ ] **2. [Second step title]**
  - Detail or substep

## Verification

- [ ] Verification check
```

Preserve the technical substance of the original plan. Do not add or remove implementation details — only restructure the format.

### Step 6: Write Output

Write the reformatted plan(s) to the project root.

### Step 7: Report and Offer Promotion

Tell the user:
- Source plan file that was read
- Output file(s) created
- Summary of the canonical structure (objective, file count, step count)
- Note that the original `.claude/plans/` file is untouched
- Suggest using `/promote` to activate the plan

## Example

```
/formalize-plan
```

Output:
```
Read: .claude/plans/2026-02-12_hook-generation.md

Created MASTER_PLAN9.md: Hook Generation System

Sections:
  Objective: Implement configurable git hook generation
  Files: 6 files to create/modify
  Steps: 4 numbered steps
  Verification: 3 checks

Source plan file left unchanged.
Use /promote to activate this plan.
```

### Split Example

```
/formalize-plan --split
```

Output:
```
Read: .claude/plans/2026-02-12_hook-generation.md

Created 3 plan files:
  MASTER_PLAN9.md  — Phase 1: Hook template engine
  MASTER_PLAN10.md — Phase 2: CLI integration
  MASTER_PLAN11.md — Phase 3: Test suite

Source plan file left unchanged.
Use /promote to activate the first plan.
```
