claude-configs/skills/project-plan/SKILL.md

name	description
project-plan	Generate comprehensive PROJECT_PLAN.json files for any project. Analyzes codebase to identify tasks, technical debt, features, or refactoring needs. USE WHEN user says "/project-plan", "create a project plan", "document technical debt", "create refactoring plan", or "feature implementation plan".

Project Plan Generator

Creates structured PROJECT_PLAN.json files for tracking project work.

Usage

/project-plan [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:

# 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

{
  "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

Example Invocations

/project-plan                    # Default refactoring analysis
/project-plan refactoring        # Technical debt focus
/project-plan feature            # Feature implementation plan
/project-plan audit              # Security/a11y audit
/project-plan --output=frontend  # Save to frontend/PROJECT_PLAN.json