project-manager

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: project-manager
description: Meta-orchestration agent that manages high-volume development workflows by spawning and coordinating parallel Claude Code CLI sessions using Git Worktrees for isolation. Use when executing multiple development tasks autonomously with 3 concurrent workers.
---

# Project Manager Skill ("The Architect")

## Overview

The Project Manager is a **Meta-Agent** that orchestrates up to 3 parallel Claude Code CLI sessions ("Workers") to execute development tasks autonomously. It uses:

- **Git Worktrees** for environment isolation (no file conflicts)
- **Affinity Scheduling** to minimize context switching
- **Greenfield/Brownfield** strategies for optimal prompting
- **Autonomous execution** with no human-in-the-loop for sub-processes

Target throughput: **15 tasks/day**

## When to Use

- Executing multiple development tasks in parallel
- Batch processing of backlog items (bugs, features, refactors)
- Large-scale refactoring across multiple domains
- Automated code generation campaigns

## Quick Start

```bash
# Invoke the skill
/project-manager

# Or with initial tasks
/project-manager --tasks "Add auth middleware" "Fix pagination bug" "Refactor user model"
```

## Key Commands

### Start Orchestration
```bash
# Start with default settings (3 workers)
python .claude/skills/project-manager/scripts/orchestrate.py start

# Start with custom worker count
python .claude/skills/project-manager/scripts/orchestrate.py start --workers 2
```

### Monitor Status
```bash
# View real-time status
python .claude/skills/project-manager/scripts/orchestrate.py status

# View metrics dashboard
python .claude/skills/project-manager/scripts/metrics.py dashboard
```

### Kill Switch (Emergency Stop)
```bash
# Graceful shutdown - saves state and terminates all workers
python .claude/skills/project-manager/scripts/orchestrate.py kill

# Force kill (immediate, still saves state)
python .claude/skills/project-manager/scripts/orchestrate.py kill --force
```

### Manage Tasks
```bash
# Add tasks to backlog
python .claude/skills/project-manager/scripts/state_manager.py add-task \
    --title "Add user authentication" \
    --domain "auth" \
    --type "feature"

# List all tasks
python .claude/skills/project-manager/scripts/state_manager.py list

# Move task status
python .claude/skills/project-manager/scripts/state_manager.py update-task \
    --id 3 --status DONE
```

## Architecture

### Components

| Component | File | Role |
|-----------|------|------|
| Orchestrator | `orchestrate.py` | "The Boss" - manages workers and worktrees |
| Scheduler | `scheduler.py` | "Traffic Controller" - affinity-based task assignment |
| Context Curator | `context_curator.py` | "Briefing Officer" - generates prompts |
| State Manager | `state_manager.py` | "The Scribe" - JSON/MD sync |
| Metrics | `metrics.py` | Performance tracking and reporting |

### Directory Structure
```
project-manager/
├── SKILL.md                  # This file
├── KANBAN_BOARD.md           # Human-readable task board
├── kanban_state.json         # Machine-readable state
├── learned_context.md        # Shared learnings
├── scripts/
│   ├── orchestrate.py        # Main orchestrator
│   ├── scheduler.py          # Affinity scheduling
│   ├── context_curator.py    # Prompt generation
│   ├── state_manager.py      # State management
│   ├── metrics.py            # Performance metrics
│   └── setup_worktrees.sh    # Git worktree setup
├── templates/
│   ├── task_greenfield.j2    # New feature template
│   └── task_brownfield.j2    # Maintenance template
└── memory/
    ├── learned_context.md
    └── logs/
```

## Task Workflow

### States
```
TODO → IN_PROGRESS → REVIEW → DONE
         ↓
      FAILED (retry_count > 3 → escalate)
```

### Affinity Scheduling

Tasks are tagged with:
- **domain**: `auth`, `api`, `frontend`, `database`, `infra`, etc.
- **type**: `feature`, `bugfix`, `refactor`, `test`, `docs`

Workers maintain "sticky" domain affinity - a worker that just