Project Configuration

One policy file

blueprint/config.json contains deterministic workflow settings shared by every installed adapter. It is user-owned, so Blueprint updates preserve it. A missing file uses the built-in defaults.

Read-only status reports invalid configuration and falls back safely. Commands that change project state stop and point to /doctor instead of guessing.

Available settings

Review cadence and checkpoints are separate

workflow.stepReview controls when you approve implementation:

• feature lets the agent implement and verify the small spec steps, then presents one complete feature-level review packet.
• every pauses after every step for your approval before continuing.

Both values end with the same optional read-only walkthrough of the completed code. The setting changes approval cadence, not whether Implement explains the result.

workflow.checkpointCommits controls whether Implement offers an optional checkpoint commit after an approved step. It does not control review cadence, and checkpoint prompts occur only with per-step review.

Setting only stepReview to every restores per-step approval pauses. It does not restore checkpoint prompts. To match the previous Blueprint workflow exactly, use both settings:

"workflow": {
  "stepReview": "every",
  "checkpointCommits": "enabled"
}

The lower-context default for new projects is feature plus disabled. Existing projects keep their user-owned configuration during an update.

Local merge or pull request landing

git.landing controls how /complete offers to land finished regular work. The default local-merge value keeps the local squash-merge flow. Use pull-request when the default branch is protected or several developers or agents are working in isolated checkouts:

"git": {
  "landing": "pull-request"
}

In pull-request mode, Complete requests approval to push the work branch and open a pull request against the confirmed remote default branch. That approval does not approve the pull request merge. After the provider reports a squash merge, run Complete again so it can verify the result and offer local cleanup.

Parallel work does not add a separate team mode or per-item state folders. Give each work item its own clone or Git worktree and dedicated branch. Each checkout then has its own current feature, findings, and review state. Never run two active work items in the same working directory.

See Working With Multiple Developers for the full clone, worktree, branch, and landing workflow.

This setting applies only to regular Complete runs. Continuous Mode remains a serial, local-only workflow and ignores git.landing.

Onboarding presents three friendly choices:

These are presets, not another stored mode. Blueprint writes only the two low-level settings shown above. You can edit either value at any time, and the next Implement run reads the current configuration.

Quality gate modes

Independent review defaults to when-sensitive for regular and Continuous work. Audit and Check default to manual. Try guide defaults to when-testable, which produces one small Try It Now proof only when the work has a safe, meaningful direct observation. Sensitive or unusually broad work therefore selects independent review automatically, while ordinary small work does not.

• when-sensitive audits or independently reviews work involving security boundaries, user data, payments, secrets, migrations, destructive operations, external effects, or unusually broad changes.
• when-behavioral checks work that needs observed runtime behavior, such as a click, request, download, command, or multi-screen flow.
• when-testable creates Try It Now for CLI, library, API, UI, generated-file, configuration, or data changes with a safe direct observation. It skips documentation-only and invisible internal work instead of inventing a path.
• when-user-facing creates a manual try guide for UI, CLI, public API, output, and other workflows a person directly uses.
• always applies that gate to every work item in the selected workflow.

qualityGates.regular applies to the normal workflow and Autopilot. qualityGates.continuous applies to each feature in Continuous Mode.

When Audit and independent review are both selected, the fresh independent pass satisfies Audit. It does not run a second builder-session audit over the same checkpoint.

Review selection and execution are separate

The independent-review quality gate decides when review is required. Set it to manual to disable automatic selection for that workflow, or use /audit independent current whenever you explicitly want an independent pass.

review.independentExecution decides how a selected review runs. The default, automatic, uses an isolated reviewer in the current runtime when the adapter can prove fresh context, its exact reviewer identity and model, and completion. If it cannot, Blueprint preserves the review request and stops with the manual fresh-session handoff. Set the value to manual when you always want that handoff.

Automatic review uses the Audit skill and review contract installed in the project. It does not discover or depend on global agent roles or another workflow. Requests record the selected execution method, and completed receipts record what actually ran.

Boundaries configuration cannot change

Configuration never grants permission to commit, merge, push, deploy, publish, send, delete data, waive a failed check, or accept a finding. Those actions keep their normal approval and safety gates.

Commands stay in AGENTS.md, communication preferences stay in blueprint/context/ai-interaction.md, and installed-version metadata stays in blueprint/.state/manifest.json.

The existing tryGuide quality-gate keys select /check guide. Their names remain unchanged for compatibility, and manual, when-user-facing, and always remain valid. A generated guide does not count as executed verification.