# Claude Multi-Agent PM Framework Ticketing System v4.2.2

## Overview
The Claude PM Framework uses ai-trackdown-tools CLI for comprehensive project management with hierarchical ticket organization. This document provides complete documentation for CLI-based ticket management in the Claude Max + mem0AI enhancement project.

**AI-Trackdown-Tools Integration**: ✅ ACTIVE
**CLI Version**: 1.0.1+build.1
**Framework Version**: 4.2.2
**Last Updated**: 2025-07-09
**Package**: @bobmatnyc/ai-trackdown-tools
**Documentation Status**: Updated for CLI usage


## AI-Trackdown-Tools CLI Integration

### Hierarchical Ticket Structure
The framework uses ai-trackdown-tools CLI for hierarchical ticket management:

```
Epics → Issues → Tasks → PRs (Pull Requests)
```

### CLI Commands Reference

#### Core Commands
- **`aitrackdown`** - Main CLI command
- **`atd`** - Alias for aitrackdown (shorter command)
- **`./bin/aitrackdown`** - Framework-specific CLI wrapper
- **`./bin/atd`** - Framework-specific CLI alias

#### Epic Management
```bash
# Create new epic
aitrackdown epic create "User Authentication System"

# List epics with progress
aitrackdown epic list --status active --show-progress
atd epic list --status todo,in-progress --show-progress

# Show epic details with issues
aitrackdown epic show EP-0001 --with-issues

# Complete epic
aitrackdown epic complete EP-0001 --actual-tokens 1500
```

#### Issue Management
```bash
# Create issue within epic
aitrackdown issue create "Implement login form" --epic EP-0001

# List issues by epic and status
aitrackdown issue list --epic EP-0001 --status active
atd issue list --priority high --status todo,in-progress

# Complete issue
aitrackdown issue complete ISS-0001 --actual-tokens 500

# Assign issue
aitrackdown issue assign ISS-0001 --assignee john
```

#### Task Management
```bash
# Create task within issue
aitrackdown task create "Create login UI" --issue ISS-0001

# List tasks
aitrackdown task list --issue ISS-0001 --assignee john

# Complete task
aitrackdown task complete TSK-0001 --time-spent 2h

# Update task status
aitrackdown task update TSK-0001 --status active
```

#### PR Management
```bash
# Create PR for issue
aitrackdown pr create "Add login functionality" --issue ISS-0001

# List PRs by status
aitrackdown pr list --status open --assignee john

# Merge PR
aitrackdown pr merge PR-0001 --delete-branch

# Review PR
aitrackdown pr review PR-0001 --approve --comment "LGTM"
```

### Ticket ID Format
All tickets follow ai-trackdown-tools naming conventions:

```
EP-XXXX: Epic Title
ISS-XXXX: Issue Title
TSK-XXXX: Task Title
PR-XXXX: Pull Request Title
```

### Priority Levels
- **CRITICAL**: Must be completed for system to function
- **HIGH**: Important for milestone completion
- **MEDIUM**: Standard feature development
- **LOW**: Nice-to-have enhancements

## Current Project Structure

### Active Tickets (AI-Trackdown-Tools Format)
The framework currently manages tickets using ai-trackdown-tools CLI with the following structure:

#### Active Epics (EP-XXXX)
```bash
# View active epics
aitrackdown epic list --status active --show-progress
```

Sample active epics:
- **EP-0032**: CMPM Dashboard/Command NPM Publishing
- **EP-0030**: Remove Memory Dependencies from ai-trackdown-tools
- **EP-0029**: Multi-Agent Coordination Demo
- **EP-0026**: Memory System Security Audit Enhancement
- **EP-0016**: Core Framework Development

#### Active Issues (ISS-XXXX)
```bash
# View active issues
aitrackdown issue list --status active --priority high
```

Sample active issues:
- **ISS-0053**: Add claude-pm-portfolio-manager as framework dependency
- **ISS-0052**: Publish claude-pm-portfolio-manager as npm package
- **ISS-0051**: Implement CMPM dashboard command with headless browser
- **ISS-0049**: Delegate root directory cleanup to code cleanup agent
- **ISS-0047**: Implement CMPM agents command for active agent registry

#### Active Tasks (TSK-XXXX)
```bash
# View active tasks
aitrackdown task list --status active
```

Sample active tasks:
- **TSK-0014**: Design dashboard layout
- **TSK-0013**: Set up JWT token generation
- **TSK-0012**: Test task
- **TSK-0011**: Update health monitoring config paths

### Legacy Ticket References
The framework has completed foundational work previously tracked under legacy ticket prefixes:

#### Completed Foundation Work
- **Memory Integration**: Core mem0AI integration completed
- **Multi-Agent Architecture**: 11-agent ecosystem operational
- **Task Delegation**: Subprocess coordination architecture complete
- **Framework Core**: Base PM framework functionality complete

#### Current Implementation Status
- **Framework Version**: 4.2.2
- **AI-Trackdown-Tools**: 1.0.1+build.1
- **Memory Service**: Integrated with mem0AI
- **Agent Ecosystem**: Multi-agent coordination operational
- **CLI Management**: Full ai-trackdown-tools integration
- **Deployment**: Universal deployment package available

## Key Files and Directories

### CLI-Based Ticket Management
- **Tasks Directory**: `/Users/masa/Projects/claude-multiagent-pm/tasks/`
  - `epics/` - Strategic epics (EP-XXXX)
  - `issues/` - Implementation issues (ISS-XXXX)
  - `tasks/` - Development tasks (TSK-XXXX)
  - `prs/` - Pull requests (PR-XXXX)
  - `templates/` - Standard templates

### Framework Configuration
- **Deployment Config**: `/Users/masa/Projects/claude-multiagent-pm/.claude-pm/config.json`
- **CLI Wrappers**: `/Users/masa/Projects/claude-multiagent-pm/bin/aitrackdown`
- **Health Checks**: `/Users/masa/Projects/claude-multiagent-pm/scripts/health-check.sh`
- **Package Config**: `/Users/masa/Projects/claude-multiagent-pm/package.json`

### Documentation
- **This Document**: `/Users/masa/Projects/claude-multiagent-pm/docs/TICKETING_SYSTEM.md`
- **Framework Config**: `/Users/masa/Projects/claude-multiagent-pm/CLAUDE.md`
- **Design Documents**: `/Users/masa/Projects/claude-multiagent-pm/docs/design/`

### Core Framework Structure
```
/Users/masa/Projects/claude-multiagent-pm/
├── claude_pm/          # Framework core
├── tasks/              # AI-trackdown-tools managed tickets
├── bin/               # CLI wrappers (aitrackdown, atd)
├── scripts/           # Health checks and utilities
├── .claude-pm/        # Deployment configuration
├── requirements/      # Python dependencies
├── docs/             # Documentation
└── package.json      # NPM package configuration
```

## Current Architecture Status

### Framework Capabilities
- ✅ AI-trackdown-tools CLI integration
- ✅ Hierarchical ticket management (Epics → Issues → Tasks → PRs)
- ✅ Multi-agent coordination system
- ✅ Memory-augmented project management
- ✅ Universal deployment package
- ✅ Health monitoring and validation
- ✅ GitHub Issues synchronization
- ✅ Token tracking and analytics

### Integration Status
- ✅ @bobmatnyc/ai-trackdown-tools package integration
- ✅ CLI command aliases (aitrackdown/atd)
- ✅ Framework-specific CLI wrappers
- ✅ Deployment configuration management
- ✅ Health check automation
- ✅ Portfolio management capabilities

## Working with AI-Trackdown-Tools CLI

### CRITICAL: CLI-Only Ticket Operations
All ticket operations MUST use ai-trackdown-tools CLI - manual file creation is DEPRECATED.

**REQUIRED CLI USAGE:**
- **Epic Creation**: `aitrackdown epic create --title "Epic Title" --description "Description"`
- **Issue Creation**: `aitrackdown issue create --title "Issue Title" --epic "EP-001"`
- **Task Creation**: `aitrackdown task create --title "Task Title" --issue "ISS-001"`
- **Status Updates**: `aitrackdown status` or `atd status --summary`
- **Ticket Completion**: `aitrackdown issue complete ISS-001`

**DEPRECATED - DO NOT USE:**
- Manual tasks/ directory creation
- Manual markdown file creation
- Direct file system ticket management

### Framework Backlog Location
The ai-trackdown-tools manages tickets in the hierarchical structure:
```
/Users/masa/Projects/claude-multiagent-pm/tasks/
├── epics/          # Strategic epics (EP-XXXX)
├── issues/         # Implementation issues (ISS-XXXX)
├── tasks/          # Development tasks (TSK-XXXX)
├── prs/            # Pull requests (PR-XXXX)
└── templates/      # Standard templates
```

### For AI Assistants
1. **Use CLI commands only** - Never create manual ticket files
2. **Reference correct ticket IDs** - Use ai-trackdown-tools format (EP-XXXX, ISS-XXXX, etc.)
3. **Update via CLI** - All status updates through aitrackdown commands
4. **Check dependencies** - Use `aitrackdown epic show EP-XXXX --with-issues`
5. **Follow CLI workflow** - Create epics → issues → tasks → PRs

### Quick CLI Commands for Status Review
```bash
# View comprehensive project status
aitrackdown status --verbose
atd status --summary

# View current sprint progress
aitrackdown status --current-sprint

# List active epics with progress
aitrackdown epic list --status active --show-progress

# List high priority issues
aitrackdown issue list --priority high --status todo,in-progress

# View project backlog
aitrackdown backlog --with-issues
```

### CLI Status Tracking
- **todo**: Pending/Not Started
- **in-progress**: Currently being worked on
- **blocked**: Blocked (with blocker explanation)
- **done**: Completed

### Token and Time Tracking
- **Estimated Tokens**: Set during creation
- **Actual Tokens**: Recorded at completion
- **Time Spent**: Tracked per task
- **Progress Analytics**: Built-in reporting

## AI-Trackdown-Tools vs Legacy System

### Migration Complete
The framework has fully migrated from legacy manual ticket management to ai-trackdown-tools CLI:

#### Before (Legacy)
```bash
# Manual file creation (DEPRECATED)
touch /path/to/ticket.md
echo "# Ticket Title" > ticket.md
```

#### After (Current)
```bash
# CLI-based ticket management
aitrackdown epic create "Epic Title" --description "Epic description"
aitrackdown issue create "Issue Title" --epic EP-0001
aitrackdown task create "Task Title" --issue ISS-0001
```

### Key Differences
1. **Hierarchical Structure**: Epics → Issues → Tasks → PRs
2. **Automated ID Generation**: EP-XXXX, ISS-XXXX, TSK-XXXX, PR-XXXX
3. **Built-in Analytics**: Token tracking, time estimation, progress reporting
4. **GitHub Integration**: Bidirectional sync with GitHub Issues
5. **CLI Consistency**: Standardized commands across all operations
6. **Template System**: Automated template generation
7. **Relationship Management**: Automatic parent-child ticket relationships

### Benefits of AI-Trackdown-Tools
- **Consistency**: Standardized ticket format across all projects
- **Automation**: Reduced manual work for ticket creation and management
- **Analytics**: Built-in reporting and progress tracking
- **Integration**: GitHub Issues sync and external system integration
- **Scalability**: Portfolio management across multiple projects
- **AI Features**: Token tracking, context management, pattern recognition

## AI-Trackdown-Tools Package Integration

### Package Information
- **Package**: @bobmatnyc/ai-trackdown-tools
- **Version**: 1.0.1+build.1
- **Installation**: Local development link via npm
- **Repository**: https://github.com/bobmatnyc/ai-trackdown-tools

### Framework Integration
- **CLI Wrappers**: `./bin/aitrackdown` and `./bin/atd`
- **Package Dependency**: File-based local package link
- **Configuration**: `.claude-pm/config.json`
- **Health Checks**: `./scripts/health-check.sh`

### Advanced CLI Features

#### AI-Specific Commands
```bash
# Token tracking and reporting
aitrackdown ai track-tokens --report

# Generate LLM context files
aitrackdown ai generate-llms-txt --format detailed

# Add context to tickets
aitrackdown ai context --item-id EP-0001 --add "context/requirements"
```

#### GitHub Integration
```bash
# Setup GitHub sync
aitrackdown sync setup --repository owner/repo --token ghp_xxx

# Push tickets to GitHub Issues
aitrackdown sync push --verbose

# Pull GitHub Issues to local tickets
aitrackdown sync pull --dry-run

# Bidirectional sync
aitrackdown sync bidirectional
```

#### Portfolio Management
```bash
# Portfolio-wide status across multiple projects
aitrackdown portfolio --health

# Export project data
aitrackdown export --format json

# Work with any project from anywhere
aitrackdown status --project-dir ~/Projects/managed/other-project
```

### Migration from Legacy Systems
```bash
# Migrate from old trackdown structure
aitrackdown migrate --dry-run --verbose
aitrackdown migrate --backup

# Migrate directory structure
aitrackdown migrate-structure --dry-run
```

### Framework Memory Enhancement
The ai-trackdown-tools CLI integrates with the Claude PM Framework's memory system:
- Token usage tracking and optimization
- Pattern recognition for successful task decomposition
- Cross-project knowledge sharing
- Intelligent context management
- Continuous learning from ticket completion patterns

## Repository Locations
- **Claude PM Framework**: https://github.com/bobmatnyc/claude-multiagent-pm
- **AI-Trackdown-Tools**: https://github.com/bobmatnyc/ai-trackdown-tools

## Framework Status
The Claude PM Framework uses ai-trackdown-tools CLI for all ticket management operations, providing hierarchical project organization with advanced analytics and AI-driven insights.