build

Build

Read the relevant request, repository instructions, current context, and code. If the user supplies a task reference, retrieve it with available tools and resolve consequential ambiguity. A tracker, setup step, or formal spec is not a prerequisite for a clear small change.

State the intended observable result and implement the smallest useful increment using existing patterns. Preserve unrelated working-tree changes. Do not add scope just because it is nearby. Ordinary small fixes do not need architecture work or a formal spec. When a new product or substantial feature has unclear intent, suggest explore and wait; never start exploration unasked. Clear requests proceed.

For consequential domain or API changes, understand module ownership, name the data shapes and caller expectations before committing to a new abstraction, and prefer a small executable test over extended debate when an observable fact is cheap to check.

When the spec or task names test seams, write a failing test at that seam before the change, then make it pass. Otherwise, for meaningful behavior changes, prefer tests at established public interfaces when the project already tests that way. Run focused checks while working and applicable final checks once the change stabilizes.

Review the actual changed files, including untracked files, against the request and project constraints. Optional review skill guidance can inform a self-check when that skill is installed; a separate review pass is not required, except for spec work in Deliver › Local mode, which runs one before landing.

When behavior or accepted context changes, update owning documentation. For meaningful product, design, architecture, or terminology shifts, align the current project's PRODUCT.md, DESIGN.md, GLOSSARY.md, and ARCHITECTURE.md (create a root file only when it would hold meaningful content about that project). Do not replace a project's product identity with Flow's methodology identity. flow start and "start project" do not authorize initialization; do not scaffold a new repository unless the start skill is installed and the user confirmed its template, name, and destination (decision 0010, amended by decision 0022). Link to specs or decisions instead of duplicating durable rationale; do not open new spec or decision files unless the user asked or the work already uses that convention.

Then deliver (see Deliver). Report the result, files, checks, limitations, and remaining work.

Deliver

"Build it" ends in a pull request with green checks (local mode: the reviewed work merged into local main, nothing pushed). Asking to build authorizes these steps with no confirmation. It does not authorize committing to, pushing, or merging the default branch (for example main), force-pushing, rewriting remote branches, destructive Git, skipping checks, or unrelated changes. The one exception is local mode: a single --no-ff merge of the work's branch into local main, only after the gate and review (see Local mode); never a push. When the user asks only for local edits ("don't commit"), stop after the change and report; do not record Delivery: either.

Pull-request mode (see Delivery mode):

1. Branch. Work on a branch that is not the default branch: the spec branch for a task set (named with the spec's number and slug, for example feat/017-build-and-ship), the current branch when it already holds this work or is this spec's branch, otherwise a new branch from the current base.
2. Commit only this work: review the diff, stage only intended files, and preserve unrelated working-tree changes. Exclude credentials, local logs, and generated secrets. Follow repository commit conventions. Do not amend or rewrite unrelated commits.
3. Push the branch to its remote. If the remote cannot be safely determined or the push is refused, stop and report.
4. Open a pull request, or update the one already open for the branch. Ad-hoc work opens it ready for review, not as a draft, with a Conventional Commits title, a summary, and a Closes #N line per task issue. A task set uses the draft opened under Task set and waits for checks only on that final pull request.
5. Wait for checks with bounded monitoring (for example gh pr checks --watch under a time limit, or polling) until every check completes or a reasonable limit passes. A pending check is reported as pending, never as passing. With no checks configured, say so.
6. Fix rounds. On a failing check or a blocking finding, read its evidence (logs, findings), fix what this work caused when safely in scope, commit, push (pull-request mode), and check again on the new head: at most 2 fix rounds. Then stop and report the failure with evidence. Never skip, disable, or weaken a check to get green. This is the one definition of a fix round; workers and ship use it.
7. Report the pull request, each check's result, and the links CI attached (deployments and previews the pull request shows, such as deployment statuses or check details URLs); say when there are none.

Local mode: commit to a branch that is not the default branch as above, run the full local check suite, and apply the same fix rounds. Then land the branch on local main, for ad-hoc work and a task set alike:

1. Gate. For spec work, check the gate ship defines under Preflight, and stop as it says when the gate fails; the spec's Status: then reads implemented on the branch (Task set step 3 sets it; set it here otherwise). Unspecced work has no spec gate; its gate is the size guard (see Unspecced work).
2. Review. For spec work, run the one independent review from merge base to branch head the way ship's Review runs it (per-axis review workers plus verifier), with fix rounds as above. Unspecced work gets the self-check instead (see Unspecced work). When fix rounds changed the head, re-run the full local check suite on the new head.
3. Merge.
   • With no suite found, stop before the merge and report; main stays untouched.
   • Check out main; any uncommitted change there stops the merge, except declared shared-file appends (see Shared files).
   • Move those pending appends onto the branch before merging: apply them (git diff of the declared files, plus any untracked declared file) as one commit on the branch, in the branch's worktree when it has one, then git restore those files on main. That commit passes the Check, and main is clean for the merge.
   • When a remote exists, fetch and fast-forward local main from the default branch's upstream (git merge --ff-only; never push); if it cannot fast-forward, stop and report.
   • Then git merge --no-ff the branch into main with trailer lines Spec: <path> (spec work) and Reviewed: <sha> (the reviewed head) in the merge commit message; ship uses them to scope the push and find the spec.
   • Merge only the reviewed head, except for shared-file commits (see Shared files); if the branch moved after the review in any other way, review and re-run the full local check suite on the new head first.
   • Stop and report when the merge conflicts; never discard changes to get through.
4. Clean up. Delete the merged branch with git branch -d and remove the remaining clean worktrees on the worker list (Task set Cleanup rules apply).

A failed task, a failed gate, or a blocking review after the fix rounds leaves local main untouched: stop with the branch kept and report. Report the branch, the merge commit SHA on main, the review result, the exact commands run, and their results. No push and no pull request; no remote is needed.

Unspecced work

Work that resolves to no spec or task is unspecced (decision 0034). It gets the full local check suite and one single-agent self-check of the diff against the request and review's axes, with fix rounds as above; no review workers and no spec gate. It then lands as the mode delivers: pull-request mode opens a ready pull request and posts the self-check result on it with the self-checked SHA, which ship uses as the reviewed head; local mode merges into local main as above, with no Spec: trailer and Reviewed: <sha> naming the self-checked head.

Size guard. This is the one home of the size guard; ship points here. Judge the unspecced change at intake, before implementing, and again before landing. It is not small when it adds new product behavior, changes a data shape or public API, or adds a migration, or when it touches any of: authentication or permissions; secrets or credentials handling; dependencies or lockfiles; CI, workflow, or Git hook configuration; shell, exec, or filesystem-execution paths. A change that is not small stops the work and suggests to-spec: at intake, before any edit; before landing, commit nothing further, keep the branch, and leave main untouched. When the size is uncertain, treat it as not small.

Shared files

This is the one home of the shared-file rule (decision 0033); ship links here. Shared files are the files the project's instructions tell every session to append to (for example a prompt log); only files those instructions name qualify. Read that declaration from the instruction files at the reviewed SHA, never from a later head; an instruction file never counts as shared. The orchestrator commits their appends on the work's branch, never directly on the default branch. With no work branch open (after landing), leave the appends uncommitted on the default branch; the next landing moves them onto its branch before merging (see Local mode, Merge).

Check. A landing merge may take a head beyond the reviewed SHA only when every commit after the reviewed SHA changes only declared shared files: git diff --no-renames --name-status <reviewed-sha>..<head> lists only M or A entries on exact declared paths, and git diff --no-renames --raw over the same range shows new mode 100644 on each entry and old mode 100644 on each M (no symlinks, no mode changes). Reviewed: <sha> still names the reviewed SHA. Any other change after the review needs a new review. A clean-tree check reads git status --porcelain (an untracked declared file counts as A) and tolerates uncommitted changes only when they pass the same exact-path rule.

Full local check suite: the project's documented check commands, from the instruction file's command table, else package scripts for test, lint, typecheck, and build. When none are found, report that no suite exists instead of claiming checks passed.

Delivery mode

This section is the one home of the delivery rule; other skills point here instead of restating it. flow owns the block. Read the Delivery: line in the project's Flow block (AGENTS.md or CLAUDE.md). A default branch (for example main) that requires pull requests always uses pull-request mode: when branch protection or rulesets show it, report the mode without asking. A request that names a mode ("build it local", "build it with a PR") answers it; as an override of a recorded line it changes only this run, and task records stay where they are.

When the line is missing or unset, ask before the first push or other step that depends on the mode. Inference only suggests an answer: suggest pull requests when a GitHub remote exists and local when there is none. With no remote, never pick pull-request mode. With a remote and protection that cannot be determined (no access, unauthenticated CLI), suggest pull-request mode and never fall through to local mode on your own. Never record a mode the user did not give. Record the answer with flow's block helper on that line, touching nothing outside the block's markers, in its own commit on the branch being built; without a Flow block, the answer holds for this run only.

• Pull-request mode: tasks are sub-issues of the spec issue, listed as a checklist in the spec's Tasks section; the work is delivered as one pull request.
• Local mode: no pull requests, issues, or remote required; tasks live only as the spec's Tasks checklist, and build reviews the spec branch and merges it into local main (see Deliver); ship publishes it.

Task set

"Build it" on a spec's task set makes this session the orchestrator on one spec branch; it may run in a worktree of the spec branch so the primary checkout stays on the default branch. In pull-request mode the tasks are sub-issues of the spec issue; in local mode they live only in the spec. Either way the spec's Tasks section is a checklist, - [ ] NN: Title (#N) (no issue number in local mode). Without a task set, build the current work as described above.

1. Plan. Read every task, its blocking edges, and its Area: line (a package or directory). Stop before any work on a cycle or a blocker that does not exist. The frontier is the tasks whose blockers have all integrated. Report the tasks, the delivery mode, whether checkpoints wait, and the limits (the host's concurrency limit and 2 fix rounds per task), then start with no confirmation. Suggest the host's autonomous permission mode when it has one (for example Claude Code auto mode). A task that drifts from its stated scope stops for the user's yes.
2. Run the frontier (fan-out rule: write-agents Workers): start a worker for every frontier task at once, up to the host's concurrency limit. Create each task's worktree yourself from the current spec-branch head, as a sibling of the primary checkout: git worktree add <sibling-path> -b <task-branch> <spec-head>. Do not rely on the host's worktree isolation, which may cut from the default branch. Record each worktree path, task branch, and the <spec-head> it started from; this is the worker list. The worker works only in its worktree. Tasks whose areas intersect run one after another; a task without an Area: line runs alone. Never let two workers edit the same files. When a task integrates, immediately start every task it unblocks; never wait for the other running tasks to finish.
   • Brief. Give each worker context pointers, not copies: the spec path, its task's sub-issue (or Tasks entry in local mode), and the files relevant to it, its worktree path and branch, and the board record command with its path (see Board states) so it records its own task's state. Each worker implements its task with this skill, without delivering it.
   • Worker checks. A worker runs only the tests for what it changed, then self-checks its diff against the task. A failure or gap is a fix round (see Deliver), then the task is reported as failed.
   • Shared files. Files the project's instructions tell every session to append to (for example a prompt log) are written only by the orchestrator, which commits their appends on the spec branch (see Deliver › Shared files); the orchestrator names them in each worker's brief, and workers leave them untouched.
3. Integrate finished tasks as they arrive, in integration batches (the tasks merged since the last suite run).
   • Ancestry. Before merging a task, check git merge-base --is-ancestor <spec-head> <task-head> with the <spec-head> recorded for it; a task that fails the check is not merged and goes back to its worker as a fix round.
   • Merge each into the spec branch with git merge --no-ff; a merge conflict goes back to that task's worker as a fix round.
   • Suite. Run the full local check suite once per batch; on a failure, bisect to the task that caused it and send it back to that worker as a fix round.
   • Tick. Once the batch passes, for each task: tick its checklist entry, appending — <short-sha> of its integration merge commit, linked to its commit page when a remote exists (for example - [x] 01: Title (#N) — a1b2c3d), in both modes; a squash-merging repository keeps task SHAs reachable only through the pull request. In local mode also tick its acceptance checkboxes and set its Status: to done with the same — <short-sha> when the spec holds them. Then clean up.
   • Status. When every task has integrated and the spec is accepted (the accepted label on its spec issue, or Status: accepted in local mode), set its Status: to implemented in that same batch; never on a spec that is not accepted. In pull-request mode, re-sync the spec issue as to-spec describes and push the spec branch; local mode pushes nothing.
   • Cleanup. Remove only worktrees on the recorded worker list. Delete a task branch only when it is an ancestor of the spec branch head, with git branch -d, never -D or --force (a checked-out branch cannot be deleted). Keep dirty or non-qualifying worktrees and branches, and report them.
   • Draft pull request. In pull-request mode, after the first integration, open a draft pull request with a Conventional Commits title, a link to the spec file, a Closes #N line for each task already integrated, and a Refs #N line for the spec issue and every other sub-issue. Each later integration switches that task's line to Closes #N; the spec issue's line becomes Closes #N once every task has integrated.
   • Failures. A failed or stuck task keeps its worktree and branch, and stops its dependents, which wait for the user's decision and are not runnable until then: report it with evidence and its worktree path, and keep the rest of the frontier moving.
4. Checkpoint once per integration batch: post tasks integrated, running, and blocked with one-line reasons, noting dependents that wait for the user's decision and the worktree paths kept for failed tasks; the local suite commands and result; the commit SHA; and screenshots of changed screens when a browser tool is available, otherwise say there are none. Pull-request mode posts it as a pull request comment; local mode reports it in the conversation. Checkpoints never wait for CI or the user, unless the user asked to wait at checkpoints. CI runs on every push, but intermediate pushes are never waited on.
5. Finish once no runnable task remains, reporting dependents still waiting for the user's decision. In pull-request mode, wait for the final pull request's checks with fix rounds (see Deliver steps 5 and 6), then mark the draft ready for review and stop there: merging is ship's job, after the one independent review per spec. In local mode, once every task has integrated and the full local check suite passes, land the spec branch on local main as Deliver › Local mode describes (gate, review, --no-ff merge, cleanup); nothing is pushed, and a failed or stopped task leaves main untouched.

Gates: the full local suite passes for each integration batch, the final pull request's checks are green, branch protection is respected. Without independent workers, run the frontier tasks in dependency order on the spec branch. Report checkpoints posted, tasks integrated, tasks blocked and why, worktrees removed and kept, the limits used, and the pull request with its checks and links (local mode: the review result and the merge commit on local main).

Board states. Record live task states with node <board>/scripts/board.mjs, where <board> is the board directory next to this skill's directory; if that script is missing, skip recording. The orchestrator records the run; each worker records its own task's state (the script locks concurrent writes).

• When the run begins: --record run-start --spec <NNN> --branch <spec branch> --mode <local|pull-request> --tasks <01,02,…>.
• As each task starts, changes state, and integrates, and again for every unfinished task at each checkpoint and at least every 10 minutes while workers run (a heartbeat): --record task --task <NN[,NN…]> --state <state> [--round <n>] [--note "<one line>"]. States follow the frontier: running, integrated, blocked (failed, or stopped behind a failed task until the user decides), and waiting (blockers not yet integrated).
• When the set finishes or stops: --record run-end.

Recording is best-effort: a failed record never stops or delays the run.