> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fermata.run/llms.txt
> Use this file to discover all available pages before exploring further.

# Your first piece

> Walk one feature end to end: a short interview, a spec, a plan, a team of coding agents, a diff you read, and an opened pull request.

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](/loop/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](/control/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](/piece/interview-and-spec).

<Frame caption="The interview asks, you answer, and the spec takes shape until you mark it ready">
  <video autoPlay muted loop playsInline aria-label="Answering a batch of interview question cards, opening the spec draft panel, sending a follow-up, and clicking Mark Spec Ready">
    <source src="https://mintcdn.com/keliosllc/pg1SGBNjstRDbutF/videos/SHORT-2.mp4?fit=max&auto=format&n=pg1SGBNjstRDbutF&q=85&s=74070775cf2e35eaab79e2bd59a0a0d6" type="video/mp4" data-path="videos/SHORT-2.mp4" />
  </video>
</Frame>

## 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](/piece/strategy).

<Frame caption="Leave a note on the plan, then regenerate the strategy with it">
  <video autoPlay muted loop playsInline aria-label="Selecting a sentence in the strategy, adding a note in the margin, and clicking Regenerate">
    <source src="https://mintcdn.com/keliosllc/pg1SGBNjstRDbutF/videos/SHORT-3.mp4?fit=max&auto=format&n=pg1SGBNjstRDbutF&q=85&s=94eda22aeb1309016f69e739219330ef" type="video/mp4" data-path="videos/SHORT-3.mp4" />
  </video>
</Frame>

## 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](/loop/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](/piece/agents).

<Frame caption="Give one agent a stronger model, start the run, and look inside a running agent">
  <video autoPlay muted loop playsInline aria-label="Selecting an agent in the graph, setting its model override to Opus, clicking Start Execution, and opening the running agent's view">
    <source src="https://mintcdn.com/keliosllc/pg1SGBNjstRDbutF/videos/SHORT-4.mp4?fit=max&auto=format&n=pg1SGBNjstRDbutF&q=85&s=50b4fe883f495750de52cc8369886084" type="video/mp4" data-path="videos/SHORT-4.mp4" />
  </video>
</Frame>

## 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](/piece/review-and-pull-request).

<Frame caption="Ask for a change, commit what the agent did, and open the pull request">
  <video autoPlay muted loop playsInline aria-label="Clicking Request Changes, describing a character counter, committing the round, and creating a pull request with an AI-written title and description">
    <source src="https://mintcdn.com/keliosllc/pg1SGBNjstRDbutF/videos/SHORT-5.mp4?fit=max&auto=format&n=pg1SGBNjstRDbutF&q=85&s=0771fa63793e072b31d897a2e3478711" type="video/mp4" data-path="videos/SHORT-5.mp4" />
  </video>
</Frame>

## 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](/surfaces/canvas-and-sessions) on the Canvas is lighter and faster. For running pieces hands-off across a backlog, there is [the Loop board](/loop/board).