Artifacts

Artifacts are structured documents that capture every stage of building software. They live as YAML files in the .tracigo folder of your workspace.

Unlike traditional documentation that's written after the fact and quickly goes stale, artifacts are created during the work — as part of your conversations with AI agents, as part of team discussions, as part of the decision-making process. They stay current because they ARE the source of truth, not a copy of it.

Why artifacts matter

Decisions survive. When you choose MongoDB over Cassandra, the reasoning is in the artifact — not in a Slack thread from three months ago.

Context carries forward. Every new AI agent session reads existing artifacts automatically. No re-explaining what was decided or why.

The team sees everything. PMs, engineers, QA, and leads all work from the same artifacts. No fragmented context across five tools.

New members onboard fast. Instead of asking "why did we build it this way?", they read the artifact trail.

Artifact types

Tracigo includes eight built-in types. Each serves a specific purpose in the development lifecycle.

REQUIREMENTS

What needs to be built and why. Written from the user or business perspective. Contains individual requirements with acceptance criteria. This is the starting point — everything else traces back here.

DESIGN

How it will be built at a high level. Architecture decisions, component interactions, data models, API contracts. Most importantly: trade-offs considered and why the chosen approach won. Uses the context section — no array items.

SPEC

The detailed implementation plan. A task breakdown with specific technical steps. Each task references which requirement it implements, creating a clear link between "what" and "how."

TEST_PLAN

Test cases that verify requirements are met. Each test case describes the scenario, expected behavior, and which requirement it covers. Written early — not after code is complete.

SECURITY

Security considerations and checks. Threat model, attack surfaces, controls to implement. Each check describes what to verify and why it matters.

RCA

Root cause analysis after an incident. Documents what happened, the timeline, root cause, contributing factors, and action items to prevent recurrence.

RELEASE_NOTES

User-facing summary of what changed. Written for end users, not the engineering team.

USER_GUIDE

Documentation for end users on how to use the feature.

Custom types

The kind field can be anything. Need a DEPLOYMENT_PLAN? API_CONTRACT? ARCHITECTURE_REVIEW? Create a YAML file with that kind. The only rule: each kind must be unique within a workspace. Use uppercase with underscores.

YAML structure

Every artifact follows the same basic structure:

meta:
  kind: REQUIREMENTS
  title: "Guest Checkout Flow"

context: |
  ## Background

  Payment failures account for 12% of checkout abandonment. Analysis shows
  that 60% of failed payments are from first-time users who abandoned during
  account creation. Guest checkout removes this friction.

  ## Approach

  Server-side session management with 7-day cookie persistence.
  Post-purchase account creation offered but not required.

requirements:
  - id: REQ-001
    title: "Complete purchase without account"
    status: proposed
    priority: p0
    description: |
      Users can complete a purchase without creating an account.

      ## Acceptance criteria
      - Cart persists via session cookie for 7 days
      - All payment methods available to guest users
      - Order confirmation sent to provided email
      - Guest orders searchable by email in order lookup

change_log:
  - added: "REQ-001 guest checkout, REQ-002 post-purchase account creation"
    removed: ""
    why: "Analytics show 40% of users abandon at login — guest checkout removes friction for first-time buyers"
    affects: "DESIGN needs guest session handling. SPEC needs task breakdown."

context

Free-form markdown. The narrative section — background, scope, constraints, key decisions, trade-offs. This is where you explain the "why." Supports all standard markdown: headings, lists, code blocks, tables, images.

Array sections

Structured items with id, title, and description. The section name depends on the artifact type:

Type	Section name	Key fields per item
REQUIREMENTS	`requirements`	id, title, status, priority, description, tags
SPEC	`task_list`	id, title, status, description, related_requirement
TEST_PLAN	`test_cases`	id, title, status, description
SECURITY	`security_checks`	id, title, status, description
RCA	`action_items`	id, title, status, description

DESIGN, RELEASE_NOTES, and USER_GUIDE use the context section only.

Custom fields are welcome on any item — the schema is flexible. Just keep id and title on every item.

change_log

An append-only log of what changed in this artifact. Each entry has:

added — what was added or changed
removed — what was removed (empty string if nothing)
why — the reasoning behind the change
affects — what downstream artifacts need to react (optional, "None" if no impact)

The changelog — capturing decisions

The changelog is the most valuable part of an artifact. It preserves the reasoning that would otherwise be lost in conversation history.

Writing good `why` entries

The why field should capture the actual reasoning — the data, the trade-off, the insight from the conversation. Not just what happened, but why it matters.

Weak:

why: "Added per user request"

Better:

why: "Analytics show 40% of users abandon at login — guest checkout removes this friction for first-time buyers while keeping account creation as a post-purchase option"

Weak:

why: "Changed database approach"

Better:

why: "Switched from Redis to encrypted cookies for session storage after staging incident revealed Redis connection pool exhaustion under concurrent token refresh (100K+ sessions)"

The `affects` field

When a change in one artifact has implications for others, note it:

affects: "DESIGN needs guest session handling section. TEST_PLAN needs guest checkout flow coverage."

This creates traceability — when someone reads the DESIGN artifact and wonders why it needs updating, the REQUIREMENTS changelog tells them exactly what changed and why.

Why YAML files in your repo

Artifacts are plain YAML files that live in your git repository — not in a database you don't control, not behind an API, not in a proprietary format.

This is a deliberate choice:

No lock-in. Your artifacts are files in your repo. If you stop using Tracigo tomorrow, everything stays. Read them, edit them, process them with any tool you want.

No MCP server needed. Your AI agents read and write artifacts directly from the filesystem. Claude Code, Codex, Copilot — they all work with files natively. No plugin to install, no server to run, no authentication to configure.

Your team owns the data. Artifacts get committed and pushed to your GitHub, GitLab, or Bitbucket — wherever your code lives. They go through your code review process. They're backed up with your repo. They're subject to your access controls.

Any agent, any editor. Because they're just files, they work with every tool in your stack. grep them, diff them, write scripts against them. They're not trapped inside a UI.

The shared collaboration features (real-time editing, comments, status tracking) layer on top of this foundation — but the source of truth is always the file in your repo.

Local and shared modes

Artifacts start as local YAML files. You and your AI agents edit them directly — fast, flexible, no friction.

When ready, save to share with the team. The artifact becomes a live collaborative document:

Real-time editing — multiple teammates can edit simultaneously
Comments — leave feedback on specific sections, resolve when addressed
Status tracking — draft, in review, approved, update required, outdated
Version history — every save creates a version, with full diff visibility

Local mode is your working draft. Shared mode is the team's source of truth.

Cross-artifact traceability

Artifacts in a workspace are connected:

REQUIREMENTS → DESIGN: The design should reference specific requirement IDs
REQUIREMENTS → SPEC: Each task in the spec links to the requirement it implements via related_requirement
REQUIREMENTS → TEST_PLAN: Test cases map to requirements to ensure coverage
Any upstream change: When REQUIREMENTS changes after DESIGN is approved, the changelog affects field flags it

This traceability is what makes artifacts a team tool, not just documentation. Every decision connects to why it was made, and every downstream artifact knows what it was based on.

Next steps

Getting started — Create your first artifact
Agent integration — How your AI agents read and write artifacts automatically
Workspaces — How workspace isolation works