Greenfield and brownfield
Where a build actually starts, and why every planning document is optional.
Fragua runs a chain of agents — Product Brief, Research, MVP Plan, Brand Guide, Technical Guide, then Foundation, Spec, and Execution. It reads like a sequence you must complete in order, but most of it is optional. The agents that produce documents exist to give later agents richer context, not to gate your build.
Only two things are actually required before Fragua can write code: a Foundation — the working copy of your app — and an accepted Spec. Everything upstream is context you can add, skip, or supply yourself.
Foundation builds the app and unlocks specs; an accepted spec triggers execution, which opens a pull request you review and merge.
Two ways a Foundation starts
When you point a workspace at a git repository, Fragua probes it and picks a path on its own — you don't choose between them.
Greenfield
The repository is empty or has only a README. Fragua scaffolds a fresh Rails app on the Maquina stack, seeds a starter agent-instructions file with your project's commands, and pushes the first commit. You confirm the app name before it runs.
Brownfield
The repository already has code. Fragua clones it and leaves it as it is — it never writes a CLAUDE.md into your repo. Afterward it reads the codebase to draft a Technical Guide and a Brand Guide from what's already there.
Either way you end up with the same thing: a Foundation that's ready, and a branch the agents build on. Fragua's interface always calls it a branch.
The planning documents are optional
The Product Brief, Research, MVP Plan, Brand Guide, and Technical Guide are enrichment, not prerequisites. A downstream agent uses them when they exist and works without them when they don't — so you can build with none of them, or just the one or two that matter to you.
-
Product Brief — what you're building, who it's for, and what makes it different.
-
Research — a competitor and market scan; builds on the brief when one exists.
-
MVP Plan — the brief and research turned into a concrete first release.
-
Brand Guide — colors, type, and voice; runs at any time, even on an empty workspace.
-
Technical Guide — stack, data model, and conventions; on existing repos it's drawn from the code.
The one real gate is the Foundation. Once it's ready you can shape a Spec and ship — with or without any of the documents above.
Bring your own, or let an agent write it
You're not stuck with agent-written documents. Every planning document gives you two ways in on its New screen — let an agent interview you, or paste a version you already have.
Interview
Describe what you want and the agent asks follow-up questions, then writes the document for you. Good when you're starting from a rough idea.
Paste
Already have the document — from another tool, a past project, or your own notes? Paste the Markdown. It skips the interview and lands straight in review, ready to accept.
How the agents fit together
Most steps are optional. These are the connections that matter — what unlocks what, and what just adds context.
The Product Brief unlocks Research and the MVP Plan.
The Foundation unlocks Specs and Issues — the one thing required before any building.
An accepted Spec or approved Issue starts Execution, which opens a pull request.
Your planning documents feed the Spec agent as context — used when present, skipped when not.
The agents in detail
Each agent has its own page — what it does, what you share to start it, and how to reach the result.
Install the CLI and run your first agent on your own machine.