Architecture Overview

Defiant is built around three interlocking systems: the Conductor (the orchestration daemon), the 14 Agents (specialized AI workers), and the Mandate System (the governance layer). A fourth concept — the Sprint State Machine — ties them together into a unit of work.

System diagram

┌─────────────────────────────────────────────────────────┐
│                      Defiant Platform                    │
│                                                         │
│  ┌──────────┐    JSON-RPC     ┌─────────────────────┐   │
│  │  CLI /   │◄──────────────►│     Conductor        │   │
│  │  SDK /   │                │  (TypeScript daemon) │   │
│  │  REST API│                │  ~/.defiant/ipc/     │   │
│  └──────────┘                │  conductor.sock      │   │
│                              └─────────┬───────────┘   │
│                                        │ dispatches     │
│                         ┌──────────────▼──────────┐    │
│                         │    Sprint State Machine  │    │
│                         │ INTAKE→THINK→PLAN→BUILD  │    │
│                         │      →SHIP→COMPLETE      │    │
│                         └──────────────┬──────────┘    │
│                                        │                │
│              ┌─────────────────────────┼──────────┐    │
│              │          14 Agents      │          │    │
│        ┌─────▼────┐  ┌────────┐  ┌────▼─────┐   │    │
│        │ Captain  │  │Builder │  │ Reviewer │...│    │
│        └──────────┘  └────────┘  └──────────┘   │    │
│                         │ write to                │    │
│              ┌──────────▼──────────┐              │    │
│              │  Git worktrees       │              │    │
│              │  ~/.defiant/         │              │    │
│              │  worktrees/<sprint>/ │              │    │
│              └─────────────────────┘              │    │
│                                                   │    │
│              ┌────────────────────────────────────┘    │
│              │  Mandate System                          │
│              │  mandate-library/*.yaml                  │
│              │  Checked at: plan time + commit time     │
│              └─────────────────────────────────────────┘
└─────────────────────────────────────────────────────────┘

The Conductor

The Conductor is a long-running TypeScript process that starts with defiant watch start. It:

• Listens on a Unix socket at ~/.defiant/ipc/conductor.sock for JSON-RPC commands
• Maintains an append-only SQLite event log at ~/.defiant/events.db
• Drives the sprint state machine for every active sprint
• Dispatches agents by constructing their system prompts, providing handoff packets, and calling the Anthropic API
• Enforces token budgets: 200k tokens per task, 2M tokens per day
• Manages git worktrees for build isolation

Token budget throttle states

State	Daily remaining	Behavior
green	> 1M	No restrictions
yellow	500k - 1M	Warns; favors smaller models where possible
orange	100k - 500k	Blocks new sprints; queues them
red	< 100k	Blocks all agent dispatch; only system tasks run

IPC protocol

All local tooling communicates with the Conductor over JSON-RPC 2.0 via the Unix socket:

// Example: create a sprint via IPC
const payload = {
  jsonrpc: '2.0',
  id: 1,
  method: 'sprint.create',
  params: {
    projectId: 'proj_01hw...',
    goal: 'Add user profile page',
  },
};

The REST API and CLI both use this socket. The SDK calls the REST API.

The Sprint State Machine

Each sprint is an instance of the state machine. State transitions are atomic — the Conductor writes the new state to the event log before dispatching the next agent.

INTAKE
  │  Captain validates goal, checks budget, selects agents
  ▼
THINK
  │  Captain + Navigator analyze requirements
  ▼
PLAN
  │  Architect produces technical plan with task breakdown
  ▼
BUILD
  │  Builder(s) implement tasks in parallel worktrees
  ▼
SHIP
  │  Reviewer + Guardian audit; merge if clean
  ▼
COMPLETE
  │  Scribe updates trackers; Conductor archives
  ▼
(done)

Any state → BLOCKED (gate failure, needs human)
Any state → FAILED  (unrecoverable error)

Handoff packets

At each state transition, the Conductor constructs a handoff packet — structured JSON that gives the incoming agent everything it needs:

interface HandoffPacket {
  sprintId: string;
  state: SprintState;
  goal: string;
  plan?: TechnicalPlan;        // populated after PLAN
  priorAgentSummary: string;   // what the previous agent did
  mandates: MandateSnapshot;   // active mandates for this sprint
  tokenBudgetRemaining: number;
  workingDirectory: string;    // path to the git worktree
  artifacts: Artifact[];       // files, PRs, test results so far
}

Completion certificates

Before a state transition is accepted, the departing agent produces a completion certificate — a signed JSON blob proving the work passed checks:

interface CompletionCertificate {
  agentId: string;
  sprintId: string;
  state: SprintState;
  tasksCompleted: string[];
  typecheckPassed: boolean;
  testsPassed: boolean;
  mandateViolations: string[];   // must be empty to proceed
  signature: string;             // HMAC of the above fields
}

If mandateViolations is non-empty or either boolean is false, the sprint transitions to BLOCKED rather than the next state.

The 14 Agents

Each agent is a specialized AI worker with a defined role, a set of skills, and a token budget. Agents run one at a time per task (though multiple agents can run in parallel on different tasks within the same sprint).

Agent	Primary role	Dispatched in state
Captain	Sprint coordination	INTAKE, THINK
Architect	Technical planning	PLAN
Navigator	Constraints and dependencies	THINK, PLAN
Marketer	Market and user research	THINK
Designer	UI/UX specs	PLAN
Builder	Code implementation	BUILD
Reviewer	Code review	SHIP
Guardian	Security and compliance	SHIP
Ambassador	External API integrations	BUILD
Medic	Error diagnosis and recovery	FAILED
Scribe	Documentation and task tracking	COMPLETE
Launcher	Deploy and release	SHIP, COMPLETE
Counselor	Policy and legal review	PLAN, SHIP
Commander	Multi-sprint coordination	INTAKE

See the agent pages for details on each.

The Mandate System

Mandates are YAML files in mandate-library/. Every agent must comply with all active mandates for the current project. Mandates are checked:

1. At plan time — the Architect’s plan is validated against mandates before BUILD starts
2. At commit time — the Conductor runs mandate checks before accepting a completion certificate
3. On demand — defiant mandates check runs all checks against the current working tree

mandate_7_security_baseline.yaml

id: mandate_7
name: Security Baseline
version: 1.0.0
category: security
severity: blocking

rules:
  - id: no-sql-injection
    description: All DB queries must use parameterized statements
    check: ast-pattern
    pattern: "raw_query|exec_sql"
    action: block

  - id: owasp-headers
    description: HTTP responses must include security headers
    check: file-contains
    file: "src/**/*.ts"
    pattern: "helmet|Content-Security-Policy"
    action: block

See the Mandate System docs for the full format and enforcement details.

Worktree isolation

Each sprint runs in a dedicated git worktree at ~/.defiant/worktrees/<sprint-id>/. This means:

• Multiple sprints can run in parallel without interfering with each other
• The main branch is never modified mid-sprint
• If a sprint fails, the worktree can be inspected, debugged, and re-run
• Worktrees are cleaned up automatically after COMPLETE or FAILED

Event log

The Conductor writes every significant event to ~/.defiant/events.db (SQLite, append-only):

CREATE TABLE events (
  id TEXT PRIMARY KEY,
  sprint_id TEXT NOT NULL,
  agent_id TEXT,
  type TEXT NOT NULL,       -- 'state_transition' | 'agent_dispatch' | 'mandate_check' | ...
  payload JSON NOT NULL,
  created_at TEXT NOT NULL
);

Query it directly for debugging:

sqlite3 ~/.defiant/events.db \
  "SELECT type, payload FROM events WHERE sprint_id = 'spr_01hw...' ORDER BY created_at"

Or use the CLI:

defiant sprint events spr_01hw... --type state_transition

Next steps

The 14 Agents

Deep dives on each agent’s role, skills, and dispatch conditions. Browse agents →

Mandate System

How mandates are defined, applied, and enforced. Mandate docs →

Vertical Packs

Domain-specific mandate bundles for different business models. Vertical packs →

Learning Engine

How Defiant learns from sprint outcomes to improve future runs. Learning engine →