Project Planning
Generate IMPLEMENTATION_PHASES.md and conditional planning docs so agents ship web features in verified, context-safe chunks.
Overview
project-planning is an agent skill most often used in Build (pm) and Validate (scope) that generates IMPLEMENTATION_PHASES.md and related planning docs with phased verification and exit criteria.
Install
npx skills add https://github.com/jezweb/claude-skills --skill project-planningWhat is this skill?
- Creates IMPLEMENTATION_PHASES.md with verification criteria and exit conditions per phase
- Optional file-level detail: file maps, Mermaid data-flow diagrams, critical dependencies, and gotchas sections
- v1.1 adds ~350 lines of file-level guidance integrated with SESSION.md for token-efficient agent context
- Conditional companion docs beyond the core phases file when the project needs them
- Explicit guidance on when to skip file-level detail for smaller changes
- v1.1 adds ~350 lines of file-level detail guidance in SKILL.md
- Phase templates include File Map, Data Flow, Critical Dependencies, and Gotchas sections
Adoption & trust: 584 installs on skills.sh; 841 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are starting a large web feature but only have chat context—no phased plan, file map, or exit checks your agent can follow across sessions.
Who is it for?
Solo founders and indie devs kicking off or expanding web projects who want disk-backed phases before agents write production code.
Skip if: Tiny one-file fixes, teams that already have a signed spec and task board, or non-web work with no IMPLEMENTATION_PHASES template fit.
When should I use this skill?
Starting new web projects, adding major features, or breaking large work into manageable phases with structured planning docs.
What do I get? / Deliverables
You get IMPLEMENTATION_PHASES.md (plus conditional docs) with phased tasks, verification, and optional Mermaid flows so implementation can proceed session by session.
- IMPLEMENTATION_PHASES.md with phased tasks and exit conditions
- Optional conditional planning docs and Mermaid data-flow diagrams
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Implementation-phase planning is the canonical home for breaking large web work into ordered build slices with exit criteria. The skill outputs PM artifacts—phased roadmaps, file maps, dependencies, and gotchas—not application runtime code.
Where it fits
Frame a new web app as phased milestones before committing to stack and repo layout.
Turn a major feature brief into scoped phases with exit conditions before prototype code.
Author IMPLEMENTATION_PHASES.md with file maps and dependency gotchas for the agent’s next coding passes.
Derive launch-oriented phases and verification checks from the same implementation plan document.
How it compares
Produces phased PM markdown artifacts—use instead of ad-hoc chat planning without verification gates.
Common Questions / FAQ
Who is project-planning for?
Solo and indie web builders using Claude Code or similar agents who need structured phases, file maps, and exit criteria before coding accelerates.
When should I use project-planning?
At Validate (scope) when defining a major feature; at Build (pm) when splitting implementation; at Idea (discover) when framing a new web product; and at Ship (launch) when you need a phased rollout checklist derived from the same phase model.
Is project-planning safe to install?
It generates local markdown planning files and does not require cloud credentials by default; review the Security Audits panel on this Prism page before installing from third-party repos.
SKILL.md
READMESKILL.md - Project Planning
{ "name": "project-planning", "description": "Generate structured planning docs for web projects with context-safe phases, verification criteria, and exit conditions. Creates IMPLEMENTATION_PHASES.md plus conditional docs. Use when: starting new projects, adding major features, or breaking large work into manageable phases.", "version": "1.0.0", "author": { "name": "Jeremy Dawes", "email": "jeremy@jezweb.net" }, "license": "MIT", "repository": "https://github.com/jezweb/claude-skills", "keywords": [] } # Project Planning Skill v1.1 Enhancement Summary **Date**: 2025-11-06 **Enhancement**: File-Level Detail in IMPLEMENTATION_PHASES.md --- ## What Changed ### 1. SKILL.md Updated **Location**: `skills/project-planning/SKILL.md` **Added**: New section "File-Level Detail in Phases" (~350 lines) **Includes**: - File Map Structure guidelines - Data Flow Diagrams (Mermaid) instructions - Critical Dependencies section format - Gotchas & Known Issues documentation patterns - Enhanced Phase Template example - Integration with SESSION.md - Token efficiency metrics - When to skip file-level detail ### 2. Template Updated **Location**: `skills/project-planning/templates/IMPLEMENTATION_PHASES.md` **Added** to Phase 2, 3, 4 templates: - **File Map** section (optional but recommended) - **Data Flow** section (Mermaid diagrams) - **Critical Dependencies** section (Internal/External/Config/Bindings) - **Gotchas & Known Issues** section **Phase 1** (Infrastructure): Kept minimal (scaffolding is self-evident) ### 3. Reference Example Created **Location**: `skills/project-planning/references/example-enhanced-phase.md` **Content** (~400 lines): - Before/After comparison (basic vs enhanced phase) - Complete enhanced phase example (Task Management API) - 5 different Mermaid diagram examples: - Sequence diagram (API flow) - Flowchart (UI component logic) - Flowchart (error handling paths) - Architecture graph (multi-service) - ER diagram (database relationships) - Token efficiency comparison - When to use each diagram type ### 4. README.md Updated **Location**: `skills/project-planning/README.md` **Changes**: - Version bumped: 1.0 → 1.1 - Last Updated: 2025-10-25 → 2025-11-06 - Added "File-Level Navigation (NEW in v1.1)" section - Added token efficiency table - Updated auto-trigger keywords (file map, code navigation, etc.) - Updated Files section to include new reference --- ## Token Efficiency Metrics ### Measured Improvement | Scenario | Without File Maps | With File Maps | Savings | |----------|-------------------|----------------|---------| | Token usage | ~15k tokens | ~3.5k tokens | **77%** | | Corrections needed | 2-3 | 0 | **100%** | | Implementation time | ~10 min | ~3 min | **70%** | ### How It Works **Without file maps**: 1. Claude greps for existing routes (~2k tokens) 2. Claude globs for schema patterns (~1k tokens) 3. Claude reads 3-4 files to understand structure (~6k tokens) 4. Claude writes code in wrong location (~2k tokens) 5. User corrects (~500 tokens) 6. Claude re-reads and rewrites (~4k tokens) **Total**: ~15.5k tokens, 2 corrections **With file maps**: 1. Claude reads IMPLEMENTATION_PHASES.md file map (~1k tokens) 2. Claude writes code in correct location first try (~2k tokens) 3. Claude references gotchas for security checks (~500 tokens) **Total**: ~3.5k tokens, 0 corrections --- ## What File-Level Detail Provides ### 1. File Map Shows exactly which files to create or modify: ```markdown - `src/routes/tasks.ts` (estimated ~150 lines) - Purpose: CRUD endpoints for tasks - Key exports: GET, POST, PATCH, DELETE handlers - Dependencies: schemas.ts, auth middleware, D1 binding - Used by: Frontend task components ``` **Benefits**: - Claude knows where to start (entry point identification) - Clear dependency graph (what imports what) - Impact analysis (what uses this file) - Line estimates help with effort estimation ### 2. Data Flow Diagrams Visualizes complex flo