Blueprints

What Is a Blueprint?

A blueprint is a YAML file that defines a workflow — a sequence of steps that Tack executes to turn an objective into merged code. You do not need to write blueprints to use Tack (it ships working defaults), but understanding them helps you customize the workflow.

The key idea: blueprints make the workflow explicit and inspectable. Every step is declared in YAML. You can see exactly what will happen, in what order, and what happens when things fail.

Blueprint Identity

Every blueprint has an id. This is the public identity used when selecting a blueprint — filenames are organizational only.

id: build-review
name: Build and review

Two blueprints with the same id are the same blueprint, regardless of their filenames. This is how overrides work.

Step Types

Default Blueprints

Tack ships two blueprints that work together:

standard — The Top-Level Workflow

This is what runs when you submit an objective. It handles the full lifecycle:

id: standard
default: true
steps:
  - id: plan
    type: agent
    role: planner
    next: approve

  - id: approve
    type: human
    next: execute

  - id: execute
    type: blueprint_ref
    ref: build-review
    foreach: work_item
    on_work_item_failure: escalate

  - id: merge
    type: deterministic
    action: merge_queue

  - id: pr
    type: deterministic
    action: create_pr

  - id: complete
    type: deterministic
    action: mark_complete

The foreach: work_item on the execute step is what makes streams run in parallel — each work item (stream) gets its own execution of the build-review blueprint.

build-review — The Per-Stream Workflow

This runs for each stream independently:

id: build-review
name: Build and review

retry:
  profile: self_healing

steps:
  - id: build
    type: agent
    role: builder
    commit: auto
    messages:
      commit: true
    next: lint

  - id: lint
    type: deterministic
    action: run_quality_gates
    retry:
      max_attempts: 2
    on_fail: build
    max_fix_iterations: 3
    next: review

  - id: review
    type: agent
    role: reviewer
    commit: none
    on_fail: build
    max_fix_iterations: 3
    next: merge_ready

  - id: merge_ready
    type: deterministic
    action: signal_merge_ready

Walkthrough of the steps:

1. build — the builder agent implements the stream's task and commits
2. lint — quality gates run; on failure, jump back to build with the gate output (up to 3 fix iterations)
3. review — the reviewer agent checks the implementation; on rejection, jump back to build with feedback (up to 3 fix iterations)
4. merge_ready — signals that this stream is ready to merge

Customizing Blueprints

You can override shipped blueprints or add new ones. Place files in .tack/blueprints/ (per-project) or ~/.config/tack/blueprints/ (per-user).

Blueprints override by id, not filename. To replace the shipped build-review, create a file with id: build-review:

# .tack/blueprints/review-lite.yaml
id: build-review
name: Review lite — skip review for faster iteration

retry:
  profile: balanced

steps:
  - id: build
    type: agent
    role: builder
    commit: auto
    next: lint

  - id: lint
    type: deterministic
    action: run_quality_gates
    retry:
      max_attempts: 3
    on_fail: build
    max_fix_iterations: 5
    next: merge_ready

  - id: merge_ready
    type: deterministic
    action: signal_merge_ready

This version drops the review step entirely. The blueprint id is still build-review, so it replaces the shipped workflow for this project.

See Custom Blueprints for more examples.

Default Resolution

When an objective starts, Tack resolves which blueprint to use:

1. If the objective explicitly requested --blueprint <id>, use that
2. Otherwise, if exactly one blueprint is loaded, use it
3. Otherwise, exactly one loaded blueprint must set default: true

If no default exists or multiple blueprints claim default, Tack returns an error. Fix this by either passing --blueprint explicitly or ensuring exactly one blueprint has default: true.

Step Options Reference

Agent Steps

Deterministic Steps

Blueprint Reference Steps

Retry Profiles

Blueprints can set a retry profile that controls the recovery posture:

retry:
  profile: self_healing
  default_max_attempts: 4
  default_on_exhausted: ask_human

See Recovery & Retries for how retry profiles map to failure kinds and recovery actions.