---
description: How to structure research and plan artifacts in thoughts/
---

# Artifact Format

Standardized format for thoughts/ artifacts. All beads-related artifacts should follow these conventions for consistency and machine parseability.

## Frontmatter (Required)

Every artifact MUST include YAML frontmatter:

```yaml
---
date: 2026-01-15T10:00:00-08:00  # ISO 8601 with timezone
bead_id: project-abc              # Bead identifier
bead_title: "Title of the bead"   # Human-readable title
author: claude                    # Who created this
git_commit: abc123def             # Commit hash at creation
branch: main                      # Branch name
repository: repo-name             # Repository name
status: draft|complete            # Artifact status
---
```

### Gathering Metadata

```bash
git rev-parse HEAD                           # Current commit
git branch --show-current                    # Current branch
basename $(git rev-parse --show-toplevel)    # Repo name
date -Iseconds                               # ISO timestamp
```

## Research Artifact Structure

Location: `thoughts/beads-{bead-id}/research.md`

```markdown
# Research: {bead title}

**Bead**: {bead-id}
**Date**: {timestamp}
**Git Commit**: {commit hash}

## Research Question
{Original question from bead description}

## Summary
{2-3 sentence overview answering the research question}

## Key Discoveries
- {Finding with file:line reference}
- {Pattern or convention found}
- {Architectural decision documented}

## Architecture
{Current patterns and conventions in the codebase}

## Code References
- `path/to/file.py:123` - Description of relevance
- `another/file.ts:45-67` - Description of relevance

## Open Questions
{Areas needing further investigation or human clarification}
```

## Plan Artifact Structure

Location: `thoughts/beads-{bead-id}/plan.md`

```markdown
# {Title} Implementation Plan

## Overview
{What we're implementing and why - 1-2 sentences}

## Current State
{What exists now, key constraints discovered}

### Key Discoveries
- {Finding with file:line reference}
- {Pattern to follow}

## Desired End State
{Specification of what success looks like}

## What We're NOT Doing
{Explicitly list out-of-scope items}

## Phase 1: {Descriptive Name}

### Overview
{What this phase accomplishes}

### Changes
- [ ] {Specific change with file path}
- [ ] {Another change}

### Success Criteria

#### Automated
- [ ] Tests pass: `{test command}`
- [ ] Lint passes: `{lint command}`

#### Manual
- [ ] {Human verification step}

## Phase 2: {Descriptive Name}
{Repeat structure...}

## References
- Bead: {bead-id}
- Research: `thoughts/beads-{bead-id}/research.md`
```

## Key Principles

1. **Always include file:line references** - Makes artifacts actionable
2. **Separate automated vs manual verification** - Enables agent autonomy
3. **Use checkboxes for phases** - Enables resumability after interruption
4. **Keep frontmatter machine-parseable** - Enables tooling integration
5. **Link related artifacts** - Research links to plan, plan links to bead