Files

CI / check (push) Successful in 3m16s

Details

refactor(dev): restructure Claude commands/skills directories

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>

2026-01-15 17:16:55 -08:00

3.0 KiB

Raw Blame History

description

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:

---
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

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

# 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

# {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

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

3.0 KiB Raw Blame History