Artifact schema

JSON structure for each phase.

Common fields

Every artifact includes these fields at the top level:

{
  "phase": string,          // phase name
  "timestamp": string,      // ISO 8601
  "agent": string,          // agent identifier
  "intensity": string,      // "quick" | "standard" | "thorough" | null
  "summary": string,        // one-line description
  "context_checkpoint": {
    "git_sha": string,
    "files_analyzed": number,
    "total_lines": number
  },
  "integrity": {
    "sha256_post_redaction": string,
    "secrets_redacted": number
  }
}

Think artifact

{
  "phase": "think",
  "scope": {
    "description": "Build a habit tracker with daily check-ins",
    "constraints": [
      "No auth for v1",
      "SQLite storage",
      "Max 3 habits to keep scope tight"
    ],
    "deferred": [
      "User authentication",
      "Habit categories",
      "Weekly/monthly views"
    ],
    "risks": [
      {
        "description": "Timezone handling in streak calculation",
        "mitigation": "Normalize dates to user local timezone"
      }
    ]
  },
  "decision_trail": [
    {
      "question": "SQLite vs JSON file for v1?",
      "answer": "SQLite — migrations are simpler for v2 features",
      "confidence": 0.8
    }
  ]
}

Plan artifact

{
  "phase": "plan",
  "planned_files": [
    {
      "path": "db/schema.sql",
      "action": "create",
      "description": "Table definitions for habits and check-ins"
    },
    {
      "path": "src/routes/habits.ts",
      "action": "create",
      "description": "CRUD endpoints for habits"
    }
  ],
  "planned_routes": [
    {
      "method": "POST",
      "path": "/api/habits",
      "description": "Create a new habit"
    }
  ],
  "planned_migrations": [
    {
      "file": "db/schema.sql",
      "description": "Initial schema with habits and checkins tables"
    }
  ],
  "estimated_lines": 420,
  "knowledge_refs": [
    "know-how/bugs/timezone-streak-calc.json"
  ]
}

Review artifact

{
  "phase": "review",
  "passes": ["structural", "adversarial"],
  "drift": {
    "drift_detected": false,
    "planned_count": 6,
    "actual_count": 6,
    "unplanned_files": [],
    "missing_files": []
  },
  "findings": [
    {
      "pass": "structural",
      "type": "issue",
      "severity": "medium",
      "file": "db/migrate.sh",
      "line": 8,
      "message": "Missing IF NOT EXISTS guard on CREATE TABLE",
      "confidence": 0.91,
      "auto_fixed": true,
      "fix_description": "Added IF NOT EXISTS to CREATE TABLE statement"
    },
    {
      "pass": "adversarial",
      "type": "edge_case",
      "severity": "medium",
      "file": "src/routes/streaks.ts",
      "line": 42,
      "message": "Duplicate check-in on same day not handled",
      "confidence": 0.82,
      "auto_fixed": false
    }
  ],
  "suppressed_findings": [],
  "stats": {
    "files_reviewed": 6,
    "issues_found": 2,
    "auto_fixed": 1,
    "needs_input": 1
  }
}

QA artifact

{
  "phase": "qa",
  "test_suites": [
    {
      "file": "tests/habits.test.ts",
      "tests": 12,
      "passed": 12,
      "failed": 0,
      "type": "unit"
    },
    {
      "file": "tests/integration/streaks.test.ts",
      "tests": 8,
      "passed": 8,
      "failed": 0,
      "type": "integration"
    },
    {
      "file": "tests/edge/duplicate-checkin.test.ts",
      "tests": 4,
      "passed": 4,
      "failed": 0,
      "type": "edge_case"
    }
  ],
  "coverage": {
    "lines": 87.3,
    "branches": 79.1,
    "functions": 92.0
  },
  "stats": {
    "total_tests": 24,
    "passed": 24,
    "failed": 0,
    "generated": 20,
    "existing": 4
  }
}

Security artifact

{
  "phase": "security",
  "grade": "A",
  "owasp_top_10": {
    "A01_broken_access_control": "pass",
    "A02_cryptographic_failures": "not_applicable",
    "A03_injection": "pass",
    "A04_insecure_design": "pass",
    "A05_security_misconfiguration": "pass",
    "A06_vulnerable_components": "pass",
    "A07_auth_failures": "not_applicable",
    "A08_data_integrity_failures": "pass",
    "A09_logging_failures": "info",
    "A10_ssrf": "not_applicable"
  },
  "stride": {
    "spoofing": [],
    "tampering": [],
    "repudiation": [
      {
        "description": "No audit log for habit deletions",
        "severity": "low",
        "recommendation": "Add logging for destructive operations"
      }
    ],
    "information_disclosure": [],
    "denial_of_service": [],
    "elevation_of_privilege": []
  },
  "findings": [],
  "dependency_audit": {
    "total": 12,
    "vulnerable": 0,
    "outdated": 2
  }
}

Ship artifact

{
  "phase": "ship",
  "commit_sha": "a1b2c3d",
  "branch": "feature/habit-tracker",
  "pr_number": 42,
  "pr_url": "https://github.com/user/repo/pull/42",
  "aggregated_findings": {
    "review": { "total": 2, "fixed": 1, "deferred": 1 },
    "qa": { "tests": 24, "passed": 24, "failed": 0 },
    "security": { "grade": "A", "findings": 0 }
  },
  "conflicts_resolved": [],
  "sprint_duration_seconds": 342,
  "next_suggestions": [
    "Add user authentication (deferred from /think)",
    "Add habit categories"
  ]
}