forge

Forge

A Claude Code plugin for executing ambitious projects through big-picture prompts, without losing sight of your constraints. No new tools or CLIs required, just your existing Claude Code session.

Forge has replaced my use of ralph-loops and my needs for spec-kit.

Why

I wanted Claude Code to automate large goals, not just answer questions or write a file, but actually drive ambitious, multi-step work to completion. Since the release of Claude Code, I tried many solutions and landed on spec-driven designs, but that too was problematic for various reasons: The AI would lose track of important specs I gave it, new sessions didn't have my previous specs, and it would do a poor job of implementing ambitious goals.

That's why I built Forge. It keeps track of your constitution, product, and project specs so you don't have to re-explain yourself. It handles context rot by launching subagents with exactly the right context for each piece of work. It manages the task workflow from decomposition to completion, tracking what's done, what's in progress, and what's blocked. And it all happens inside a natural Claude Code workflow, with no new tools or setup required.

Install

Forge is a Claude Code plugin. See the Claude Code documentation for how to install plugins from the marketplace or load them locally via --plugin-dir.

Usage

1. /forge:setup: set up your product spec (what and why) and constitution (non-negotiables). Do this once per project.
2. /forge:new-spec <name>: create a new project spec through a guided conversation. Forge reads your constitution and product spec to keep the work aligned, then automatically decomposes it into tasks.
3. /forge:start <name>: execute the tasks. Forge runs each one through an implement, verify, and commit loop using focused subagents.
4. If tasks block: Forge writes a blocked-summary.md in the spec directory summarizing each failure. Edit it to add context or clarify requirements, then re-run.
5. /forge:list: check progress across all specs at any time.

Always forward. Completed work is never re-run. Interrupted runs pick up where they stopped.

/forge:setup                                      # set up product.md + constitution.md (once per project)
/forge:new-spec <name>                            # create a new project spec interactively
/forge:start <name>                               # execute tasks for a spec
/forge:start <name> --ask                         # pause for approval at each phase
/forge:start <name> --clean                       # clear state and start over
/forge:stop <name>                                # pause a run cleanly
/forge:new-task [<name>] <prompt>                 # add a new task to an existing spec
/forge:remove <name>                              # remove a spec
/forge:list                                       # list incomplete specs and their status
/forge:list --all                                 # include completed specs
/forge:info                                       # summarize specs and task progress

<name> accepts a full spec name (auth_system), its number (00003), or an unambiguous prefix (auth). Hyphens and spaces are normalized to underscores. Most commands default to the latest spec when <name> is omitted.

Project specs live in numbered directories under .forge/:

.forge/
  product.md                  # what and why
  constitution.md             # non-negotiable principles
  council.md                  # generated by forge (shared across specs)
  council/                    # generated role agents (shared across specs)
  00001_auth_system/
    project.md                # the project spec (user design + Forge config)
    verifier.md               # generated by forge (project-specific verifier)
    plan.md                   # generated by forge
    todo/  working/  done/  blocked/    # task lifecycle

How It Works

Specs layer on top of each other

There are three kinds of specs, each narrowing the scope for the next. Forge keeps track of all of them so you don't have to:

1. Product spec: the what and why. Defines who the product is for, what problems it solves, and what success looks like. Keeps individual project specs mission-aligned.
2. Constitution: non-negotiable principles for the entire project. Every task Forge generates must comply with these rules. Written once, enforced always.
3. Project specs: concrete goals — what to build, how to verify it's done, and any constraints specific to that piece of work. Each lives in a numbered directory (.forge/00001_name/). When you create one, Forge reads your constitution and product to flag conflicts before any work begins.

/forge:new-spec sets up the work