Workflow

Project setup comes first. For each piece, you then agree on the scope, build, review and merge the change. Hosting is set up once, and maintenance continues over the life of the project.

1. Set up a project/setup-ai-build-kit
2. Shape a piece/shape
3. Implement a piece/implement
4. Review the change
5. Merge the change
6. Set up or check the live tool/setup-hosting
7. Maintain the project/maintain

Set up a project

Setup checks the tools and access needed to prepare the project.

What you decide

You answer the interview questions and decide whether to use existing work.

See checks for this step

Checks and source details

Command

/setup-ai-build-kit

Supporting skills (instructions for the agent)

• clarify
• fit-check
• second-opinion
• records
• merge

Checks

check-tooling.sh: The tooling check reports whether required tools and GitHub access are available before building begins.

use-push-guard.sh: The agent enables Git’s pre-push hook, which blocks direct pushes to the main branch.

protect-branch.py: Branch protection requires the project check to pass on GitHub where your plan supports it.

first-upload.py: The first upload requires your approval.

checks.yml: Without a selected recipe, the initial project check deliberately fails until the agent replaces the placeholder with real project tests.

check.yml: Recipe projects skip the placeholder and use the starter's recipe-check workflow for application checks.

Source skill (for maintainers)

Workflow stages

1. Set up a project
2. Shape a piece
3. Implement a piece
4. Review the change
5. Merge the change
6. Set up or check the live tool
7. Maintain the project

Step by step

Set up a project

What happens: You describe the tool and answer setup questions. The agent prepares the project.

Checks and mechanisms:

• The tooling check reports whether required tools and GitHub access are available before building begins.
• The agent enables Git’s pre-push hook using this script. The hook blocks direct pushes to the main branch.
• Branch protection requires the project check to pass on GitHub where your plan supports it.
• The first upload requires your approval.
• Without a selected recipe, the initial project check deliberately fails until the agent replaces the placeholder with real project tests. Recipe projects skip that placeholder and use the starter’s recipe-check workflow for application checks.

What you decide: You answer the setup questions and decide whether to use existing work.

Why: The project needs the tools and accounts assessed during setup before work can begin (design reasons).

Shape a piece

What happens: You and the agent define one piece and agree on its acceptance criteria.

Checks and mechanisms:

• The readiness script adds the ready label only when the piece has acceptance criteria under “Done when”, records its risk areas and records decisions for any open-question labels. Projects with code also require a Reaches line describing the proposed scope.
• The reach check identifies the files the piece may affect.
• The agent gives a risk notice for work touching a risk area whose precaution has not been completed and whose risk has not been accepted, and records your decision and the date.

What you decide: You settle the questions that need your judgement, then decide whether to ask /implement to build the ready piece.

Why: You agree on the intended result and resolve open questions before the agent starts building (design reasons).

Implement a piece

What happens: The agent builds one ready piece on its own branch.

Checks and mechanisms:

• The test protection check rejects unexplained edits to tests frozen by a Test: commit.
• The test evidence check reports tests for the change that already passed beforehand and acceptance criteria without matching tests. Criteria marked for you to try are excluded from the automated test mapping.
• The structure script reports new circular dependencies, where parts of the code depend on each other in a loop. Boundary crossings are checked separately, using the project’s tools or an examination of the changed dependencies.
• The clean-up script refuses to save a clean-up that changes tests or their supporting files.
• In Claude Code, the secret protection hook blocks commands that match its secret-detection rules.
• The repair reset script removes a failed repair before the next attempt, so failed fixes do not accumulate.

What you decide: By default, you try the result and approve the named pull request. Automatic merging is off until you enable it. It requires three previous merges with recorded approvals and a dated “Runs on its own:” decision in the masterplan, and applies only within its recorded limits.

Why: Scripts check rules with testable conditions; written instructions guide decisions requiring a person’s or an agent’s judgement (design reasons).

Review the change

What happens: A reviewer agent assesses the change and its evidence in a separate session, without the builder’s conversation history.

Checks and mechanisms:

• The review packet contains the change and supporting evidence. The review record identifies the version reviewed.
• The review protection script restores changed or deleted files that it copied before the review; it reports other changes without restoring them.
• The review check fails the project check while a blocking finding remains unresolved or the review record identifies a different version.
• The review is marked “unverified” unless a different GitHub login has approved the version reviewed.

What you decide: You can ask the agent to explain a finding. The reviewer agent marks whether a finding should stop the merge.

Why: The review gives you evidence about the change without asking you to read its code. Each report says what the agent tried and what happened (design reasons).

Merge the change

What happens: The agent asks you to approve the named pull request. A merge script then merges that change.

Checks and mechanisms:

• The merge script requires your recorded approval unless you have enabled automatic merging. It merges only the version that was checked.
• It stops when the project check is missing, failed or did not run. The billing-only fallback permits an approved merge only after the local check passes for the exact commit. Other checks that failed or did not run still hold the merge.
• It stops when a blocking review finding remains unresolved or the review identifies another version.
• The risk-area check reports the areas affected by the change and blocks merging while a risk decision remains unresolved.
• For a live project, the settings script identifies new settings in .env.example. The agent waits for hosting setup to confirm them before requesting a merge.

What you decide: You approve the named pull request. Each approval authorises one merge and can be used only once.

Why: You decide whether to merge the change into the main branch. The merge script verifies your recorded approval and the project check results (design reasons).

Set up or check the live tool

What happens: The agent sets up hosting or checks the live tool.

Checks and mechanisms:

• On a supported recipe, the launch script requires a confirmed backup. Later launches also require a confirmed earlier build for rollback; a first launch requires a defined rollback step. With no recipe, the script gives a one-time notice that it cannot run the recipe checks.
• Before a live change, the approval script verifies that an unused approval names that exact change.
• The live check compares the live version with the main branch on Vercel or Coolify without changing the live tool.
• The recipe validator rejects recipes missing a rollback, backup or restore section.

What you decide: You decide whether to launch after the agent explains the live change.

Why: Hosting recipes define the launch, backup and rollback steps; outside one, the kit provides no guarantees (design reasons).

Maintain the project

What happens: The agent checks project records and the live tool, then handles upkeep that is due.

Checks and mechanisms:

• The live check runs at every maintenance visit.
• The update check lists the follow-up work that maintenance needs to complete after a kit update.
• The recipe freshness check reports recipes missing from the current menu, recipes last checked more than 90 days ago, and superseded settings still used by the project.
• The branch report lists branches whose work has already been merged into the main branch. It deletes nothing.
• The instruction length check reports when the standing instructions reach 200 lines.
• The Claude Code settings script offers updated Claude Code safety rules and applies them only with your approval.

What you decide: You decide whether to apply changes beyond routine updates.

Why: Records and the live tool can change over time, so the agent rechecks them during maintenance (design reasons).