Plan Documentation

vibeeval/plan-documentation

Structured plan file generation for large tasks -- phased planning, completion tracking, and decision documentation

1k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

521

stars on the repo

on the repository, not the skill itself

Install

one command, takes just this skill from the repository

npx skills add https://github.com/vibeeval/vibecosystem --skill plan-documentation

The instruction itself

7 sections, as written by the author

Plan Documentation

Generate structured plan files when starting large features, refactoring efforts, or multi-phase work. Plans create a paper trail that survives context resets and helps collaborators understand what was planned, what changed, and why.

When to Generate Plan Files

Create a plan document when:

The task spans more than 2 files or requires multiple coordinated changes
Work will take more than one session or phase
Multiple approaches exist and the chosen path should be documented
Other people (or future you) need to understand the sequence of work

Do NOT create plan files for:

Single-file fixes or tweaks
Routine maintenance (dependency updates, formatting)
Tasks that can be completed in under 15 minutes

Plan Document Template

Create the plan at plans/<task-slug>-plan.md in the project root.

# Plan: <Task Title>

Created: <ISO date>
Status: IN_PROGRESS | COMPLETE | ABANDONED

## Summary

<2-3 sentences explaining what this work accomplishes and why it matters.>

## Phases

### Phase 1: <Phase Title>
- [ ] Step 1 description
- [ ] Step 2 description
- [ ] Step 3 description

**Acceptance Criteria:**
- <What must be true when this phase is done>
- <Measurable or verifiable condition>

### Phase 2: <Phase Title>
- [ ] Step 1 description
- [ ] Step 2 description

**Acceptance Criteria:**
- <Condition>

### Phase N: <Phase Title>
...

## Open Questions

1. <Question about approach or requirement> -- Suggested: <Option A> vs <Option B>
2. <Question about scope> -- Suggested: <Option A> vs <Option B>
3. <Question about dependency or risk> -- Suggested: <Option A>

Keep open questions between 1-5. Each should have suggested options so they can be resolved quickly. Remove questions as they get answered -- move the decision to the relevant phase.

## Dependencies

- <External system, API, library, or team dependency>
- <Prerequisite work that must finish first>

## Risks

- <What could go wrong and how likely it is>
- <Mitigation strategy if applicable>

Phase Completion Template

After finishing each phase, create plans/<task-slug>-phase-N-complete.md:

# Phase N Complete: <Phase Title>

Completed: <ISO date>
Plan: <task-slug>-plan.md

## Phase N Summary

<1-2 sentences on what was accomplished.>

## What Changed

| File | Change |
|------|--------|
| `path/to/file.ts` | Added validation logic for user input |
| `path/to/test.ts` | 6 new unit tests for validation edge cases |

## What Was Tested

- <Test suite or manual verification performed>
- <Edge cases covered>
- <What was NOT tested and why>

## Decisions Made

- <Decision>: <Why this option was chosen over alternatives>

## Next Phase Preview

Phase N+1 will focus on <brief description>. Prerequisites met: <yes/no>.

Final Completion Template

When all phases are done, create plans/<task-slug>-complete.md:

# Complete: <Task Title>

Completed: <ISO date>
Plan: <task-slug>-plan.md
Duration: <how long the work took>

## Task Summary

<2-3 sentences on the full scope of work completed.>

## All Phases

| Phase | Title | Status |
|-------|-------|--------|
| 1 | <Title> | COMPLETE |
| 2 | <Title> | COMPLETE |
| N | <Title> | COMPLETE |

## Total Changes

- Files modified: <count>
- Files created: <count>
- Tests added: <count>
- Lines changed: <approximate>

## Lessons Learned

- <Insight that would help someone doing similar work>
- <Unexpected challenge and how it was resolved>
- <Pattern discovered that should be reused>

File Naming Convention

All plan files go in the plans/ directory at the project root.

| File | Purpose |

|------|---------|

| <task-slug>-plan.md | Initial plan with phases and acceptance criteria |

| <task-slug>-phase-N-complete.md | Completion record for phase N |

| <task-slug>-complete.md | Final completion summary |

The <task-slug> should be a short, lowercase, hyphenated description of the task (e.g., auth-refactor, search-api-v2, dashboard-redesign).

Rules

Write the plan BEFORE starting implementation
Update phase status in the plan file as work progresses
Do not skip phase completion docs -- they are the audit trail
Keep summaries concise -- if it takes more than 3 sentences, it is too long
Open questions should block work until resolved, not be ignored
If the plan changes significantly mid-work, update the plan file and note what changed and why

How to use it

Copy the folder

Take vibeeval/plan-documentation from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.