plan-reference

Planning System Reference

Core reference for the /plan command and its tracker adapters. This file defines the contract between plan generation and sync adapters.

Plan File Format

Plan files are markdown with YAML frontmatter. They live in {PROJECT_ROOT}/.claude/plans/ and are the contract between /plan and tracker adapters (gh-plan, local-plan, etc.).

Simple Task

A task that can be implemented in a single focused session without architectural decisions. Sections: Problem, Desired Outcome, Constraints, Scope (P0/P1/Out of Scope), Acceptance Criteria.

Template: see assets/simple-plan-template.md in this skill's directory.

Complex Task

A feature requiring multiple implementation steps, architectural decisions, or coordination across layers. Produces two artifacts:

1. Epic file (<feature-slug>.md) — high-level: problem, outcome, architecture decisions, task summary table, build order.
2. Task directory (<feature-slug>/) — one detailed file per task with objective, approach, files to create/modify, and acceptance criteria.

.claude/plans/
├── 2fa-authentication.md              ← epic
└── 2fa-authentication/
    ├── 01-okta-sdk-setup.md           ← detailed task
    ├── 02-keychain-service.md
    ├── 03-okta-auth-service.md
    └── ...

Adapters treat the epic file as the parent issue and each task file as a sub-issue — one nesting level.

Templates:

• Epic: see assets/complex-plan-template.md in this skill's directory.
• Task: see assets/complex-task-template.md in this skill's directory.

Complexity Assessment

Evaluate the feature request against these heuristics. If any complex indicator is true, classify as complex.

Simple indicators

• Single area of the codebase affected
• No architectural decisions needed — the pattern already exists
• No new dependencies or integrations
• Can be described with one user story
• Implementation path is obvious to someone familiar with the codebase

Complex indicators

• Multiple layers or modules affected (e.g., API + database + UI)
• Requires a new pattern, abstraction, or integration
• Multiple user stories or personas involved
• Has ordering constraints — some work must finish before other work can start
• Requires data migration, schema changes, or breaking API changes
• Needs coordination with external systems or teams

When in doubt, lean toward complex. A complex plan that turns out simple is harmless; a simple plan that misses tasks causes rework.

Planning Frameworks

Brief format (simple tasks)

1. State the problem — not the solution. "Users can't X" not "Add a Y button."
2. Define the outcome — observable behavior, not implementation details.
3. List constraints — what limits the solution space.
4. Scope ruthlessly — P0 is the minimum that solves the core problem. Everything else is P1 or out of scope.
5. Write testable acceptance criteria — each one answers "how do I verify this works?"

Decomposition format (complex tasks)

1. State the problem and outcome — same as brief.
2. Identify decision points — where does the implementation fork? Document each decision with rationale.
3. Break into tasks — each task is independently implementable and testable. A task should be completable in one /task session.
4. Write detailed task files — for each task, create a file in the task subdirectory with objective, approach (files to create/modify, patterns to follow, key APIs), and acceptance criteria. The task file should give /task enough context to skip investigation and go straight to planning.
5. Assign priorities — P0 tasks form the minimum viable implementation. P1 tasks improve it.
6. Map dependencies — which tasks block others? Draw the build order.
7. Verify coverage — walk the acceptance criteria. Every criterion should map to at least one task.