Core Workflow

Visual overview

The fresh-project loop starts with /onboard, turns your plans into the project overview, then repeats through spec, implementation, proof, review, and completion. Write the plans directly or optionally run /discovery for a deep planning conversation. For existing apps, start with Existing Codebase instead of /onboard.

Explore an idea

Use Explore to investigate a possible change without creating plans or editing files. Use Brief when you want an explanation of an existing build-plan item. The command guide helps choose among neighboring commands.

Establish the plan

You own project-plan.md and build-plan.md. The overview step checks those inputs and generates compact project context that workflow skills load on demand.

write plans directly ---------------------------> /overview
optional /discovery -> review + approve plans -> /overview

Both paths produce the same user-owned planning files. Discovery never runs from onboarding and never becomes a gate before Overview.

Before Feature 1, an eligible initial Overview run offers to create chore: establish Blueprint project baseline. The agent shows the candidate diff and waits for approval, keeping installation and planning separate from the first feature commit. It does not offer this for local-only installations, later Overview reruns, or a working tree that would mix in unrelated application work.

Configure shared workflow policy

blueprint/config.json keeps deterministic workflow preferences consistent across every adapter. It controls review cadence, checkpoint commits, branch prefixes, verification strictness, regular and Continuous quality gates, and Continuous Mode limits. Independent review defaults to when-sensitive for regular and Continuous work, while Audit and Check default to manual. Try guide defaults to when-testable, which adds a compact Try It Now proof only when the work has a safe direct observation. Independent review execution defaults to an isolated reviewer with a manual fresh-session fallback when the active adapter cannot prove that path.

New projects use one feature-level implementation review packet and disable step checkpoint commits. stepReview: "every" restores approval after every step, but the previous workflow’s checkpoint prompts return only when checkpointCommits: "enabled" is set too. These are separate settings. Both review styles end by offering the same read-only walkthrough of the completed code.

Onboarding can explain and update selected values. See Project Configuration for the complete schema and the approval boundaries configuration cannot change.

Run overview again whenever the plans change materially, including when you add a feature after the initial build.

Set up shared verification separately

Automatic GitHub checks are optional setup, not another stage inside every feature. Run $ci or /ci after onboarding or adoption when the project should use one documented Verify command locally and in GitHub Actions.

/onboard or /adopt -> /ci -> Verify locally -> GitHub runs Verify

Verify combines only configured checks in order: typecheck, tests, then build. If you later run /tests, it adds the real test command to an existing Verify recipe without creating CI by itself.

Repeat for each feature

The everyday workflow keeps one active scope at a time in each checkout:

/feature -> /implement -> /check -> /audit current -> /complete

Feature still stops for spec approval. Audit is shown as a useful review step; this teaching path does not change configured gates or require a manual audit on every feature.

The normal workflow stops for approval after Feature writes the spec. Implement then builds that approved scope using the configured review cadence. After Verify and any required Check pass, the default try-guide policy adds one ## Try it now command or interaction when the change can be directly observed. The final packet includes that proof and always offers a code walkthrough organized around the spec’s build steps. /check guide remains separate from the code walkthrough because it explains how to review the product, not how the code works.

Before landing, /audit current can review the builder’s delta in the same session. /audit independent current instead creates a checkpoint-bound request for an isolated reviewer or a manual fresh-session handoff. Sensitive or unusually broad work selects that independent review by default; ordinary small work does not. A required or started independent review must have a current passing receipt before Complete can merge.

Work in parallel with isolated checkouts

Parallel work uses normal Git isolation rather than a separate Blueprint team mode. Give each developer or agent its own clone or Git worktree, then create one dedicated branch and active work item in each checkout. This keeps current-feature.md, findings, and review evidence isolated until the branches land.

Set git.landing to pull-request when those branches should go through the hosting provider instead of being merged locally. Complete requests approval to push the work branch and open its pull request, but never treats that as approval to merge. Parallel branches can still touch build-plan.md, so the later pull request may need a normal Git conflict resolution after an earlier feature lands.

The default local workflow is unchanged. Do not run two active work items in the same working directory. Follow Working With Multiple Developers for the complete setup and landing flow. See Project Configuration for the setting schema.

If a bug or small request is not in the build plan, use /fix instead of /feature.

If you know something is failing but do not yet know why, start with /debug. It reproduces and traces the failure without editing the project. A confirmed problem then returns to /implement when it belongs to active work, or /fix when it is a standalone bug.

Run the remaining plan continuously

$continuous or /continuous is an explicit alternative when you want to run multiple planned features without the normal step pauses:

/continuous -> next unchecked feature -> local completion -> repeat

The build plan is the queue, so no feature list is required. Each feature keeps its own branch, verification, archive, and one clean local main commit. The run stops on decisions, unsafe state, failed checks, or unresolved serious findings, and it never pushes. See Continuous.

Continue after the initial build

build-plan.md remains the ordered roadmap after the first release. Keep completed items checked, preserve their numbers, and add new unchecked features under the current list or a milestone heading such as ## Post-MVP.

The continuing loop is:

add feature to build-plan.md -> /overview -> /feature -> /implement -> /check -> /complete

Most incremental features change only the build plan. Update project-plan.md too when the new capability changes the product direction, users, data, stack, monetization, UI/UX, or deployment.

If you run /feature "new capability" and no planned item matches, the skill offers to add it. It shows the proposed plan changes first, waits for approval, refreshes the overview, and then creates the spec. It checks for near-duplicates before adding anything and keeps /fix as the path for bugs or small ad-hoc changes.

Reverse a completed feature

Use /rollback <feature> when shipped work needs to be removed. Rollback matches the checked build-plan item to its archived spec and exact git commit, reviews later commits for dependency risk, then writes a guarded rollback spec and stops.

/rollback 4 -> review risk + spec -> /implement -> /check -> /complete

Implementation reverses only the approved product diff on a rollback/ branch. Blueprint plans, context, adapters, and history are protected. Completion keeps the original feature archive, adds a separate rollback record, and unchecks the build-plan item so the roadmap reflects that the capability is no longer present. See the Rollback command for the conflict and data safety boundaries.

Keep human gates visible

The workflow deliberately pauses before application code and before merging. A feature spec is cheaper to change than a large diff, and a diff is cheaper to change than a broken main branch.

Autopilot is an explicit opt-in for one bounded feature or fix pass. It combines spec creation and implementation, continuing through the normal spec-approval stop. It uses Verify and the configured regular quality gates, repairs confirmed high-severity findings when its audit gate runs, and delays the human review packet until the pass ends. It does not run rollbacks or merge.

Continuous Mode is explicit opt-in for the remaining planned feature queue. It uses the configured Continuous quality gates and can complete the local branch, archive, and merge lifecycle for each feature. Neither mode can push, deploy, publish, send, perform destructive actions, waive checks, or make product decisions for you.

Resume from files

The current feature checklist records completed steps. Git records code and any enabled checkpoint commits. After a context clear, $status or /status can determine the exact next action without reconstructing the project from conversation history.