# Driver

> Skill: SDLC Swarm Driver (Entry Point & Orchestrator)

- Skill: `farmountain/driver` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add farmountain/driver`
- Raw SKILL.md: https://api.skillmd.com/api/skills/farmountain/driver/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: farmountain (https://skillmd.com/u/farmountain)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/farmountain/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: <Agent Role>
- **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:**

```markdown
### 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:**
```markdown
# 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):**
```typescript
// 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:**
```markdown
# 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:**
```typescript
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):**
```typescript
// 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

```markdown
# 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:**

```typescript
// 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`

```typescript
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

```typescript
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

```typescript
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

```typescript
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`

```typescript
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:**
```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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
```markdown
## 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
```markdown
## 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
```markdown
## 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`

```markdown
## 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:

```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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)