feat(skills): Add beads-aware workflow skills
New skills for integrated beads + humanlayer workflow:
- beads_research.md: Research with per-bead artifact storage
- beads_plan.md: Planning with bead linking
- beads_implement.md: Implementation with per-plan checkpoints
- beads_iterate.md: Plan iteration with version history
- beads_workflow.md: Comprehensive workflow documentation
Skills output to thoughts/beads-{id}/ for artifact storage
and automatically update bead notes with artifact links.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
206
home/roles/development/skills/beads_research.md
Normal file
206
home/roles/development/skills/beads_research.md
Normal file
@@ -0,0 +1,206 @@
|
||||
---
|
||||
description: Research a bead topic comprehensively and store findings in thoughts/
|
||||
model: opus
|
||||
---
|
||||
|
||||
# Beads Research
|
||||
|
||||
You are tasked with conducting comprehensive research for a bead issue. This skill integrates with the beads issue tracker and stores findings in the `thoughts/` directory.
|
||||
|
||||
## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
|
||||
- DO NOT suggest improvements or changes unless the user explicitly asks for them
|
||||
- DO NOT perform root cause analysis unless the user explicitly asks for them
|
||||
- DO NOT propose future enhancements unless the user explicitly asks for them
|
||||
- DO NOT critique the implementation or identify problems
|
||||
- ONLY describe what exists, where it exists, how it works, and how components interact
|
||||
- You are creating a technical map/documentation of the existing system
|
||||
|
||||
## Initial Setup
|
||||
|
||||
When this command is invoked:
|
||||
|
||||
1. **Parse the input for bead ID**:
|
||||
- If a bead ID is provided (e.g., `nixos-configs-abc123`), use it
|
||||
- If no bead ID provided, run `bd ready --type=research` to find research beads, or ask which bead to research
|
||||
|
||||
2. **Load bead context**:
|
||||
```bash
|
||||
bd show {bead-id}
|
||||
```
|
||||
- Read the bead description to understand the research question
|
||||
- Note any linked files or references in the bead
|
||||
|
||||
3. **Create artifact directory**:
|
||||
```bash
|
||||
mkdir -p thoughts/beads-{bead-id}
|
||||
```
|
||||
|
||||
4. **Respond with**:
|
||||
```
|
||||
Starting research for bead {bead-id}: {bead-title}
|
||||
|
||||
Research question: {extracted from bead description}
|
||||
|
||||
I'll analyze this thoroughly and store findings in thoughts/beads-{bead-id}/research.md
|
||||
```
|
||||
|
||||
## Research Process
|
||||
|
||||
### Step 1: Read any directly mentioned files
|
||||
- If the bead or user mentions specific files, read them FULLY first
|
||||
- Use the Read tool WITHOUT limit/offset parameters
|
||||
- Read these files yourself in the main context before spawning sub-tasks
|
||||
|
||||
### Step 2: Analyze and decompose the research question
|
||||
- Break down the query into composable research areas
|
||||
- Identify specific components, patterns, or concepts to investigate
|
||||
- Create a research plan using TodoWrite
|
||||
- Consider which directories, files, or patterns are relevant
|
||||
|
||||
### Step 3: Spawn parallel sub-agent tasks
|
||||
|
||||
Use specialized agents for research:
|
||||
|
||||
**For codebase research:**
|
||||
- **codebase-locator** - Find WHERE files and components live
|
||||
- **codebase-analyzer** - Understand HOW specific code works
|
||||
- **codebase-pattern-finder** - Find examples of existing patterns
|
||||
|
||||
**For thoughts directory:**
|
||||
- **thoughts-locator** - Discover what documents exist about the topic
|
||||
- **thoughts-analyzer** - Extract key insights from specific documents
|
||||
|
||||
**For web research (only if explicitly requested):**
|
||||
- **web-search-researcher** - External documentation and resources
|
||||
|
||||
Key principles:
|
||||
- Run multiple agents in parallel when searching for different things
|
||||
- Each agent knows its job - tell it what you're looking for, not HOW to search
|
||||
- Remind agents they are documenting, not evaluating
|
||||
|
||||
### Step 4: Synthesize findings
|
||||
|
||||
Wait for ALL sub-agents to complete, then:
|
||||
- Compile all results (codebase and thoughts findings)
|
||||
- Prioritize live codebase findings as primary source of truth
|
||||
- Connect findings across different components
|
||||
- Include specific file paths and line numbers
|
||||
- Highlight patterns, connections, and architectural decisions
|
||||
|
||||
### Step 5: Gather metadata
|
||||
|
||||
```bash
|
||||
# Git metadata
|
||||
git rev-parse HEAD # Current commit
|
||||
git branch --show-current # Current branch
|
||||
basename $(git rev-parse --show-toplevel) # Repo name
|
||||
date -Iseconds # Current timestamp
|
||||
```
|
||||
|
||||
### Step 6: Write research document
|
||||
|
||||
Write to `thoughts/beads-{bead-id}/research.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
date: {ISO timestamp with timezone}
|
||||
bead_id: {bead-id}
|
||||
bead_title: "{bead title}"
|
||||
researcher: claude
|
||||
git_commit: {commit hash}
|
||||
branch: {branch name}
|
||||
repository: {repo name}
|
||||
status: complete
|
||||
---
|
||||
|
||||
# Research: {bead title}
|
||||
|
||||
**Bead**: {bead-id}
|
||||
**Date**: {timestamp}
|
||||
**Git Commit**: {commit hash}
|
||||
**Branch**: {branch name}
|
||||
|
||||
## Research Question
|
||||
{Original question from bead description}
|
||||
|
||||
## Summary
|
||||
{High-level documentation answering the research question}
|
||||
|
||||
## Detailed Findings
|
||||
|
||||
### {Component/Area 1}
|
||||
- Description of what exists (file.ext:line)
|
||||
- How it connects to other components
|
||||
- Current implementation details
|
||||
|
||||
### {Component/Area 2}
|
||||
...
|
||||
|
||||
## Code References
|
||||
- `path/to/file.py:123` - Description
|
||||
- `another/file.ts:45-67` - Description
|
||||
|
||||
## Architecture Documentation
|
||||
{Current patterns, conventions found in codebase}
|
||||
|
||||
## Historical Context (from thoughts/)
|
||||
{Relevant insights from thoughts/ with references}
|
||||
|
||||
## Open Questions
|
||||
{Any areas needing further investigation}
|
||||
```
|
||||
|
||||
### Step 7: Update the bead
|
||||
|
||||
```bash
|
||||
# Add artifact link to bead notes
|
||||
bd update {bead-id} --notes="Research complete: thoughts/beads-{bead-id}/research.md"
|
||||
```
|
||||
|
||||
### Step 8: Autonomy decision
|
||||
|
||||
**For research beads (type=research):**
|
||||
- If research is complete and comprehensive, close the bead:
|
||||
```bash
|
||||
bd close {bead-id} --reason="Research complete. See thoughts/beads-{bead-id}/research.md"
|
||||
```
|
||||
- Present summary to user
|
||||
|
||||
**For other bead types:**
|
||||
- Do NOT close the bead
|
||||
- Present findings and ask how to proceed
|
||||
|
||||
### Step 9: Handle follow-up questions
|
||||
|
||||
If the user has follow-up questions:
|
||||
- Append to the same research document
|
||||
- Add a new section: `## Follow-up Research [{timestamp}]`
|
||||
- Update the bead notes with the new findings
|
||||
|
||||
## Important Guidelines
|
||||
|
||||
- Always use parallel Task agents to maximize efficiency
|
||||
- Always run fresh codebase research - never rely solely on existing documents
|
||||
- Focus on finding concrete file paths and line numbers
|
||||
- Research documents should be self-contained
|
||||
- Document cross-component connections
|
||||
- Include temporal context (when research was conducted)
|
||||
- Keep the main agent focused on synthesis, not deep file reading
|
||||
- **CRITICAL**: You and all sub-agents are documentarians, not evaluators
|
||||
- **REMEMBER**: Document what IS, not what SHOULD BE
|
||||
|
||||
## Example Invocation
|
||||
|
||||
```
|
||||
User: /beads:research nixos-configs-abc123
|
||||
Assistant: Starting research for bead nixos-configs-abc123: Investigate auth flow
|
||||
...
|
||||
```
|
||||
|
||||
Or without bead ID:
|
||||
```
|
||||
User: /beads:research
|
||||
Assistant: Let me check for research beads...
|
||||
[runs bd ready]
|
||||
Which bead would you like me to research?
|
||||
```
|
||||
Reference in New Issue
Block a user