From 7903b2dfd0cc57e4ef140a7badb7ab9986f42274 Mon Sep 17 00:00:00 2001 From: John Ogle Date: Thu, 15 Jan 2026 17:16:55 -0800 Subject: [PATCH] refactor(dev): restructure Claude commands/skills directories MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../beads_batch_research_plan.md | 0 .../{skills => commands}/beads_implement.md | 0 .../{skills => commands}/beads_iterate.md | 0 .../{skills => commands}/beads_plan.md | 0 .../{skills => commands}/beads_research.md | 0 .../{skills => commands}/beads_workflow.md | 0 .../{skills => commands}/gitea_pr_review.md | 0 .../import_gitea_issues.md | 0 .../{skills => commands}/parallel_beads.md | 0 .../{skills => commands}/reconcile_beads.md | 0 home/roles/development/default.nix | 39 +++++- .../formulas/quick-fix.formula.toml | 115 ++++++++++++++++ .../development/formulas/rpi.formula.toml | 124 ++++++++++++++++++ .../skills/micro/artifact-format.md | 123 +++++++++++++++++ .../development/skills/micro/planning.md | 121 +++++++++++++++++ .../skills/micro/pr-description.md | 68 ++++++++++ .../skills/micro/research-agents.md | 49 +++++++ 17 files changed, 632 insertions(+), 7 deletions(-) rename home/roles/development/{skills => commands}/beads_batch_research_plan.md (100%) rename home/roles/development/{skills => commands}/beads_implement.md (100%) rename home/roles/development/{skills => commands}/beads_iterate.md (100%) rename home/roles/development/{skills => commands}/beads_plan.md (100%) rename home/roles/development/{skills => commands}/beads_research.md (100%) rename home/roles/development/{skills => commands}/beads_workflow.md (100%) rename home/roles/development/{skills => commands}/gitea_pr_review.md (100%) rename home/roles/development/{skills => commands}/import_gitea_issues.md (100%) rename home/roles/development/{skills => commands}/parallel_beads.md (100%) rename home/roles/development/{skills => commands}/reconcile_beads.md (100%) create mode 100644 home/roles/development/formulas/quick-fix.formula.toml create mode 100644 home/roles/development/formulas/rpi.formula.toml create mode 100644 home/roles/development/skills/micro/artifact-format.md create mode 100644 home/roles/development/skills/micro/planning.md create mode 100644 home/roles/development/skills/micro/pr-description.md create mode 100644 home/roles/development/skills/micro/research-agents.md diff --git a/home/roles/development/skills/beads_batch_research_plan.md b/home/roles/development/commands/beads_batch_research_plan.md similarity index 100% rename from home/roles/development/skills/beads_batch_research_plan.md rename to home/roles/development/commands/beads_batch_research_plan.md diff --git a/home/roles/development/skills/beads_implement.md b/home/roles/development/commands/beads_implement.md similarity index 100% rename from home/roles/development/skills/beads_implement.md rename to home/roles/development/commands/beads_implement.md diff --git a/home/roles/development/skills/beads_iterate.md b/home/roles/development/commands/beads_iterate.md similarity index 100% rename from home/roles/development/skills/beads_iterate.md rename to home/roles/development/commands/beads_iterate.md diff --git a/home/roles/development/skills/beads_plan.md b/home/roles/development/commands/beads_plan.md similarity index 100% rename from home/roles/development/skills/beads_plan.md rename to home/roles/development/commands/beads_plan.md diff --git a/home/roles/development/skills/beads_research.md b/home/roles/development/commands/beads_research.md similarity index 100% rename from home/roles/development/skills/beads_research.md rename to home/roles/development/commands/beads_research.md diff --git a/home/roles/development/skills/beads_workflow.md b/home/roles/development/commands/beads_workflow.md similarity index 100% rename from home/roles/development/skills/beads_workflow.md rename to home/roles/development/commands/beads_workflow.md diff --git a/home/roles/development/skills/gitea_pr_review.md b/home/roles/development/commands/gitea_pr_review.md similarity index 100% rename from home/roles/development/skills/gitea_pr_review.md rename to home/roles/development/commands/gitea_pr_review.md diff --git a/home/roles/development/skills/import_gitea_issues.md b/home/roles/development/commands/import_gitea_issues.md similarity index 100% rename from home/roles/development/skills/import_gitea_issues.md rename to home/roles/development/commands/import_gitea_issues.md diff --git a/home/roles/development/skills/parallel_beads.md b/home/roles/development/commands/parallel_beads.md similarity index 100% rename from home/roles/development/skills/parallel_beads.md rename to home/roles/development/commands/parallel_beads.md diff --git a/home/roles/development/skills/reconcile_beads.md b/home/roles/development/commands/reconcile_beads.md similarity index 100% rename from home/roles/development/skills/reconcile_beads.md rename to home/roles/development/commands/reconcile_beads.md diff --git a/home/roles/development/default.nix b/home/roles/development/default.nix index c16fc30..bdfa682 100644 --- a/home/roles/development/default.nix +++ b/home/roles/development/default.nix @@ -90,8 +90,8 @@ in fi done - # Copy local skills from this repo (with retry for race conditions with running Claude) - for file in ${./skills}/*.md; do + # Copy local commands from this repo (with retry for race conditions with running Claude) + for file in ${./commands}/*.md; do if [ -f "$file" ]; then filename=$(basename "$file" .md) dest="$HOME/.claude/commands/''${filename}.md" @@ -104,11 +104,36 @@ in fi done - $DRY_RUN_CMD echo "Claude Code humanlayer commands and agents installed successfully${ - if cfg.allowArbitraryClaudeCodeModelSelection - then " (model specifications preserved)" - else " (model selection removed)" - } + local skills" + # Copy local skills (reference materials) to skills subdirectory + mkdir -p ~/.claude/commands/skills + for file in ${./skills}/*.md; do + if [ -f "$file" ]; then + filename=$(basename "$file" .md) + dest="$HOME/.claude/commands/skills/''${filename}.md" + rm -f "$dest" 2>/dev/null || true + if ! cp "$file" "$dest" 2>/dev/null; then + sleep 0.5 + cp "$file" "$dest" || echo "Warning: Failed to copy $filename.md to skills" + fi + fi + done + + # Copy micro-skills (compact reusable knowledge referenced by formulas) + for file in ${./skills/micro}/*.md; do + if [ -f "$file" ]; then + cp "$file" "$HOME/.claude/commands/skills/$(basename "$file")" + fi + done + + # Install beads formulas to user-level formula directory + mkdir -p ~/.beads/formulas + for file in ${./formulas}/*.formula.toml; do + if [ -f "$file" ]; then + cp "$file" "$HOME/.beads/formulas/$(basename "$file")" + fi + done + + $DRY_RUN_CMD echo "Claude Code plugins installed: humanlayer commands/agents + local commands + local skills + formulas" ''; # Set up beads Claude Code integration (hooks for SessionStart/PreCompact) diff --git a/home/roles/development/formulas/quick-fix.formula.toml b/home/roles/development/formulas/quick-fix.formula.toml new file mode 100644 index 0000000..8e9708e --- /dev/null +++ b/home/roles/development/formulas/quick-fix.formula.toml @@ -0,0 +1,115 @@ +# Quick Fix Formula +# +# Streamlined workflow for well-understood bugs and small fixes. +# Skips the deep research and planning phases of RPI - get in, fix, get out. +# +# Use when: +# - Bug is well-understood (you know what's broken) +# - Fix is straightforward (no architectural decisions) +# - Change is small (< 100 lines) +# +# Use RPI instead when: +# - Root cause is unclear +# - Multiple approaches possible +# - Significant design decisions needed + +formula = "quick-fix" +description = """ +Streamlined workflow for bugs and small fixes. + +A faster alternative to RPI for well-understood issues: +1. Quick investigation to confirm understanding +2. Implement the fix +3. Verify with tests +4. Commit and close + +No human gates - designed for quick turnaround on obvious fixes. +""" +version = 1 +type = "workflow" + +# === Variables === + +[vars.title] +required = true +description = "Brief description of the bug/fix" + +[vars.bead_id] +description = "Existing bead ID (creates new if not provided)" + +[vars.test_cmd] +default = "make test" +description = "Command to verify the fix" + +# === Steps === + +[[steps]] +id = "investigate" +title = "Investigate: {{title}}" +description = """ +Quick investigation to confirm understanding of the bug. + +Goals: +- Locate the problematic code +- Confirm root cause matches expectations +- Identify files that need changes + +This is NOT deep research - spend 5-10 minutes max. +If the bug is more complex than expected, pivot to RPI workflow. + +Output: Mental model of what to fix (no artifact needed). +""" + +[[steps]] +id = "fix" +title = "Fix: {{title}}" +needs = ["investigate"] +description = """ +Implement the fix. + +Guidelines: +- Make minimal changes to fix the issue +- Follow existing code patterns +- Add/update tests if appropriate +- Keep changes focused (no drive-by refactors) + +If the fix grows beyond expectations, pause and consider: +- Should this be an RPI workflow instead? +- Should we split into multiple changes? +""" + +[[steps]] +id = "verify" +title = "Verify fix" +needs = ["fix"] +description = """ +Verify the fix works correctly. + +Run: {{test_cmd}} + +Also check: +- Bug is actually fixed (manual verification) +- No obvious regressions introduced +- Code compiles/builds cleanly + +If tests fail, iterate on the fix step. +""" + +[[steps]] +id = "commit" +title = "Commit and close" +needs = ["verify"] +description = """ +Commit the fix and close the bead. + +Actions: +1. Stage changes: git add -A +2. Commit with descriptive message: git commit -m "fix: {{title}}" +3. Push to remote: git push +4. Close the bead: bd close {{bead_id}} + +Commit message should explain: +- What was broken +- How it was fixed +- Any relevant context +""" diff --git a/home/roles/development/formulas/rpi.formula.toml b/home/roles/development/formulas/rpi.formula.toml new file mode 100644 index 0000000..00f5b7a --- /dev/null +++ b/home/roles/development/formulas/rpi.formula.toml @@ -0,0 +1,124 @@ +# RPI Formula - Research -> Plan -> Implement +# +# Universal workflow for feature development with human gates. + +formula = "rpi" +description = """ +Research -> Plan -> Implement workflow. + +Usage: + bd pour rpi --var title="Add user preferences" + bd pour rpi --var title="Auth" --var bead_id="project-abc" --var test_cmd="nix flake check" +""" +version = 1 +type = "workflow" + +# ─── Variables ─── + +[vars.title] +required = true +description = "What are we building?" + +[vars.bead_id] +description = "Existing bead ID (creates new if not provided)" + +[vars.test_cmd] +default = "make test" +description = "Command to run tests" + +[vars.lint_cmd] +default = "make lint" +description = "Command to run linting" + +# ─── Research Phase ─── + +[[steps]] +id = "research" +title = "Research: {{title}}" +skill = "research-agents" +description = """ +Conduct comprehensive codebase research. + +Goals: +- Understand current implementation +- Identify patterns to follow +- Find relevant files and dependencies +- Document key discoveries + +Output: thoughts/beads-{{bead_id}}/research.md +""" + +# ─── Planning Phase ─── + +[[steps]] +id = "plan" +title = "Plan: {{title}}" +needs = ["research"] +type = "human" +skill = "planning" +description = """ +Create detailed implementation plan based on research. + +Goals: +- Present understanding and clarify requirements +- Propose design options with tradeoffs +- Define phases with success criteria +- Identify what we're NOT doing + +Output: thoughts/beads-{{bead_id}}/plan.md +""" + +[steps.gate] +type = "human" +reason = "Plan approval before implementation" + +# ─── Implementation Phase ─── + +[[steps]] +id = "implement" +title = "Implement: {{title}}" +needs = ["plan"] +description = """ +Execute the approved plan phase by phase. + +For each phase: +1. Make the changes +2. Run verification: {{test_cmd}}, {{lint_cmd}} +3. Update plan checkboxes for resumability + +Stop and ask if encountering unexpected issues. +""" + +# ─── Verification Phase ─── + +[[steps]] +id = "verify" +title = "Manual verification" +needs = ["implement"] +type = "human" +description = """ +Human confirms implementation works correctly. + +Check: feature works, edge cases handled, no regressions. +Tests: {{test_cmd}} | Lint: {{lint_cmd}} +""" + +[steps.gate] +type = "human" +reason = "Confirm implementation is correct" + +# ─── Completion ─── + +[[steps]] +id = "complete" +title = "Close bead" +needs = ["verify"] +skill = "artifact-format" +description = """ +Mark work as complete. + +Actions: +- bd update {{bead_id}} --notes="Implementation complete" +- bd close {{bead_id}} --reason="Completed: {{title}}" +- bd sync && git push +""" diff --git a/home/roles/development/skills/micro/artifact-format.md b/home/roles/development/skills/micro/artifact-format.md new file mode 100644 index 0000000..d75bef9 --- /dev/null +++ b/home/roles/development/skills/micro/artifact-format.md @@ -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 diff --git a/home/roles/development/skills/micro/planning.md b/home/roles/development/skills/micro/planning.md new file mode 100644 index 0000000..210a596 --- /dev/null +++ b/home/roles/development/skills/micro/planning.md @@ -0,0 +1,121 @@ +--- +description: How to create effective implementation plans with phased delivery and clear success criteria +--- + +# Planning + +Create implementation plans that enable incremental, verifiable progress. + +## Core Principles + +1. **Incremental delivery**: Each phase should produce working, testable changes +2. **Clear checkpoints**: Success criteria that can be verified without ambiguity +3. **Buy-in before detail**: Confirm understanding and approach before writing specifics +4. **Explicit scope**: State what we're NOT doing to prevent scope creep + +## Plan Document Structure + +```markdown +# {Feature} Implementation Plan + +## Overview +{1-2 sentences: what we're building and why} + +## Current State Analysis +{What exists now, key constraints, file:line references} + +## Desired End State +{Specification of outcome and how to verify it} + +## What We're NOT Doing +{Explicit out-of-scope items} + +## Phase 1: {Descriptive Name} +### Overview +{What this phase accomplishes - should be independently valuable} + +### Changes Required +{Specific files and modifications with code snippets} + +### Success Criteria +#### Automated Verification +- [ ] Tests pass: `{test command}` +- [ ] Lint passes: `{lint command}` + +#### Manual Verification +- [ ] {Human-observable outcome} + +## Testing Strategy +{Unit tests, integration tests, manual testing steps} + +## References +{Links to research, related files, similar implementations} +``` + +## Phase Design + +Good phases are: +- **Self-contained**: Completable in one session +- **Testable**: Has clear pass/fail criteria +- **Reversible**: Can be rolled back if needed +- **Incremental**: Builds on previous phases without requiring all phases + +Bad phases are: +- "Refactor everything" (too broad) +- "Add helper function" (too granular) +- Phases that only work if ALL phases complete + +## Success Criteria Guidelines + +**Automated Verification** (agent-runnable): +- Test commands: `make test`, `npm test`, `nix flake check` +- Lint/format: `make lint`, `cargo fmt --check` +- Type checking: `make typecheck`, `tsc --noEmit` +- Build verification: `make build`, `nix build` + +**Manual Verification** (requires human): +- UI/UX functionality and appearance +- Performance under realistic conditions +- Edge cases hard to automate +- Integration with external systems + +**From Contribution Guidelines** (if CONTRIBUTING.md exists): +- Include any testing requirements specified +- Reference the guideline: "Per CONTRIBUTING.md: {requirement}" + +## Presenting Understanding + +Before writing the plan, confirm alignment: + +``` +Based on the requirements and my research, I understand we need to [summary]. + +I've found that: +- [Current implementation detail with file:line] +- [Relevant pattern or constraint] +- [Potential complexity identified] + +Questions my research couldn't answer: +- [Specific technical question requiring judgment] +``` + +Only ask questions you genuinely cannot answer through code investigation. + +## Design Options Pattern + +When multiple approaches exist: + +``` +**Design Options:** +1. [Option A] - [1-sentence description] + - Pro: [benefit] + - Con: [drawback] + +2. [Option B] - [1-sentence description] + - Pro: [benefit] + - Con: [drawback] + +Which approach aligns best with [relevant consideration]? +``` + +Get buy-in on approach before detailing phases. diff --git a/home/roles/development/skills/micro/pr-description.md b/home/roles/development/skills/micro/pr-description.md new file mode 100644 index 0000000..c636a88 --- /dev/null +++ b/home/roles/development/skills/micro/pr-description.md @@ -0,0 +1,68 @@ +--- +description: How to write comprehensive PR descriptions that help reviewers understand changes +--- + +# PR Description + +Write PR descriptions that help reviewers understand what changed and why. + +## Structure + +Use this standard structure for PR descriptions: + +```markdown +## Summary +<1-3 bullet points of what changed and why> + +## Context + + + +## Changes + +- Area 1: What changed and why +- Area 2: What changed and why + +## Testing + +- Automated: Tests added/updated, CI status +- Manual: Steps to verify functionality + +## Screenshots (if UI changes) + +``` + +## Guidelines + +### Lead with WHY, not WHAT +- The diff shows WHAT changed - your description explains WHY +- Start with the problem being solved +- Explain the approach chosen and alternatives considered + +### Link to context +- Reference related issues: `Fixes #123` or `Relates to #456` +- Link to design docs or discussions +- Mention dependent PRs if any + +### Call out review areas +- Highlight areas needing careful review +- Note any tricky or non-obvious code +- Point out architectural decisions + +### Note breaking changes prominently +- Use a dedicated "Breaking Changes" section if applicable +- Explain migration path for consumers +- List any deprecations + +### Be scannable +- Use bullet points over paragraphs +- Keep sections focused and concise +- Put the most important info first + +## Anti-patterns to Avoid + +- Empty descriptions or just "fixes bug" +- Repeating the commit messages verbatim +- Including irrelevant implementation details +- Missing context on why the change was made +- Forgetting to mention breaking changes diff --git a/home/roles/development/skills/micro/research-agents.md b/home/roles/development/skills/micro/research-agents.md new file mode 100644 index 0000000..a57dd24 --- /dev/null +++ b/home/roles/development/skills/micro/research-agents.md @@ -0,0 +1,49 @@ +--- +description: How to spawn and coordinate research sub-agents +--- + +# Research Agents + +Use parallel sub-agents for efficient codebase research. + +## Available Agents + +| Agent | Purpose | +|-------|---------| +| codebase-locator | Find WHERE files and components live | +| codebase-analyzer | Understand HOW specific code works | +| codebase-pattern-finder | Find examples of existing patterns | +| thoughts-locator | Discover relevant documents in thoughts/ | + +## Spawning Protocol + +1. **Decompose** - Break the research question into 3-5 specific questions +2. **Spawn parallel** - Use one Task call with multiple agents +3. **Be specific** - Include directories and file patterns in prompts +4. **Wait for all** - Do not synthesize until ALL agents complete +5. **Synthesize** - Combine findings into coherent summary with file:line references + +## Example + +``` +Task(codebase-locator, "Find all files related to authentication in src/") +Task(codebase-analyzer, "Explain how JWT tokens are validated in src/auth/") +Task(codebase-pattern-finder, "Find examples of middleware patterns in src/") +Task(thoughts-locator, "Find documents about auth design decisions in thoughts/") +``` + +## Key Principles + +- **Parallel when different** - Run agents in parallel when searching for different things +- **WHAT not HOW** - Each agent knows its job; tell it what you need, not how to search +- **Document, don't evaluate** - Agents should describe what exists, not critique it +- **Specific directories** - Always scope searches to relevant directories +- **File references** - Include specific file:line references in synthesis + +## Agent Prompts + +When spawning agents, include: +- The specific question or goal +- Relevant directories to search +- Reminder to document (not evaluate) what they find +- Request for file:line references in findings