project-planner

What this skill does

# Project Planner

> **Cross-Platform AI Agent Skill**
> This skill works with any AI agent platform that supports the skills.sh standard.

# Project Planner

Break down large, complex projects into manageable tasks with clear dependencies, progress tracking, and visual diagrams.

## Project to Plan

command arguments

## Planning Workflow

### Phase 0: Project Analysis

**Step 0.1: Understand Project Scope**

Use lightweight exploration for token-efficient codebase analysis:

**Step 0.2: Clarify Requirements**

If the project description is vague or has multiple valid approaches, use `interactive clarification` to clarify:
- What are the must-have vs nice-to-have features?
- Are there specific architectural constraints?
- What's the target completion timeline?
- Should this integrate with existing systems?
- Are there specific technology preferences?

### Phase 1: Task Breakdown

**Step 1.1: Identify Major Milestones**

Break the project into 3-7 major milestones. Each milestone represents a significant deliverable or phase:

**Example for a new authentication system**:
1. Discovery & Planning
2. Database schema and migrations
3. Core authentication logic
4. API endpoints
5. Frontend integration
6. Testing & verification
7. Documentation & deployment

**Step 1.2: Create Tasks for Each Milestone**

For each milestone, create tasks that are:
- **Specific**: Clear deliverable and acceptance criteria
- **Measurable**: Can be marked completed objectively
- **Achievable**: Can be completed in a reasonable timeframe
- **Relevant**: Contributes to the milestone goal
- **Time-bound**: Not open-ended

**Task Granularity Guidelines**:
- **Too large**: "Build the authentication system" (breaks into 10+ subtasks)
- **Too small**: "Import bcrypt library" (trivial step within a larger task)
- **Just right**: "Implement password hashing with bcrypt and validation"

### Phase 2: Dependency Mapping

**Step 2.1: Identify Task Dependencies**

For each task, determine:
- **Prerequisites**: Which tasks must complete before this can start?
- **Blockers**: Which tasks does this one block?
- **Parallelizable**: Which tasks can run concurrently?

**Dependency Types**:
- **Sequential**: Task B requires output from Task A
- **Parallel**: Tasks A and B can run simultaneously
- **Convergence**: Tasks A and B must both complete before Task C

**Step 2.2: Set Up Task Dependencies**

```
# Example: Authentication system task chain
TaskCreate: subject="Set up auth database tables", description="..."
TaskCreate: subject="Implement password hashing", description="..."
TaskCreate: subject="Create JWT token service", description="..."
TaskCreate: subject="Build login API endpoint", description="..."
TaskCreate: subject="Build registration API endpoint", description="..."
TaskCreate: subject="Add auth middleware", description="..."
TaskCreate: subject="Frontend login form", description="..."
TaskCreate: subject="Frontend registration form", description="..."
TaskCreate: subject="Integration tests", description="..."

# Sequential dependencies
TaskUpdate: { taskId: "2", addBlockedBy: ["1"] } # Hash needs DB schema
TaskUpdate: { taskId: "3", addBlockedBy: ["1"] } # JWT needs DB schema
TaskUpdate: { taskId: "4", addBlockedBy: ["2", "3"] } # Login needs hash + JWT
TaskUpdate: { taskId: "5", addBlockedBy: ["2", "3"] } # Registration needs hash + JWT
TaskUpdate: { taskId: "6", addBlockedBy: ["4", "5"] } # Middleware after endpoints
TaskUpdate: { taskId: "7", addBlockedBy: ["4", "6"] } # Frontend needs API + middleware
TaskUpdate: { taskId: "8", addBlockedBy: ["5", "6"] } # Frontend needs API + middleware
TaskUpdate: { taskId: "9", addBlockedBy: ["7", "8"] } # Tests after all frontend
### Phase 3: Visualization

**Step 3.1: Generate Dependency Diagram**

Create a Mermaid diagram showing the task dependency graph:

```mermaid
graph TD
 A[Set up auth database tables] --> B[Implement password hashing]
 A --> C[Create JWT token service]
 B --> D[Build login API endpoint]
 C --> D
 B --> E[Build registration API endpoint]
 C --> E
 D --> F[Add auth middleware]
 E --> F
 D --> G[Frontend login form]
 F --> G
 E --> H[Frontend registration form]
 F --> H
 G --> I[Integration tests]
 H --> I
**Diagram Guidelines**:
- Use clear, concise node labels
- Show critical path in a different color if possible
- Group related tasks visually
- Include milestone markers
- Add estimates if available

**Step 3.2: Document Critical Path**

Identify and highlight the critical path (longest sequential chain):
```
Critical Path: Database → Password Hashing → Login API → Middleware → Frontend Login → Tests
Estimated Duration: [X days/weeks]
### Phase 4: Task Templates

**Step 4.1: Create Task Templates**

For common project types, provide reusable templates:

**Web Feature Template**:
```
1. Discovery & Requirements
2. Database schema (if needed)
3. Backend API implementation
4. Frontend component implementation
5. Integration & E2E tests
6. Documentation
7. Deployment
**Bug Fix Template**:
```
1. Reproduce bug
2. Root cause analysis
3. Plan fix
4. Implement fix
5. Verify with tests
6. Commit and document
**Refactoring Template**:
```
1. Identify refactoring scope
2. Write characterization tests
3. Plan refactoring approach
4. Incremental refactoring (with commits)
5. Verify no behavior changes
6. Update documentation
### Phase 5: Progress Tracking

**Step 5.1: Initial Task List**

After creating all tasks and dependencies, show the full plan:
```
TaskList
**Step 5.2: Track Implementation Progress**

As work progresses, update task status:
```
TaskUpdate: { taskId: "1", status: "in_progress" }
# ... work ...
TaskUpdate: { taskId: "1", status: "completed" }
TaskList # Show updated progress
**Step 5.3: Handle Blockers**

If a task becomes blocked by external factors:
```
TaskUpdate:
 taskId: "4"
 metadata: { blocked_reason: "Waiting for design mockups from UI team" }
Use `interactive clarification` to notify stakeholders and get resolution timeline.

## Common Project Patterns

### Pattern 1: API + Frontend Feature

**Parallel Work Opportunity**: Backend and frontend can be built simultaneously with agreed API contract.

```
Discovery → API Contract Definition → (API Implementation || Frontend Implementation) → Integration → Testing
**Tasks**:
1. Discover project structure
2. Define API contract (OpenAPI/Swagger)
3. Implement API endpoints (parallel)
4. Implement frontend component (parallel)
5. Integration testing (after both)
6. E2E testing
7. Documentation and deployment

### Pattern 2: Database Migration

**Strict Sequential**: Schema changes before code changes.

```
Discovery → Schema Design → Migration Script → Update Models → Update Queries → Tests → Deploy
**Tasks**:
1. Discover existing schema
2. Design new schema/changes
3. Write migration script
4. Update ORM models
5. Update application queries
6. Update tests
7. Test migration on staging
8. Deploy to production

### Pattern 3: Library Integration

**Research First**: Understand library before implementation.

```
Discovery → Research Library → Proof of Concept → Integration → Tests → Documentation
**Tasks**:
1. Discover project patterns
2. Research library documentation (Context7)
3. Create proof of concept
4. Integrate into existing code
5. Write unit tests
6. Write integration tests
7. Document usage patterns

## Advanced Features

### Multi-Phase Projects

For very large projects, create meta-tasks (epics) with sub-task hierarchies:

```
Epic: "User Authentication System"
 Milestone 1: "Core Auth"
 - Task 1.1: Database schema
 - Task 1.2: Password hashing
 - Task 1.3: JWT service
 Milestone 2: "API Endpoints"
 - Task 2.1: Login endpoint
 - Task 2.2: Registration endpoint
 - Task 2.3: Password reset endpoint
 Milestone 3: "Frontend Integration"
 - Task 3.1: Login form
 - Task 3.2: Registration form
 - Task 3.3: Password reset form
Use metadata to track parent-child relationships:
```
TaskCreate:
 subject: "Milestone 1: Core Auth"
 description: "..."
 met