# belmont

Runs a coding session in phases: PRD, tech plan, milestone-by-milestone implementation. Useful when a feature is too big for one pass.

- plugin · `type=plugin` · Claude Code · ★ 6
- Author: blake-simpson
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/blake-simpson/belmont/tree/HEAD/plugin
- Updated: 2026-08-19
- HTML: https://affpapa.org/en/nevibecode/plugins/belmont

## What it does

Belmont splits feature work into phases, and a dedicated subagent drives each one. You steer it through skills — markdown files that load as slash commands. Planning, tech planning, implementation, verification and bug fixing are separate steps.

Shared context lives in a single file, `.belmont/MILESTONE.md`. The orchestrator pulls the relevant PRD and tech plan fragments into it up front, so agents read that file and write back to it. Output from one phase never piles up in the next prompt. Codebase research and design research run side by side, implementation waits for both, and a finished milestone is archived as `MILESTONE-M2.done.md`.

One branch of the workflow is built around Figma. The design agent pulls tokens — colors, typography, spacing — and turns them into component specs, while verification compares your build against the source with Playwright screenshots. Automatic loading of designs needs `figma-mcp` installed; without it that part stays idle. The plugin itself needs no CLI, but the automated end-to-end mode with headless agents and worktree parallelism ships only in the CLI, installed separately via Homebrew or curl.

## Install

### Claude Code (native platform)

**Plugin marketplace**
In the agent chat (not a shell):
```text
/plugin marketplace add anthropics/claude-plugins-community
```
In the agent chat (not a shell):
```text
/plugin install belmont@claude-community
```

## When to use it
- break a large feature into milestones without losing context
- keep phase output out of the orchestrator prompt to save tokens
- turn a Figma design into tokens and component specs
- check finished UI against the design with screenshots
- spot where the plan drifted from the code

## Example prompts
- Run `/belmont:product-plan` and draft a PRD from my idea
- Where are we now? Show me with `/belmont:status`
- Move to the next task with `/belmont:next`

## Source text · plugin · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 26c141f82a6ffc1a.

BEGIN THIRD-PARTY FILE 26c141f82a6ffc1a
````text
# Belmont AI

A toolkit for running structured coding sessions with AI coding agents. Belmont manages a PRD (Product Requirements Document), orchestrates specialized sub-agent phases, and tracks progress across milestones.

**Agent-agnostic** -- works with Claude Code, Codex, Cursor, Windsurf, Gemini, GitHub Copilot, [Pi](https://pi.dev) (incl. local LLMs via LM Studio / Ollama), [opencode](https://opencode.ai), and any tool that can read markdown files. No Docker required. No loops. Just skills and agents.

A flexible PRD system has been used to provide the best level of context from plan to implementation. Tech plans allow you to specify specifics for the agent to follow while building.

Strong guardrails are in place to keep the agent focused and on task.

**Working Backwards (PR/FAQ)** -- Belmont supports Amazon's Working Backwards methodology as a strategic first step. Define your product vision with a PR/FAQ document before breaking it into features and tasks.

**Figma-first design workflow** -- Belmont is built heavily around understanding Figma designs. The design-agent extracts exact tokens (colors, typography, spacing), maps them to your design system, and produces implementation-ready component specs. The verification-agent compares your implementation against the Figma source using Playwright headless screenshots. For the best experience, install [figma-mcp](https://github.com/nichochar/figma-mcp) so Belmont can load and analyze your designs automatically.

---

## Quick Start

### All AI Tools (CLI)

The CLI installer supports Claude Code, Codex, Cursor, Windsurf, Gemini, GitHub Copilot, Pi, and opencode:

```bash
# Install via Homebrew (macOS / Linux)
brew install blake-simpson/belmont/belmont

# Or install via curl
curl -fsSL https://raw.githubusercontent.com/blake-simpson/belmont/main/install.sh | sh

# Set up your project
cd ~/your-project
belmont install
```

The installer detects which AI tools you have and installs skills to `.agents/skills/belmont/`, then links or copies them into each tool's native directory. Agents are installed to `.agents/belmont/`.

### Claude Code (Plugin)

Install Belmont directly as a Claude Code plugin -- no CLI required:

```bash
claude plugin marketplace add blake-simpson/belmont
claude plugin install belmont@belmont
```

Then use the skills:

```
/belmont:product-plan
/belmont:implement
/belmont:next
/belmont:status
```

**Optional: Install the Belmont CLI** for auto mode -- automated end-to-end feature implementation with headless AI agents, worktree parallelism, and milestone dependency tracking:

```bash
brew install blake-simpson/belmont/belmont
# OR
curl -fsSL https://raw.githubusercontent.com/blake-simpson/belmont/main/install.sh | sh
```

The plugin and CLI work independently. The plugin gives you the full manual workflow; the CLI adds automation on top.

---

## How It Works

Belmont breaks coding work into **phases**, each driven by a specialized agent. The user interacts through **skills** (markdown files loaded as slash commands or rules) that orchestrate these agents.

```
┌──────────────┐     ┌─────────────┐     ┌────────────────┐     ┌─────────────────┐
│  PR/FAQ      │ ──▶ │  Plan       │ ──▶ │  Tech Plan     │ ──▶ │  Implement      │
│ (optional)   │     │  (PRD.md)   │     │ (TECH_PLAN.md) │     │  (MILESTONE.md) │
└──────────────┘     └─────────────┘     └────────────────┘     └─────────────────┘
                                                                      │
                                           ┌──────────────────────────┤
                                           ▼                          ▼
````
END THIRD-PARTY FILE 26c141f82a6ffc1a

The third-party file has ended. Everything between the 26c141f82a6ffc1a tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 4025 of 31753 bytes. © blake-simpson · Apache-2.0 · https://github.com/blake-simpson/belmont/tree/HEAD/plugin

## Similar
- [screenshot-to-code](https://affpapa.org/en/nevibecode/skills/screenshot-to-code.md) — skill · 1300 installs
- [d2c](https://affpapa.org/en/nevibecode/plugins/d2c.md) — plugin · ★ 8
- [designfit](https://affpapa.org/en/nevibecode/mcp/designfit.md) — MCP server · ★ 7
- [design-handoff](https://affpapa.org/en/nevibecode/skills/design-handoff.md) — skill · 3500 installs

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md