Skip to main content
This is the whole factory in one feature. You describe the work in a short interview, approve the spec it drafts, and Fermata runs the four phases: Spec, Strategy, Agents, Review. At the end you get an opened pull request. You merge. That bundle of documents, worktree, branch, and pull request is a piece: one spec, one pull request. Read this page once end to end, then use the per-phase pages when you want the detail.

​
Spec

Hit the New Piece button in the toolbar (⌘I), or the one in the sidebar header (⌘⇧N). Creating the piece drills straight into a guided interview, which reads the relevant parts of your codebase and keeps drafting until the spec has the sections a build needs. Already have a spec written, or an issue to start from? Import a file, or (Edge) pick a Linear or GitHub issue, instead of talking it through; see starting from an issue. The interview’s research is saved with the piece, and the strategy phase turns it into a codebase analysis before it plans. Mark Spec Ready closes the phase and asks how far this piece should run without you, which is the lane, covered in the two layers. Leave it on Manual for your first one and you approve every phase by hand. The approved spec is the contract and it locks, so a change of mind mid-flight is noted in Review rather than rewritten here. More in the interview and the spec.

The interview asks, you answer, and the spec takes shape until you mark it ready

​
Strategy

Approving the spec kicks off strategy generation, and Fermata proposes an implementation plan as a readable document: the approach, the order, the risks. Drop inline notes on any section to push back, edit the document directly, or click Regenerate to redo it with your feedback folded in. Two or three passes until the plan reads right is normal, and Approve closes the phase. More on strategy.

Leave a note on the plan, then regenerate the strategy with it

​
Agents

Approving the strategy decomposes it into a graph of agents, one per unit of work, which you can edit before anything runs. How many agents come out of the decomposition follows the strategy’s Estimated Complexity, unless the piece’s Split budget overrides that; the caps per size are on limits. Start Execution dispatches the graph, and the phase surface lays it out in waves: everything in a wave runs at the same time, and a wave waits for the one before it. All of them work in one git worktree on one branch belonging to the piece, never in your checkout, and each commits its own work. More on agents.

Give one agent a stronger model, start the run, and look inside a running agent

​
Review

Every agent produces a diff, and Review is where you read it and decide how the changes land. By the time it opens, a work review has already checked that the plan was followed and the work was done, and its verdict sits beside the diff. On the Edge channel you can also run an optional code-review pass, which is advisory. Create PR pushes the branch and opens the pull request through gh, and Fermata stops there. You merge. More on review and the pull request.

Ask for a change, commit what the agent did, and open the pull request

​
When to reach for a piece

A piece is the right shape when the work has a plan worth drawing before you start: new features with real scope, refactors that touch several files, anything you would regret redoing. For bug fixes, spikes, and one-off questions, a standalone session on the Canvas is lighter and faster. For running pieces hands-off across a backlog, there is the Loop board.