refactor(dev): restructure Claude commands/skills directories
All checks were successful
CI / check (push) Successful in 3m16s
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:
123
home/roles/development/skills/micro/artifact-format.md
Normal file
123
home/roles/development/skills/micro/artifact-format.md
Normal 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
|
||||
Reference in New Issue
Block a user