Plan Documentation Agent Skill
Structured plan file generation for large tasks -- phased planning, completion tracking, and decision documentation
Install
one command, takes just this skill from the repositorynpx skills add https://github.com/vibeeval/vibecosystem --skill plan-documentationThe instruction itself
7 sections, as written by the authorPlan 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
Other skills for the same job
different authors, same section of the catalogue
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.
Intelligently organizes your files and folders across your computer by understanding context, finding duplicates, suggesting better structures, and automating cleanup tasks. Reduces cognitive load and keeps your digital workspace tidy without manual effort.
Generates creative domain name ideas for your project and checks availability across multiple TLDs (.com, .io, .dev, .ai, etc.). Saves hours of brainstorming and manual checking.
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
Creative research ideation and exploration. Use for open-ended brainstorming sessions, exploring interdisciplinary connections, challenging assumptions, or identifying research gaps. Best for early-stage research planning when you do not have specific observations yet. For formulating testable hypotheses from data use hypothesis-generation.
Comprehensive GitHub project management with swarm-coordinated issue tracking, project board automation, and sprint planning
Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
How to use it
Take vibeeval/plan-documentation from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
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.