Forge bridges the gap between product vision and engineering execution. PMs create tickets in the web app. Developers review and build from the CLI. Both sides agree on a verified contract before code is written.

Installation

npm i forge-aec

Requires Node.js 20+.

Quick Start

forge login                  # Authenticate via browser (auto-registers MCP)
forge tickets                # Browse your tickets
forge show <id>              # View ticket details
forge review <id>            # Review a spec — add your codebase knowledge
forge develop <id>           # Start AI-assisted implementation
forge develop <id> -y        # Same, but skip all Claude permission prompts

How It Works — The PM + Developer Flow

Forge is a team tool. The PM defines what to build. The developer adds the technical reality. Together, they produce a verified contract called an Agent Execution Contract (AEC).

PM creates ticket in web app
  "Users should be able to filter by tags"
        │
        ▼
Forge reads the codebase + asks clarification questions
  PM answers in plain language
        │
        ▼
Spec is generated
  Acceptance criteria, file changes, API contracts, wireframes
        │
        ▼
Developer reviews via CLI (forge review)
  Adds technical context:
  "Use the existing Zustand store pattern"
  "Filter server-side for performance"
  "Reuse the TagBadge component"
        │
        ▼
PM reads developer feedback, re-bakes the spec, approves
  Both sides agreed. Contract is locked.
        │
        ▼
Developer implements (forge develop)
  AI agent receives the full contract — builds the right thing, first time.
        │
        ▼
Developer marks complete
  Ticket is done.

Ticket Lifecycle

Every ticket follows a structured flow. The CLI shows you where each ticket is:

| Status | Label | Who acts | What happens | |--------|-------|----------|--------------| | draft | Define | PM (web) | PM creates the ticket, answers AI questions, spec is generated | | dev-refining | Dev-Refine | Developer (CLI) | Developer runs forge review — adds codebase context and technical knowledge | | review | Review | PM (web) | PM reads developer feedback, re-bakes the spec, approves | | forged | Ready | — | Contract is locked. Quality score 75+. Ready for implementation. | | executing | Executing | Developer (CLI) | Developer runs forge develop — AI agent implements with full context | | complete | Done | — | Implementation is complete |

Dev-Refine and Review are optional — a PM can create and approve tickets without developer review. But the best specs come from collaboration.

The Developer's Role

As a developer, you bring the technical reality that PMs can't provide:

1. Review a ticket

forge review <id>

The AI asks you targeted questions about implementation:

• "Which existing components should be reused?"
• "What's the best approach for state management here?"
• "Are there edge cases the PM might not know about?"

Your answers are sent back to the PM and baked into the spec. This is where specs go from "good" to "great."

2. Implement a ticket

forge develop <id>
forge develop <id> --yolo   # skip Claude permission prompts (-y for short)

This launches an AI-assisted implementation session:

• The AI agent receives the full AEC — acceptance criteria, file changes, architecture decisions
• A branch is created automatically (forge/<id>-<slug>)
• The agent knows exactly which files to touch and what "done" looks like
• No guessing. No Slack threads. Just build.

3. Mark it done

The ticket transitions to Done via the MCP tool update_ticket_status or from the web app.

What's in an AEC?

The spec your PM and AI generate isn't a vague description — it's a structured contract:

✓ Problem statement with context and constraints
✓ Acceptance criteria: Given/When/Then (directly testable)
✓ File changes: TicketGrid.tsx (modify), tags.store.ts (create)
✓ API contracts: GET /api/tickets?tags=urgent → filtered results
✓ Scope: In (tag filtering, multi-select) / Out (tag management admin)
✓ Quality score: 87/100
✓ HTML wireframe of the proposed UI
✓ Test plan with specific scenarios

Every file path references your real codebase. Every acceptance criterion is testable. The scope boundaries prevent "can you also add..." surprises.

MCP Server (Claude Code / Cursor / Windsurf)

Forge ships an embedded MCP server that gives AI coding tools direct access to your tickets.

Setup

forge login automatically registers the MCP server with Claude Code — no extra steps:

forge login                  # Authenticate + auto-registers MCP

Restart Claude Code after logging in. If auto-registration didn't work:

forge mcp install            # Manual registration

Slash Commands in Claude Code

/forge:tickets               # Browse all tickets
/forge:develop <id>          # Start AI-assisted implementation
/forge:review <id>           # Review a ticket

These give Claude full context — tech spec, acceptance criteria, file changes, review answers — so it can implement without you copy-pasting anything.

MCP Tools

| Tool | What it does | |------|-------------| | get_ticket_context | Full ticket spec, acceptance criteria, review Q&A | | get_file_changes | Exact files to create, modify, or delete | | get_repository_context | Git metadata and file tree from your working directory | | update_ticket_status | Transition ticket status (e.g., mark as complete) | | submit_review_session | Save developer review Q&A | | start_implementation | Begin implementation — creates branch, sets status to Executing | | list_tickets | List your team's tickets with status and priority |

Flexible Configurations

Forge adapts to your team's constraints:

| Configuration | Codebase connected | Developer review | AI agent | Best for | |---|---|---|---|---| | Full lifecycle | Yes | Yes | Yes | Maximum spec quality + AI implementation | | No agent | Yes | Yes | No | Verified specs, manual implementation | | No codebase | No | Yes | No | Security-restricted teams (no GitHub access) | | PM only | Optional | No | No | Solo PMs, quick drafts |

Even without a codebase connection, the developer review step adds the file-level context manually. The protocol still works.

All Commands

| Command | Description | |---------|-------------| | forge login | Authenticate via browser + register MCP server | | forge logout | Clear stored credentials | | forge whoami | Check your identity and token status | | forge tickets | Browse your team's tickets | | forge show <id> | View full ticket details and spec | | forge review <id> | Review a ticket — answer AI questions with your codebase knowledge | | forge review <id> --yolo | Review without Claude permission prompts (-y shorthand) | | forge develop <id> | Start AI-assisted implementation via MCP | | forge develop <id> --yolo | Implement without Claude permission prompts (-y shorthand) | | forge mcp install | Manually register MCP server with Claude Code | | forge doctor | Run diagnostics — checks config, auth, API, MCP setup |

Updating

npm update -g forge-aec

Configuration

Credentials are stored securely in ~/.forge/config.json with restricted file permissions. Tokens refresh automatically.

Security

• Encrypted credentials with owner-only file permissions, auto-refresh, never logged
• HTTPS only for all communication
• Filesystem isolation — MCP only reads git metadata from the current working directory
• Prompt injection protection — ticket content is sandboxed and separated from system instructions
• Short-lived auth codes — device login codes are single-use and expire quickly
• Team-scoped access — only authenticated team members can view or modify tickets

Learn More

• Documentation — full guides for PMs and developers
• Web App — where PMs create and manage tickets
• Team Workflows — how to configure Forge for your team

License

MIT