Project Manager

Project Manager Skill

Manages the complete feature lifecycle: feature registry, roadmap generation, visual documentation, GitHub issue management, and project reporting.

When to Use This Skill

Invoke this skill when the user:

• Feature Management: Needs to add, update, or track features in the registry
• Roadmap Generation: Wants to create visual roadmaps (Markdown/HTML/JSON)
• GitHub Integration: Needs to create or update GitHub issues from features/TODOs
• Visual Documentation: Wants to attach screenshots to issues or features
• Issue Automation: Needs bulk issue creation with smart labeling
• Project Reports: Wants daily/weekly status reports or summaries
• Feature Tracking: Needs to track feature status, dependencies, progress
• Dashboard Integration: Wants to trigger actions from the interactive dashboard

Core Capabilities

1. Feature Registry Management (PM-3)

• CRUD Operations: Create, read, update, delete features
• Dependency Tracking: Manage feature dependencies, detect circular deps
• Status Management: Track features through planning → development → shipped
• Single Source of Truth: CSV-based registry with full history
• T-Shirt Sizing: Track implementation effort using token-based estimates

2. Roadmap Generation (PM-9)

• Markdown Export: Beautiful roadmaps with progress bars and tables
• HTML Export: Dark-themed, responsive HTML roadmaps for stakeholders
• JSON Export: Structured data for integrations and dashboards
• Grouping Options: By phase, category, priority, or status

3. GitHub Issue Management

• Create Issues (PM-1): From features, TODOs, or analysis results
• Update Issues (PM-35): Auto-update when features change
• Smart Labeling: Auto-apply labels based on type, priority, category
• Duplicate Prevention: SHA256-based state tracking
• Issue Linking (PM-36): Automatic parent/child relationships

4. Visual Documentation (PM-12-15)

• Screenshot Capture: Code snippets, UI elements, full pages
• Multi-Viewport (PM-13): Mobile, tablet, desktop screenshots
• Visual Comparison (PM-14): Before/after with diff analysis
• UI Bug Detection (PM-15): Automated accessibility scanning
• GitHub Upload: Attach visual evidence to issues

5. Reporting & Analytics

• Daily Reports: Automated status reports with statistics
• Summary Reports: 30-day aggregated summaries
• Progress Tracking: Feature completion rates, velocity
• Export Formats: Markdown, JSON, CSV

Integration with Dashboard

The manager integrates with the interactive dashboard at http://localhost:5173:

1. Feature Registry: View/edit features in interactive cards
2. Drag & Drop: Move features between backlog/nextUp/inProgress
3. Action Triggers: Click buttons to generate roadmaps, create issues
4. Live Updates: Real-time feature status updates
5. Visual Tracking: See progress bars, statistics, trends

Dashboard Workflow

User clicks "Create Issues" in dashboard
→ Dashboard creates action in .dashboard-actions/
→ Claude detects action, invokes manager skill
→ Manager creates GitHub issues with screenshots
→ Results stream back to dashboard in real-time
→ Dashboard updates feature cards with issue links

Instructions

Step 1: Verify Prerequisites

Check GitHub authentication and configuration:

# Check GitHub token
if [ -z "$GITHUB_TOKEN" ]; then
  if ! gh auth status >/dev/null 2>&1; then
    echo "Please run: gh auth login"
    exit 1
  fi
fi

# Verify config exists
cd "{{INSTALL_DIR}}/project-manager"
if [ ! -f "project-manager.config.json" ]; then
  echo "Config needed. Creating from template..."
  cp project-manager.config.example.json project-manager.config.json
fi

Step 2: Feature Registry Operations

Add/Update Features

cd "{{INSTALL_DIR}}/project-planner"

# Add a new feature
npx ts-node src/cli.ts registry add \
  --name "User Authentication" \
  --category "Auth" \
  --phase "Phase 1" \
  --status "planning" \
  --description "Login/signup with email and password"

# Update feature status
npx ts-node src/cli.ts registry update PM-42 --status "in-progress"

# List all features
npx ts-node src/cli.ts registry list --status backlog

# Get feature by ID
npx ts-node src/cli.ts registry get PM-42

Manage Dependencies

# Add dependency
npx ts-node src/cli.ts registry add-dependency PM-42 PM-15

# Check for circular dependencies
npx ts-node src/cli.ts registry validate-dependencies

# View dependency graph
npx ts-node src/cli.ts registry graph -o dependency-graph.md

T-Shirt Sizing for Effort Estimation

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:

Sizing Guidelines:

• 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

Add sizing when creating features:

npx ts-node src/cli.ts registry add \
  --name "User Authentication" \
  --category "Auth" \
  --size "M" \
  --token-estimate 200000 \
  --description "Login/signup with email and password"

Step 3: Generate Roadmaps

cd "{{INSTALL_DIR}}/project-planner"

# Generate Markdown roadmap
npx ts-node src/cli.ts export roadmap \
  --format markdown \
  --group-by phase \
  -o roadmap.md

# Generate HTML roadmap for stakeholders
npx ts-node src/cli.ts export roadmap \
  --format html \
  --group-by category \
  -o roadmap.html

# Generate JSON for dashboard
npx ts-node src/cli.ts export roadmap \
  --format json \
  -o roadmap.json

# Grouped by priority
npx ts-node src/cli.ts export roadmap \
  --format markdown \
  --group-by priority \
  --filter-status "backlog,in-progress" \
  -o priority-roadmap.md

Step 4: Create GitHub Issues

From Features

cd "{{INSTALL_DIR}}/project-manager"

# Create issues from feature registry
npx ts-node src/cli.ts create-issues \
  --from-registry \
  --status "backlog" \
  --dry-run  # Always dry-run first!

# Create for real
npx ts-node src/cli.ts create-issues \
  --from-registry \
  --status "backlog"

From Analysis Results

# Create issues from analyzer output (TODOs, bugs, features)
npm run manage create-issues -- -i analysis-results.json --dry-run

# With screenshots
npm run manage create-issues -- -i analysis-results.json --screenshots

# Review and create
npm run manage create-issues -- -i analysis-results.json

Step 5: Visual Documentation

cd "{{INSTALL_DIR}}/project-manager"

# Capture screenshots for feature
npx ts-node src/cli.ts capture-screenshots \
  --feature PM-42 \
  --url https://staging.example.com/login \
  --viewports mobile,tablet,desktop

# Create issue with screenshots
npx ts-node src/cli.ts create-issue-with-screenshots \
  --feature PM-42 \
  --url https://staging.example.com/login

# Scan for UI bugs and create issues
npx ts-node src/cli.ts scan-and-create-issues \
  --url https://staging.example.com \
  --auto-screenshot

Step 6: Generate Reports

cd "{{INSTALL_DIR}}/project-manager"

# Daily status report
npm run manage report

# Summary report (last 30 days)
npm run manage summary -- -d 30 -o summary-report.md

# Statistics
npm run manage stats

# Feature progress report
npx ts-node src/cli.ts report feature-progress -o progress.md

Step 7: Dashboard Integration

Launch Dashboard

cd dashboard
npm run dev
# Open http://localhost:5173

Trigger Manager Actions from Dashboard

1. From Roadmap Tab: Click "Create Issues" → Triggers manager to create issues
2. From Feature Cards: Click "Generate Roadmap" → Creates roadmap export
3. From Action Queue: Monitor manager execution in real-time
4. Drag & Drop: Move features → Auto-updates registry via manager

Common Workflows

Workflow 1: Complete Feature Lifecycle

1. Discover features (use project-analyzer skill)
2. Add discovered features to registry (manager)
3. Generate roadmap for stakeholders (manager)
4. Verify features in production (use project-analyzer skill)
5. Create GitHub issues for gaps (manager)
6. Track progress in dashboard
7. Generate weekly status reports (manager)

Workflow 2: Feature Release Management

1. Update feature statuses to "ready-to-ship"
2. Generate release roadmap
3. Verify features in staging (use project-analyzer)
4. Create visual documentation with screenshots
5. Generate deployment checklist
6. Update GitHub issues with production URLs
7. Generate release notes

Workflow 3: Issue Automation with Screenshots

1. Scan UI for bugs (use project-analyzer)
2. Capture screenshots of each bug
3. Create GitHub issues with visual evidence
4. Apply smart labels (bug, priority, component)
5. Link related issues automatically
6. Generate bug report for team

Workflow 4: Dashboard-Driven Workflow

1. User opens dashboard at localhost:5173
2. Views features in Roadmap tab
3. Drags feature from backlog to nextUp
4. Clicks "Create Issue" button
5. Manager creates GitHub issue automatically
6. Dashboard updates with issue link
7. User clicks "Generate Roadmap"
8. Manager exports HTML roadmap
9. Dashboard displays success message

Configuration

Manager Config Structure

{
  "github": {
    "owner": "username",
    "repo": "repository",
    "defaultLabels": ["auto-created"],
    "issueTitlePrefix": "[PM]"
  },
  "stateFile": ".project-state.json",
  "reporting": {
    "outputPath": "docs/reports",
    "schedule": "daily"
  },
  "labels": {
    "TODO": ["feature", "priority-medium"],
    "FIXME": ["bug", "priority-high"],
    "BUG": ["bug", "priority-high"],
    "feature": ["feature", "priority-medium"]
  },
  "screenshots": {
    "enabled": true,
    "outputDir": "./screenshots",
    "uploadToGitHub": true,
    "viewports": ["mobile", "tablet", "desktop"]
  }
}

Customizing Labels

Labels are automatically applied based on:

• Feature category: auth → authentication label
• Priority: high → priority-high label
• Type: bug → bug label, feature → feature label
• Phase: Phase 1 → phase-1 label
• Source: Auto-adds from-registry, from-todo, or from-analyzer

Output Formats

Feature Registry (CSV)

id,name,category,phase,status,priority,size,tokenEstimate,description,dependencies,tags
PM-42,User Login,Auth,Phase 1,in-progress,P0,S,100000,"Email/password authentication",PM-15,"security,mvp"
PM-43,Dashboard,UI,Phase 1,backlog,P1,M,200000,"Main dashboard view",PM-42,"ui,analytics"

Roadmap (Markdown)

# Project Roadmap

## Phase 1 (5 features)
Progress: ████████░░ 80% (4/5 complete)
**Effort**: 500k tokens (2 S, 2 M, 1 L)

### ✅ User Login (PM-42)
**Status**: Shipped | **Priority**: P0 | **Size**: S (100k tokens)
Email/password authentication with JWT tokens

### 🚧 Dashboard (PM-43)
**Status**: In Progress | **Priority**: P1 | **Size**: M (200k tokens)
Main dashboard with analytics and charts

GitHub Issue Template

# User Login

## Description
Email/password authentication with JWT tokens

## Details
- **Category**: Auth
- **Phase**: Phase 1
- **Priority**: P0
- **Size**: S (100k tokens)
- **Dependencies**: PM-15 (Authentication Service)

## Effort Estimate
**T-Shirt Size**: S
**Token Estimate**: 100,000 tokens
**Complexity**: Feature implementation with small test suite

## Screenshots
### Desktop View
![Desktop](screenshots/login-desktop.png)

### Mobile View
![Mobile](screenshots/login-mobile.png)

## Implementation Notes
- JWT with 24-hour expiration
- Password hashing with bcrypt
- Rate limiting on login endpoint

---
*Auto-generated by Project Manager*
*Feature ID: PM-42*

Examples

Example 1: Generate Stakeholder Roadmap

User: "Create a roadmap for our Q1 features to share with stakeholders"

Response:

1. Navigate to project-planner
2. Run: npx ts-node src/cli.ts export roadmap --format html --group-by phase --filter-phase "Phase 1" -o Q1-roadmap.html
3. Open Q1-roadmap.html in browser
4. Present: "Generated HTML roadmap with 15 Phase 1 features, grouped by category"
5. Offer: "Would you like me to create GitHub issues for these features?"

Example 2: Feature with Visual Documentation

User: "Create a GitHub issue for the login feature with screenshots"

Response:

1. Check feature exists in registry: PM-42
2. Capture multi-viewport screenshots
3. Create GitHub issue with screenshots attached
4. Link issue back to feature registry
5. Update dashboard with issue link
6. Report: "Created issue #156 with 3 screenshots (mobile, tablet, desktop)"

Example 3: Bulk Issue Creation from Dashboard

User (clicks "Create Issues" button in dashboard):

Response:

1. Dashboard creates action file
2. Manager detects action
3. Reads features marked "backlog" from registry
4. Runs dry-run, streams output to dashboard
5. User reviews in dashboard
6. Manager creates 12 GitHub issues
7. Dashboard updates feature cards with issue links
8. Display success: "Created 12 issues for backlog features"

Dashboard Features

Roadmap Tab

• Interactive Cards: Click to view/edit features
• Drag & Drop: Move between backlog/nextUp/inProgress
• Search & Filter: Find features by category, phase, priority
• Action Buttons: "Create Issues", "Generate Roadmap", "Export"
• Progress Bars: Visual tracking of phase/category completion

Action Queue Tab

• Live Output: Stream manager execution in real-time
• Action History: See past operations
• Status Indicators: Pending, processing, completed, failed
• Cancel Actions: Stop long-running operations

Tests Tab

• Test Coverage: See feature test status
• Verification Results: Production verification status
• Visual Tests: Screenshot comparisons

State Management

The manager maintains state in .project-state.json:

{
  "lastUpdated": "2025-10-22T14:30:00.000Z",
  "processedItems": [
    {
      "hash": "abc123",
      "type": "feature",
      "featureId": "PM-42",
      "issueNumber": 156,
      "issueUrl": "https://github.com/owner/repo/issues/156",
      "status": "created",
      "createdAt": "2025-10-22T14:30:00.000Z"
    }
  ],
  "metadata": {
    "totalFeatures": 40,
    "totalIssuesCreated": 25,
    "totalScreenshots": 75
  }
}

Important: Never delete this file - it prevents duplicate issue creation!

Safety Features

Dry-Run Mode

Always preview changes before committing:

• Shows exactly what will be created/updated
• No actual GitHub API calls
• Safe to run multiple times
• Review output before proceeding

Duplicate Detection

• SHA256 hash prevents duplicate issues
• Checks registry for existing features
• Compares with state file
• Warns before creating duplicates

Dependency Validation

• Detects circular dependencies
• Validates dependency existence
• Warns about missing prerequisites
• Suggests resolution order

Error Handling

Common errors and solutions:

1. GitHub token not found: Run gh auth login or set GITHUB_TOKEN
2. Config not found: Created from template automatically
3. Registry not found: Initialize with npx ts-node src/cli.ts registry init
4. Circular dependencies: Run registry validate-dependencies to identify
5. Screenshot capture fails: Ensure Playwright installed: npx playwright install

Integration with Project Analyzer

Complete workflow combining both skills:

1. Analyzer discovers features from code/web/TODOs
2. Manager adds discovered features to registry
3. Analyzer verifies features in production
4. Manager creates GitHub issues for gaps/bugs
5. Manager generates roadmap and reports
6. Dashboard displays complete feature status

Tips for Best Results

• Use dashboard for interactive feature management
• Start with dry-run before bulk operations
• Generate roadmaps weekly to track progress
• Attach screenshots to UI-related issues
• Link dependencies to show feature relationships
• Customize labels to match your team's workflow
• Regular reports keep stakeholders informed
• Validate dependencies before marking features ready
• Multi-viewport screenshots for responsive features
• Chain with analyzer for complete automation