Architect

Role

The Architect owns the PLAN state. It receives the Captain’s sprint brief and produces the technical plan that the Builder agents execute. The Architect does not write production code — it writes the plan that guides those who do.

A good Architect plan is detailed enough that a Builder agent can implement each task without needing to make architectural decisions. Ambiguous plans produce bad builds.

Responsibilities

• Task decomposition — break the sprint goal into discrete, independently implementable tasks
• Data model design — specify schema changes (new tables, columns, indexes, migrations)
• Component mapping — identify new and modified components, their interfaces, and their dependencies
• API contract definition — specify new endpoints, request/response shapes, and error codes
• Technology selection — choose libraries and patterns consistent with the existing codebase
• Mandate compliance — ensure the plan satisfies all active mandates before BUILD starts
• Dependency ordering — sequence tasks so no Builder blocks another

Skills

Skill	Description
codebase.analyze	Reads the working tree to understand existing patterns and conventions
schema.design	Generates SQL migration files and TypeScript type definitions
plan.write	Produces the structured TechnicalPlan object
mandate.validate	Runs mandate checks against the plan before BUILD
api.contract	Generates OpenAPI-compatible endpoint specs

When dispatched

• PLAN: after Captain + Navigator complete THINK

Inputs (handoff packet)

{
  parsedGoal: ParsedGoal;          // from Captain
  dependencyAnalysis: DepAnalysis; // from Navigator
  mandates: MandateSnapshot;
  workingDirectory: string;        // path to the git worktree
  existingSchema: string;          // current DB schema (auto-provided)
  existingRoutes: string[];        // current API routes (auto-provided)
}

Outputs

The Architect produces a TechnicalPlan:

interface TechnicalPlan {
  tasks: Task[];
  schemaMigrations: Migration[];
  newComponents: ComponentSpec[];
  modifiedComponents: ComponentSpec[];
  apiContracts: EndpointSpec[];
  testPlan: TestPlan;
  mandateCompliance: MandateComplianceReport;
}

interface Task {
  id: string;
  title: string;
  description: string;
  assignedAgent: 'builder' | 'ambassador';
  dependsOn: string[];             // task IDs
  files: string[];                 // files to create or modify
  estimatedTokens: number;
  acceptanceCriteria: string[];
}

Sample plan output

{
  "tasks": [
    {
      "id": "task-1",
      "title": "Add profile table migration",
      "description": "Create user_profiles table with columns: user_id, display_name, avatar_url, updated_at. Add foreign key to users table.",
      "assignedAgent": "builder",
      "dependsOn": [],
      "files": ["supabase/migrations/20260505_add_user_profiles.sql"],
      "estimatedTokens": 8000,
      "acceptanceCriteria": [
        "Migration runs cleanly on fresh DB",
        "Rollback migration also included",
        "RLS policies: users can read their own row; no public read"
      ]
    },
    {
      "id": "task-2",
      "title": "UserProfile React component",
      "description": "Create src/components/UserProfile.tsx. Props: userId. Fetches profile via Supabase client. Renders avatar, display name (editable inline on click), and ActivityFeed.",
      "assignedAgent": "builder",
      "dependsOn": ["task-1"],
      "files": ["src/components/UserProfile.tsx", "src/components/UserProfile.test.tsx"],
      "estimatedTokens": 24000,
      "acceptanceCriteria": [
        "Renders avatar from avatar_url; shows initials fallback",
        "Display name editable inline; saves on blur",
        "Loading and error states handled",
        "Test coverage >= 80%"
      ]
    }
  ]
}

Sample system prompt excerpt

You are the Architect agent for Defiant 2.0.

You are in the PLAN state. Your job is to produce a complete, unambiguous technical
plan for the Builders to execute.

Sprint brief:
<brief>{{ sprintBrief }}</brief>

Existing codebase structure:
<codebase>{{ codemapSummary }}</codebase>

Current DB schema:
<schema>{{ currentSchema }}</schema>

Active mandates:
<mandates>{{ mandateList }}</mandates>

Requirements for your plan:
- Every task must be independently implementable. No task may depend on uncommitted
  work from another task except via its explicit dependsOn ordering.
- Specify exact file paths for every file to create or modify.
- Include a test file for every new component or module.
- Validate your plan against all active mandates before returning it.
  If any mandate would be violated, revise the plan or flag it as a blocker.
- Do not invent features not in the sprint brief.

Mandate validation at plan time

Before the Architect produces its final plan, it runs a mandate preflight. Any blocking mandate violation halts BUILD before it starts:

# Architect runs internally:
defiant mandates check --plan /path/to/plan.json

# Example output:
# [PASS] mandate_1: AI-native baseline
# [PASS] mandate_7: Security baseline
# [FAIL] mandate_8: Dependency hygiene — plan includes 'gpl-library@1.2.3' (GPL license)
# Result: BLOCKED — resolve mandate_8 violation before BUILD

Failure modes

• Underspecified plan: Architect requests more information via inbox item rather than guessing
• Mandate violation: plan is revised or sprint is blocked before Builder is dispatched
• Schema conflict: if the proposed migration conflicts with the existing schema, Architect flags it for human review