project-planner

Project Planner Skill

This skill provides templates and guidance for generating comprehensive project planning documents that serve as blueprints for AI-assisted implementation.

Quick Start

When a user wants to start a new project, generate three core documents:

1. Requirements Document - User stories with acceptance criteria
2. Design Document - Technical architecture and component specifications
3. Implementation Plan - Hierarchical task breakdown with requirement tracing

Why Explicit Architectural Planning Works

Setting clear roles, responsibilities, and deliverables upfront dramatically improves project outcomes:

Benefits of Upfront Definition

1. Component Clarity - Defining all system components first prevents scope creep and ensures complete coverage
2. Data Flow Visibility - Mapping data movement early reveals integration complexities and performance bottlenecks
3. Integration Planning - Identifying all touchpoints upfront prevents surprise dependencies during implementation
4. Clear Boundaries - Explicitly stating what's in/out of scope focuses effort and prevents feature drift
5. Measurable Success - Specific goals and constraints enable objective progress tracking

The Architect Mindset

When acting as a Project Architect, approach planning with:

• Systems Thinking - See the whole before diving into parts
• Interface-First Design - Define contracts between components before internals
• Traceability Focus - Every requirement maps to design elements and tasks
• Constraint Awareness - Acknowledge limitations upfront to guide decisions
• Deliverable Orientation - Know exactly what artifacts you're producing

Document Generation Workflow

1. Project Architect Role Definition

When starting a project, explicitly establish Claude as the Project Architect with clear responsibilities:

Role: System Architect and Planning Specialist Responsibilities:

• Define complete system architecture with all components
• Map data flow between system elements
• Identify all integration points and interfaces
• Establish clear project boundaries and constraints
• Create traceable requirements to implementation tasks

2. Initial Project Understanding

Before generating documents, gather key information and architectural elements:

Required Project Information:
- Project name and purpose
- Target users (single-user local, multi-tenant SaaS, etc.)
- Core functionality (3-5 main features)
- Technical preferences (languages, frameworks, deployment)
- Non-functional requirements (performance, security, scalability)

Required Architectural Elements (define upfront):
- System Components: All major modules/services and their purposes
- Data Flow: How data moves through the entire system
- Integration Points: All external APIs, services, databases
- System Boundaries: What's in scope vs out of scope
- Constraints: Technical, business, and resource limitations
- Success Metrics: Clear, measurable goals for the system

3. Deliverable Definition (Set Upfront)

Define all deliverables explicitly before starting documentation:

Standard Deliverables Package:
1. Requirements Document
   - User stories with measurable acceptance criteria
   - Complete glossary of terms
   - Traceable requirement IDs
   
2. System Design Document  
   - Component architecture diagram
   - Data flow diagrams for all major processes
   - Integration point specifications
   - API/Interface contracts
   - Performance and scaling targets
   
3. Implementation Plan
   - Hierarchical task breakdown
   - Requirement-to-task mapping
   - Dependency graph
   - Phase-based delivery schedule

Optional Deliverables (specify if needed):
- API Documentation
- Database Schema Design
- Security Threat Model
- Deployment Guide
- Testing Strategy Document

4. Generate Requirements Document

Use the requirements template to create user-focused specifications:

# Execute this to generate requirements structure
requirements = {
    "introduction": "System purpose and scope",
    "glossary": "Domain-specific terms",
    "requirements": [
        {
            "id": "REQ-X",
            "user_story": "As a [role], I want [feature], so that [benefit]",
            "acceptance_criteria": [
                "WHEN [condition], THE system SHALL [behavior]",
                "WHERE [context], THE system SHALL [behavior]",
                "IF [condition], THEN THE system SHALL [behavior]"
            ]
        }
    ]
}

5. Generate Design Document

Create technical specifications with explicit architectural elements:

# Execute this to generate comprehensive design structure
design = {
    "overview": "High-level system description",
    "architecture": {
        "diagram": "ASCII or visual representation of all components",
        "components": [
            {
                "id": "COMP-1",
                "name": "Component Name",
                "type": "Frontend/Backend/Service/Database",
                "responsibility": "Single clear purpose",
                "boundaries": "What it does and doesn't do"
            }
        ]
    },
    "data_flow": {
        "primary_flows": [
            {
                "name": "User Registration Flow",
                "steps": [
                    "1. User submits form → Frontend",
                    "2. Frontend validates → API Gateway",
                    "3. API Gateway → Auth Service",
                    "4. Auth Service → User Database",
                    "5. Response flows back"
                ],
                "data_transformations": "How data changes at each step"
            }
        ]
    },
    "integration_points": [
        {
            "name": "External Payment API",
            "type": "REST/GraphQL/WebSocket/Database",
            "purpose": "Process payments",
            "interface": "API contract definition",
            "authentication": "Method used",
            "error_handling": "Retry/fallback strategy"
        }
    ],
    "components_detail": [
        {
            "name": "Component Name",
            "responsibility": "What it does",
            "key_classes": ["Class descriptions"],
            "interfaces": "API/method signatures",
            "dependencies": "What it needs to function",
            "performance": "Targets and constraints"
        }
    ],
    "data_models": "Entity definitions with relationships",
    "system_boundaries": {
        "in_scope": ["What the system handles"],
        "out_of_scope": ["What it delegates or ignores"],
        "assumptions": ["External dependencies assumed available"]
    },
    "error_handling": "Strategies for failures",
    "testing_strategy": "Unit, integration, performance",
    "deployment": "Docker, environment, configuration"
}

6. Generate Implementation Plan

Break down the project into executable tasks with clear scope boundaries:

# Execute this to generate task structure with boundaries
tasks = {
    "project_boundaries": {
        "must_have": ["Core features for MVP"],
        "nice_to_have": ["Enhancement features"],
        "out_of_scope": ["Features explicitly excluded"],
        "technical_constraints": ["Framework/library limitations"]
    },
    "phases": [
        {
            "id": 1,
            "name": "Infrastructure Setup",
            "deliverables": ["What this phase produces"],
            "tasks": [
                {
                    "id": "1.1",
                    "description": "Task description",
                    "subtasks": ["Specific actions"],
                    "requirements_fulfilled": ["REQ-1.1", "REQ-2.3"],
                    "components_involved": ["COMP-1", "COMP-3"],
                    "dependencies": [],
                    "estimated_hours": 4,
                    "success_criteria": "How to verify completion"
                }
            ]
        }
    ]
}

Requirements Document Template

# Requirements Document

## Introduction

[System description in 2-3 sentences. Target user and deployment model.]

## Glossary

- **Term**: Definition specific to this system
- **Component**: Major system module or service
[Add all domain-specific terms]

## Requirements

### Requirement [NUMBER]

**User Story:** As a [user type], I want [capability], so that [benefit]

#### Acceptance Criteria

1. WHEN [trigger/condition], THE [component] SHALL [action/behavior]
2. WHERE [mode/context], THE [component] SHALL [action/behavior]  
3. IF [condition], THEN THE [component] SHALL [action/behavior]
4. THE [component] SHALL [capability with measurable target]

[Repeat for each requirement]

Requirements Best Practices

1. One capability per requirement - Each requirement should address a single feature
2. Testable criteria - Every criterion must be verifiable
3. Use SHALL for mandatory - Consistent RFC 2119 keywords
4. Include performance targets - "within X milliseconds/seconds"
5. Specify all states - Success, failure, edge cases
6. Number systematically - REQ-1, REQ-2 for traceability

Acceptance Criteria Patterns

Behavior criteria:
- WHEN [event occurs], THE system SHALL [respond]
- THE system SHALL [provide capability]
- THE system SHALL [enforce rule/limit]

Conditional criteria:
- IF [condition], THEN THE system SHALL [action]
- WHERE [mode is active], THE system SHALL [behavior]

Performance criteria:
- THE system SHALL [complete action] within [time]
- THE system SHALL support [number] concurrent [operations]
- THE system SHALL maintain [metric] above/below [threshold]

Data criteria:
- THE system SHALL persist [data type] with [attributes]
- THE system SHALL validate [input] against [rules]
- THE system SHALL return [data] in [format]

Design Document Template

# Design Document

## Overview

[System architecture summary in 3-4 sentences. Key design decisions and p

---

*Content truncated.*