refactor(dev): restructure Claude commands/skills directories
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>
This commit is contained in:
2026-01-15 17:16:55 -08:00
parent f472aa9b3d
commit 7903b2dfd0
17 changed files with 632 additions and 7 deletions

View File

@@ -0,0 +1,123 @@
---
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