# Plan Format

> This skill should be used when creating plan files, writing Gherkin requirements, generating tasks with verification commands, or parsing plan file structure. Provides the plan file template and format specifications.

- Skill: `majiayu000/plan-format` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/plan-format`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/plan-format/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/plan-format

---


# Plan File Format

Specification for plan files used by the tommymorgan plugin. Plan files capture feature requirements as Gherkin scenarios and tasks with verification commands.

## Plan File Purpose

Plan files serve as the single source of truth for feature development:
- Capture requirements as executable Gherkin scenarios
- Define tasks with verification commands that prove completion
- Track progress across Claude sessions
- Enable autonomous TDD execution

## File Location

Plan files live in the project's plans directory:

```
<project>/plans/YYYY-MM-DD-<slug>.md
```

Where:
- `<project>` is the project path (e.g., `apps/web`, `libs/shared`, `tools/cli`)
- `YYYY-MM-DD` is the creation date
- `<slug>` is a kebab-case version of the feature name

Example: `apps/web/plans/2024-12-15-user-authentication.md`

## Plan File Template

```markdown
# Feature: <Title>

**Created**: YYYY-MM-DD
**Branch**: feat/<slug>
**Goal**: <One-sentence description of user-facing outcome>

## Requirements

Feature: <Feature Name>
  Scenario: <Scenario name>
    Given <precondition>
    When <action>
    Then <expected outcome>
    And <additional outcome>

  Scenario: <Another scenario>
    Given <precondition>
    When <action>
    Then <expected outcome>

## Tasks

### 1. <Task description>
**Verify**: `<command that exits 0 on success>`
**Status**: pending

### 2. <Task description>
**Verify**: `<command>`
**Status**: pending

### N. Refactor tests for maintainability
**Verify**: `<full test suite command>`
**Status**: pending
**Notes**: Reorganize from implementation-coupled to feature-focused tests

## Notes

<Design decisions, constraints, and context for future sessions>
```

## Section Specifications

### Header Section

**Required fields:**
- `**Created**`: Date in YYYY-MM-DD format
- `**Branch**`: Git branch name, typically `feat/<slug>`
- `**Goal**`: Single sentence describing user-facing outcome

### Requirements Section

Write Gherkin scenarios that fully capture the feature requirements.

**Gherkin syntax:**
- `Feature:` - Groups related scenarios
- `Scenario:` - Specific behavior to test
- `Given` - Preconditions/setup
- `When` - Action being tested
- `Then` - Expected outcome
- `And` - Additional conditions

**Coverage requirements:**
- Happy path scenarios (successful operations)
- Error cases (invalid input, failures)
- Edge cases (boundaries, empty states)
- Security considerations (authorization, validation)

**Writing tips:**
- Use concrete values in examples ("user@example.com" not "an email")
- One behavior per scenario
- Focus on user-observable outcomes
- Avoid implementation details in scenarios

### Tasks Section

Each task maps 1:1 with a test file. Task format:

```markdown
### N. <Task description>
**Verify**: `<verification command>`
**Status**: pending|complete|blocked
```

**Verification command requirements:**
- Must exit 0 on success, non-zero on failure
- Typically runs a specific test file
- Must be deterministic and repeatable

**Common verification patterns:**
- TypeScript/JavaScript: `pnpm test src/path/to/test.test.ts`
- Python: `pytest src/path/to/test_file.py`
- Go: `go test ./path/to/package -run TestName`
- Rust: `cargo test test_name`

**Status values:**
- `pending` - Task not yet completed
- `complete` - Verification command passes
- `blocked` - Cannot proceed, includes root cause

**For blocked tasks, add root cause:**
```markdown
### 3. Add authentication middleware
**Verify**: `pnpm test src/middleware/auth.test.ts`
**Status**: blocked
**Root Cause**: Requires JWT library upgrade in shared-lib, out of scope for this feature.
```

**Final task requirement:**
Every plan must end with a test refactoring task:
```markdown
### N. Refactor tests for maintainability
**Verify**: `<full test suite command>`
**Status**: pending
**Notes**: Reorganize from implementation-coupled to feature-focused tests
```

### Notes Section

Preserve context for future sessions:
- Design decisions and rationale
- Constraints and dependencies
- Implementation approach chosen
- Rejected alternatives and why
- Links to relevant documentation

## Parsing Plan Files

To extract tasks from a plan file:

1. Find lines matching `### \d+\. `
2. Extract description (text after number and period)
3. Find next line matching `**Verify**: \`(.+)\``
4. Extract command from backticks
5. Find next line matching `**Status**: (.+)`
6. Extract status value

To update task status:

1. Locate the specific task by number
2. Find the `**Status**: ` line
3. Replace status value (pending → complete)
4. Preserve all other content

## Validation Rules

**Plan file validation:**
- [ ] Has title starting with `# Feature:`
- [ ] Has Created, Branch, Goal header fields
- [ ] Has Requirements section with Gherkin scenarios
- [ ] Has Tasks section with numbered tasks
- [ ] Each task has Verify and Status fields
- [ ] Verification commands are in backticks
- [ ] Status values are valid (pending|complete|blocked)
- [ ] Final task is test refactoring

**Gherkin validation:**
- [ ] At least one Feature block
- [ ] Each Scenario has Given/When/Then
- [ ] Scenarios are independent
- [ ] No implementation details in scenarios

## Example Plan File

See `references/example-plan.md` for a complete working example.