claude-plugins/plugins/project-plan/commands/generate.md

---
description: Analyze codebase and generate comprehensive PROJECT_PLAN.json task files
---

# Project Plan Generator

Creates structured `PROJECT_PLAN.json` files for tracking project work.

## Usage

```
/project-plan:generate [type]
```

**Types:**
- `refactoring` - Technical debt and code quality improvements (default)
- `feature` - New feature implementation tasks
- `migration` - System migration or upgrade tasks
- `audit` - Security, accessibility, or compliance audit
- `custom` - Ask user for specific focus areas

## Analysis Process

### 1. Codebase Scan

Search for indicators based on plan type:

**For refactoring/technical debt:**
```bash
# Find TODOs, FIXMEs, HACKs
grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.{ts,js,vue,py,go}" .

# Find console.log/print statements
grep -rn "console\.log\|print(" --include="*.{ts,js,vue,py}" .

# Find 'any' types in TypeScript
grep -rn ": any" --include="*.ts" .

# Find hardcoded values
grep -rn "localhost\|:3000\|:8000" --include="*.{ts,js,vue,py}" .

# Find skipped tests
grep -rn "\.skip\|@skip\|pytest\.mark\.skip" --include="*.{test,spec}.*" .
```

**For features:**
- Review PRD or requirements documents
- Check existing feature flags or incomplete implementations
- Identify placeholder UI or stub functions

**For audits:**
- Check for missing ARIA labels, keyboard handlers
- Look for SQL queries, user input handling
- Review authentication/authorization patterns

### 2. Categorize Findings

| Category | Criteria |
|----------|----------|
| `critical` | Broken functionality, security issues, data loss risk |
| `high` | Production blockers, major UX issues |
| `medium` | Code quality, maintainability, moderate UX |
| `low` | Polish, nice-to-have, minor improvements |
| `feature` | New capabilities, enhancements |

### 3. Generate JSON

Create `PROJECT_PLAN.json` in the project root or relevant subdirectory.

## JSON Schema

```json
{
  "meta": {
    "version": "1.0.0",
    "created": "YYYY-MM-DD",
    "lastUpdated": "YYYY-MM-DD",
    "planType": "refactoring|feature|migration|audit|custom",
    "totalEstimatedHours": 0,
    "totalTasks": 0,
    "completedTasks": 0
  },
  "categories": {
    "critical": "Must fix immediately",
    "high": "Required for production",
    "medium": "Quality improvements",
    "low": "Polish and nice-to-have",
    "feature": "New capabilities"
  },
  "tasks": [
    {
      "id": "CRIT-001",
      "name": "Short task name",
      "description": "Detailed explanation of what needs to be done and why",
      "category": "critical",
      "priority": 1,
      "completed": false,
      "tested": false,
      "dependencies": ["OTHER-001"],
      "files": [
        {
          "path": "src/example.ts",
          "lines": [45, 67, 89],
          "issue": "Description of issue in this file"
        }
      ],
      "suggestedFix": "Step-by-step approach to resolve",
      "estimatedHours": 2,
      "notes": "Additional context, gotchas, or tips"
    }
  ],
  "quickWins": [
    {
      "taskId": "LOW-001",
      "estimatedMinutes": 15,
      "impact": "Brief description of value"
    }
  ],
  "productionBlockers": [
    {
      "taskId": "CRIT-001",
      "reason": "Why this blocks production"
    }
  ],
  "weeklyRoadmap": {
    "week1": {
      "theme": "Critical Fixes",
      "tasks": ["CRIT-001", "CRIT-002"],
      "estimatedHours": 8
    }
  }
}
```

## Task ID Conventions

| Prefix | Category |
|--------|----------|
| `CRIT-` | Critical blockers |
| `HIGH-` | High priority |
| `MED-` | Medium priority |
| `LOW-` | Low priority |
| `FEAT-` | New features |
| `SEC-` | Security issues |
| `A11Y-` | Accessibility |
| `PERF-` | Performance |
| `TEST-` | Testing gaps |
| `DOCS-` | Documentation |

## Required Task Fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | string | Yes | Unique identifier |
| `name` | string | Yes | Short descriptive name |
| `description` | string | Yes | Detailed explanation |
| `completed` | boolean | Yes | Task completion status |
| `tested` | boolean | Yes | Whether fix was tested |
| `dependencies` | string[] | Yes | Task IDs this depends on (empty array if none) |
| `notes` | string | Yes | Additional context |

## Recommended Task Fields

| Field | Type | Description |
|-------|------|-------------|
| `category` | string | critical/high/medium/low/feature |
| `priority` | number | Numeric sort order (1 = highest) |
| `files` | array | Affected files with paths and line numbers |
| `suggestedFix` | string | How to resolve the issue |
| `estimatedHours` | number | Time estimate |

## Output Location

- Default: `PROJECT_PLAN.json` in project root
- For monorepos: `{subproject}/PROJECT_PLAN.json`
- For focused work: `{directory}/PROJECT_PLAN.json`