John Ogle
7903b2dfd0
All checks were successful
CI / check (push) Successful in 3m16s
Correct terminology mismatch: - Rename skills/ to commands/ (these are user-invokable commands) - Create new skills/ for reference materials - Move bd_workflow.md to skills/ (it's reference material) - Add micro-skills and formulas directories - Update default.nix to install both commands and skills Commands → ~/.claude/commands/ (invokable as /command-name) Skills → ~/.claude/commands/skills/ (reference materials) Formulas → ~/.beads/formulas/ (workflow templates) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
124 lines
3.0 KiB
Markdown
124 lines
3.0 KiB
Markdown
---
|
|
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
|