Claude Multi-Agent PM - Quick Start Guide

July 22, 2025 · View on GitHub

Version Node.js Python

AI project manager that orchestrates specialized agents for your development workflow.

⚡ Quick Install & Run

# Install globally
npm install -g @bobmatnyc/claude-multiagent-pm

# Navigate to your project
cd your-project

# Start the framework
claude-pm

📱 macOS Installation (Homebrew Python)

If you encounter an "externally-managed-environment" error on macOS:

# Option 1: Use pipx (recommended)
brew install pipx
pipx ensurepath
pipx install @bobmatnyc/claude-multiagent-pm

# Option 2: Run the macOS installer
curl -fsSL https://raw.githubusercontent.com/bobmatnyc/claude-multiagent-pm/main/scripts/install-claude-pm-macos.sh | bash

See our macOS Installation Guide for detailed instructions.

🎯 What It Does

Claude Multi-Agent PM transforms your development workflow by providing:

  • 🤖 AI Agent Orchestration: Specialized agents handle documentation, testing, deployment, and quality assurance
  • 📝 Intelligent Documentation: Auto-generates and maintains project documentation
  • 🔍 Code Quality: Automated testing, linting, and security scanning
  • 🚀 Safe Deployment: Validates deployments locally and to production
  • 🧠 Memory Integration: Learns from your patterns and preferences over time

🏃 Three Essential Commands

1. push - Complete Development Pipeline

push

What it does: Runs the complete development pipeline:

  • Documentation analysis and updates
  • Comprehensive testing and quality checks
  • Git operations with semantic versioning
  • Automated changelog generation

2. deploy - Local Deployment

deploy

What it does:

  • Validates your application locally
  • Checks configuration and dependencies
  • Runs deployment health checks

3. publish - Package Publication

publish

What it does:

  • Prepares your package for publication
  • Validates package.json and metadata
  • Publishes to NPM, PyPI, or other registries

🚀 Installation Guide

Prerequisites

  • Node.js: Version 16.0.0 or higher
  • Python: Version 3.8.0 or higher
  • Git: For version control integration

Step 1: Install the Framework

# Global installation (recommended)
npm install -g @bobmatnyc/claude-multiagent-pm

# Verify installation
claude-pm --version

Step 2: Initialize Your Project

# Navigate to your project directory
cd your-project

# Initialize the framework
claude-pm init

# Start using the framework
claude-pm

Step 3: Verify Installation

# Check framework health
claude-pm health

# Run a quick test
claude-pm status

🛠️ Basic Usage

Starting the Framework

# In your project directory
claude-pm

# The framework will:
# 1. Analyze your project structure
# 2. Initialize specialized agents
# 3. Provide an interactive interface

Common Workflows

New Feature Development

# Create a feature branch
git checkout -b feature/new-feature

# Use the framework for development
claude-pm

# When ready to merge
push  # Runs complete pipeline

Bug Fix Workflow

# Create a fix branch
git checkout -b fix/bug-description

# Develop your fix with AI assistance
claude-pm

# Test and commit
push

Documentation Updates

# The framework automatically:
# - Scans your codebase for patterns
# - Updates documentation based on changes
# - Generates changelogs from commits

🤖 Complete Agent Ecosystem

The framework includes 9 specialized core agent types that work together to handle different aspects of development:

1. Documentation Agent (Documenter)

  • Purpose: Project documentation pattern analysis and operational understanding
  • Capabilities:
    • Analyzes codebase patterns and architectural decisions
    • Generates changelogs from Git commit history
    • Maintains README files and technical documentation
    • Provides operational insights for better development practices
  • Usage: Automatically activated during documentation tasks and push operations

2. Ticketing Agent (Ticketer)

  • Purpose: Universal ticketing interface and lifecycle management using ai-trackdown-tools
  • Core Tool: Uses aitrackdown (or atd) CLI for all ticketing operations
  • Capabilities:
    • Epic Management: Creates and manages high-level project epics
    • Issue Tracking: Handles issue creation, updates, and lifecycle management
    • Task Management: Manages detailed tasks and subtasks within issues
    • PR Coordination: Links pull requests to issues and tracks completion
    • Cross-Platform Integration: Native GitHub Issues sync (Linear, JIRA, Asana support coming soon)
    • GitHub Issues Sync: Automatically syncs issues created in ai-trackdown-tools to GitHub Issues
    • Hierarchical Organization: Maintains Epic → Issue → Task → PR relationships
    • Status Tracking: Real-time status updates across all ticket types and platforms
  • ai-trackdown-tools Integration: 
    # Core ticketing commands the agent uses:
aitrackdown epic create "Feature Development"
aitrackdown issue create "Implement authentication"
aitrackdown task create "Write JWT middleware"
aitrackdown pr create "Add auth middleware"
aitrackdown status                    # View all tickets
aitrackdown update ISS-001 --status "in-progress"
  • Usage: Activated when working with issues, tasks, project tracking, or any ticketing operations

3. Version Control Agent (Versioner)

  • Purpose: Git operations, branch management, and version control
  • Capabilities:
    • Manages branches, merges, and Git operations
    • Applies semantic version bumps based on commit analysis
    • Updates version files (package.json, VERSION, version.py)
    • Creates version tags with changelog annotations
  • Usage: Handles all Git-related operations and version management

4. QA Agent (QA)

  • Purpose: Quality assurance, testing, and validation
  • Capabilities:
    • Executes comprehensive test suites
    • Performs code linting and quality validation
    • Validates deployment readiness
    • Ensures code follows project standards
  • Usage: Activated during push command and quality checks

5. Research Agent (Researcher)

  • Purpose: Investigation, analysis, and information gathering
  • Capabilities:
    • Researches best practices and libraries
    • Analyzes technical documentation and APIs
    • Provides recommendations for implementation approaches
    • Gathers information for informed decision-making
  • Usage: Called when you need analysis or investigation of technologies

6. Ops Agent (Ops)

  • Purpose: Deployment, operations, and infrastructure management
  • Capabilities:
    • Handles local and production deployments
    • Manages infrastructure and environment setup
    • Performs health checks and system validation
    • Coordinates deployment pipelines
  • Usage: Activated during deploy and infrastructure operations

7. Security Agent (Security)

  • Purpose: Security analysis, vulnerability assessment, and protection
  • Capabilities:
    • Scans for security vulnerabilities and compliance issues
    • Validates dependencies for security risks
    • Performs security audits and assessments
    • Ensures secure coding practices
  • Usage: Runs security checks during quality assurance and deployment

8. Engineer Agent (Engineer)

  • Purpose: Code implementation, development, and inline documentation
  • Capabilities:
    • Writes, modifies, and implements code changes
    • Creates inline documentation and code comments
    • Implements feature requirements and bug fixes
    • Ensures code follows project conventions
  • Usage: Handles all code writing and implementation tasks

9. Data Engineer Agent (Data Engineer)

  • Purpose: Data store management and AI API integrations
  • Capabilities:
    • Manages databases, caches, and storage systems
    • Handles AI API integrations (OpenAI, Claude, etc.)
    • Designs and optimizes data pipelines
    • Manages API key rotation and data analytics
  • Usage: Activated for data operations and AI service integrations

💬 Working with Agents - Prompting Examples

How to Engage Specific Agents

The framework automatically delegates tasks to appropriate agents, but you can also explicitly request specific agent types:

Documentation Tasks

"Generate comprehensive API documentation for the authentication module"
"Update the README with the new deployment process"
"Create a changelog entry for the latest features"

Ticketing and Project Management

"Create an epic for the user authentication feature"
"Break down the authentication epic into issues and tasks"
"Update the status of issue ISS-001 to in-progress"
"Create a PR linked to issue ISS-001"
"Show me the current status of all tickets"
"Create a task for implementing JWT middleware under the auth issue"
"Sync the authentication issues to GitHub Issues"
"Set up GitHub Issues synchronization for this project"

Code Implementation

"Implement a JWT authentication system with refresh tokens"
"Create a React component for user profile management"
"Add error handling to the payment processing service"

Quality Assurance

"Run comprehensive tests and fix any failures"
"Perform security audit on the authentication system"
"Validate the deployment configuration"

Research and Analysis

"Research best practices for microservices architecture"
"Analyze the performance implications of this database design"
"Compare different authentication libraries for Node.js"

DevOps and Deployment

"Deploy the application to staging environment"
"Set up health monitoring for the API service"
"Configure CI/CD pipeline for automated testing"

Advanced Prompting Techniques

Multi-Agent Coordination

"Work with the QA agent to implement comprehensive testing for the new feature I'm about to build with the Engineer agent"

"Have the Research agent investigate GraphQL best practices, then have the Engineer agent implement those patterns"

"Coordinate with the Security agent to audit the authentication system while the Ops agent prepares the deployment"

Ticketing-Driven Development with ai-trackdown-tools

"Create an epic for the payment processing feature, then break it down into issues and tasks using the Ticketing agent"

"Use the Ticketing agent to track the current sprint progress and update ticket statuses as the Engineer agent completes tasks"

"Coordinate with the Ticketing agent to create a PR for the completed authentication task, then have the QA agent validate it"

"Show me the ticketing hierarchy for the user management epic and create any missing tasks"

Context-Aware Requests

"Based on the current project patterns, implement a user management system that follows our established architectural conventions"

"Using the team's coding standards stored in memory, refactor the payment processing module"

"Analyze the recent deployment issues and implement preventive measures"

Agent Interaction Patterns

The framework uses intelligent delegation patterns:

  • Automatic Agent Selection: The framework chooses the most appropriate agent based on your request
  • Multi-Agent Workflows: Complex tasks automatically involve multiple agents in sequence
  • Context Sharing: Agents share relevant context and learnings across sessions
  • Memory Integration: Agents remember your preferences and project patterns

Complete Ticketing Workflow with ai-trackdown-tools

The Ticketing Agent provides a comprehensive workflow using ai-trackdown-tools:

1. Epic Creation and Planning

"Create a new epic for implementing user authentication system"
# Agent executes: aitrackdown epic create "User Authentication System"
# Result: Epic created with ID EPK-001

2. Issue Breakdown

"Break down the authentication epic into specific issues"
# Agent executes: 
# aitrackdown issue create "Design authentication schema" --epic EPK-001
# aitrackdown issue create "Implement JWT middleware" --epic EPK-001
# aitrackdown issue create "Add user registration endpoint" --epic EPK-001

3. Task Management

"Create detailed tasks for the JWT middleware issue"
# Agent executes:
# aitrackdown task create "Research JWT libraries" --issue ISS-001
# aitrackdown task create "Write JWT token generation" --issue ISS-001
# aitrackdown task create "Add token validation middleware" --issue ISS-001

4. Development Workflow Integration

"Update task TSK-001 to in-progress and start development"
# Agent executes: aitrackdown update TSK-001 --status "in-progress"
# Then coordinates with Engineer agent for implementation

5. PR Creation and Tracking

"Create a PR for the completed JWT middleware task"
# Agent executes: aitrackdown pr create "Implement JWT middleware" --task TSK-001
# Links PR to task and updates status automatically

6. GitHub Issues Synchronization

"Sync the authentication issues to GitHub Issues"
# Agent executes: aitrackdown sync --platform github --filter "authentication"
# Automatically creates corresponding GitHub Issues with proper links

7. Status Monitoring

"Show me the current status of all authentication-related tickets"
# Agent executes: aitrackdown status --filter "authentication"
# Displays hierarchical view: Epic → Issues → Tasks → PRs
# Shows both local and GitHub Issue status

This integration ensures that all development work is properly tracked, organized, and linked through the hierarchical Epic → Issue → Task → PR structure that ai-trackdown-tools provides. GitHub Issues synchronization keeps your team aligned by automatically creating corresponding GitHub Issues for seamless integration with your existing workflow.

Platform Support Roadmap

  • ✅ GitHub Issues: Full synchronization available now
  • 🔄 Linear: Coming soon
  • 🔄 JIRA: Coming soon
  • 🔄 Asana: Coming soon

📁 Project Structure

The framework works with any project structure but creates these directories:

your-project/
├── .claude-pm/           # Framework configuration
├── docs/                 # Documentation (auto-generated)
├── src/                  # Your source code
└── README.md             # Project documentation

# Framework files (in parent directory)
../
├── CLAUDE.md             # 🚨 FRAMEWORK FILE - AUTO-GENERATED
└── framework/            # Framework deployment files

Key Files and Directories

CLAUDE.md (Framework File)

⚠️ IMPORTANT: This file is located in the parent directory of your project, not in the project itself.

  • Location: ../CLAUDE.md (one level up from your project)
  • Purpose: Contains framework configuration and agent instructions
  • Management: AUTOMATICALLY GENERATED - Do not edit by hand
  • Updates: The framework updates this file automatically during initialization and operations
  • Scope: Applies to all projects under the parent directory

Why it's in the parent directory:

  • Allows the framework to manage multiple projects consistently
  • Provides shared configuration across related projects
  • Enables the framework to coordinate cross-project operations
  • Maintains version control and automatic updates

.claude-pm/ (Project Configuration)

Framework configuration directory containing:

  • Agent configurations: Project-specific agent settings
  • Project settings: Local project preferences and overrides
  • Cached data and memories: Performance optimization and learning data
  • Session state: Current working state and context

Project-Specific Customization

While CLAUDE.md is auto-generated, you can create project-specific configuration:

your-project/
├── .claude-pm/
│   ├── project-config.json    # Project-specific settings
│   ├── agent-overrides.yaml   # Custom agent configurations
│   └── local-preferences.json # Your personal preferences

Example project-config.json:

{
  "project_name": "my-web-app",
  "primary_language": "typescript",
  "framework": "react",
  "testing_framework": "jest",
  "coding_standards": "eslint-airbnb",
  "deployment_target": "vercel"
}

This local configuration works alongside the framework's auto-generated CLAUDE.md to provide project-specific customization without interfering with the framework's operation.

🔧 Configuration

Basic Configuration

The framework works out-of-the-box with sensible defaults. The main framework configuration is automatically managed:

# View current configuration
claude-pm config show

# Initialize framework configuration
claude-pm init

# Check framework status
claude-pm status

Project-Specific Configuration

For custom project settings, create local configuration files:

# Create project-specific settings
mkdir -p .claude-pm
cat > .claude-pm/project-config.json << 'EOF'
{
  "project_name": "my-project",
  "primary_language": "javascript",
  "framework": "express",
  "testing_framework": "mocha",
  "coding_standards": "standard"
}
EOF

⚠️ Framework Configuration Warning

Never edit ../CLAUDE.md directly - it's automatically generated and will be overwritten. Instead:

  • Use .claude-pm/project-config.json for project-specific settings
  • Use .claude-pm/agent-overrides.yaml for custom agent behavior
  • Use .claude-pm/local-preferences.json for personal preferences

Environment Variables

# Optional: Set custom configuration
export CLAUDE_PM_HOME=~/claude-pm
export CLAUDE_PM_LOG_LEVEL=info

🎭 Use Cases

1. New Project Setup

# Create a new project
mkdir my-new-project
cd my-new-project

# Initialize with framework
claude-pm init --setup

# Start development
claude-pm

2. Existing Project Integration

# Navigate to existing project
cd existing-project

# Initialize framework (non-destructive)
claude-pm init

# Framework adapts to your existing structure
claude-pm

3. Team Development

# Each team member installs globally
npm install -g @bobmatnyc/claude-multiagent-pm

# Framework maintains consistency across team
# Shared configuration in CLAUDE.md

4. Monorepo Management

# Framework automatically detects monorepo structure
# Handles workspace dependencies
# Coordinates testing across packages

🔍 Common Commands

Status and Health

claude-pm status          # Current project status
claude-pm health          # Framework health check
claude-pm --version       # Version information

Project Operations

claude-pm init            # Initialize project
claude-pm config          # Show configuration
claude-pm agents          # List available agents

Development Workflow

push                      # Complete development pipeline
deploy                    # Local deployment
publish                   # Package publication

🚨 Troubleshooting

Common Issues

"Command not found"

# Check if installed globally
npm list -g @bobmatnyc/claude-multiagent-pm

# Reinstall if needed
npm install -g @bobmatnyc/claude-multiagent-pm

Permission Errors

# Fix npm permissions
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

Python Issues

# Check Python version
python3 --version

# Install Python if needed (macOS)
brew install python3

Getting Help

# Built-in help
claude-pm --help

# Command-specific help
claude-pm init --help

📚 Next Steps

Learn More

  1. Explore Commands: Try different commands to understand the framework
  2. Read Documentation: Check the generated docs in your project
  3. Customize Settings: Create .claude-pm/project-config.json for your project needs

Advanced Features

  • Memory Integration: Framework learns from your patterns
  • Custom Agents: Create project-specific agents
  • Multi-project Management: Manage multiple projects simultaneously

Best Practices

  • Feature Branches: Always use feature branches for development
  • Regular Pushes: Use push command regularly for quality assurance
  • Documentation: Let the framework maintain your documentation
  • Testing: Rely on automated testing through the QA agent

🤝 Community & Support

Resources

  • GitHub: claude-multiagent-pm
  • Issues: Report bugs and request features
  • Documentation: Find detailed guides in the repository

Contributing

  • Fork the repository
  • Create feature branches
  • Submit pull requests
  • Help improve documentation

🎉 You're Ready!

You now have a powerful AI-driven development framework at your fingertips. The framework will:

✅ Learn your patterns and adapt to your workflow
✅ Maintain quality through automated testing and reviews
✅ Handle deployment safely and efficiently
✅ Generate documentation automatically
✅ Coordinate agents for complex development tasks

Start with a simple project and let the framework guide you through the development process!

Framework Version: 0.8.6
Last Updated: 2025-07-15
Installation Success Rate: 98%+ across all platforms