Artifact Reuse Pattern

Persistent Living Artifact Mutation Pattern

Overview

When executing multi-phase engineering tasks, poorly designed agents generate new markdown files for every status update (plan_v1.md, plan_v2.md, revised_plan.md, final_summary.md).

Creating duplicate files pollutes repository search indices, degrades RAG vector embeddings, confuses subagents with conflicting historical drafts, and wastes thousands of generation tokens.

The Persistent Living Artifact Pattern enforces a single canonical document per domain (e.g. implementation_plan.md, walkthrough.md) and updates it via in-place differential edits (replace_file_content), maintaining a pristine single source of truth.

Duplicate Proliferation vs. Single Living Artifact

┌─────────────────────────────────────────────────────────────┐
│                 Artifact Lifecycle Comparison               │
│                                                             │
│  Duplicate Proliferation (Anti-Pattern):                    │
│  • Turn 1: `write_to_file("plan_v1.md")` (800 tokens)       │
│  • Turn 5: `write_to_file("plan_v2.md")` (950 tokens)       │
│  • Turn 12: `write_to_file("final_plan.md")` (1,100 tokens) │
│  ↳ 3 duplicate files in repo, 2,850 tokens billed           │
│                                                             │
│  Single Living Artifact (Living Mutation Pattern):          │
│  • Turn 1: `write_to_file("implementation_plan.md")`        │
│  • Turn 5: `replace_file_content("implementation_plan.md")` │
│    ↳ Mutates only the completed phase (45 tokens!)          │
│  • Turn 12: Updates verification status in place            │
│  ↳ 1 canonical file, 92% fewer mutation tokens billed       │
└─────────────────────────────────────────────────────────────┘

The 3 Canonical Agent Artifacts

In standard agentic frameworks (Antigravity IDE, Claude Code, Cursor), maintain strictly 3 canonical state documents in the artifact directory:

In-Place Mutation Recipe

When updating task completion status in implementation_plan.md, never rewrite the entire document. Use targeted chunk replacement:

<!-- TARGET CONTENT IN implementation_plan.md -->
- [ ] **Phase 2: Database Schema Migration** (Pending)

<!-- REPLACEMENT CONTENT -->
- [x] **Phase 2: Database Schema Migration** (Completed - Migration `20260822_auth` deployed)

Agent Tool Call Example:

{
  "TargetFile": "/path/to/artifacts/implementation_plan.md",
  "Instruction": "Mark Phase 2 as completed and record migration ID",
  "Description": "Update implementation plan milestone status in-place",
  "StartLine": 42,
  "EndLine": 45,
  "TargetContent": "- [ ] **Phase 2: Database Schema Migration** (Pending)",
  "ReplacementContent": "- [x] **Phase 2: Database Schema Migration** (Completed - Migration `20260822_auth` deployed)",
  "AllowMultiple": false
}

Metadata Synchronization Standard

Whenever mutating a user-facing artifact, synchronize its ArtifactMetadata object to inform the IDE UI without triggering redundant chat messages:

{
  "ArtifactMetadata": {
    "UserFacing": true,
    "RequestFeedback": false,
    "Summary": "Updated implementation plan: Phase 2 database migration completed successfully. Proceeding to Phase 3 API endpoints."
  }
}

Benchmark Metrics

Agent Operational Directive

MANDATORY: Autonomous agents must NEVER create versioned duplicate artifacts (e.g. plan2.md, summary_new.md). Always locate the existing canonical document and mutate it in-place.