Artifacts

Artifacts are the tangible outputs of agent work. Every time an agent completes a task, the result is captured as an artifact with full provenance, citations, and verification.

Artifact Types

Specs

Product requirements, technical designs, feature briefs

Code

Pull requests, patches, migrations, tests

Content

Blog posts, email sequences, social copy, landing pages

Reports

Research findings, competitive analysis, market trends

Briefs

Campaign briefs, design rationale, meeting prep

Sequences

Sales outreach, nurture campaigns, follow-up emails

Artifact Lifecycle

Every artifact moves through defined states:

States

State	Description	Actions Available
Forming	Agent actively working	View progress, cancel
Testing	Running verification checks	Wait for results
Ready	Passed verification, awaiting approval	Approve, reject, edit
NeedsYou	Verification failed, needs human input	Fix issues, provide feedback
Shipped	Approved and deployed/published	View, archive
Degraded	Issues found after shipping	Remediate, rollback
Dormant	Archived or superseded	Reference only

Artifact Structure

Each artifact contains:

interface OrgArtifact {
  id: string;
  type: 'spec' | 'pr' | 'content' | 'report' | 'brief' | 'sequence';
  title: string;
  content: string | Record<string, unknown>;

  // Provenance
  agent_instance_id: string;
  workflow_id: string;
  initiative_id: string;
  work_item_id: string;

  // Verification
  verification_status: 'pending' | 'passed' | 'failed';
  verification_proof: VerificationProof;

  // Evidence
  citations: Citation[];
  evidence_ids: string[];

  // Lifecycle
  state: ArtifactState;
  created_at: string;
  updated_at: string;
  shipped_at?: string;

  // Metadata
  schema_version: string;
  tags: string[];
}

Citations

Every artifact includes source citations:

interface Citation {
  id: string;
  source_type:
    | 'linear_issue'
    | 'github_pr'
    | 'document'
    | 'url'
    | 'agent_output';
  source_id: string;
  source_url?: string;
  excerpt?: string;
  confidence: number; // 0-1
}

Example citations in an artifact:

{
  "citations": [
    {
      "source_type": "linear_issue",
      "source_id": "ENG-123",
      "source_url": "https://linear.app/acme/issue/ENG-123",
      "excerpt": "User reported infinite loop when clicking login",
      "confidence": 0.95
    },
    {
      "source_type": "github_pr",
      "source_id": "45",
      "source_url": "https://github.com/acme/app/pull/45",
      "excerpt": "Previous auth fix that may be related",
      "confidence": 0.72
    }
  ]
}

Verification

Before an artifact can ship, it passes through the Verifier:

Verification Checks

Citation Check

What it verifies: Sources are referenced and accessible

Minimum 3 citations for most artifact types
All URLs resolve and return expected content
Citations support the claims made in the artifact

Failure action: Surface for human to add citations or verify claims

Policy Check

What it verifies: Content complies with policies

Brand tone and style guidelines
Legal compliance (no false claims)
Security best practices (no exposed secrets)
Accessibility standards where applicable

Failure action: Highlight violations for human review

Contract Check

What it verifies: Output matches expected schema

Required fields present
Data types correct
Format matches workflow spec

Failure action: Agent retries or escalates to human

Budget Check

What it verifies: Execution stayed within limits

Token usage within p95 budget
Latency within p95 budget
No runaway tool calls

Failure action: Flag for ops review, may still ship

Verification Proof

Successful verification generates a proof:

interface VerificationProof {
  id: string;
  artifact_id: string;
  checks: {
    citation: { passed: boolean; score: number; details: string };
    policy: { passed: boolean; violations: string[] };
    contract: { passed: boolean; schema_version: string };
    budget: { passed: boolean; tokens_used: number; latency_ms: number };
  };
  overall_verdict: 'passed' | 'failed' | 'warning';
  verified_at: string;
  verifier_version: string;
}

Artifact Schemas

Different artifact types have specific schemas:

Spec Artifact

interface SpecArtifact {
  type: 'spec';
  content: {
    overview: string;
    requirements: Requirement[];
    acceptance_criteria: string[];
    technical_notes?: string;
    open_questions?: string[];
  };
}

interface Requirement {
  id: string;
  description: string;
  priority: 'must' | 'should' | 'could';
  rationale?: string;
}

PR Artifact

interface PRArtifact {
  type: 'pr';
  content: {
    title: string;
    description: string;
    branch: string;
    base: string;
    files_changed: FileChange[];
    tests_added: string[];
    review_notes: string;
  };
  github_pr_url?: string;
  linear_issue_id?: string;
}

Campaign Brief Artifact

interface CampaignBriefArtifact {
  type: 'brief';
  content: {
    objective: string;
    target_audience: string;
    key_messages: string[];
    channels: Channel[];
    timeline: TimelineItem[];
    success_metrics: Metric[];
    budget_estimate?: number;
  };
}

Working with Artifacts

Viewing Artifacts

Artifacts appear in several places:

Mission Control: Recent artifacts in the activity feed
Initiative Detail: Artifacts linked to the initiative
Decision Review: Artifact preview when approving
Task Detail: Artifacts produced for the task

Editing Before Ship

While in Ready state, you can edit artifacts:

Open the artifact detail view
Click Edit to modify content
Changes are tracked in version history
Re-run verification if needed
Approve the edited version

Exporting Artifacts

Export formats available:

Format	Use Case
Markdown	Documentation, GitHub
PDF	Stakeholder sharing
JSON	API integration
Notion	Push to Notion database

Artifact Evidence

Each artifact links to its evidence chain: This evidence chain enables:

Audit: Trace how any artifact was produced
Debug: Understand why verification failed
Improve: Learn from successful patterns

Best Practices

Review Citations

Always check that citations support the artifact’s claims. Agents sometimes hallucinate connections—verification catches most, but human review catches all.

Use Edit Sparingly

If you frequently edit artifacts before shipping, consider adjusting agent prompts or providing better context in tasks. Artifacts should be close to shippable on first pass.

Track Verification Trends

If verification failures spike, investigate: - Are task descriptions unclear?

Do agents need different tools? - Are policies too strict?

Archive Don't Delete

Move artifacts to Dormant instead of deleting. The evidence chain is valuable for learning and compliance.

Artifact Types

Specs

Code

Content

Reports

Briefs

Sequences

Artifact Lifecycle

States

Artifact Structure

Citations

Verification

Verification Checks

Verification Proof

Artifact Schemas

Spec Artifact

PR Artifact

Campaign Brief Artifact

Working with Artifacts

Viewing Artifacts

Editing Before Ship

Exporting Artifacts

Artifact Evidence

Best Practices

Next Steps

Decisions

Architecture

​Artifact Types

Specs

Code

Content

Reports

Briefs

Sequences

​Artifact Lifecycle

​States

​Artifact Structure

​Citations

​Verification

​Verification Checks

​Verification Proof

​Artifact Schemas

​Spec Artifact

​PR Artifact

​Campaign Brief Artifact

​Working with Artifacts

​Viewing Artifacts

​Editing Before Ship

​Exporting Artifacts

​Artifact Evidence

​Best Practices

​Next Steps

Decisions

Architecture

Artifact Types

Artifact Lifecycle

States

Artifact Structure

Citations

Verification

Verification Checks

Verification Proof

Artifact Schemas

Spec Artifact

PR Artifact

Campaign Brief Artifact

Working with Artifacts

Viewing Artifacts

Editing Before Ship

Exporting Artifacts

Artifact Evidence

Best Practices

Next Steps