zhongwei/gh-duongdev-ccpm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f4fe5ac0c33919108b18317642b30fba1f9c69e7
gh-duongdev-ccpm/commands/SPEC_MANAGEMENT_SUMMARY.md
Zhongwei Li f4fe5ac0c3 Initial commit
2025-11-29 18:24:24 +08:00

13 KiB
Raw Blame History

PM Commands: Spec Management System - Implementation Summary

Date: 2025-11-10 Status: ✅ COMPLETE Version: PM Commands 2.0 + Spec Management

🎯 Overview

Implemented a comprehensive Spec Management System for PM Commands, enabling spec-first development workflow with Linear Documents integration. This enhances the existing PM Commands 2.0 (Interactive Mode) with 6 new spec-focused commands plus a context-aware help system.

📊 What Was Built

6 New Spec Management Commands

1. /ccpm:spec:create <type> "<title>" [parent-id]

Purpose: Create Epic/Feature with Linear Document

Features:

  • Creates Linear Initiative (Epic) or Parent Issue (Feature)
  • Generates associated Linear Document for specs
  • Pre-populates with appropriate template (Epic Spec or Feature Design)
  • Links document to issue
  • Supports hierarchy (Features can belong to Epics)

Templates Included:

  • Epic Spec Template: Vision, User Research, Architecture, Features Breakdown, Timeline, Security
  • Feature Design Template: Requirements, UX, Technical Design, Testing, Implementation Plan, Risks

2. /ccpm:spec:write <doc-id> <section>

Purpose: AI-assisted spec writing with codebase analysis

Sections:

  • requirements - Functional, non-functional, acceptance criteria
  • architecture - System design, component breakdown, tech stack
  • api-design - RESTful endpoints, request/response, validation
  • data-model - Database schema, TypeScript types, migrations
  • testing - Unit, integration, E2E strategies
  • security - Auth, validation, rate limiting, audit logs
  • user-flow - User journeys, wireframes, error states
  • timeline - Task breakdown, estimates, milestones
  • all - Write all sections sequentially

AI Capabilities:

  • Analyzes existing codebase for patterns
  • Fetches library documentation via Context7 MCP
  • Follows project conventions
  • Generates specific, testable content

3. /ccpm:spec:review <doc-id>

Purpose: AI-powered spec validation

Analysis:

  • Completeness Score (0-100%) based on required vs optional sections
  • Quality Assessment: Specificity, testability, clarity, consistency
  • Risk Identification: Scope creep, technical risks, timeline issues
  • Grading: A (90-100%), B (75-89%), C (60-74%), D (50-59%), F (<50%)

Output:

  • Detailed review report
  • Actionable recommendations
  • Best practices checklist
  • Missing sections identified

4. /ccpm:spec:break-down <epic-or-feature-id>

Purpose: Generate implementation items from spec

Breakdown Logic:

  • Epic → Features: Parses "Features Breakdown" table, creates Parent Issues
  • Feature → Tasks: Parses "Task Breakdown" checklist, creates Sub-Issues

Features:

  • Auto-extracts from spec sections
  • AI suggests missing items
  • Detects and preserves dependencies
  • Maps priorities (P0=Urgent, P1=High, etc.)
  • Converts time estimates to Linear points
  • Shows preview before creation
  • Requires user confirmation

5. /ccpm:spec:migrate <project-path> [category]

Purpose: Migrate existing markdown specs to Linear

Discovery:

  • Scans .claude/ directory: docs, plans, enhancements, tasks, research, analysis
  • Categorizes files: Epic, Feature, Task, Documentation
  • Auto-detects based on content patterns and file location

Migration Process:

  1. Discover all markdown files in project
  2. Categorize by type (Epic/Feature/Task/Doc)
  3. Show detailed preview for EVERY file (MANDATORY)
  4. Ask confirmation before ANY creation
  5. Create Linear Issues + Documents
  6. Extract checklists → create sub-tasks
  7. Move originals to .claude/migrated/
  8. Create breadcrumb files with Linear links

Safety:

  • ✅ ALWAYS shows full preview before migration
  • ✅ Requires explicit confirmation
  • ✅ Original files moved (NOT deleted)
  • ✅ Can rollback from .claude/migrated/
  • ✅ Preserves full content in Linear Documents

6. /ccpm:spec:sync <doc-id-or-issue-id>

Purpose: Sync spec with implementation reality

Drift Detection:

  • Requirements Drift: Missing, extra, or changed features
  • API Drift: Endpoint signatures, new/missing endpoints
  • Data Model Drift: Schema changes, field modifications
  • Task Drift: Status mismatches between spec checklist and Linear

Sync Options:

  1. Update spec to match reality (recommended)
  2. Update implementation to match spec
  3. Hybrid approach (choose per item)
  4. Review only

Drift Score: 0-100% (lower is better, 0% = perfect sync)

1 New Help Command

7. /ccpm:utils:help [issue-id]

Purpose: Context-aware help and command suggestions

Features:

  • General Mode: Shows all commands categorized
  • Context-Aware Mode: Analyzes issue status and suggests relevant commands
  • Priority-Based Suggestions: High/Medium/Low based on current state
  • Interactive Actions: Quick action menu for common workflows
  • Workflow Guidance: Spec-first vs Task-first flowcharts

Smart Suggestions:

  • Status "Planning" → Suggest: Create spec, Write spec, Break down
  • Status "In Progress" → Suggest: Next action, Sync spec, Quality checks
  • Status "Verification" → Suggest: Run verification
  • Status "Done" → Suggest: Finalize, Final spec sync
  • Label "blocked" → Suggest: Fix issues, Review status

📁 Files Created

Spec Management Commands (6 files)

`$CCPM_COMMANDS_DIR/`
├── create.md         - Create Epic/Feature with spec doc (459 lines)
├── write.md          - AI-assisted spec writing (934 lines)
├── review.md         - Spec validation & grading (333 lines)
├── break-down.md     - Epic→Features, Feature→Tasks (413 lines)
├── migrate.md        - Migrate .claude/ specs to Linear (634 lines)
└── sync.md           - Sync spec with implementation (536 lines)

Help Command (1 file)

`$CCPM_COMMANDS_DIR/`
└── help.md           - Context-aware help (434 lines)

Documentation Updates (1 file)

`$CCPM_COMMANDS_DIR/`
└── README.md         - Updated with spec management section

Total: 8 files created/modified, ~3,743 lines of documentation

🔄 Integration with Existing PM Commands

Spec Management enhances PM Commands 2.0 (Interactive Mode + 10 workflow commands):

Combined Workflow Options

Option 1: Spec-First Workflow (Recommended for Personal Project)

1. /ccpm:spec:create epic "User Auth"
2. /ccpm:spec:write DOC-123 all
3. /ccpm:spec:review DOC-123
4. /ccpm:spec:break-down WORK-100    ← Creates Features
5. /ccpm:spec:write DOC-124 all       ← For each feature
6. /ccpm:spec:break-down WORK-101    ← Creates Tasks
7. /ccpm:implementation:start WORK-201
8. /ccpm:spec:sync WORK-101          ← Keep in sync
9. /ccpm:verification:check WORK-201
10. /ccpm:complete:finalize WORK-201

Option 2: Task-First Workflow (Quick tasks)

1. /ccpm:planning:create "Add dark mode" personal-project
2. /ccpm:implementation:start WORK-300
3. /ccpm:verification:check WORK-300
4. /ccpm:complete:finalize WORK-300

Option 3: Migrate Existing → Spec Workflow

1. /ccpm:spec:migrate ~/personal/personal-project
2. Review migrated items in Linear
3. /ccpm:spec:sync DOC-XXX            ← Sync with codebase
4. Continue with spec-first workflow

All PM Commands (25 Total)

Spec Management (6):

  • /ccpm:spec:create
  • /ccpm:spec:write
  • /ccpm:spec:review
  • /ccpm:spec:break-down
  • /ccpm:spec:migrate
  • /ccpm:spec:sync

Planning (3):

  • /ccpm:planning:create
  • /ccpm:planning:plan
  • /ccpm:planning:quick-plan

Implementation (3):

  • /ccpm:implementation:start
  • /ccpm:implementation:next
  • /ccpm:implementation:update

Verification (3):

  • /ccpm:verification:check
  • /ccpm:verification:verify
  • /ccpm:verification:fix

Completion (1):

  • /ccpm:complete:finalize

Utilities (9):

  • /ccpm:utils:status
  • /ccpm:utils:context
  • /ccpm:utils:report
  • /ccpm:utils:insights
  • /ccpm:utils:auto-assign
  • /ccpm:utils:sync-status
  • /ccpm:utils:rollback
  • /ccpm:utils:dependencies
  • /ccpm:utils:agents
  • /ccpm:utils:help ← NEW

🎯 Use Cases

Use Case 1: New Feature Development (personal-project)

Scenario: Building "Task Comments System" feature

# 1. Create Feature with Spec
/ccpm:spec:create feature "Task Comments System"
# Creates: WORK-100 + DOC-123

# 2. Write Comprehensive Spec
/ccpm:spec:write DOC-123 requirements
/ccpm:spec:write DOC-123 api-design
/ccpm:spec:write DOC-123 data-model
/ccpm:spec:write DOC-123 testing
# AI generates detailed specs based on codebase

# 3. Review & Validate
/ccpm:spec:review DOC-123
# Output: Grade A (92%) - Ready for approval

# 4. Break Down into Tasks
/ccpm:spec:break-down WORK-100
# Creates: WORK-101, WORK-102, WORK-103 (subtasks)

# 5. Implement
/ccpm:implementation:start WORK-101
# Works on first subtask

# 6. Keep Spec in Sync
/ccpm:spec:sync WORK-100
# Detects: API added optional field not in spec
# Updates spec to match reality

Use Case 2: Migrating Existing Specs

Scenario: You have 45 markdown files in .claude/ to migrate

# 1. Run Migration
/ccpm:spec:migrate ~/personal/personal-project

# Output: Detailed preview for ALL 45 files
# - 2 Epics → Linear Initiatives + Spec Docs
# - 12 Features → Parent Issues + Design Docs
# - 25 Tasks → Issues (some with subtasks)
# - 6 Docs → Reference documents

# 2. Confirm after reviewing preview
# → Creates all items in Linear

# 3. Review in Linear
/ccpm:utils:report personal-project
# Shows all migrated items organized

# 4. Continue with spec workflow
/ccpm:spec:sync WORK-102
/ccpm:spec:break-down WORK-103

Use Case 3: Daily Development

Morning:

/ccpm:utils:report personal-project
# Shows: 5 active tasks, 2 blocked, 3 in verification

/ccpm:utils:help WORK-150
# Suggests: Continue with /ccpm:implementation:next WORK-150

During Work:

/ccpm:implementation:next WORK-150
# AI: Next task is Task 3 (no dependencies, ready)

/ccpm:spec:sync WORK-150
# Drift Score: 15% (minor - API signature changed)
# Updates spec to match

End of Day:

/ccpm:verification:check WORK-150
# All checks pass

/ccpm:complete:finalize WORK-150
# Creates PR, updates Jira (with confirmation)

✅ Key Features

1. Safety First

  • Migration: ALWAYS shows full preview, requires confirmation
  • External Systems: Never writes to Jira/Confluence/Slack without explicit approval
  • Rollback: Original files preserved in .claude/migrated/

2. AI-Powered

  • Codebase Analysis: Searches existing code for patterns
  • Library Docs: Fetches latest via Context7 MCP
  • Smart Suggestions: Context-aware next actions
  • Complexity Analysis: Estimates and risk identification

3. Spec-First Development

  • Linear Documents as source of truth
  • Epic → Feature → Task hierarchy
  • Sync Detection for spec drift
  • Automated Breakdown from specs

4. Interactive & Guided

  • Context-Aware Help: Suggests commands based on status
  • Interactive Mode: Every command suggests next action
  • Workflow Guidance: Built-in flowcharts and examples

5. Migration-Friendly

  • Discovers all markdown specs automatically
  • Categorizes intelligently (Epic/Feature/Task)
  • Preserves full content and metadata
  • Safe with backup and rollback

🚀 Next Steps for User

Getting Started with Spec Management

  1. Migrate Existing Specs (if you have any):

    /ccpm:spec:migrate ~/personal/personal-project

  2. Create First Epic with Spec:

    /ccpm:spec:create epic "Your Epic Name"
/ccpm:spec:write DOC-XXX all
/ccpm:spec:review DOC-XXX

  3. Break Down into Features:

    /ccpm:spec:break-down WORK-XXX

  4. Start Implementation:

    /ccpm:implementation:start WORK-YYY

  5. Keep Spec in Sync:

    /ccpm:spec:sync WORK-XXX

Daily Workflow

Morning:

/ccpm:utils:report personal-project
/ccpm:utils:help WORK-XXX  # Get context-aware suggestions

During Work:

/ccpm:implementation:next WORK-XXX
/ccpm:spec:sync WORK-XXX  # Periodically

End of Day:

/ccpm:verification:check WORK-XXX
/ccpm:complete:finalize WORK-XXX

📚 Documentation

Main README:

  • ``$CCPM_COMMANDS_DIR/README.md

Spec Command Docs:

  • ``$CCPM_COMMANDS_DIR/*.md

Help Command:

/ccpm:utils:help           # General help
/ccpm:utils:help WORK-123  # Context-aware help

🎉 Summary

Implemented:

  • ✅ 6 Spec Management Commands
  • ✅ 1 Context-Aware Help Command
  • ✅ Comprehensive documentation
  • ✅ Safety-first migration process
  • ✅ AI-powered spec writing
  • ✅ Spec-implementation sync detection
  • ✅ Integration with PM Commands 2.0

Benefits:

  • 📐 Spec-first development workflow
  • 🔄 Keep specs in sync with code
  • 📦 Migrate existing markdown specs
  • 🤖 AI-assisted spec writing
  • 🎯 Context-aware guidance
  • ✅ Linear Documents as source of truth

Total Commands: 25 (was 19 in PM Commands 2.0, now 25 with Spec Management)

Ready to use! 🚀

Reference in New Issue View Git Blame Copy Permalink