agentleFS
mevans2120mevans2120/project-suite-claude-skills/.claude/skills/project-planner/SKILL.md

project-planner

Skill4 starsChanged 13 months agoMITView on GitHub

Discovers features from codebases, manages feature registries, and exports roadmaps. Analyzes React routes, Express endpoints, component structures, and generates CSV/Markdown roadmaps. Use this for feature discovery from code, roadmap generation, and feature registry management.

21 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use api-designer, security-auditor and 1 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • AutumnsGroveSkill

    api-designer

    Design and document RESTful and GraphQL APIs with OpenAPI/Swagger specifications, authentication patterns, versioning strategies, and best practices. Use for: (1) Creating API specifications, (2) Designing REST endpoints, (3) GraphQL schema design, (4) API authentication and authorization, (5) API versioning strategies, (6) Documentation generation

    Also in 3 projects that use this

  • nahisahoSkill

    security-auditor

    security-auditor skill

    Also in 3 projects that use this

  • Microsoft AzureSkill

    git-workflow

    Squad branching model: dev-first workflow with insiders preview channel

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 6 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 20 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Bulk Operations: Import/export features, merge registries

    line 31
  2. Distinctive:

    Validation: Ensure feature data consistency

    line 32
  3. Distinctive:

    Ask the user what they need:

    line 45
  4. Distinctive:

    Parse errors: Check code syntax, ensure valid JS/TS

    line 341
  5. Distinctive:

    File not found: Verify paths exist

    line 342
  6. Distinctive:

    CSV errors: Check CSV format, validate headers

    line 344
  7. Very specific:

    Dependencies missing: Run npm install in project-planner directory

    line 345

“Common” is measured: kept by at least 6 in 10 of the 20 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Project Planner Skill

Discovers features from codebases, manages feature registries, and exports comprehensive roadmaps.

When to Use This Skill

Invoke this skill when the user:

  • Code Feature Discovery: Wants to discover what features exist in a codebase
  • Roadmap Generation: Needs to create a feature roadmap from code analysis
  • Feature Registry: Wants to track and manage features in CSV format
  • React Analysis: Needs to analyze React Router routes and component structure
  • Express Analysis: Wants to discover Express.js API endpoints and routes
  • Export Roadmaps: Needs to export feature lists as CSV or Markdown

Core Capabilities

1. Code Discovery

  • React Discovery: Analyze React Router routes, components, hooks
  • Express Discovery: Extract API endpoints, middleware, route handlers
  • Component Analysis: Discover UI components and their props
  • Config Analysis: Parse configuration files for feature flags

2. Feature Registry Management

  • CSV Registry: Maintain features in CSV format with phases, priorities
  • Feature Tracking: Track implementation status, categories, dependencies
  • Bulk Operations: Import/export features, merge registries
  • Validation: Ensure feature data consistency
  • T-Shirt Sizing: Estimate implementation effort using token-based sizing

3. Roadmap Export

  • Markdown Roadmaps: Generate formatted markdown roadmaps
  • CSV Export: Export to CSV for spreadsheet tools
  • Phase Organization: Group features by development phases
  • Priority Sorting: Sort by priority, status, or custom criteria

Instructions

Step 1: Determine Task Type

Ask the user what they need:

  • Discover features from codebase
  • Export roadmap from existing feature registry
  • Manage feature registry (add, update, export features)

Step 2: Code Discovery

Discover Features from React Codebase

import { CodeDiscovery } from '{{INSTALL_DIR}}/project-planner';

const discovery = new CodeDiscovery();
const features = await discovery.discoverFromReact('/path/to/react/app', {
  includeRoutes: true,
  includeComponents: true,
  includeHooks: true
});

// Save to CSV
const registry = new CSVFeatureRegistry();
await registry.saveFeatures(features, 'features.csv');

Discover Features from Express Codebase

import { CodeDiscovery } from '{{INSTALL_DIR}}/project-planner';

const discovery = new CodeDiscovery();
const features = await discovery.discoverFromExpress('/path/to/express/app', {
  includeRoutes: true,
  includeMiddleware: true,
  includeControllers: true
});

Analyze Any JavaScript/TypeScript Project

import { CodeDiscovery } from '{{INSTALL_DIR}}/project-planner';

const discovery = new CodeDiscovery();
const features = await discovery.analyze('/path/to/project', {
  detectFramework: true,
  includeConfigs: true
});

Step 3: T-Shirt Sizing Estimates

The Project Suite uses token-based effort estimation instead of traditional time/team size estimates. This approach aligns with Claude's capabilities and provides more accurate scoping.

Size Categories

SizeToken EstimateExample Task
XS50k tokensBug fix, config change, simple implementation
S100k tokensFeature implementation, small test suite
M200k tokensLarge test suite, complex feature
L400k tokensFull module implementation
XL>400k tokensMust be broken down into smaller features

Sizing Guidelines

When sizing features, consider:

  • Code complexity and lines to write
  • Test coverage requirements
  • Integration points and dependencies
  • Documentation needs
  • Configuration and setup

Best Practices:

  • Features sized XL should be decomposed into multiple smaller features
  • Most features should fall in the S-M range (100k-200k tokens)
  • XS features are good for quick wins and bug fixes
  • L features may need multiple implementation sessions

Adding Size to Registry

registry.addFeature({
  id: 'PM-123',
  name: 'User Authentication',
  category: 'Security',
  phase: 'Phase 1',
  priority: 'high',
  status: 'backlog',
  size: 'M',  // T-shirt size
  tokenEstimate: 200000,  // 200k tokens
  description: 'Implement JWT-based authentication'
});

Step 4: Feature Registry Management

Load Features from CSV

import { CSVFeatureRegistry } from '{{INSTALL_DIR}}/project-planner';

const registry = new CSVFeatureRegistry();
const features = await registry.loadFeatures('features.csv');

Add/Update Features

registry.addFeature({
  id: 'F-123',
  name: 'User Authentication',
  category: 'Security',
  phase: 'Phase 1',
  priority: 'high',
  status: 'in-progress',
  description: 'Implement JWT-based authentication'
});

await registry.saveFeatures(features, 'features.csv');

Filter and Query Features

// Get features by phase
const phase1Features = registry.getFeaturesByPhase('Phase 1');

// Get features by status
const inProgressFeatures = registry.getFeaturesByStatus('in-progress');

// Get high priority features
const criticalFeatures = registry.getFeaturesByPriority('high');

Step 4: Export Roadmaps

Export to Markdown

import { RoadmapExporter } from '{{INSTALL_DIR}}/project-planner';

const exporter = new RoadmapExporter();
const markdown = await exporter.exportToMarkdown(features, {
  groupBy: 'phase',
  includeStats: true,
  includeTimeline: true
});

await exporter.writeToFile(markdown, 'ROADMAP.md');

Export to CSV

const csv = await exporter.exportToCSV(features, {
  includeMetadata: true,
  sortBy: 'priority'
});

await exporter.writeToFile(csv, 'roadmap.csv');

Step 5: Complete Workflow Example

Here's a complete workflow for discovering features and creating a roadmap:

import {
  CodeDiscovery,
  CSVFeatureRegistry,
  RoadmapExporter
} from '{{INSTALL_DIR}}/project-planner';

async function analyzeAndExportRoadmap(projectPath: string) {
  // 1. Discover features from code
  const discovery = new CodeDiscovery();
  const discoveredFeatures = await discovery.analyze(projectPath, {
    detectFramework: true,
    includeComponents: true,
    includeRoutes: true,
    includeAPIs: true
  });

  // 2. Save to CSV registry
  const registry = new CSVFeatureRegistry();
  await registry.saveFeatures(discoveredFeatures, 'features.csv');

  // 3. Export roadmap
  const exporter = new RoadmapExporter();
  const roadmap = await exporter.exportToMarkdown(discoveredFeatures, {
    groupBy: 'phase',
    sortBy: 'priority',
    includeStats: true
  });

  await exporter.writeToFile(roadmap, 'ROADMAP.md');

  return {
    totalFeatures: discoveredFeatures.length,
    roadmapPath: 'ROADMAP.md',
    registryPath: 'features.csv'
  };
}

Common Workflows

Workflow 1: Initial Code Analysis

1. Run CodeDiscovery on codebase
2. Save features to CSV registry
3. Export initial roadmap in Markdown
4. Review and categorize features
5. Update priorities and phases manually

Workflow 2: Roadmap Update

1. Load existing feature registry from CSV
2. Run CodeDiscovery to find new features
3. Merge new features into registry
4. Re-export updated roadmap
5. Commit changes to version control

Workflow 3: Multi-Repo Analysis

1. Discover features from multiple repositories
2. Merge into single registry
3. Deduplicate and categorize
4. Export consolidated roadmap
5. Share with team

Output Formats

CSV Registry Format

id,name,category,phase,priority,status,size,tokenEstimate,description,source,dependencies
F-1,User Login,Auth,Phase 1,high,implemented,S,100000,JWT authentication,code/routes.ts,
F-2,Dashboard,UI,Phase 1,high,implemented,M,200000,Main dashboard view,code/Dashboard.tsx,F-1
F-3,API Rate Limiting,Backend,Phase 2,medium,planned,XS,50000,Rate limit endpoints,code/middleware.ts,

Markdown Roadmap Format

# Product Roadmap

## Phase 1 - Core Features (5 features)
**Effort**: 500k tokens (2 S, 2 M, 1 L)

### ✅ Completed (3)
- **User Login** (Auth) - JWT authentication [Size: S, 100k tokens]
- **Dashboard** (UI) - Main dashboard view [Size: M, 200k tokens]
- **Profile** (UI) - User profile page [Size: S, 100k tokens]

### 🚧 In Progress (2)
- **Settings** (UI) - User settings management [Size: M, 200k tokens]
- **Notifications** (Features) - Real-time notifications [Size: L, 400k tokens]

## Phase 2 - Enhanced Features (3 features)
**Effort**: 250k tokens (1 XS, 1 S, 1 M)

### 📋 Planned (3)
- **API Rate Limiting** (Backend) - Rate limit endpoints [Size: XS, 50k tokens]
- **Advanced Search** (Features) - Full-text search [Size: S, 100k tokens]
- **Export Data** (Features) - CSV/JSON export [Size: S, 100k tokens]

## Statistics
- **Total Features**: 8
- **Completion Rate**: 37.5%
- **High Priority**: 3 features
- **Total Effort**: 750k tokens
- **Completed Effort**: 400k tokens (53%)

Integration with Other Skills

With project-analyzer

  1. Discover features from code (project-planner)
  2. Verify features in production (project-analyzer)
  3. Create roadmap with verified status

With project-manager

  1. Discover features from code (project-planner)
  2. Create GitHub issues for unimplemented features (project-manager)
  3. Track progress in registry

Technical Details

  • Location: {{INSTALL_DIR}}/project-planner/
  • Language: TypeScript/Node.js
  • Dependencies:
    • @babel/parser - Code parsing
    • glob - File pattern matching
    • csv-parse / csv-stringify - CSV handling
  • Performance:
    • Code scan: ~500 files/second
    • Feature extraction: ~100 features/second
    • Registry operations: In-memory (very fast)

Error Handling

If discovery fails:

  1. Parse errors: Check code syntax, ensure valid JS/TS
  2. File not found: Verify paths exist
  3. Framework detection failed: Manually specify framework type
  4. CSV errors: Check CSV format, validate headers
  5. Dependencies missing: Run npm install in project-planner directory

Tips for Best Results

  • Start with automatic discovery to get initial feature list
  • Review and refine feature names, categories, priorities
  • Keep registry in version control to track changes over time
  • Re-run discovery periodically to catch new features
  • Use consistent naming for features across discovery runs
  • Link to code by including file paths in feature metadata
  • Track dependencies between features for better planning

Examples

Example 1: Analyze React App

User: "Discover all features in my React app"

Response:

// I'll analyze your React application to discover features
const discovery = new CodeDiscovery();
const features = await discovery.discoverFromReact('/path/to/app', {
  includeRoutes: true,
  includeComponents: true
});

// Found 42 features:
// - 15 routes
// - 27 components
//
// Saved to features.csv

Example 2: Generate Roadmap

User: "Create a roadmap from the feature registry"

Response:

// Loading features from CSV...
const registry = new CSVFeatureRegistry();
const features = await registry.loadFeatures('features.csv');

// Exporting roadmap...
const exporter = new RoadmapExporter();
const roadmap = await exporter.exportToMarkdown(features, {
  groupBy: 'phase',
  sortBy: 'priority'
});

// Roadmap created: ROADMAP.md
// - 3 phases
// - 42 total features
// - 65% completion rate

Example 3: Complete Discovery to Issues Workflow

User: "Analyze my code and create issues for missing features"

Response:

1. Discovering features from code...
   → Found 42 features in codebase

2. Discovering features from documentation...
   → Found 58 planned features

3. Comparing lists...
   → 16 features exist in docs but not in code

4. Creating GitHub issues... (project-manager skill)
   → Created 16 issues with "missing-feature" label

5. Roadmap updated: ROADMAP.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.