Project Planning Skill

Generate four essential planning documents to guide AI-assisted development. These documents maintain context coherence across coding sessions and prevent architectural drift.

When to Use This Skill

• •User describes a project concept and asks for planning documents
• •Files in docs/planning/ show "Awaiting Generation" status
• •User invokes /plan command with project description
• •Starting development on a new feature requiring architectural decisions

Output Documents

Generation Process

Step 1: Gather Project Context

Before generating, collect:

1. •Project description from user input
2. •Technical constraints from pyproject.toml and existing code
3. •Cookiecutter choices reflected in project structure

Step 2: Generate Documents in Order

Generate documents sequentially, as later documents reference earlier ones:

1. •Project Vision & Scope - Establishes what we're building and why
2. •Architecture Decision Record - Key technical choices based on PVS
3. •Technical Implementation Spec - Detailed how-to based on ADRs
4. •Development Roadmap - Implementation plan based on all above

Step 3: Expert Review via Consensus

After generating each document, use the zen-mcp-server consensus tool to get expert review:

Use mcp__zen__consensus with gemini-3-pro-preview to review:

"Review this [document type] for sufficiency to begin development.

Evaluate:
1. SPECIFICITY: Are requirements concrete enough to implement?
2. COMPLETENESS: Are all critical sections filled with project-specific content?
3. FEASIBILITY: Are timelines and technical choices realistic?
4. CLARITY: Can a developer understand what to build from this?
5. GAPS: What critical information is missing?

Respond with:
- READY: Document is sufficient to begin work
- NEEDS REVISION: [List specific improvements required]

Document content:
[paste document content]"

Review each document in order:

1. •PVS → Must be READY before generating ADR
2. •ADR → Must be READY before generating Tech Spec
3. •Tech Spec → Must be READY before generating Roadmap
4. •Roadmap → Must be READY before completing

If any document NEEDS REVISION, incorporate feedback and re-review before proceeding.

Step 4: Validate and Cross-Reference

After all documents pass review:

• •Ensure documents reference each other correctly
• •Verify technical choices are consistent across documents
• •Flag any assumptions needing user validation
• •Run validation script if available

Document Generation Guidelines

All Documents

• •Be specific: Use concrete technologies, versions, and measurable criteria
• •No boilerplate: Every section must contain project-specific information
• •Under 1000 words: Dense information, minimal prose
• •Markdown format: Use headers, bullets, tables for structure
• •Include TL;DR: 2-3 sentence summary at top of each document

Project Vision & Scope (PVS)

Use template: templates/pvs-template.md

Focus on:

• •Problem being solved and user impact
• •Core capabilities (3-5 max for MVP)
• •Explicit scope boundaries (in vs out)
• •Measurable success metrics

Architecture Decision Record (ADR)

Use template: templates/adr-template.md

Create ADR for:

• •Database/storage choice
• •Authentication strategy
• •API design approach
• •Key framework decisions
• •Any choice expensive to reverse

Format: adr-001-{decision-slug}.md

Technical Implementation Spec

Use template: templates/tech-spec-template.md

Include:

• •Complete tech stack with versions
• •Component architecture diagram (ASCII)
• •Data model with schemas
• •API endpoints specification
• •Security requirements
• •Error handling approach

Development Roadmap

Use template: templates/roadmap-template.md

Structure as:

• •Phase 0: Foundation (environment, CI/CD)
• •Phase 1: MVP Core (essential features)
• •Phase 2: Enhancement (additional features)
• •Phase 3: Polish (testing, documentation)

Each phase needs:

• •Clear deliverables
• •Success criteria (testable)
• •Estimated duration
• •Dependencies

Pre-Filling from Project Context

When generating, incorporate known information:

# From pyproject.toml / cookiecutter context
python_version = "3.12"
project_name = "Fragrance Rater"
project_slug = "fragrance_rater"
cli_framework = "Click"
containerization = "Docker"

Quality Checklist

Before completing generation:

• • All four documents created in docs/planning/
• • Each document has TL;DR section
• • No "[TODO]" or "[TBD]" placeholders remain
• • Documents cross-reference each other
• • Technical choices are consistent
• • Success criteria are measurable
• • Scope boundaries are explicit
• • At least one ADR created

Templates Reference

Templates are in templates/ directory:

• •pvs-template.md - Project Vision & Scope structure
• •adr-template.md - Architecture Decision Record structure
• •tech-spec-template.md - Technical Spec structure
• •roadmap-template.md - Development Roadmap structure

Detailed Guidance

For comprehensive documentation on each document type, see reference/ directory:

• •reference/document-guide.md - Full guidance for all document types
• •reference/prompting-patterns.md - How to use documents during development

After Generation

Instruct user to:

1. •Review each document for accuracy
2. •Validate assumptions marked with [ ]
3. •Adjust timelines in roadmap if needed
4. •Commit documents to version control
5. •Reference documents in future development sessions

Example Usage

When user says: "I want to build a CLI tool for managing personal finances..."

Generation Flow with Consensus Review

1. •

   Generate PVS

   • •Read templates/pvs-template.md
   • •Generate docs/planning/project-vision.md with finance CLI specifics
   • •Review: mcp__zen__consensus with gemini-3-pro-preview → READY or revise
2. •

   Generate ADR

   • •Read templates/adr-template.md
   • •Generate docs/planning/adr/adr-001-database-choice.md for SQLite decision
   • •Review: mcp__zen__consensus with gemini-3-pro-preview → READY or revise
3. •

   Generate Tech Spec

   • •Read templates/tech-spec-template.md
   • •Generate docs/planning/tech-spec.md with Python/Click/SQLite stack
   • •Review: mcp__zen__consensus with gemini-3-pro-preview → READY or revise
4. •

   Generate Roadmap

   • •Read templates/roadmap-template.md
   • •Generate docs/planning/roadmap.md with phased implementation
   • •Review: mcp__zen__consensus with gemini-3-pro-preview → READY or revise
5. •

   Final Validation

   • •Run scripts/validate-planning-docs.py
   • •Summarize what was created and review outcomes
   • •List next steps for beginning development

Consensus Review Prompt Template

mcp__zen__consensus with gemini-3-pro-preview:

Review this Project Vision & Scope document for Fragrance Rater.

EVALUATION CRITERIA:
1. SPECIFICITY - Can a developer implement from these requirements?
2. COMPLETENESS - All sections filled with project-specific content?
3. FEASIBILITY - Realistic scope for the described constraints?
4. CLARITY - Unambiguous success criteria and scope boundaries?
5. GAPS - Any critical missing information?

RESPOND:
- READY: Sufficient to proceed to next document
- NEEDS REVISION: [Specific improvements with examples]

DOCUMENT:
[Full document content here]

MCP Server Requirement

This skill requires the zen-mcp-server for consensus review. If not available, skip Step 3 and proceed with manual review.

Configuration: Ensure mcp__zen__consensus tool is accessible.