Get started

This guide walks through installing contractor, wiring it into a project, and running a blueprint from proposal to merged branch.

Prerequisites

• Node.js ≥ 18 and a package manager (npm, pnpm, or yarn).
• A git repository. contractor runs inside the repo root and uses worktrees to isolate each in-flight change.
• Claude Code (recommended) — contractor ships slash commands that drive every phase of the workflow.

Install

Install the CLI globally:

npm install -g @soel/contractor

This gives you the contractor command.

Initialize a repo

Run these once per repository:

contractor repo install
contractor ai install

• contractor repo install creates a contractor/ directory at the project root with config.yaml, requirements/, blueprints/, archive/, and .observations/ (gitignored).
• contractor ai install installs provider slash commands (e.g. Claude Code) into .claude/commands/ so agents can invoke /contractor:propose, /blueprint:implement, and friends.

You can check which providers are available with contractor ai list.

Create your first blueprint

A blueprint is one change you want to ship. Create one with a kebab-case name:

contractor blueprint new add-search-feature

This creates contractor/blueprints/add-search-feature/ with placeholders for the four artifacts.

Check what's expected next:

contractor blueprint status --blueprint add-search-feature

Artifacts are blocked until their dependencies complete, ready when they can be written, and done once their files exist. The default schema (contractor-base) flows:

proposal → requirements + design → tasks

Fill the artifacts

The idiomatic path is to let an AI agent create the artifacts via the slash commands. From inside Claude Code:

/contractor:propose add-search-feature

This walks the four-artifact graph in order, stopping at each step so you can review before moving on.

If you'd rather drive the artifacts by hand, use contractor blueprint instructions to get the creation prompt (with full context) for any artifact:

contractor blueprint instructions proposal --blueprint add-search-feature
contractor blueprint instructions requirements --blueprint add-search-feature
contractor blueprint instructions design --blueprint add-search-feature
contractor blueprint instructions tasks --blueprint add-search-feature

Run the pipeline

Once tasks.md exists, run the pipeline to implement, review, and close the blueprint:

contractor run --blueprint add-search-feature

The default pipeline runs:

implement → review → close

• implement expands into one sub-step per incomplete task-group in tasks.md. Each sub-step runs an agent that writes code, runs the repo's verify command, iterates until green, marks checkboxes, and commits the group.
• review runs four parallel review agents (reuse, quality, efficiency, blueprint compliance) against the branch and surfaces their findings.
• close merges the branch, archives the blueprint, and folds its requirements into contractor/requirements/.

Between phases the pipeline pauses at gates for human confirmation. Approve them from the CLI or the dashboard.

Watch from the dashboard

Launch the interactive TUI dashboard to watch runs, approve gates, and inspect task-group output:

contractor dashboard

The dashboard picks up every blueprint in the current repo and shows live status for each run.

Next steps

• Concepts — understand the three loops and the artifact graph before you scale up.
• CLI reference — the full command surface, grouped by setup, blueprints, and execution.