Skip to content
Defiant

Quickstart

This guide walks you from zero to a completed sprint in about 15 minutes. You’ll create a project, define a sprint goal, and watch the Conductor dispatch agents to plan and build it.

Before you start

  • Defiant CLI installed and defiant config check passes
  • Conductor running (defiant watch status shows running)
  • A GitHub repository the CLI has access to

Step 1 — Create a project

A project maps to a GitHub repository. Create one:

Terminal window
defiant projects create \
  --name "my-app" \
  --repo "github.com/yourorg/my-app" \
  --vertical solo-founder

The --vertical flag loads the Solo Founder mandate pack. Other options: b2b-saas, marketplace, fintech, healthcare, pe-portfolio.

List projects to confirm:

Terminal window
defiant projects list
# ID                                   NAME       REPO                      VERTICAL
# proj_01hwabcdefg0000000000000000     my-app     yourorg/my-app            solo-founder

Step 2 — Create a sprint

A sprint has a goal written in plain language. The agents interpret it; you don’t need to specify tasks.

Terminal window
defiant sprint create \
  --project proj_01hwabcdefg0000000000000000 \
  --goal "Add a user profile page that shows avatar, display name, and recent activity feed. Users can edit their display name inline."

The Conductor assigns a sprint ID and immediately transitions to INTAKE:

[Sprint] Created: spr_01hwxyz0000000000000000
[Sprint] State: INTAKE
[Agent:captain] Dispatched — reviewing goal and assembling agent team

Step 3 — Watch it run

Tail the sprint log in real time:

Terminal window
defiant sprint status spr_01hwxyz0000000000000000 --follow

You’ll see the state machine progress:

[Sprint] INTAKE → THINK
[Agent:captain] Goal validated. Complexity: medium. Estimated: 2 agents, ~45 min.
[Sprint] THINK → PLAN
[Agent:architect] Dispatched — generating technical plan
[Agent:navigator] Dispatched — checking dependencies and constraints
[Agent:architect] Plan complete: 4 tasks, 2 new components, 1 DB migration
[Sprint] PLAN → BUILD
[Agent:builder] Dispatched — task 1/4: UserProfile component
[Agent:builder] Dispatched — task 2/4: ActivityFeed component
[Agent:builder] Task 1 complete — PR #42 opened
[Agent:builder] Task 2 complete — PR #43 opened
[Sprint] BUILD → SHIP
[Agent:reviewer] Dispatched — reviewing PRs #42, #43
[Agent:guardian] Dispatched — security scan on PRs #42, #43
[Agent:reviewer] Approved PR #42 — 2 comments addressed
[Agent:reviewer] Approved PR #43 — clean
[Agent:guardian] No security issues found
[Sprint] SHIP → COMPLETE
[Agent:scribe] Dispatched — updating Asana tasks
[Sprint] COMPLETE ✓ — elapsed: 38m

Step 4 — Review the output

Check what was produced:

Terminal window
defiant sprint status spr_01hwxyz0000000000000000
Sprint:    spr_01hwxyz0000000000000000
Project:   my-app
Goal:      Add a user profile page...
State:     COMPLETE
Started:   2026-05-05T14:00:00Z
Finished:  2026-05-05T14:38:22Z
Agents:    captain, architect, navigator, builder (x2), reviewer, guardian, scribe
PRs:       #42 (merged), #43 (merged)
Tokens:    182,304 used

The Builder opened PRs in your repository. The Reviewer and Guardian checked them. If all checks passed, they were merged automatically. If any check failed, the sprint lands in a BLOCKED state and you get an inbox item.

Step 5 — Check the inbox

The inbox holds items that need your attention:

Terminal window
defiant inbox list
# (empty — sprint completed cleanly)

If anything was blocked:

Terminal window
defiant inbox list
# [BLOCKED] spr_01hwxyz0000000000000000 — PR #44 failing CI: test coverage below 80%
# Run: defiant inbox show <id>  to see details and options

Sprint states reference

StateWhat happens
INTAKECaptain validates the goal, checks token budget, selects agents
THINKCaptain + Navigator analyze requirements and constraints
PLANArchitect produces the technical plan with task breakdown
BUILDBuilder agents implement tasks in parallel worktrees
SHIPReviewer + Guardian audit PRs; merge if clean
COMPLETEScribe updates trackers; Conductor archives the sprint
BLOCKEDA gate failed — inbox item created, human approval needed
FAILEDUnrecoverable error — Medic has filed a report

Using the TypeScript SDK

If you prefer code over CLI:

import { DefiantClient } from '@defiant/sdk';


const client = new DefiantClient({
  supabaseUrl: process.env.SUPABASE_URL!,
  supabaseKey: process.env.SUPABASE_ANON_KEY!,
});


// Create a sprint
const sprint = await client.sprints.create({
  projectId: 'proj_01hwabcdefg0000000000000000',
  goal: 'Add user profile page with avatar and activity feed',
});


console.log(sprint.id); // spr_01hwxyz...


// Poll for completion
for await (const event of client.sprints.stream(sprint.id)) {
  console.log(event.type, event.state);
  if (event.state === 'COMPLETE' || event.state === 'FAILED') break;
}

See the TypeScript SDK reference for the full API.

Tips for writing good sprint goals

Be specific about the user experience, not the implementation:

# Good
Add a user profile page that shows avatar, display name, and recent activity feed.
Users can edit their display name inline. Changes save on blur.


# Too vague
Make a profile page.


# Too prescriptive (let the Architect decide)
Create a React component at src/components/Profile.tsx that uses useState...

Include acceptance criteria when you have specific requirements:

Add email notification preferences to the settings page.
Users must be able to toggle: marketing emails, product updates, security alerts.
Preferences persist to the database. Unsubscribe link in all emails must work.
Default: all on for new users.

Scope to one feature per sprint. Large goals (multiple pages, new auth system) are better split into two sprints so the Architect can plan each cleanly.

Next steps