Stop arguing with your coding agent.
Forge gets you from a rough idea to a spec worth building, and from a spec worth building to working software somebody other than its author has reviewed.
curl -fsSL https://get.brightstack.ai/forge/install.sh | shmacOS and Linux. On Claude Code, end it with FORGE_TOOLS=claude sh instead of plain sh. It writes the binary, pulls the skills into this repository, and gets out of the way.
- 01Specwhat done means, in writing
- youapprove
- 02Planthe order the work happens in
- youapprove
- 03Buildsimplifyreviewrepair
- 04Acceptancedriven in a real browser
- 05Shipmerged, with the spec attached
the assembly line
Set the spec, say build, go touch grass or something.
You will come back to beautifully crafted software. Makers are happiest when they are making, and Forge takes the rest: the re-explaining, the checking, and the deciding whether the thing in front of you is actually done.
01You spec
FR-3 · resume where it dropped
- given
- a websocket dropped mid-stream
- when
- the tab regains focus
- then
- the transcript resumes at the last delivered event
FR-4 · ordering survives the gap
- given
- events buffered during the outage
- when
- the socket reopens
- then
- they replay in their original order
You edit it until it says what you meant, and this is the only part that needs you.
02You press play
engineerintegratingowner
worker 1queuedcursor persistence· tests green
worker 2queuedreconnect backoff· compiles clean
worker 3queuedreplay ordering tests· 12 cases added
reviewerqueued· waits for the candidate
qaqueued· waits for review
You go do something else.
03You come back
code reviewpass
designpass
qualityn/a
specpass
craftpass
findings3 admitted, 3 repaired
There is a candidate, a verdict, and the evidence behind it.
the factory
Ship like a company of one.
Every project gets its own worktree, its own team and its own branch, so they run side by side without ever reaching into each other. You are one person, and the only thing you are actually doing is deciding what gets built.
forge · parallel loops
what you decided to build
- loginnew sign-in screen
- editormarkdown in the composer
- evalsstop the support agent apologizing
- themedark mode, again
- parserrewrite it in Rust
- parserrewrite it back in JS
- emailsactually write the onboarding emails
divvied up · 7 worktrees, 7 branches
- worktrees/login
- worktrees/editor
- worktrees/evals
- worktrees/theme
- worktrees/parser
- worktrees/parser-2
- worktrees/emails
1 builds2 review1 applies
progress
· login build: the password field remembers nothing, deliberately
· parser review: the Rust one is faster and nobody on the team writes Rust
· evals acceptance: 6 journeys driven in a real browser → PASS
the spec
Change the spec on purpose, or not at all.
You settle what done means once, and every change after it arrives as a delta you accept or reject. When a new requirement contradicts one you already accepted, Forge brings you both and the evidence instead of quietly picking a winner. Each loop opens its own slice, folds it back when it ships, and leaves what it learned where the next one will read it.
- auth.md
- billing.md
- exports.md
- search.md
- uploads.md
- given
- a client whose socket dropped mid-session
- when
- it reconnects inside the resume window
- then
- it replays only the revisions after its last acknowledged one
- was
- every export completes within ten seconds
- now
- exports above 50 MB stream, and the ceiling is stated to the user
the change keeps presence alive for the length of the resume window
FR-3, accepted 2026-08-19 drops presence the moment the socket closes
- on ship
- realtime-editing.md folds back into the app spec, conflict and all
- .forge/kb/ keeps what the loop learned, and the next one reads it first
subagent-driven development
Forge does not make one agent work harder, it puts a team on the job.
Everyone is building software factories, and this is what standing on the floor of one feels like.
- PM
- Designer
- Architect
- Engineer
- Reviewer
- QA
- Researcher
3 of 7 staffed on this loop · the rest stay out of it
01The work happens at once
Three specialists on three branches, so a big change is one pass instead of twenty turns of nudging.
02The last file gets the first file's care
Nobody is running on fumes at the end of a long conversation.
03Somebody owns the result
The Engineer merges it, simplifies it and answers for it, so you get one change instead of a pile of patches.
review
Way past what your coding agent calls a code review.
Your team checks correctness, simplicity, spec compliance, design fidelity, accessibility, your repository's own standards and craft. Every dimension answers to its own rubric and its own evidence, and to its own independent judge when the work earns one.
correctness · simplicity reconnect retries with no ceiling at src/socket/reconnect.ts:40; the retry test covers the happy path only
fidelity · accessibility reconnect banner rendered at 390 / 768 / 1440; focus returns to the composer, Escape dismisses
no written deliverables in this candidate, so there is nothing to judge
compliance FR-3 and FR-4 traced forward to implementation and back to the accepted delta; no invented requirement
reported as excluded rather than folded into the verdict as a pass
- authority
- NFR-2,
src/socket/AGENTS.md - trigger
- the server answers 503 for longer than the retry budget
- observed
- 61 attempts in 40 seconds, no ceiling reached
- consequence
- the tab keeps retrying and the elapsed ticker never stops
- reason
- no reachable trigger and no current maintenance consequence; an architectural preference, and an equally valid tactic is already in the file
01Evidence or it didn't happen
A finding needs controlling authority, a reachable trigger, observed evidence, and a material consequence before it is admitted.
02No finding quota
A clean candidate earns a clean report, which is why the report means something when it is not clean.
03Anti-slop checks
After a few repairs your Forge team stops patching and rethinks the approach from the top, because nobody wants to come back to a mountain of patches and wonder what the hell happened here.
proof
Your team tests your code like real users do.
A real browser at real viewports, clicking the actual thing in a clean context, because review asks whether the code is right and acceptance asks whether the outcome happened.
Export undefined files as
decisions
Your decision is law.
Every call you make is written down where the next agent has to read it, so the pattern you chose in week one is still the pattern in week nine. Nothing gets quietly refactored because some model preferred it the other way.
D-004live state stays in the runtime, never in React hooksaccepted 4 weeks ago
D-007repeat yourself before you reach for a factoryaccepted 2 weeks ago
D-011integration tests are the spec; mock-heavy unit tests are paddingaccepted 6 days ago
proposed by worker 2, mid-build
“Extract a useSocket() hook and move the cursor into it.”
checked against D-004 · turned back, and the brief came back rewritten against the runtime
From builders, for builders, with ❤️🔥