4.8 KiB

Raw Blame History

Agent Completion Artifact Pattern

Problem: Agents fail to update story files reliably (60% success rate) Solution: Agents create completion.json artifacts. Orchestrator uses them to update story files.

The Contract

Agent Responsibility

Each agent MUST create a completion artifact before finishing:

File path: docs/sprint-artifacts/completions/{{story_key}}-{{agent_name}}.json
Format: Structured JSON (see formats below)
Verification: File exists = work done (binary check)

Orchestrator Responsibility

Orchestrator reads completion artifacts and:

Parses JSON for structured data
Updates story file tasks (check off completed)
Fills Dev Agent Record with evidence
Verifies updates succeeded

Why This Works

File-based verification:

✅ Binary check: File exists or doesn't
✅ No complex parsing of agent output
✅ No reconciliation logic needed
✅ Hard stop if artifact missing

JSON format:

✅ Easy to parse reliably
✅ Structured data (not prose)
✅ Version controllable
✅ Auditable trail

How to Use This Pattern

In Agent Prompts

Include this in every agent prompt:

## CRITICAL: Create Completion Artifact

**MANDATORY:** Before returning, you MUST create a completion artifact JSON file.

**File Path:** `docs/sprint-artifacts/completions/{{story_key}}-{{agent_name}}.json`

**Format:**
```json
{
  "story_key": "{{story_key}}",
  "agent": "{{agent_name}}",
  "status": "SUCCESS",
  "files_created": ["file1.ts", "file2.ts"],
  "files_modified": ["file3.ts"],
  "timestamp": "2026-01-27T02:30:00Z"
}

Use Write tool to create this file. No exceptions.


### In Orchestrator Verification

After agent completes, verify artifact exists:

```bash
COMPLETION_FILE="docs/sprint-artifacts/completions/{{story_key}}-{{agent}}.json"

if [ ! -f "$COMPLETION_FILE" ]; then
  echo "❌ BLOCKER: Agent failed to create completion artifact"
  exit 1
fi

echo "✅ Completion artifact found"

In Reconciliation

Parse artifact to update story file:

1. Load completion artifact with Read tool
2. Parse JSON to extract data
3. Use Edit tool to update story file
4. Verify updates with bash checks

Artifact Formats by Agent

Builder Completion

{
  "story_key": "19-4",
  "agent": "builder",
  "status": "SUCCESS",
  "tasks_completed": [
    "Create PaymentProcessor service",
    "Add retry logic with exponential backoff"
  ],
  "files_created": [
    "lib/billing/payment-processor.ts",
    "lib/billing/__tests__/payment-processor.test.ts"
  ],
  "files_modified": [
    "lib/billing/worker.ts"
  ],
  "tests": {
    "files": 2,
    "cases": 15
  },
  "timestamp": "2026-01-27T02:30:00Z"
}

Inspector Completion

{
  "story_key": "19-4",
  "agent": "inspector",
  "status": "PASS",
  "quality_checks": {
    "type_check": "PASS",
    "lint": "PASS",
    "build": "PASS"
  },
  "tests": {
    "passing": 45,
    "failing": 0,
    "total": 45,
    "coverage": 95
  },
  "files_verified": [
    "lib/billing/payment-processor.ts"
  ],
  "timestamp": "2026-01-27T02:35:00Z"
}

Reviewer Completion

{
  "story_key": "19-4",
  "agent": "reviewer",
  "status": "ISSUES_FOUND",
  "issues": {
    "critical": 2,
    "high": 3,
    "medium": 4,
    "low": 2,
    "total": 11
  },
  "must_fix": [
    {
      "severity": "CRITICAL",
      "location": "api/route.ts:45",
      "description": "SQL injection vulnerability"
    }
  ],
  "files_reviewed": [
    "api/route.ts"
  ],
  "timestamp": "2026-01-27T02:40:00Z"
}

Fixer Completion (FINAL)

{
  "story_key": "19-4",
  "agent": "fixer",
  "status": "SUCCESS",
  "issues_fixed": {
    "critical": 2,
    "high": 3,
    "total": 5
  },
  "fixes_applied": [
    "Fixed SQL injection in agreement route (CRITICAL)",
    "Added authorization check (CRITICAL)"
  ],
  "files_modified": [
    "api/route.ts"
  ],
  "quality_checks": {
    "type_check": "PASS",
    "lint": "PASS",
    "build": "PASS"
  },
  "tests": {
    "passing": 48,
    "failing": 0,
    "total": 48,
    "coverage": 96
  },
  "git_commit": "a1b2c3d4e5f",
  "timestamp": "2026-01-27T02:50:00Z"
}

Benefits

Reliability: 60% → 100% (file exists is binary)
Simplicity: No complex output parsing
Auditability: JSON files are version controlled
Debuggability: Can inspect artifacts when issues occur
Enforcement: Can't proceed without completion artifact (hard stop)

Anti-Patterns

Don't do this:

❌ Trust agent output without verification
❌ Parse agent prose for structured data
❌ Let agents update story files directly
❌ Skip artifact creation ("just this once")

Do this instead:

✅ Verify artifact exists (binary check)
✅ Parse JSON for reliable data
✅ Orchestrator updates story files
✅ Hard stop if artifact missing

4.8 KiB Raw Blame History