{
  "markdown": "# Belmont AI\n\nA 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.\n\n**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.\n\nA 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.\n\nStrong guardrails are in place to keep the agent focused and on task.\n\n**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.\n\n**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.\n\n---\n\n## Quick Start\n\n### All AI Tools (CLI)\n\nThe CLI installer supports Claude Code, Codex, Cursor, Windsurf, Gemini, GitHub Copilot, Pi, and opencode:\n\n```bash\n# Install via Homebrew (macOS / Linux)\nbrew install blake-simpson/belmont/belmont\n\n# Or install via curl\ncurl -fsSL https://raw.githubusercontent.com/blake-simpson/belmont/main/install.sh | sh\n\n# Set up your project\ncd ~/your-project\nbelmont install\n```\n\nThe 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/`.\n\n### Claude Code (Plugin)\n\nInstall Belmont directly as a Claude Code plugin -- no CLI required:\n\n```bash\nclaude plugin marketplace add blake-simpson/belmont\nclaude plugin install belmont@belmont\n```\n\nThen use the skills:\n\n```\n/belmont:product-plan\n/belmont:implement\n/belmont:next\n/belmont:status\n```\n\n**Optional: Install the Belmont CLI** for auto mode -- automated end-to-end feature implementation with headless AI agents, worktree parallelism, and milestone dependency tracking:\n\n```bash\nbrew install blake-simpson/belmont/belmont\n# OR\ncurl -fsSL https://raw.githubusercontent.com/blake-simpson/belmont/main/install.sh | sh\n```\n\nThe plugin and CLI work independently. The plugin gives you the full manual workflow; the CLI adds automation on top.\n\n---\n\n## How It Works\n\nBelmont 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.\n\n```\n┌──────────────┐     ┌─────────────┐     ┌────────────────┐     ┌─────────────────┐\n│  PR/FAQ      │ ──▶ │  Plan       │ ──▶ │  Tech Plan     │ ──▶ │  Implement      │\n│ (optional)   │     │  (PRD.md)   │     │ (TECH_PLAN.md) │     │  (MILESTONE.md) │\n└──────────────┘     └─────────────┘     └────────────────┘     └─────────────────┘\n                                                                      │\n                                           ┌──────────────────────────┤\n                                           ▼                          ▼\n                                      ┌───────────┐           ┌────────────┐\n                                      │  Verify   │           │  Status    │\n                                      │ (parallel)│           │ (read-only)│\n                                      └─────┬─────┘           └────────────┘\n                                            │\n                         ┌──────────────────┼──────────────┐\n                         ▼                  ▼              ▼\n                   ┌───────────┐     ┌───────────┐  ┌───────────┐\n                   │  Debug    │     │  Next     │  │Plan Review│\n                   │ (fix bug) │     │ (1 task)  │  │ (drift)   │\n                   └───────────┘     └───────────┘  └─────┬─────┘\n                                                          │\n                                                          ▼\n                                                   Updates PRDs,\n                                                   Tech Plans,\n                                                   PROGRESS\n```\n\n### MILESTONE File Architecture\n\nBelmont uses a **MILESTONE file** (`.belmont/MILESTONE.md`) as the shared context between agents. Instead of the orchestrator passing large outputs between agents in their prompts, each agent reads from and writes to this single file. This dramatically reduces token usage and keeps each agent focused.\n\n```\nOrchestrator\n    │\n    ├─ 1. Creates MILESTONE.md with task list, PRD context & TECH_PLAN context\n    │\n    ├─ 2. Research phases (parallel — both run simultaneously):\n    │     ├─ codebase-agent ─── reads MILESTONE.md + codebase ── writes Codebase Analysis section\n    │     └─ design-agent ───── reads MILESTONE.md + Figma ──── writes Design Specifications section\n    │\n    ├─ 3. Spawns implementation-agent ── reads MILESTONE.md ── writes code + Implementation Log\n    │\n    └─ 4. Archives MILESTONE.md → MILESTONE-M2.done.md\n```\n\nEach agent reads **only the MILESTONE file** — the orchestrator extracts all relevant PRD and TECH_PLAN context into it upfront. Agents receive a minimal prompt (just identity + \"read the MILESTONE file\"). The orchestrator's context stays flat — it never accumulates the massive outputs from each phase. This helps save tokens & prevent hallucinations.\n\n> **Token-saving companion**: Belmont's agents are heavy consumers of command output (test runs, lints, git, file reads). Pairing Belmont with [RTK](https://www.rtk-ai.app/) (Rust Token Killer, `brew install rtk`) — a hook-based CLI proxy that filters command output before it reaches the model — typically halves tool-I/O input tokens (50–90% on test/lint output) with zero workflow change. This is the right lever for cutting token spend: trim the input side rather than downgrading agent models, since a cheaper model that fails a milestone re-runs the entire pipeline and costs more than it saves.\n\n### Implementation Pipeline\n\nWhen you run the implement skill, the orchestrator creates a MILESTONE file, then dispatches 3 phases. Phases 1 and 2 run in parallel, Phase 3 runs after both complete:\n\n| Phase              | Agent                  | Model* | Reads                | Writes to MILESTONE                                  |\n|--------------------|------------------------|--------|----------------------|------------------------------------------------------|\n| 1. Codebase Scan   | `codebase-agent`       | Session | MILESTONE + codebase | `## Codebase Analysis`                               |\n| 2. Design Analysis | `design-agent`         | Session | MILESTONE + Figma    | `## Design Specifications`                           |\n| 3. Implementation  | `implementation-agent` | Session | MILESTONE (only)     | Code, unit tests, E2E tests, `## Implementation Log` |\n\n\\* Agents pin no model — each sub-agent inherits your **session model** by default (run Belmont on a strong model and the whole pipeline follows). Set per-feature tiers in `.belmont/features/<slug>/models.yaml` to pin specific models per agent — see [Per-feature model tiers](docs/workflow.md). When choosing tiers, optimize for first-pass correctness: a failed milestone re-runs the whole pipeline, which costs far more tokens than a premium tier saves.\n\nAfter implementation, the MILESTONE file is archived (renamed to `MILESTONE-[ID].done.md`) to prevent stale context from bleeding into the next milestone.\n\n### Verification Pipeline\n\nWhen you run the verify skill, two agents run:\n\n| Agent                | Model* | What It Does                                                                                                   |\n|----------------------|--------|----------------------------------------------------------------------------------------------------------------|\n| `verification-agent` | Session | Checks acceptance criteria, visual Figma comparison via Playwright headless, i18n keys                         |\n| `code-review-agent`  | Session | Runs build, test, and E2E test commands (auto-detects package manager), reviews code quality and PRD alignment |\n\n\\* Inherits your session model; pin per feature via `models.yaml`. A verification false-pass is the most expensive mistake in the pipeline (it surfaces later as a debug loop), so set verification `high` when you configure tiers.\n\nBoth agents read the PRD, TECH_PLAN, and archived MILESTONE files for full context. Any issues found become follow-up tasks (plain `[ ]` entries) added to PROGRESS.md.\n\n---\n\n## Implementation Pipeline\n\nResearch phases 1–2 (codebase scan + design analysis) are fully independent — they each read from the `## Orchestrator Context` section of the MILESTONE file and write to their own designated section (`## Codebase Analysis`, `## Design Specifications`). This makes them safe to run in parallel with no conflicts. Phase 3 (implementation) always runs after both research phases complete.\n\n```\n                        ┌──────────────────┐\n                        │   Orchestrator   │\n                        └────────┬─────────┘\n                                 │\n              ┌──────────────────┴───────────────────┐\n              ▼                                      ▼\n     ┌────────────────┐                    ┌─────────────────┐\n     │   Codebase     │                    │  Design Analyst │\n     │   Analyst      │                    │                 │\n     └────────┬───────┘                    └────────┬────────┘\n              │                                     │\n              └────────── MILESTONE file ───────────┘\n                          (shared context)\n                                 │\n                                 ▼\n                    ┌─────────────────────┐\n                    │  Implementation     │\n                    │  Agent (Sub-agent)  │\n                    └─────────────────────┘\n```\n\n---\n\n## Sub-Agent Dispatch\n\nBelmont's orchestrator skills (`implement`, `verify`, `next`, `debug-auto`, `debug-manual`) run every phase as a **sub-agent** — its own context window, running one agent's instructions and returning when done. That is what stops a long `implement` run from spending the orchestrator's context on five phases at once, and it is where the per-agent model tiers in `models.yaml` are applied.\n\nEach skill checks its available tools **by name** and takes the first approach that works, then says which one it took:\n\n- **Approach A — parallel sub-agent dispatch.** Needs the dispatch tool: `Agent` on current Claude Code, `Task` under its older name on earlier versions, or opencode's `task` — whose general-purpose sub-agent is named `general`, not Claude's `general-purpose`; the skills carry both names. Parallel phases are issued in one message and return their results directly. (Model-tier overrides stay Claude-only: opencode's `task` takes no model parameter.)\n- **Approach B — sequential inline execution.** For CLIs with no sub-agent dispatch at all. Each agent's instructions run inline, one finished completely before the next starts. Context isolation is lost and `models.yaml` tiers cannot be applied, since there is no dispatch call to carry the model override — the skill states this when it falls back.\n\nNothing to configure either way.\n\n### Why not agent teams\n\nThis section used to advertise agent-team support. Belmont no longer uses it, and turning your tool's agent-team feature on changes nothing here.\n\nIt came out because it had stopped working — the tools that gated it (`TeamCreate`, `TeamDelete`, `Task` with `team_name`) were withdrawn from Claude Code in v2.1.178, so the branch was unreachable and every skill was silently taking the fallback. It stays out for a better reason: Belmont already coordinates its agents through **files**. `MILESTONE.md` and `DEBUG.md` are the shared blackboard, `PROGRESS.md` is the task list — the same two jobs a team's mailbox and shared task list do, except a file survives a resumed session, shows up in a diff, and costs nothing per message.\n\nThe parallelism is already there too, one level up: `belmont auto` runs independent milestones concurrently in isolated git worktrees, each with its own ports and a merge-back. Teammates share a single working tree, so they would trade away the isolation that makes parallel implementation safe — and they cannot spawn at all under `belmont auto`, which runs headless.\n\nThe skill-by-skill reasoning is in [`knowledge/cross-cutting/dispatch-authorization.md`](knowledge/cross-cutting/dispatch-authorization.md).\n\n---\n\n## Monorepo Support\n\nBelmont auto-detects monorepos and adjusts worktree setup so AI agents run commands in the right package, find env files where postinstall scripts actually need them, and discover sibling workspaces. Detection signals: `turbo.json`, `nx.json`, `pnpm-workspace.yaml`, `package.json` `workspaces`, `lerna.json`, `rush.json`, `Cargo.toml` `[workspace]`, `go.work`, `pyproject.toml` `[tool.uv.workspace]`. When detected, Belmont seeds `.env*` into qualifying workspace dirs (those whose manifest signals env consumption — Prisma deps, postinstall scripts, etc.), and exports `BELMONT_MONOREPO`, `BELMONT_PRIMARY_WORKSPACE`, `BELMONT_PRIMARY_WORKSPACE_PATH`, and `BELMONT_WORKSPACES` so agents can scope their `--filter`/`-w`/`-p` commands. Override auto-detection with optional `workspaces` and `primary_workspace` fields in `.belmont/worktree.json`. See [docs/monorepo-support.md](docs/monorepo-support.md).\n\nSingle-package projects are unaffected — none of the monorepo env vars are exported when no workspace is detected.\n\n---\n\n## Working Backwards (PR/FAQ)\n\nBelmont supports Amazon's **Working Backwards** methodology — a product definition process that starts with the customer and works backwards to the solution. The centerpiece is the **PR/FAQ**: a one-page press release describing the product as if it's already launched, followed by FAQs that force clarity on every aspect of the idea.\n\n### Why PR/FAQ?\n\nTraditional product development often starts with solutions and works forward to find customers. Working Backwards reverses this: you write the press release first, then figure out how to build what you promised. This forces you to:\n\n- **Define the customer precisely** — not \"users\" but \"enterprise procurement managers at companies with 500+ employees\"\n- **Articulate the single most important benefit** — if you can't say it in one sentence, the idea isn't clear enough\n- **Eliminate vague thinking** — no weasel words, no adjectives without data, no magic solutions\n- **Surface hard questions early** — the FAQ section forces you to confront trade-offs, risks, and alternatives before writing any code\n\n### How It Fits Into Belmont\n\nThe PR/FAQ is an optional but recommended first step in Belmont's workflow:\n\n```\n/belmont:working-backwards  →  .belmont/PR_FAQ.md    (strategic vision)\n        ↓\n/belmont:product-plan       →  .belmont/PRD.md       (feature catalog + detailed PRDs)\n        ↓\n/belmont:tech-plan          →  .belmont/TECH_PLAN.md (master + feature implementation specs)\n        ↓\n/belmont:implement          →  Code                  (agent pipeline)\n```\n\nThe PR/FAQ feeds into product planning — when you run `/belmont:product-plan`, it reads the PR/FAQ for strategic context, ensuring your features align with the customer promise.\n\n### Learn More\n\n- [Working Backwards: Insights, Stories, and Secrets from Inside Amazon](https://www.workingbackwards.com/) by Colin Bryar and Bill Carr\n- [Werner Vogels on Working Backwards](https://www.allthingsdistributed.com/2006/11/working_backwards.html) — the original blog post\n- [The Amazon PR/FAQ Process](https://productstrategy.co/working-backwards-the-amazon-prfaq-for-product-innovation/) — a practical guide\n\n---\n\n## Sub-Feature Architecture\n\nFor products with multiple features, Belmont supports a **sub-feature directory structure** that keeps each feature's planning state isolated while maintaining a master product view.\n\n```\n.belmont/\n  PR_FAQ.md                    ← Strategic vision (created by /belmont:working-backwards)\n  PRD.md                       ← Master PRD (feature catalog)\n  TECH_PLAN.md                 ← Master tech plan (cross-cutting architecture)\n  features/\n    user-authentication/\n      PRD.md                   ← Feature-specific requirements + tasks\n      TECH_PLAN.md             ← Feature-specific technical plan\n      PROGRESS.md              ← Milestones + task tracking\n      MILESTONE.md             ← Active implementation context\n      MILESTONE-M1.done.md     ← Archived milestones\n    payment-processing/\n      PRD.md\n      TECH_PLAN.md\n      PROGRESS.md\n```\n\n- **Master files** persist at the product level — the PR/FAQ, master PRD (feature catalog), and master tech plan (cross-cutting architecture)\n- **Feature directories** contain the detailed planning state for each feature — isolated PRDs, tech plans, progress tracking, and milestone files\n- **Skills prompt for feature selection** — when running any skill, you select or create the feature to work on\n- **Cleanup reduces bloat** — archive completed features into slim summaries, remove stale milestone files, trim notes, and audit convention files\n- **Reset is granular** — reset a single feature, all features, or everything including masters\n\n---\n\n## Installation\n\n### Install (one command)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/blake-simpson/belmont/main/install.sh | sh\n```\n\nThis downloads the latest release binary to `~/.local/bin/belmont`. Make sure it's in your PATH:\n\n```bash\n# Add to ~/.zshrc or ~/.bashrc (if not already)\nexport PATH=\"$HOME/.local/bin:$PATH\"\n```\n\nYou can override the install directory with `BELMONT_INSTALL_DIR`:\n\n```bash\nBELMONT_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/blake-simpson/belmont/main/install.sh | sh\n```\n\n### Per-Project Setup\n\nNavigate to your project and run:\n\n```bash\ncd ~/your-project\nbelmont install\n```\n\nRelease binaries have all skills and agents embedded -- no source directory needed. You can also pass options:\n\n```bash\n# Target a different project folder\nbelmont install --project /path/to/project\n\n# Limit tool setup and disable prompts\nbelmont install --tools claude,codex --no-prompt\n```\n\n### Developer Setup (contributors)\n\nIf you've cloned the repo and want to build from source:\n\n```bash\n# Build with embedded content\n./scripts/build.sh\n\n# Or use the dev installer (builds + records source path)\n./bin/install.sh --setup\n\n# Run during development (requires --source flag since go run has no embedded files)\ngo run ./cmd/belmont install --source . --project /tmp/test-project --no-prompt\n```\n\n---\n\n## Skills\n\n| Skill               | Description                                       |\n|---------------------|---------------------------------------------------|\n| `working-backwards` | Amazon-style PR/FAQ document creation             |\n| `product-plan`      | Interactive PRD and PROGRESS creation             |\n| `tech-plan`         | Technical implementation plan                     |\n| `codex-plan-apply`  | Codex-only apply step for plan-mode handoff packets |\n| `implement`         | Full milestone implementation pipeline (3 agents) |\n| `next`              | Implement a single task (lightweight)             |\n| `verify`            | Verification and code review                      |\n| `loop`              | **Claude Code or Codex** — drive one feature to completion (implement → verify → next → status) via `/loop` or `/goal` |\n| `debug`             | Debug router (auto or manual)                     |\n| `debug-auto`        | Auto debug loop with agent verification           |\n| `debug-manual`      | User-verified debug loop with deep Belmont context + in-place spec reconciliation |\n| `review-plans`      | Document alignment and drift detection            |\n| `repair`            | Fix a PROGRESS.md whose task states no longer parse |\n| `cleanup`           | Archive completed features, reduce token bloat    |\n| `status`            | Read-only progress report                         |\n| `reset`             | Reset state and start fresh                       |\n\nSee [Skills Reference](docs/skills-reference.md) for detailed descriptions of each skill.\n\n---\n\n## Supported Tools\n\n| Tool                  | How Skills Are Wired                                                  | How to Use                                          |\n|-----------------------|-----------------------------------------------------------------------|-----------------------------------------------------|\n| **Claude Code**       | `.claude/agents/belmont` symlink + per-skill symlinks `.claude/commands/belmont/<skill>.md` → `.agents/skills/belmont/<skill>/SKILL.md` | `/belmont:product-plan`, `/belmont:implement`, etc. |\n| **Codex**             | Generated per-skill `agents/openai.yaml` (`display_name: \"belmont:<skill>\"`) — skills auto-discovered via `.agents/skills/` | Type `$belmont` to list all skills, or `belmont:implement` in prompt |\n| **Cursor**            | None — `.agents/skills/` auto-discovered (Cursor Skills)              | `belmont:implement` in prompt                       |\n| **Windsurf**          | None — `.agents/skills/` auto-discovered (Cascade Skills)             | `belmont:implement` in prompt                       |\n| **Gemini**            | None — `.agents/skills/` is the documented `.gemini/skills/` alias    | `belmont:implement` in prompt                       |\n| **GitHub Copilot**    | None — `.agents/skills/` auto-discovered                              | `belmont:implement` in prompt                       |\n| **Pi** (incl. local LLMs) | None — `.agents/skills/` auto-discovered (agentskills.io)         | `belmont:implement` in prompt; configure provider/model in `~/.belmont/local-llms.json` |\n| **opencode**          | Generated per-skill wrapper commands `.opencode/command/belmont/<skill>.md` delegating to `.agents/skills/belmont/<skill>/SKILL.md` (skills also auto-discovered) | `/belmont/product-plan`, `/belmont/implement`, etc. (or `belmont:implement` in prompt) |\n| **Any other tool**    | None — point your tool at `.agents/skills/belmont/<skill>/SKILL.md`   |                                                     |\n\nSkills are installed as agentskills.io-format folders (`<skill>/SKILL.md`), the open standard supported by Codex, Cursor, Gemini, Windsurf, GitHub Copilot, Claude Code, Pi, opencode, and a growing number of other AI tools.\n\nSee [Supported Tools](docs/supported-tools.md) for detailed per-tool setup instructions.\n\n---\n\n## Feature Auto\n\nBelmont includes a built-in auto orchestrator (`belmont auto`) that takes a planned feature (with PRD + TECH_PLAN) and executes it end-to-end: implementing milestones, verifying, fixing follow-up issues, and continuing until the feature is complete. Independent milestones can run in parallel via git worktrees, and multiple features can execute in parallel across worktrees. Pure Go, no Node.js required.\n\n> **Alias**: `belmont loop` still works as an alias for `belmont auto`.\n\n```bash\n# Run auto for a feature\nbelmont auto --feature my-feature\n\n# Run specific milestones\nbelmont auto --feature my-feature --from M2 --to M6\n\n# Use a specific AI tool\nbelmont auto --feature my-feature --tool codex\n\n# Run multiple features in parallel\nbelmont auto --features feat-a,feat-b,feat-c\n\n# Run all pending features\nbelmont auto --all\n\n# Control checkpoint policy\nbelmont auto --feature my-feature --policy milestone\n\n# Cap concurrent features or milestones\nbelmont auto --all --max-parallel 2\n\n# Bypass the clean-working-tree preflight (not recommended — risks merge failures)\nbelmont auto --feature my-feature --allow-dirty\n\n# Re-verify completed milestones (e.g. after upgrading agents)\nbelmont reverify --feature my-feature\nbelmont reverify --feature my-feature --from M3 --to M10\n\n# Read the decision queue — every [!] task waiting on a person, with its detail\nbelmont blockers\nbelmont blockers --feature my-feature --summary\n\n# Sync master PROGRESS.md with actual feature states\nbelmont sync\n\n# Steer an in-flight auto run — injects instructions into active worktrees\nbelmont steer --message \"pin the ital and MONO axes too\"\nbelmont steer --milestone M5 --file fix-notes.md\nbelmont steer -   # read from stdin; or run with no source for $EDITOR\n```\n\nThe auto command auto-detects which AI tool CLI you have installed (Claude Code, Codex, Gemini, Copilot, Cursor, Pi, opencode) and shells out to it in headless mode. Override with `--tool`.\n\nIt uses a hybrid decision system: smart deterministic rules handle ~80% of cases (using git diff classification and per-milestone tracking), with AI called only for ambiguous situations like repeated verification failures. The AI receives rich context including work type, failure history, and verification state. Falls back to deterministic rules automatically if the AI call fails.\n\nIndependent milestones can execute in parallel using git worktrees. Declare dependencies in PROGRESS.md with `(depends: M1, M2)` syntax, and milestones without unmet dependencies run concurrently up to `--max-parallel` (default 5). Multiple features can also run in parallel with `--features` or `--all`, each in its own worktree with automatic merge and conflict reconciliation. Feature-level dependencies declared in the master PRD's Dependencies column enable wave-based execution — independent features run in parallel, dependent features wait for their dependencies to complete first.\n\nEach worktree gets isolated `.belmont/` state (copy-based, not symlinked) so AI agents can commit state changes as part of their feature branch. Run `belmont status` from the main repo to see live progress across all active worktrees. Each worktree is automatically assigned a unique `PORT` to prevent dev server conflicts. Dependencies are auto-installed by detecting your lock file (e.g., `package-lock.json` → `npm install`). Create `.belmont/worktree.json` to customize setup hooks, teardown, or environment variables. See [Worktree Isolation](docs/worktree-isolation.md) for details.\n\nThree checkpoint policies control human involvement:\n- `autonomous` (default) — only pauses on blockers or errors\n- `milestone` — pauses before each new milestone\n- `every_action` — human approves each step\n\nSee [Feature Auto](docs/feature-auto.md) for full documentation.\n\n---\n\n## Documentation\n\n| Document                                           | Description                                                 |\n|----------------------------------------------------|-------------------------------------------------------------|\n| [CLI Commands](docs/cli-commands.md)               | Full CLI usage, flags, and examples                         |\n| [Supported Tools](docs/supported-tools.md)         | Detailed per-tool setup (Claude Code, Codex, Cursor, etc.)  |\n| [Skills Reference](docs/skills-reference.md)       | Detailed description of each skill                          |\n| [Feature Auto](docs/feature-auto.md)               | Automated orchestrator for end-to-end feature execution     |\n| [Worktree Isolation](docs/worktree-isolation.md)   | Port assignment, lifecycle hooks, and parallel execution    |\n| [Full Workflow](docs/workflow.md)                  | Step-by-step walkthrough from vision to iteration           |\n| [Directory Structure](docs/directory-structure.md) | Repository and installed project layouts                    |\n| [PRD & Progress Format](docs/prd-format.md)        | PRD task format, states, priorities, and PROGRESS structure |\n| [Agent Pipeline Details](docs/agent-pipeline.md)   | How the 3-phase agent pipeline works internally             |\n| [Updating Belmont](docs/updating.md)               | Self-update, re-install, and developer updates              |\n| [Troubleshooting](docs/troubleshooting.md)         | Common issues and fixes                                     |\n\n---\n\n## Requirements\n\n- An AI coding tool (Claude Code, Codex, Cursor, Windsurf, Gemini, Copilot, Pi, opencode, or any tool that reads markdown)\n- [figma-mcp](https://github.com/nichochar/figma-mcp) (recommended) -- enables Belmont to load Figma designs, extract design tokens, and perform visual verification\n- [playwright-mcp](https://github.com/microsoft/playwright-mcp) (recommended) -- enables agents to interact with browsers for visual verification and E2E test debugging\n- [RTK](https://www.rtk-ai.app/) (recommended) -- hook-based CLI proxy that filters command output (tests, lints, git) before it reaches the model; typically halves tool-I/O input tokens across Belmont's agent pipeline\n- No Go required (pre-built binaries)\n- No Docker required\n- No Python required\n\n**For contributors**: Go 1.21+ is needed to build from source. See [Developer Setup](#developer-setup-contributors).\n\n---\n\n## Authors\n\n|                                                             | Name                                                                   | Contributions                                                 |\n|-------------------------------------------------------------|------------------------------------------------------------------------|---------------------------------------------------------------|\n| <img src=\"https://github.com/blake-simpson.png\" width=\"50\"> | **Blake Simpson** ([@blake-simpson](https://github.com/blake-simpson)) | Creator & maintainer                                          |\n| <img src=\"https://github.com/bigbenjoman.png\" width=\"50\">   | **Ben Lavender** ([@bigbenjoman](https://github.com/bigbenjoman))      | PR/FAQ skill, Product skill + PRD formats, Test & maintenance |\n\n---\n\n## License\n\nBelmont is licensed under the [Apache License 2.0](LICENSE). See the [NOTICE](NOTICE) file for attribution details.\n",
  "bytes": 30285,
  "sha": "82c30171a7e19f6e94111369bc121008dd1c9fb2d86996b8e5ca41f7a3a13afe",
  "repo_slug": "blake-simpson/belmont",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_blake_simpson_belmont_belmont_d4e94a8f/readme"
}