What Forge is

Your coding agent can already write the code. The part that hurts is everything around it: knowing whether what came back is what you asked for, whether anyone other than the author looked at it, whether it actually runs, and whether it's about to open a PR because the loop felt finished.

Forge is the process that wraps that agent. It's a skill pack plus a small CLI, and it runs inside the agent you already use. Five ideas carry the whole thing, and the rest of these docs are detail on them.

Spec  →  Plan  →  Build  →  Acceptance  →  Ship
                  ↳ simplify, review, repair

LoopsCopy Anchor Link

A loop is one bounded piece of work. It has an outcome, a branch or worktree, a team, and a folder in your repository where its decisions and evidence are recorded. It stops at the boundary you request, which can be earlier than Ship.

.forge/loops/export-button/
├── index.md        # what we're delivering, who approved what, what's next
├── decisions.md    # the calls you made, protected from generic edits
├── log.md          # what happened, in order
├── spec/           # only the documents this work actually needs
├── build/log.md    # reviews, findings, repairs
└── verify/         # acceptance evidence, screenshots included

It's plain Markdown, so you read it in your editor, review it in a PR, and grep it a year later. Nothing is hidden in a database and nothing is a black box.

Accepted intentCopy Anchor Link

The agent works from accepted intent. A clear request or ready Issue can supply it directly. When the outcome needs a new or materially revised spec, Forge drafts one in plain language, with Given/When/Then scenarios for behavior that matters.

In Guided mode, you approve new meaning before dependent planning or building. Accepted meaning is the authority. A passing test can't overrule it, and an agent finding can't rewrite it.

Forge records proposed changes to standing requirements in the loop. It doesn't routinely edit canonical docs/specs/ during Spec. An explicitly requested Spec apply, or Finish at actual work completion, can install approved changes through guarded memory mechanics. A document receipt proves the write, not the software.

Agent teamsCopy Anchor Link

Forge staffs the work with named professionals instead of one agent doing everything. Who shows up depends on what the work earns.

The important line in that table is between Engineer and Reviewer. One Engineer owns the candidate and can delegate as widely as it likes, but a different Reviewer in a separate context, with read access only, owns the verdict. A builder's self-review never gets recorded as an independent one.

The knowledge baseCopy Anchor Link

The optional KB retains useful facts a loop earned so later work can find them: how auth works here, what the deploy sequence is, which table matters and why.

It lives at docs/knowledge/ as a native OKF v0.2 bundle, which is to say more plain Markdown. Forge creates only the topics the work earns, so there are no empty placeholder directories waiting to be filled in by someone who never will.

When a change can affect existing behavior, Forge records a preservation chain:

signals → affected obligations → selected checks → gaps

Which means: this change touched these things, those things carry these obligations, here's what we checked, and here's what we couldn't.

QACopy Anchor Link

Review answers whether the code is sound. Acceptance answers whether the outcome behaves, which is a different question that needs different evidence, so a clean-context QA professional opens the actual candidate and tries it.

For UI work that means a real browser, with the states and viewports recorded. Written tests, generated mocks, source reading and an earlier green label don't substitute for proof somebody ran. Proof that couldn't be run stays NOT RUN rather than quietly becoming a PASS.

When Review admits findings, they go back to the builder as one packet and get fixed at the shared cause. After three substantive repair cycles, or three substantive repairs inside one of them, Forge stops editing and writes a rethink instead: the invariant that keeps failing, the common cause, and a simpler approach, challenged by an Engineer who didn't write it. If nothing supported comes out of that, or the same failure returns after it, Forge reports BLOCKED with the evidence and the decision it needs from you. Renaming the candidate to reset the counter is not allowed.

NextCopy Anchor Link

Install is one curl, run from the project you want Forge in:

curl -fsSL https://get.brightstack.ai/forge/install.sh | sh

The install page covers Claude Code and the other hosts. After that, pick the thing you're actually trying to do from How to. Forge is MIT licensed.