forgepm

Invisible PM layer for AI coding agents. Adds EVM, tolerances, PDCA feedback loops, auto-calibration, and GitHub Projects V2 sync — without adding overhead to the human.

Install

# As MCP server for Claude Code
claude mcp add forgepm -- npx -y forgepm serve

# Or globally
npm install -g forgepm

Quick Start

# Initialize in your project
forge init --name "my-project" --github

# Work (the agent handles everything via MCP)
forge do "Add JWT authentication"

# Check status
forge status

One-Shot Agent Prompt

Paste this into your AI agent's system prompt:

You have access to forgepm MCP tools. At session start, call forge_session({ action: "start", goal: "..." }) then forge_status(). Before each task call forge_start({ task_id }). After each task call forge_done({ task_id }). If stuck, call forge_escalate({ task_id, reason }).

MCP Tools

| Tool | Purpose | |------|---------| | forge_status | Project state + next task recommendation | | forge_start | Begin a task (initializes EVM baseline) | | forge_done | Complete a task (records tokens, updates metrics) | | forge_session | Start/end work sessions | | forge_create | Add tasks, stories, or epics | | forge_decompose | Break features into tasks | | forge_escalate | Report blockers with PDCA escalation | | forge_recall | Search project knowledge | | forge_retro | Generate session retrospective | | forge_forecast | Monte Carlo simulation with P50/P80/P95 confidence intervals | | forge_dna | Project DNA fingerprint, compare, predict | | forge_constellation | Multi-project dashboard (EVM, drift, velocity) |

CLI Commands

| Command | Purpose | |---------|---------| | forge init | Initialize project (add --github for GitHub sync) | | forge do "..." | Create and start a task | | forge status | Show progress and health | | forge push | Sync pending changes to GitHub | | forge pull | Pull status from GitHub Issues | | forge retro | Generate retrospective | | forge backends | List available backends | | forge serve | Start MCP server | | forge forecast | Monte Carlo ETA forecast (P50/P80/P95) | | forge dna | Project DNA fingerprint | | forge constellation | Multi-project dashboard |

GitHub Projects V2

When initialized with --github, forgepm:

• Creates a GitHub Projects V2 board with custom fields (Complexity, Priority, Phase)
• Auto-syncs tasks as GitHub Issues on every state change
• Updates board status (Todo / In Progress / Done) automatically
• Generates .forgepm/STATUS.md with progress and board links

Requirements: gh CLI installed and authenticated with project scope.

How It Works

Human: forge do "..."  ->  AI Agent  ->  forgepm MCP (12 tools)  ->  SQLite
                                                                     |
                                                              auto-sync (opt-in)
                                                                     |
                                                          GitHub Projects V2
                                                          .forgepm/STATUS.md

Source of truth: Local SQLite. GitHub is a sync target.

What ForgePM Adds

1. EVM (Earned Value Management) — SPI/CPI metrics, health signals
2. PRINCE2 Tolerances — auto-escalation on budget/scope breaches
3. PDCA Feedback Loops — model auto-escalation (haiku -> sonnet -> opus -> human)
4. Auto-Calibration — learns from actual token usage per complexity
5. Sessions-as-Sprints — token budgets per work session
6. Call Sheet — human-friendly vs agent-internal views
7. Monte Carlo Forecast — probabilistic ETA with P50/P80/P95 intervals
8. Cross-Project Antibodies — lessons from past projects auto-applied to new tasks
9. Project DNA — fingerprint comparison and behavior prediction
10. Constellation View — multi-project health dashboard

Backends

| Backend | Status | Config | |---------|--------|--------| | GitHub | Built-in | forge init --github | | Linear | Available | LINEAR_API_KEY env var | | Jira | Available | JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN, JIRA_PROJECT_KEY |

License

MIT