Driver

Skill: SDLC Swarm Driver (Entry Point & Orchestrator)

Purpose

Single orchestrator for a spec-first, TDD-first, evidence-gated SDLC swarm. The Driver is responsible for:

1. Interpreting user requests and selecting appropriate workflows
2. Orchestrating agent execution in correct sequence
3. Managing state transitions and checkpoints
4. Enforcing evidence gates and approval requirements
5. Handling errors and workflow recovery
6. Providing debugging visibility into swarm operations

Inputs (REQUIRED)

• Mode: BUILD_SWARM | RUN_SDLC (determines memory routing)
• Workflow: must match .agents/registry/workflows.yaml
• Objective: Clear statement of what to build/analyze/deploy
• Constraints: Time, resources, mandatory/forbidden technologies
• EvidencePointers: Existing repo paths for context (optional)

Mode Routing (MANDATORY)

BUILD_SWARM Mode

Used when building/improving the SDLC swarm itself.

Memory Locations:

• World model: .agents/memory/world_model.yaml
• Evidence Dev: .agents/memory/evidence_dev.md
• Evidence Prod: .agents/memory/evidence_prod.md
• Decisions: .agents/memory/decisions_log.md

Use Cases:

• Creating new agent skills
• Updating swarm capabilities
• Testing swarm workflows
• Building swarm documentation

RUN_SDLC Mode

Used when building user applications/features.

Memory Locations:

• World model: .agents/user_memory/world_model.yaml
• Evidence Dev: .agents/user_memory/evidence_dev.md
• Evidence Prod: .agents/user_memory/evidence_prod.md
• Decisions: .agents/user_memory/decisions_log.md

Use Cases:

• Building user applications (APIs, CLIs, web apps)
• Implementing features in user codebases
• Refactoring user code
• Generating tests for user projects

CRITICAL: Never mix modes. Mode must be determined at workflow start and remain constant.

Position Card Schema (MANDATORY)

All agents must produce Position Cards following this exact schema:

Position Card:

• Claims: What this agent believes to be true (assertions about requirements, architecture, implementation, etc.)
• Plan: Specific actions to take (file paths, commands, dependencies)
• Evidence pointers: Concrete repo paths where evidence exists or will be created
• Risks: Potential issues, unknowns, assumptions that may be wrong
• Confidence: 0.0 to 1.0 (how certain the agent is about claims and plan)
• Cost: Low (<1 hour) | Med (1-4 hours) | High (>4 hours)
• Reversibility: Easy (no data loss, trivial rollback) | Med (some manual work) | Hard (data loss risk, complex rollback)
• Invariant violations: List any world model invariants violated by this plan
• Required approvals: List human approvals needed (security_signoff, prod_deploy, etc.)

Example Position Card:

### Position Card: PRD Agent
- **Claims**: 
  - User wants a RESTful e-commerce API with multi-tenancy
  - Requirements include JWT auth, product catalog, orders, payments
  - Success metric: API handles 100 req/sec with p95 latency <200ms
- **Plan**:
  - Create PRD.md with 18 user stories across 6 epics
  - Map to 15 enterprise invariants (INV-001 to INV-006, INV-029, INV-033-037)
  - Define NFR targets (performance, security, observability)
- **Evidence pointers**: 
  - projects/ecommerce-api/PRD.md (320 lines)
  - projects/ecommerce-api/requirements_matrix.md
- **Risks**:
  - Payment integration complexity (Stripe webhooks, refunds)
  - Multi-tenancy RLS performance at scale (>10k tenants)
- **Confidence**: 0.95 (requirements clear from user request)
- **Cost**: Low (1 hour to generate PRD)
- **Reversibility**: Easy (PRD is documentation, no code changes)
- **Invariant violations**: None
- **Required approvals**: prd_signoff (from product owner or tech lead)

Agent Invocation Protocol (CRITICAL FOR RUNTIME)

Protocol Overview

The driver orchestrates agents using a file-based, asynchronous protocol where:

1. Position cards are stored as markdown files in .agents/memory/position_cards/
2. Each agent receives input via file paths (previous position cards + context)
3. Each agent returns output by creating a new position card file
4. The driver monitors position card files and proceeds when complete

Design Rationale:

• Inspectable: All agent communication is in version-controlled files
• Debuggable: Can inspect position cards at any time during workflow
• Resumable: Workflow can resume from last checkpoint using existing position cards
• Language-agnostic: Agents can be implemented in any language (Python, TypeScript, Rust)
• Parallel-safe: Multiple agents can write position cards concurrently without conflicts

Position Card Storage Structure

Directory Structure:

.agents/memory/position_cards/<workflow_id>/
  ├── 01_driver_init.md          # Driver initialization (workflow context)
  ├── 02_prd_generator.md        # PRD Agent output
  ├── 03_stakeholder_agent.md    # Stakeholder Agent output
  ├── 04_nfr_agent.md            # NFR Agent output
  ├── 05_domain_modeler.md       # Domain Modeler output
  ├── 06_skeptic.md              # Skeptic challenge
  ├── 07_verifier.md             # Verification receipt
  ├── 08_approval_gate.md        # Approval decision
  └── 09_memory_agent.md         # Final evidence write

Workflow ID Format: <workflow_name>_<timestamp>

• Example: requirements_gathering_20260131_142300

Position Card Filename Convention: <step_number>_<agent_id>.md

• Step number: 2-digit zero-padded (01, 02, 03...)
• Agent ID: from .agents/registry/agents.yaml (e.g., prd_generator, skeptic)

Invocation Sequence (Step-by-Step)

Step 1: Driver Initialization

Trigger: User invokes workflow

Action: Driver creates workflow context file

File: .agents/memory/position_cards/<workflow_id>/01_driver_init.md

Content:

# Workflow Initialization: Requirements Gathering

## Workflow Metadata
- **Workflow ID**: requirements_gathering_20260131_142300
- **Workflow Name**: requirements_gathering
- **Mode**: RUN_SDLC
- **Timestamp**: 2026-01-31T14:23:00Z
- **User Request**: "Build user authentication system with JWT and social login"

## User Context
- **Project Path**: projects/auth-system/
- **Constraints**: 
  - Must support OAuth2 (Google, GitHub)
  - Must use bcrypt for password hashing
  - Must have MFA support
- **Budget**: $50,000
- **Timeline**: 4 weeks
- **Stakeholders**: ["Product Manager", "Tech Lead", "Security Lead", "DevOps Lead"]

## Workflow Steps
1. **driver** (current) → Initialization complete
2. **prd_generator** (next) → Create PRD with stakeholder interviews
3. **stakeholder_agent** → Gather approvals
4. **nfr_agent** → Define performance/security targets
5. **domain_modeler** → Create domain model
6. **skeptic** → Challenge assumptions
7. **verifier** → Validate evidence chain
8. **approval_gate** → Check approval requirements
9. **memory_agent** → Write to evidence ledger

## Available Context Files
- None (new project)

Driver State: Workflow initialized, ready to invoke first agent (prd_generator)

Step 2: Agent Invocation (PRD Generator Example)

Trigger: Driver determines next agent from workflow definition

Action: Driver invokes PRD Generator agent

Invocation Command (TypeScript Runtime):

// Driver invokes agent via VS Code API (or CLI if standalone)
const agentResult = await vscode.lm.invokeAgent({
  agentId: "prd_generator",
  input: {
    workflowId: "requirements_gathering_20260131_142300",
    stepNumber: 2,
    previousPositionCards: [
      ".agents/memory/position_cards/requirements_gathering_20260131_142300/01_driver_init.md"
    ],
    contextFiles: [],
    mode: "RUN_SDLC",
    expectedOutput: ".agents/memory/position_cards/requirements_gathering_20260131_142300/02_prd_generator.md"
  }
});

Agent Receives:

• workflowId: Unique identifier for this workflow execution
• stepNumber: Current step in workflow (for sequential ordering)
• previousPositionCards: Array of file paths to read for context
• contextFiles: Additional context (existing PRD, code, etc.)
• mode: BUILD_SWARM or RUN_SDLC (determines memory routing)
• expectedOutput: File path where agent must write its position card

Agent Processing:

1. Read 01_driver_init.md to understand user request
2. Generate PRD with user stories, functional requirements, NFRs
3. Interview stakeholders (4 stakeholders: PM, Tech Lead, Security, DevOps)
4. Map requirements to enterprise invariants
5. Create position card with Claims, Plan, Evidence pointers, Risks

Agent Output: Creates .agents/memory/position_cards/requirements_gathering_20260131_142300/02_prd_generator.md

Position Card Content:

# Position Card: PRD Generator

## Agent Metadata
- **Agent ID**: prd_generator
- **Workflow ID**: requirements_gathering_20260131_142300
- **Step Number**: 2
- **Timestamp**: 2026-01-31T14:25:30Z
- **Duration**: 2.5 minutes

## Position Card
- **Claims**:
  - User requires authentication system with JWT + social login (Google, GitHub)
  - Must support 5 functional requirements: registration, login, MFA, password reset, OAuth2
  - Must satisfy 5 non-functional requirements: <200ms login latency, 99.9% uptime, bcrypt hashing
  - Stakeholders: Product Manager (business requirements), Tech Lead (architecture), Security Lead (compliance), DevOps Lead (deployment)

- **Plan**:
  - Create PRD.md with 3 user stories (User Registration, User Login, Account Security)
  - Interview 4 stakeholders for approval requirements
  - Map to 9 enterprise invariants (INV-001 JWT, INV-002 RBAC, INV-003 MFA, INV-006 bcrypt, INV-008 PII masking, INV-009 rate limiting, INV-010 audit logging, INV-014 webhook signatures, INV-029 7-year retention)
  - Define success metrics: 1000 users in first month, <5% support tickets for auth issues

- **Evidence pointers**:
  - projects/auth-system/PRD.md (480 lines with 3 user stories, 5 FRs, 5 NFRs)
  - projects/auth-system/stakeholder_interviews.md (summary of 4 stakeholder conversations)

- **Risks**:
  - OAuth2 provider downtime (Google/GitHub APIs unavailable)
  - MFA UX friction (users may disable if too complex)
  - Timeline tight (4 weeks for 5 features may require scope reduction)

- **Confidence**: 0.90 (requirements clear from user, stakeholders aligned)
- **Cost**: Low (2.5 hours to generate PRD + interview stakeholders)
- **Reversibility**: Easy (PRD is documentation, no code written)
- **Invariant violations**: None
- **Required approvals**: ["prd_signoff"]

## Next Steps
- **Next Agent**: stakeholder_agent (gather formal approvals from 4 stakeholders)
- **Input for Next Agent**: This position card + 01_driver_init.md + projects/auth-system/PRD.md

Driver Monitoring:

• Driver polls for file: .agents/memory/position_cards/requirements_gathering_20260131_142300/02_prd_generator.md
• File detected → Driver parses position card
• Driver validates schema (all required fields present)
• Driver checks: agent completed successfully (no ERROR state)
• Driver proceeds to next step

Step 3: Sequential Agent Invocation (Stakeholder Agent)

Trigger: PRD Generator completed successfully

Action: Driver invokes Stakeholder Agent

Invocation Command:

const agentResult = await vscode.lm.invokeAgent({
  agentId: "stakeholder_agent",
  input: {
    workflowId: "requirements_gathering_20260131_142300",
    stepNumber: 3,
    previousPositionCards: [
      ".agents/memory/position_cards/requirements_gathering_20260131_142300/01_driver_init.md",
      ".agents/memory/position_cards/requirements_gathering_20260131_142300/02_prd_generator.md"
    ],
    contextFiles: [
      "projects/auth-system/PRD.md",
      "projects/auth-system/stakeholder_interviews.md"
    ],
    mode: "RUN_SDLC",
    expectedOutput: ".agents/memory/position_cards/requirements_gathering_20260131_142300/03_stakeholder_agent.md"
  }
});

Key Changes:

• stepNumber: 3 (incremented)
• previousPositionCards: Array now includes 02_prd_generator.md (cumulative context)
• contextFiles: Includes PRD.md created by PRD Generator
• expectedOutput: 03_stakeholder_agent.md

Agent Processing:

1. Read position cards: 01_driver_init.md, 02_prd_generator.md
2. Read context files: PRD.md, stakeholder_interviews.md
3. Gather approvals from 4 stakeholders (PM, Tech Lead, Security, DevOps)
4. Map stakeholders to RACI matrix (Responsible, Accountable, Consulted, Informed)
5. Track approval status: APPROVED, APPROVED_WITH_CONDITIONS, REJECTED
6. Create position card with approval results

Agent Output: Creates 03_stakeholder_agent.md with approval tracking

Parallel Agent Invocation (Fan-Out Pattern)

Scenario: Multiple domain experts reviewing architecture simultaneously

Step 5: Domain experts in parallel

Invocation Commands (parallel):

// Driver invokes 3 agents in parallel
const parallelResults = await Promise.all([
  vscode.lm.invokeAgent({
    agentId: "security_iam_expert",
    input: {
      workflowId: "architecture_review_20260131_150000",
      stepNumber: 5,
      previousPositionCards: ["01_driver_init.md", "02_solver.md", "03_skeptic.md"],
      contextFiles: ["projects/ecommerce-api/ARCHITECTURE.md"],
      mode: "RUN_SDLC",
      expectedOutput: ".agents/memory/position_cards/architecture_review_20260131_150000/05a_security_iam_expert.md"
    }
  }),
  vscode.lm.invokeAgent({
    agentId: "devops_platform_expert",
    input: {
      workflowId: "architecture_review_20260131_150000",
      stepNumber: 5,
      previousPositionCards: ["01_driver_init.md", "02_solver.md", "03_skeptic.md"],
      contextFiles: ["projects/ecommerce-api/ARCHITECTURE.md"],
      mode: "RUN_SDLC",
      expectedOutput: ".agents/memory/position_cards/architecture_review_20260131_150000/05b_devops_platform_expert.md"
    }
  }),
  vscode.lm.invokeAgent({
    agentId: "backend_architect_expert",
    input: {
      workflowId: "architecture_review_20260131_150000",
      stepNumber: 5,
      previousPositionCards: ["01_driver_init.md", "02_solver.md", "03_skeptic.md"],
      contextFiles: ["projects/ecommerce-api/ARCHITECTURE.md"],
      mode: "RUN_SDLC",
      expectedOutput: ".agents/memory/position_cards/architecture_review_20260131_150000/05c_backend_architect_expert.md"
    }
  })
]);

Key Points:

• All 3 agents have same stepNumber (5) - indicates parallelism
• Filenames use suffix (05a, 05b, 05c) to distinguish parallel agents
• All 3 agents read same previous position cards (shared context)
• Driver waits for ALL 3 position cards before continuing to step 6

Reflexion Loop (Agent Retry with Feedback)

Scenario: Verifier FAIL → Driver retries agent with corrections

Step 7: Verifier detects missing evidence

Verifier Output: 07_verifier.md with receipt status FAIL

# Position Card: Verifier

## Verification Receipt
- **Status**: FAIL
- **Timestamp**: 2026-01-31T14:45:00Z
- **Checks Performed**: 7
- **Passed**: 5
- **Failed**: 2

## Failed Checks
1. ❌ Evidence Pointer Missing
   - Expected: projects/auth-system/src/routes/auth.ts
   - Actual: File does not exist
   - Required By: Code Generator position card

2. ❌ Invariant Violation
   - Invariant: INV-008 (PII masking in logs)
   - Violation: Logger configuration does not redact email addresses
   - Required Fix: Add email redaction to logging middleware

## Required Corrections
- Agent: code_generator
- Action: Retry with corrections for checks 1 and 2
- Max Retries: 3 (current attempt: 1)

Driver Response:

// Driver detects FAIL receipt
const verifierCard = parsePositionCard("07_verifier.md");
if (verifierCard.status === "FAIL") {
  // Extract corrections needed
  const corrections = verifierCard.failedChecks;
  const targetAgent = verifierCard.requiredCorrections.agent; // "code_generator"
  
  // Check max retries
  const currentAttempt = getAttemptCount(workflowId, targetAgent); // 1
  const maxRetries = getWorkflowConfig(workflowId).maxRetries; // 3
  
  if (currentAttempt < maxRetries) {
    // Re-invoke agent with corrections
    await vscode.lm.invokeAgent({
      agentId: targetAgent, // "code_generator"
      input: {
        workflowId: "requirements_gathering_20260131_142300",
        stepNumber: 6, // Re-invoke at same step (retry)
        previousPositionCards: ["01_driver_init.md", "02_prd_generator.md", ...],
        contextFiles: ["projects/auth-system/PRD.md", ...],
        mode: "RUN_SDLC",
        expectedOutput: ".agents/memory/position_cards/requirements_gathering_20260131_142300/06_code_generator_retry1.md",
        corrections: corrections, // Pass failed checks to agent
        retryAttempt: 1
      }
    });
  } else {
    // Max retries exceeded → escalate to user
    await escalateToUser({
      workflow: workflowId,
      agent: targetAgent,
      error: "Max retries exceeded (3), agent cannot satisfy verifier requirements",
      failedChecks: corrections
    });
  }
}

Retry Position Card Naming: <step>_<agent_id>_retry<N>.md

• Example: 06_code_generator_retry1.md, 06_code_generator_retry2.md

Position Card Parsing (Driver Implementation)

Driver Function: parsePositionCard(filepath: string): PositionCard

interface PositionCard {
  agentId: string;
  workflowId: string;
  stepNumber: number;
  timestamp: string;
  duration: string;
  
  // Position card fields
  claims: string[];
  plan: string[];
  evidencePointers: string[];
  risks: string[];
  confidence: number;
  cost: "Low" | "Med" | "High";
  reversibility: "Easy" | "Med" | "Hard";
  invariantViolations: string[];
  requiredApprovals: string[];
  
  // Next steps
  nextAgent?: string;
  status?: "COMPLETE" | "WAITING_FOR_APPROVAL" | "FAIL" | "ERROR";
}

function parsePositionCard(filepath: string): PositionCard {
  const content = fs.readFileSync(filepath, "utf-8");
  
  // Extract metadata
  const agentId = extractSection(content, "## Agent Metadata", "Agent ID");
  const workflowId = extractSection(content, "## Agent Metadata", "Workflow ID");
  
  // Extract position card fields
  const claims = extractListSection(content, "## Position Card", "Claims");
  const plan = extractListSection(content, "## Position Card", "Plan");
  const evidencePointers = extractListSection(content, "## Position Card", "Evidence pointers");
  const risks = extractListSection(content, "## Position Card", "Risks");
  const confidence = parseFloat(extractField(content, "Confidence"));
  const cost = extractField(content, "Cost") as "Low" | "Med" | "High";
  const reversibility = extractField(content, "Reversibility") as "Easy" | "Med" | "Hard";
  const invariantViolations = extractListSection(content, "## Position Card", "Invariant violations");
  const requiredApprovals = extractListSection(content, "## Position Card", "Required approvals");
  
  // Extract next steps
  const nextAgent = extractField(content, "Next Agent");
  const status = extractField(content, "Status") as "COMPLETE" | "WAITING_FOR_APPROVAL" | "FAIL" | "ERROR" | undefined;
  
  return {
    agentId,
    workflowId,
    stepNumber,
    timestamp,
    duration,
    claims,
    plan,
    evidencePointers,
    risks,
    confidence,
    cost,
    reversibility,
    invariantViolations,
    requiredApprovals,
    nextAgent,
    status
  };
}

Error Handling in Invocation Protocol

Error Type 1: Agent Timeout (No Position Card Produced)

Detection: Driver polls for position card file, timeout after 5 minutes

async function invokeAgentWithTimeout(agentId: string, input: AgentInput, timeout: number = 300000): Promise<PositionCard> {
  const startTime = Date.now();
  const expectedFile = input.expectedOutput;
  
  // Invoke agent (non-blocking)
  await vscode.lm.invokeAgent({ agentId, input });
  
  // Poll for position card file
  while (Date.now() - startTime < timeout) {
    if (fs.existsSync(expectedFile)) {
      // Position card created → parse and return
      return parsePositionCard(expectedFile);
    }
    await sleep(1000); // Poll every 1 second
  }
  
  // Timeout exceeded
  throw new AgentTimeoutError(`Agent ${agentId} did not produce position card within ${timeout}ms`);
}

Recovery: Retry with simplified scope or escalate to user

Error Type 2: Agent Crashed (ERROR Status)

Detection: Position card exists but has ERROR status

const positionCard = parsePositionCard("05_code_generator.md");
if (positionCard.status === "ERROR") {
  const errorMessage = positionCard.errorDetails; // Extract from position card
  
  // Log error to decisions_log.md
  await logDecision({
    type: "AGENT_ERROR",
    agent: positionCard.agentId,
    workflow: positionCard.workflowId,
    error: errorMessage,
    action: "RETRY"
  });
  
  // Retry with error context
  await invokeAgent({
    agentId: positionCard.agentId,
    input: {
      ...previousInput,
      retryAttempt: 1,
      previousError: errorMessage
    }
  });
}

Error Type 3: Invalid Position Card Schema

Detection: Position card file exists but missing required fields

function validatePositionCard(card: PositionCard): ValidationResult {
  const errors: string[] = [];
  
  // Required fields
  if (!card.claims || card.claims.length === 0) errors.push("Missing required field: claims");
  if (!card.plan || card.plan.length === 0) errors.push("Missing required field: plan");
  if (!card.evidencePointers) errors.push("Missing required field: evidencePointers");
  if (card.confidence === undefined || card.confidence < 0 || card.confidence > 1) {
    errors.push("Invalid confidence value (must be 0.0 to 1.0)");
  }
  if (!["Low", "Med", "High"].includes(card.cost)) errors.push("Invalid cost value");
  if (!["Easy", "Med", "Hard"].includes(card.reversibility)) errors.push("Invalid reversibility value");
  
  return {
    valid: errors.length === 0,
    errors
  };
}

// Usage
const card = parsePositionCard("05_solver.md");
const validation = validatePositionCard(card);
if (!validation.valid) {
  throw new InvalidPositionCardError(`Agent produced invalid position card: ${validation.errors.join(", ")}`);
}

Integration with VS Code Extension

Extension Entry Point: extension.ts

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  // Register driver command
  const driverCommand = vscode.commands.registerCommand('sdlc-swarm.runWorkflow', async (workflowName: string, userRequest: string) => {
    const driver = new SDLCDriver(context);
    await driver.executeWorkflow(workflowName, userRequest);
  });
  
  context.subscriptions.push(driverCommand);
}

class SDLCDriver {
  constructor(private context: vscode.ExtensionContext) {}
  
  async executeWorkflow(workflowName: string, userRequest: string) {
    // 1. Initialize workflow
    const workflowId = `${workflowName}_${Date.now()}`;
    const workflowDir = `.agents/memory/position_cards/${workflowId}`;
    fs.mkdirSync(workflowDir, { recursive: true });
    
    // 2. Create driver init position card
    await this.createDriverInit(workflowId, workflowName, userRequest);
    
    // 3. Load workflow definition
    const workflow = await this.loadWorkflow(workflowName);
    
    // 4. Execute workflow steps
    for (const step of workflow.steps) {
      const positionCard = await this.invokeAgent(workflowId, step);
      
      // Check for errors
      if (positionCard.status === "ERROR") {
        await this.handleAgentError(workflowId, step, positionCard);
      }
      
      // Check for verification failure
      if (step.agentId === "verifier" && positionCard.status === "FAIL") {
        await this.handleVerificationFailure(workflowId, positionCard);
      }
      
      // Check for approval requirement
      if (positionCard.requiredApprovals.length > 0) {
        await this.waitForApprovals(workflowId, positionCard);
      }
    }
    
    // 5. Workflow complete
    vscode.window.showInformationMessage(`Workflow ${workflowName} completed successfully!`);
  }
  
  private async invokeAgent(workflowId: string, step: WorkflowStep): Promise<PositionCard> {
    // Implementation: invoke agent via VS Code language model API
    // ...
  }
}

Summary: Invocation Protocol

Key Principles:

1. File-Based Communication: Position cards stored as markdown files (inspectable, debuggable)
2. Asynchronous Invocation: Driver invokes agent, polls for output file
3. Cumulative Context: Each agent receives ALL previous position cards (full history)
4. Sequential Ordering: Step numbers enforce workflow order (01, 02, 03...)
5. Parallel Support: Same step number with suffixes (05a, 05b, 05c) for fan-out
6. Retry Support: Filename suffix _retry<N> for reflexion loops
7. Schema Validation: Driver validates position card schema before proceeding
8. Error Propagation: Agents can return ERROR status for driver to handle

Files Created Per Workflow:

• .agents/memory/position_cards/<workflow_id>/ directory (1)
• 01_driver_init.md (driver initialization card) (1)
• <step>_<agent_id>.md per agent invocation (~9-15 per workflow)
• Total: ~10-20 files per workflow execution (full audit trail)

Performance:

• Sequential invocation: ~2-5 minutes per agent (typical)
• Parallel invocation: 3 agents in parallel = ~3x speedup
• Workflow with 9 agents sequential: ~20-45 minutes
• Workflow with 3 parallel stages (3 agents each): ~10-20 minutes

Traceability:

• Every agent invocation produces position card (audit trail)
• Can replay workflow by reading position card files sequentially
• Can resume from any step by reading previous position cards
• Can debug failures by inspecting position card that produced ERROR

Operating Rules (Non-Negotiable)

1. Spec-First Rule

SPEC Card must exist before any execution.

• Spec defines WHAT to build (requirements, constraints, success criteria)
• No agent may start implementation without approved SPEC
• If SPEC is ambiguous, return to user for clarification

2. TDD-First Rule

TEST Card must exist before any build steps.

• TEST defines HOW to verify success (test cases, evidence criteria)
• Tests include functional tests, NFR tests, security tests, compliance checks
• No code generation without test plan

3. Evidence-Gated Rule

No memory writes without Verifier PASS receipt.

• Verifier checks all evidence pointers exist and satisfy claims
• Verifier validates invariant compliance
• PENDING or FAIL receipts block memory writes

4. Approval-Gated Rule

High-risk actions require Decision Card + human approval.

• Risk levels: LOW (<10% failure impact) | MED (10-50% impact) | HIGH (>50% impact) | CRITICAL (data loss, security breach)
• HIGH/CRITICAL require explicit human approval before execution
• Approvals tracked in decisions_log.md

5. Transparency Rule

No hidden state. Repository is source of truth.

• All decisions, position cards, evidence must be in repo files
• No in-memory state that isn't persisted
• Swarm state must be inspectable at any checkpoint

Workflow Execution Sequence (Standard)

Phase 1: Specification

1. Driver receives user request, selects workflow from .agents/registry/workflows.yaml
2. SpecAgent produces SPEC Card (requirements, constraints, success criteria)
3. TestAgent produces TEST Card (test plan, evidence criteria, acceptance tests)
4. Driver checkpoint: SPEC + TEST approved → proceed to Phase 2

Phase 2: Planning & Challenge

5. Solver produces implementation plan (architecture, file structure, dependencies)
6. Skeptic challenges plan (edge cases, risks, alternatives, trade-offs)
7. Domain Experts (if workflow requires) provide specialized input (security, devops, language-specific)
8. Driver checkpoint: Plan challenged and refined → proceed to Phase 3

Phase 3: Convergence (if multi-agent)

9. ExperienceAgent retrieves similar past decisions from memory
10. RiskScorer calculates risk score using world model policies
11. CollapseAgent produces weighted consensus decision
12. Driver checkpoint: Consensus reached → proceed to Phase 4

Phase 4: Verification

13. Verifier validates evidence pointers, checks invariants, produces receipt (PASS/FAIL/PENDING)
14. MetricsAgent (optional) calculates quality score
15. ConfidenceAgent (optional) calibrates confidence intervals
16. DriftDetector (optional) checks for drift from standards
17. Driver checkpoint: Receipt = PASS → proceed to Phase 5

Phase 5: Approval (if high-risk)

18. ApprovalGate produces Decision Card with approval requirements
19. Driver waits for human approval (if required)
20. Driver checkpoint: Approvals obtained → proceed to Phase 6

Phase 6: Execution & Memory

21. CodeGenerator / TestGenerator / CICDAgent / etc. execute plan
22. BuildValidator (optional) validates build artifacts (compilation, tests pass)
23. MemoryAgent writes to evidence ledgers and decisions log
24. Driver checkpoint: COMPLETE → return final position card to user

Error Handling Protocols

Error Type 1: Agent Timeout

Symptom: Agent takes >5 minutes without producing position card

Recovery:

1. Driver logs timeout to decisions_log.md
2. Driver retries agent with simplified scope (e.g., break large task into smaller chunks)
3. If retry fails, Driver escalates to user with error details
4. User may choose to: skip agent, provide manual input, or abort workflow

Example:

## Decision: Agent Timeout Recovery
- Timestamp: 2026-01-31T14:23:00Z
- Agent: DomainModelerAgent
- Workflow: build_feature
- Error: Timeout after 5 minutes (no position card produced)
- Recovery Action: Retry with scope limited to 3 aggregates instead of 8
- Outcome: SUCCESS (completed in 2 minutes on retry)

Error Type 2: Verifier FAIL

Symptom: Verifier receipt status = FAIL (evidence missing, invariants violated)

Recovery:

1. Driver halts workflow before memory write
2. Driver reviews Verifier receipt for failed checks
3. Driver returns to failing agent with specific corrections needed
4. Agent produces revised position card
5. Verifier re-validates
6. If still FAIL after 3 attempts, Driver escalates to user

Example:

## Verification Failure: Missing Evidence
- Receipt Status: FAIL
- Failed Checks:
  - Evidence pointer `src/auth/jwt.ts` does not exist
  - Invariant INV-001 (OAuth2 JWT) not satisfied (no JWT implementation found)
- Required Corrections:
  - CodeGenerator must create `src/auth/jwt.ts` with JWT verification middleware
  - Must import jsonwebtoken library and configure RS256 signing
- Retry: Agent corrected plan → re-verify

Error Type 3: High-Risk Block

Symptom: RiskScorer determines action is HIGH or CRITICAL risk

Recovery:

1. Driver automatically invokes ApprovalGate
2. ApprovalGate produces Decision Card with:
   • Risk score and rationale
   • Required approvals (who must approve)
   • Mitigation options
3. Driver waits for human approval
4. If denied, Driver aborts workflow or explores alternative plan
5. If approved, Driver proceeds but logs approval in decisions_log.md

Example:

## Decision Card: Production Database Migration
- Risk Level: HIGH (85/100)
- Rationale: Schema change affects 8 tables with 1M+ rows, downtime risk
- Required Approvals: [dba_signoff, tech_lead_approval]
- Mitigation:
  - Run migration in maintenance window (3am-5am)
  - Create database backup before migration
  - Prepare rollback script
  - Test migration on staging environment first
- Approval Status: APPROVED (tech lead: @alice, DBA: @bob)
- Timestamp: 2026-01-31T10:00:00Z

Error Type 4: Invariant Violation

Symptom: Agent plan violates world model invariant (e.g., no auth, no audit logs)

Recovery:

1. Verifier detects violation and produces FAIL receipt
2. Driver reviews invariant (from world_model.yaml)
3. Driver determines if violation is:
   • Hard block (security/compliance) → MUST fix before proceeding
   • Soft block (best practice) → MAY proceed with approval
4. If hard block, Driver returns to agent for corrected plan
5. If soft block, Driver invokes ApprovalGate for exception approval

Example:

## Invariant Violation: INV-029 (7-Year Audit Retention)
- Violation: Generated code includes audit log but no retention policy
- Severity: Hard Block (compliance requirement)
- Required Fix:
  - Add audit log retention policy (7 years)
  - Add archival process (move old logs to cold storage)
  - Add deletion policy (purge after 7 years)
- Agent: CodeGenerator
- Action: Retry with corrected plan including retention policy

Error Type 5: Consensus Failure

Symptom: Solver and Skeptic have conflicting positions, CollapseAgent cannot reach consensus

Recovery:

1. Driver logs conflict to decisions_log.md
2. Driver presents both positions to user
3. User chooses one position, or provides tiebreaker guidance
4. Driver proceeds with user-selected position
5. MemoryAgent records user decision for future reference

Example:

## Consensus Failure: PostgreSQL vs MongoDB
- Solver Position: Use PostgreSQL with RLS for multi-tenancy (structured data, ACID)
- Skeptic Challenge: MongoDB more flexible for product catalog (schema-less, horizontal scaling)
- CollapseAgent: Unable to converge (both positions scored 0.75)
- User Decision: Choose PostgreSQL (user values ACID guarantees over schema flexibility)
- Rationale: E-commerce requires transactional integrity for orders and payments

Parallel Execution Patterns

Pattern 1: Independent Agents

When: Multiple agents have no dependencies on each other

Example: Language experts for multi-language project

## Parallel Execution: Multi-Language Project
1. Driver invokes TypeScript Expert, Rust Expert, Python Expert in parallel
2. Each expert produces position card for their language-specific modules
3. Driver waits for all 3 position cards
4. Driver merges position cards into unified plan
5. Driver proceeds to CodeGenerator with merged plan

Benefits:

• 3x faster than sequential execution (3 agents, 5 min each = 5 min parallel vs 15 min sequential)
• No blocking between agents

Risks:

• May produce inconsistent interface contracts (e.g., TypeScript expects JSON, Rust returns MessagePack)
• Requires IntegrationBuilder agent to reconcile

Pattern 2: Fan-Out, Fan-In

When: One agent produces output consumed by multiple agents, then results merge

Example: Architecture review by multiple domain experts

## Fan-Out, Fan-In: Architecture Review
1. Solver produces architecture plan (1 plan)
2. Driver fans out to 3 domain experts in parallel:
   - SecurityIAMExpert reviews auth/authz
   - DevOpsPlatformExpert reviews deployment
   - BackendArchitectExpert reviews data flow
3. All 3 experts produce position cards with critiques
4. Driver fans in: CollapseAgent merges 3 critiques into consensus
5. Driver returns to Solver with merged feedback for revision

Benefits:

• Comprehensive review from multiple perspectives
• Catches issues early (security, scalability, operability)

Timing:

• Fan-out: 0 seconds (parallel start)
• Expert analysis: 3-5 minutes each (parallel execution)
• Fan-in: 1-2 minutes (merge)
• Total: ~5-7 minutes (vs 12-15 minutes sequential)

Pattern 3: Pipeline Stages

When: Workflow has clear stages with dependencies between stages

Example: Code generation pipeline

## Pipeline Stages: Code Generation
Stage 1: Specification (sequential)
  - SpecAgent (SPEC Card)
  - TestAgent (TEST Card)
  - Checkpoint: SPEC + TEST approved

Stage 2: Planning (parallel within stage)
  - Solver (architecture plan)
  - NFRAgent (non-functional requirements)
  - Checkpoint: Plans produced

Stage 3: Challenge (parallel)
  - Skeptic (challenges both plans)
  - DomainExperts (specialized reviews)
  - Checkpoint: Challenges addressed

Stage 4: Generation (sequential, order matters)
  - CodeGenerator (implementation)
  - TestGenerator (test suite)
  - Checkpoint: Code + tests generated

Stage 5: Validation (parallel)
  - BuildValidator (compilation check)
  - Verifier (evidence check)
  - Checkpoint: All validations PASS

Stage 6: Memory (sequential)
  - MemoryAgent (write evidence)
  - Checkpoint: COMPLETE

Stage Parallelism:

• Within each stage, independent agents run in parallel
• Between stages, synchronous checkpoints ensure order

Checkpoint & Resume Protocol

Checkpoint Format

Every checkpoint saves swarm state to .agents/checkpoints/<workflow_id>.md

## Checkpoint: <Workflow Name> - <Phase>
- Workflow ID: build_ecommerce_api_20260131_142300
- Timestamp: 2026-01-31T14:23:00Z
- Phase: 3 (Convergence)
- Mode: RUN_SDLC
- Status: IN_PROGRESS

### Completed Agents
1. SpecAgent → SPEC Card (projects/ecommerce-api/SPEC.md)
2. TestAgent → TEST Card (projects/ecommerce-api/TEST.md)
3. Solver → Plan (projects/ecommerce-api/PLAN.md)
4. Skeptic → Challenge (projects/ecommerce-api/CHALLENGE.md)

### Next Agent
- Agent: ExperienceAgent
- Input: SPEC + Plan + Challenge cards
- Expected Output: Experience-weighted position card

### Pending Agents
- RiskScorer
- CollapseAgent
- Verifier
- MemoryAgent

### Context
- User Request: "Build multi-tenant e-commerce API with Stripe payments"
- Constraints: Node.js 20, PostgreSQL 16, Redis 7, <2 hour build time
- Evidence Pointers: None (new project)

Resume From Checkpoint

If workflow is interrupted (user cancels, system crash, timeout), Driver can resume:

## Resume Workflow
- Checkpoint ID: build_ecommerce_api_20260131_142300
- Resume From: Phase 3 (Convergence), Agent: ExperienceAgent
- Action:
  1. Load checkpoint file
  2. Verify completed agents' outputs exist (SPEC.md, TEST.md, PLAN.md, CHALLENGE.md)
  3. Re-invoke ExperienceAgent with saved context
  4. Continue workflow from interruption point

Use Cases:

• Long-running workflows (>1 hour) allow incremental progress
• User can review intermediate outputs and abort if direction is wrong
• System failures don't require full restart

Debugging Guidance

Inspect Swarm State

Command: "Driver, show me current swarm state"

Output:

## Swarm State: build_ecommerce_api
- Workflow: generate_code
- Mode: RUN_SDLC
- Phase: 4 (Verification)
- Status: WAITING_FOR_APPROVAL

### Active Agents
- Verifier: Completed (Receipt: PASS)
- ApprovalGate: Waiting for prod_deploy approval

### Position Cards
1. SpecAgent: projects/ecommerce-api/SPEC.md (APPROVED)
2. TestAgent: projects/ecommerce-api/TEST.md (APPROVED)
3. CodeGenerator: projects/ecommerce-api/CODE_PLAN.md (PENDING_APPROVAL)

### Evidence Chain
- SPEC → TEST ✅ (alignment verified)
- SPEC → CODE PLAN ✅ (requirements satisfied)
- CODE PLAN → TESTS ⏳ (tests not yet generated)

### Blockers
- Waiting for prod_deploy approval from tech lead
- 15 minutes elapsed since approval request

Trace Agent Execution

Command: "Driver, trace CodeGenerator execution"

Output:

## Agent Trace: CodeGenerator
- Invocation: 2026-01-31T14:30:00Z
- Input Files:
  - projects/ecommerce-api/SPEC.md (320 lines)
  - projects/ecommerce-api/ARCHITECTURE.md (580 lines)
  - projects/ecommerce-api/DOMAIN_MODEL.md (510 lines)
- Output Files:
  - projects/ecommerce-api/src/index.ts (70 lines) ✅
  - projects/ecommerce-api/src/lib/logger.ts (30 lines) ✅
  - projects/ecommerce-api/src/middleware/auth.middleware.ts (90 lines) ✅
  - projects/ecommerce-api/src/middlew

…(truncated)