johno/nixos-configs
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(dev): restructure Claude commands/skills directories
All checks were successful
CI / check (push) Successful in 3m16s
Details

Browse Source 
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:
John Ogle
2026-01-15 17:16:55 -08:00
parent f472aa9b3d
commit 7903b2dfd0
17 changed files with 632 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

317
home/roles/development/commands/beads_batch_research_plan.md Normal file
View File

@@ -0,0 +1,317 @@
---
description: Batch research and planning for multiple beads with interactive question review
model: opus
---
# Beads Batch Research+Plan
This skill automates the common workflow of:
1. Running /beads_research in parallel for multiple beads
2. Presenting open questions interactively for user input (bead-by-bead)
3. Running /beads_plan for all researched beads (plus any spawned from splits)
## When to Use
- You have multiple beads ready for work
- You want to research and plan them efficiently before implementation
- You prefer to batch your question-answering rather than context-switching between skills
## Phase 1: Selection
1. **Get ready beads**: Run `bd ready --limit=20` to list beads with no blockers
2. **Filter already-researched beads**:
For each ready bead, check if it already has research:
```bash
ls thoughts/beads-{bead-id}/research.md 2>/dev/null
```
Categorize beads:
- **Needs research**: No `research.md` exists
- **Has research, needs plan**: `research.md` exists but no `plan.md`
- **Already planned**: Both `research.md` and `plan.md` exist
3. **Present selection**:
```
Ready beads available for batch research+plan:
NEEDS RESEARCH:
- {bead-id}: {title} (type: {type})
- ...
HAS RESEARCH (plan only):
- {bead-id}: {title} (type: {type})
- ...
ALREADY PLANNED (skip):
- {bead-id}: {title}
Which beads would you like to process?
```
4. **Use AskUserQuestion** with `multiSelect: true`:
- Include bead ID and title for each option
- Separate options by category
- Allow selection across categories
## Phase 2: Parallel Research
For each selected bead that NEEDS RESEARCH, launch a research subagent.
### Subagent Instructions Template
```
Research bead [BEAD_ID]: [BEAD_TITLE]
1. **Load bead context**:
```bash
bd show [BEAD_ID]
```
2. **Create artifact directory**:
```bash
mkdir -p thoughts/beads-[BEAD_ID]
```
3. **Conduct research** following beads_research.md patterns:
- Analyze and decompose the research question
- Spawn parallel sub-agent tasks (codebase-locator, codebase-analyzer, etc.)
- Synthesize findings
4. **Write research document** to `thoughts/beads-[BEAD_ID]/research.md`:
- Include frontmatter with metadata
- Document findings with file:line references
- **CRITICAL**: Include "## Open Questions" section listing any unresolved items
5. **Return summary**:
- Research status (complete/partial)
- Number of open questions
- Key findings summary (2-3 bullet points)
- List of open questions verbatim
```
### Launching Subagents
Use `subagent_type: "opus"` for research subagents (matches beads_research model setting).
Launch ALL research subagents in a single message for parallel execution:
```
<Task calls for each selected bead needing research - all in one message>
```
### Collecting Results
Wait for ALL research subagents to complete. Collect:
- Bead ID
- Research status
- Open questions list
- Any errors encountered
## Phase 3: Interactive Question Review
Present each bead's open questions sequentially for user input.
### For Each Bead (in order):
1. **Present research summary**:
```
## Bead {N}/{total}: {bead-id} - {title}
Research complete. Key findings:
- {finding 1}
- {finding 2}
Open questions requiring your input:
1. {question 1}
2. {question 2}
Additionally:
- Should this bead be split into multiple beads? (y/n)
- If split, describe the split:
```
2. **Collect user responses**:
- Answers to open questions
- Split decision (yes/no)
- If split: new bead titles and how to divide the work
3. **Handle splits**:
If user indicates a split:
```bash
# Create new beads for split work
bd create --title="{split title 1}" --type={type} --priority={priority} \
--description="{description based on user input}"
# Update original bead if scope narrowed
bd update {original-bead-id} --description="{updated description}"
```
Track new bead IDs for inclusion in planning phase.
4. **Update research document**:
Append user answers to `thoughts/beads-{id}/research.md`:
```markdown
## User Clarifications [{timestamp}]
Q: {question 1}
A: {user answer 1}
Q: {question 2}
A: {user answer 2}
## Bead Splits
{If split: description of split and new bead IDs}
```
### Progress Tracking
After each bead's questions are answered, confirm before moving to next:
```
Questions answered for {bead-id}. {N-1} beads remaining.
Continue to next bead? (y/n)
```
### Beads with No Questions
If a bead's research had no open questions:
```
## Bead {N}/{total}: {bead-id} - {title}
Research complete with no open questions.
Key findings:
- {finding 1}
- {finding 2}
Should this bead be split? (y/n)
```
## Phase 4: Parallel Planning
After all questions answered, launch planning subagents for all beads.
### Beads to Plan
Include:
- Original beads that were researched
- Beads that had existing research (from selection phase)
- New beads spawned from splits
### Subagent Instructions Template
```
Create implementation plan for bead [BEAD_ID]: [BEAD_TITLE]
1. **Load context**:
```bash
bd show [BEAD_ID]
```
2. **Read research** (it exists and has user clarifications):
Read `thoughts/beads-[BEAD_ID]/research.md` FULLY
3. **Create plan** following beads_plan.md patterns:
- Context gathering via sub-agents
- Design approach based on research findings and user clarifications
- **Skip interactive questions** - they were already answered in research review
4. **Write plan** to `thoughts/beads-[BEAD_ID]/plan.md`:
- Full plan structure with phases
- Success criteria (automated and manual)
- References to research document
5. **Update bead**:
```bash
bd update [BEAD_ID] --notes="Plan created: thoughts/beads-[BEAD_ID]/plan.md"
```
6. **Return summary**:
- Plan status (complete/failed)
- Number of phases
- Estimated complexity (small/medium/large)
- Any issues encountered
```
### Launching Subagents
Use `subagent_type: "opus"` for planning subagents (matches beads_plan model setting).
Launch ALL planning subagents in a single message:
```
<Task calls for each bead to plan - all in one message>
```
### Handling Beads Without Research
For beads that had existing research but user didn't review questions:
- Planning subagent reads existing research
- If research has unresolved open questions, subagent should flag this in its return
## Phase 5: Summary
After all planning completes, present final summary.
### Summary Format
```
## Batch Research+Plan Complete
### Successfully Processed:
| Bead | Title | Research | Plan | Phases | Complexity |
|------|-------|----------|------|--------|------------|
| {id} | {title} | Complete | Complete | 3 | medium |
| {id} | {title} | Complete | Complete | 2 | small |
### New Beads (from splits):
| Bead | Title | Parent | Status |
|------|-------|--------|--------|
| {new-id} | {title} | {parent-id} | Planned |
### Failed:
| Bead | Title | Phase Failed | Error |
|------|-------|--------------|-------|
| {id} | {title} | Research | Timeout |
### Next Steps:
1. Review plans at `thoughts/beads-{id}/plan.md`
2. Run `/parallel_beads` to implement all planned beads
3. Or run `/beads_implement {id}` for individual implementation
### Artifacts Created:
- Research: thoughts/beads-{id}/research.md (x{N} files)
- Plans: thoughts/beads-{id}/plan.md (x{N} files)
```
## Error Handling
### Research Subagent Failure
- Log the failure with bead ID and error
- Continue with other beads
- Exclude failed beads from question review and planning
- Report in final summary
### Planning Subagent Failure
- Log the failure with bead ID and error
- Research still valid - can retry planning manually
- Report in final summary
### User Cancellation During Question Review
- Save progress to bead notes
- Report which beads were completed
- User can resume with remaining beads in new session
### Split Bead Creation Failure
- Report error but continue with original bead
- User can manually create split beads later
## Resource Limits
- Maximum concurrent research subagents: 5
- Maximum concurrent planning subagents: 5
- If more beads selected, process in batches
## Notes
- This skill is designed for the "research+plan before implementation" workflow
- Pairs well with `/parallel_beads` for subsequent implementation
- Run `/reconcile_beads` after implementation PRs merge

253
home/roles/development/commands/beads_implement.md Normal file
View File

@@ -0,0 +1,253 @@
---
description: Implement a plan from thoughts/ for a bead issue
---
# Beads Implement
You are tasked with implementing an approved plan for a bead issue. Plans are stored in `thoughts/beads-{id}/plan.md`.
## Initial Setup
When this command is invoked:
1. **Parse the input for bead ID**:
- If a bead ID is provided, use it
- If no bead ID, check for beads with plans:
```bash
bd list --status=in_progress
```
Then check which have plans in `thoughts/beads-{id}/plan.md`
2. **Load bead context**:
```bash
bd show {bead-id}
```
Note the bead **type** (bug, feature, task) from the output.
3. **Check for plan and handle by type**:
Check if plan exists:
```bash
ls thoughts/beads-{bead-id}/plan.md 2>/dev/null
```
**If plan exists**: Proceed normally (skip to step 4)
**If no plan**:
- **type=bug**: Proceed without plan (simple bugs can implement directly)
- **type=feature or type=task**: Warn and ask:
```
No plan found for this {type}.
Plans help ensure complex work is well-designed and verifiable.
Location expected: thoughts/beads-{bead-id}/plan.md
Options:
1. Create a plan first (recommended) - Run /beads_plan {bead-id}
2. Proceed without a plan (for simple changes)
How would you like to proceed?
```
Wait for user response before continuing.
4. **Load plan and research context** (if plan exists):
- Read `thoughts/beads-{bead-id}/plan.md` FULLY
- Check for any existing checkmarks (- [x]) indicating partial progress
- Read any research at `thoughts/beads-{bead-id}/research.md`
- If plan's Success Criteria references contribution guidelines (e.g., "Per CONTRIBUTING.md:"),
verify the original CONTRIBUTING.md still exists and requirements are current
5. **Mark bead in progress** (if not already):
```bash
bd update {bead-id} --status=in_progress
```
6. **Respond with**:
```
Implementing plan for bead {bead-id}: {bead-title}
Plan location: thoughts/beads-{bead-id}/plan.md
{If partial progress: "Resuming from Phase X - previous phases completed."}
I'll implement each phase and verify success criteria before proceeding.
```
## Implementation Process
### Step 1: Understand the Plan
1. **Read the plan completely**
2. **Check for existing progress** (checkmarked items)
3. **Read all files mentioned in the plan**
4. **Create a TodoWrite list** tracking each phase
### Step 2: Implement Each Phase
For each phase in the plan:
1. **Announce the phase**:
```
## Starting Phase {N}: {Phase Name}
This phase will: {overview from plan}
```
2. **Make the changes**:
- Follow the plan's specific instructions
- Use Edit tool for modifications
- Create new files only when specified
3. **Run automated verification**:
- Execute each command in "Automated Verification"
- Fix any issues before proceeding
4. **Update plan checkboxes**:
- Use Edit tool to check off completed items in the plan
- This enables resume if session is interrupted
5. **Update bead notes** with progress:
```bash
bd update {bead-id} --notes="Phase {N} complete. Automated verification passed."
```
### Step 3: Per-Plan Checkpoint
**CRITICAL**: After completing ALL phases and ALL automated verification:
```
## Implementation Complete - Ready for Manual Verification
All phases completed and automated verification passed:
- [ ] Phase 1: {name} - DONE
- [ ] Phase 2: {name} - DONE
- [ ] ...
**Automated checks passed:**
- {List of automated checks that passed}
**Please perform manual verification:**
- {List manual verification items from plan}
Let me know when manual testing is complete so I can close the bead.
**Contribution guidelines compliance:**
- {List any contribution guideline requirements that were part of Success Criteria}
- {Note if any requirements could not be automated and need manual review}
```
**STOP HERE and wait for user confirmation.**
Do NOT:
- Close the bead automatically
- Proceed to "next steps" without confirmation
- Start additional work
### Step 4: After Manual Verification
When user confirms manual verification passed:
1. **Update plan status**:
- Edit the plan's frontmatter: `status: complete`
2. **Close the bead**:
```bash
bd close {bead-id} --reason="Implementation complete. All verification passed."
```
3. **Final summary**:
```
Bead {bead-id} closed.
Summary:
- {What was implemented}
- {Key changes made}
Artifacts:
- Plan: thoughts/beads-{bead-id}/plan.md
- {Any other artifacts created}
```
## Handling Issues
### When something doesn't match the plan:
```
Issue in Phase {N}:
Expected: {what the plan says}
Found: {actual situation}
Why this matters: {explanation}
Options:
1. Adapt the implementation to work with current state
2. Update the plan to reflect reality
3. Stop and investigate further
How should I proceed?
```
### When tests fail:
1. **Analyze the failure**
2. **Attempt to fix** if the fix is clear and within scope
3. **If fix is unclear**, report:
```
Test failure in Phase {N}:
Failing test: {test name}
Error: {error message}
I've attempted: {what you tried}
This may require: {your assessment}
```
### When blocked:
```
Blocked in Phase {N}:
Blocker: {description}
Impact: {what can't proceed}
Suggested resolution: {your recommendation}
```
## Resuming Work
If the plan has existing checkmarks:
1. **Trust completed work** - don't re-verify unless something seems off
2. **Pick up from first unchecked item**
3. **Verify previous work only if** current phase depends on it and seems broken
## Important Guidelines
1. **Follow the plan's intent** while adapting to reality
2. **Implement each phase fully** before moving to next
3. **Update checkboxes in real-time** as you complete items
4. **One checkpoint per plan** - not per phase
5. **Never close bead** without manual verification confirmation
6. **Keep bead notes updated** with progress
## Session Close Protocol
If you need to end the session before completion:
1. **Update plan** with current progress (checkboxes)
2. **Update bead notes**:
```bash
bd update {bead-id} --notes="In progress: Phase {N} partially complete. Next: {what's next}"
```
3. **Inform user** of status and how to resume
## Example Invocation
```
User: /beads:implement nixos-configs-abc123
Assistant: Implementing plan for bead nixos-configs-abc123...
## Starting Phase 1: Database Schema
This phase will add the new user_preferences table...
```

214
home/roles/development/commands/beads_iterate.md Normal file
View File

@@ -0,0 +1,214 @@
---
description: Iterate on existing implementation plans for a bead issue
model: opus
---
# Beads Iterate
You are tasked with updating existing implementation plans based on feedback. Plans are stored in `thoughts/beads-{id}/plan.md`.
## Initial Setup
When this command is invoked:
1. **Parse the input**:
- Bead ID (required or ask for it)
- Requested changes/feedback (can be provided with command or after)
2. **Handle different scenarios**:
**No bead ID provided**:
```
Which bead's plan would you like to iterate on?
Recent beads with plans:
{list beads that have thoughts/beads-{id}/plan.md}
```
**Bead ID but no feedback**:
```
I've found the plan at thoughts/beads-{bead-id}/plan.md
What changes would you like to make? For example:
- "Add a phase for migration handling"
- "Update success criteria to include performance tests"
- "Adjust scope to exclude feature X"
- "Split Phase 2 into two separate phases"
```
**Both bead ID and feedback provided**:
- Proceed immediately to Step 1
## Iteration Process
### Step 1: Understand Current Plan
1. **Read the existing plan COMPLETELY**:
```bash
cat thoughts/beads-{bead-id}/plan.md
```
- Understand current structure, phases, scope
- Note success criteria and approach
2. **Read the bead for context**:
```bash
bd show {bead-id}
```
3. **Understand requested changes**:
- Parse what user wants to add/modify/remove
- Identify if changes require codebase research
### Step 2: Research If Needed
**Only if changes require new technical understanding:**
1. **Spawn parallel research tasks**:
- **codebase-locator**: Find relevant files
- **codebase-analyzer**: Understand implementation details
- **codebase-pattern-finder**: Find similar patterns
2. **Be specific about directories** in prompts
3. **Wait for ALL tasks** before proceeding
### Step 3: Present Understanding
Before making changes:
```
Based on your feedback, I understand you want to:
- {Change 1 with specific detail}
- {Change 2 with specific detail}
{If research was needed:}
My research found:
- {Relevant discovery}
- {Important constraint}
I plan to update the plan by:
1. {Specific modification}
2. {Another modification}
Does this align with your intent?
```
Get user confirmation before proceeding.
### Step 4: Update the Plan
1. **Make focused, precise edits**:
- Use Edit tool for surgical changes
- Maintain existing structure unless explicitly changing it
- Keep file:line references accurate
2. **Ensure consistency**:
- New phases follow existing pattern
- Update "What We're NOT Doing" if scope changes
- Maintain automated vs manual success criteria distinction
3. **Update plan metadata**:
- Update frontmatter `date` to current timestamp
- Add `iteration: {N}` to frontmatter
- Add `iteration_reason: "{brief description}"` to frontmatter
4. **Preserve completed work**:
- Don't uncheck items that were already completed
- If changing completed phases, discuss with user first
### Step 5: Save Iteration History (Optional)
For significant changes, save the previous version:
```bash
cp thoughts/beads-{bead-id}/plan.md thoughts/beads-{bead-id}/plan-v{N}.md
```
Then update the main plan.
### Step 6: Update Bead
```bash
bd update {bead-id} --notes="Plan iterated: {brief description of changes}"
```
### Step 7: Present Changes
```
I've updated the plan at `thoughts/beads-{bead-id}/plan.md`
Changes made:
- {Specific change 1}
- {Specific change 2}
The updated plan now:
- {Key improvement}
- {Another improvement}
Would you like any further adjustments?
```
## Important Guidelines
1. **Be Skeptical**:
- Don't blindly accept changes that seem problematic
- Question vague feedback - ask for clarification
- Point out conflicts with existing phases
2. **Be Surgical**:
- Make precise edits, not wholesale rewrites
- Preserve good content that doesn't need changing
- Only research what's necessary
3. **Be Thorough**:
- Read entire plan before making changes
- Ensure updated sections maintain quality
- Verify success criteria are still measurable
4. **Be Interactive**:
- Confirm understanding before making changes
- Allow course corrections
- Don't disappear into research without communicating
5. **No Open Questions**:
- If changes raise questions, ASK
- Don't update plan with unresolved questions
## Success Criteria Guidelines
When updating success criteria, maintain two categories:
**Automated Verification**:
- Commands: `make test`, `npm run lint`
- Prefer `make` commands when available
- File existence checks
**Manual Verification**:
- UI/UX functionality
- Performance under real conditions
- Edge cases hard to automate
## Handling Major Changes
If feedback requires significant restructuring:
1. **Discuss scope** before proceeding
2. **Consider if this should be a new plan** instead of iteration
3. **Preserve the original** in `plan-v{N}.md`
4. **Update bead description** if scope changed significantly
## Example Invocations
**With full context**:
```
User: /beads:iterate nixos-configs-abc123 - add error handling phase
Assistant: Based on your feedback, I understand you want to add a new phase for error handling...
```
**Interactive**:
```
User: /beads:iterate nixos-configs-abc123
Assistant: I've found the plan. What changes would you like to make?
User: Split Phase 2 into backend and frontend phases
Assistant: I'll split Phase 2 into two separate phases...
```

306
home/roles/development/commands/beads_plan.md Normal file
View File

@@ -0,0 +1,306 @@
---
description: Create detailed implementation plans for a bead issue
model: opus
---
# Beads Plan
You are tasked with creating detailed implementation plans for a bead issue. This skill integrates with the beads issue tracker and stores plans in the `thoughts/` directory.
## Initial Setup
When this command is invoked:
1. **Parse the input for bead ID**:
- If a bead ID is provided, use it
- If no bead ID, run `bd ready` and ask which bead to plan for
2. **Load bead context**:
```bash
bd show {bead-id}
```
- Read the bead description for requirements
- Check for existing research: `thoughts/beads-{bead-id}/research.md`
- Note any dependencies or blockers
3. **Create artifact directory**:
```bash
mkdir -p thoughts/beads-{bead-id}
```
4. **Check for existing research**:
- If `thoughts/beads-{bead-id}/research.md` exists, read it fully
- This research provides crucial context for planning
5. **Respond with**:
```
Creating implementation plan for bead {bead-id}: {bead-title}
{If research exists: "Found existing research at thoughts/beads-{bead-id}/research.md - incorporating findings."}
Let me analyze the requirements and codebase to create a detailed plan.
```
## Planning Process
### Step 1: Context Gathering
1. **Read all mentioned files FULLY**:
- Bead description references
- Existing research document
- Any linked tickets or docs
- Use Read tool WITHOUT limit/offset
2. **Check for contribution guidelines**:
```bash
# Check standard locations for contribution guidelines
for f in CONTRIBUTING.md .github/CONTRIBUTING.md docs/CONTRIBUTING.md; do
if [ -f "$f" ]; then
echo "Found: $f"
break
fi
done
```
If found:
- Read the file fully
- Extract actionable requirements (testing, code style, documentation, PR conventions)
- These requirements MUST be incorporated into the plan's Success Criteria
If not found, note "No contribution guidelines found" and proceed.
3. **Spawn initial research tasks**:
- **codebase-locator**: Find all files related to the task
- **codebase-analyzer**: Understand current implementation
- **codebase-pattern-finder**: Find similar features to model after
- **thoughts-locator**: Find any existing plans or decisions
4. **Read all files identified by research**:
- Read them FULLY into main context
- Cross-reference with requirements
### Step 2: Present Understanding
Before writing the plan, confirm understanding:
```
Based on the bead and my research, I understand we need to [accurate summary].
I've found that:
- [Current implementation detail with file:line reference]
- [Relevant pattern or constraint discovered]
- [Potential complexity or edge case identified]
Questions that my research couldn't answer:
- [Specific technical question requiring human judgment]
- [Business logic clarification]
```
Only ask questions you genuinely cannot answer through code investigation.
### Step 3: Research & Discovery
After getting clarifications:
1. **If user corrects any misunderstanding**:
- Spawn new research tasks to verify
- Read specific files/directories mentioned
- Only proceed once verified
2. **Present design options**:
```
Based on my research:
**Current State:**
- [Key discovery about existing code]
- [Pattern or convention to follow]
**Design Options:**
1. [Option A] - [pros/cons]
2. [Option B] - [pros/cons]
Which approach aligns best?
```
### Step 4: Plan Structure
Once aligned on approach:
```
Here's my proposed plan structure:
## Overview
[1-2 sentence summary]
## Implementation Phases:
1. [Phase name] - [what it accomplishes]
2. [Phase name] - [what it accomplishes]
Does this phasing make sense?
```
Get feedback on structure before writing details.
### Step 5: Write the Plan
Write to `thoughts/beads-{bead-id}/plan.md`:
```markdown
---
date: {ISO timestamp}
bead_id: {bead-id}
bead_title: "{bead title}"
author: claude
git_commit: {commit hash}
branch: {branch name}
repository: {repo name}
status: draft
---
# {Feature/Task Name} Implementation Plan
## Overview
{Brief description of what we're implementing and why}
## Current State Analysis
{What exists now, what's missing, key constraints}
### Key Discoveries:
- {Finding with file:line reference}
- {Pattern to follow}
## Desired End State
{Specification of desired end state and how to verify it}
## What We're NOT Doing
{Explicitly list out-of-scope items}
## Implementation Approach
{High-level strategy and reasoning}
## Phase 1: {Descriptive Name}
### Overview
{What this phase accomplishes}
### Changes Required:
#### 1. {Component/File Group}
**File**: `path/to/file.ext`
**Changes**: {Summary}
```{language}
// Specific code to add/modify
```
### Success Criteria:
#### Automated Verification:
- [ ] Tests pass: `make test`
- [ ] Linting passes: `make lint`
- [ ] Type checking passes: `make typecheck`
#### Manual Verification:
- [ ] Feature works as expected in UI
- [ ] Edge cases handled correctly
---
## Phase 2: {Descriptive Name}
{Similar structure...}
---
## Testing Strategy
### Unit Tests:
- {What to test}
- {Key edge cases}
### Integration Tests:
- {End-to-end scenarios}
### Manual Testing Steps:
1. {Specific step}
2. {Another step}
## References
- Bead: {bead-id}
- Research: `thoughts/beads-{bead-id}/research.md`
- Similar implementation: {file:line}
```
### Step 6: Update the bead
```bash
bd update {bead-id} --notes="Plan created: thoughts/beads-{bead-id}/plan.md"
```
### Step 7: Create implementation bead (if appropriate)
If the planning bead is separate from implementation:
```bash
bd create --title="Implement: {feature name}" --type=task --priority=1 \
--description="Implement the plan at thoughts/beads-{original-bead-id}/plan.md
See bead {original-bead-id} for planning context."
# Link as dependency
bd dep add {new-bead-id} {original-bead-id}
```
### Step 8: Present for Review
```
I've created the implementation plan at:
`thoughts/beads-{bead-id}/plan.md`
Please review it and let me know:
- Are the phases properly scoped?
- Are the success criteria specific enough?
- Any technical details that need adjustment?
- Missing edge cases or considerations?
```
## Important Guidelines
1. **Be Skeptical**: Question vague requirements, identify potential issues early
2. **Be Interactive**: Don't write the full plan in one shot, get buy-in at each step
3. **Be Thorough**: Read all context files COMPLETELY, include specific file:line refs
4. **Be Practical**: Focus on incremental, testable changes
5. **No Open Questions**: If you have unresolved questions, STOP and ask
## Success Criteria Guidelines
Always separate into two categories:
**Automated Verification** (run by agents):
- Commands: `make test`, `npm run lint`, etc.
- File existence checks
- Type checking
**Manual Verification** (requires human):
- UI/UX functionality
- Performance under real conditions
- Edge cases hard to automate
**From Contribution Guidelines** (if CONTRIBUTING.md exists):
- Include any testing requirements specified in guidelines
- Include any code style/linting requirements
- Include any documentation requirements
- Reference the guideline: "Per CONTRIBUTING.md: {requirement}"
## Example Invocation
```
User: /beads:plan nixos-configs-abc123
Assistant: Creating implementation plan for bead nixos-configs-abc123...
```

222
home/roles/development/commands/beads_research.md Normal file
View File

@@ -0,0 +1,222 @@
---
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 1.5: Check for contribution guidelines
Before spawning sub-agents, check if the repository has contribution guidelines:
```bash
for f in CONTRIBUTING.md .github/CONTRIBUTING.md docs/CONTRIBUTING.md; do
if [ -f "$f" ]; then echo "Found: $f"; break; fi
done
```
If found, read the file and note key requirements. These should be included in the research document under a "## Contribution Guidelines" section if relevant to the research question.
### 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}
## Contribution Guidelines
{If CONTRIBUTING.md exists, summarize key requirements relevant to the research topic}
{If no guidelines found, omit this section}
## 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?
```

387
home/roles/development/commands/beads_workflow.md Normal file
View File

@@ -0,0 +1,387 @@
---
description: Comprehensive guide for the beads + humanlayer integrated workflow
---
# Beads Workflow Guide
This document describes the integrated workflow combining **beads** (issue tracking) with **humanlayer-style skills** (deep research, planning, implementation).
## Philosophy
### Two Systems, Complementary Purposes
| System | Purpose | Storage |
|--------|---------|---------|
| **Beads** | Track WHAT work exists | `.beads/` (git-synced) |
| **Thoughts** | Store HOW to do the work | `thoughts/` (local or symlinked) |
### Autonomy Model
| Bead Type | Agent Autonomy | Checkpoint |
|-----------|----------------|------------|
| `research` | **Full** - agent closes when satisfied | None |
| `feature`, `task`, `bug` | **Checkpointed** - pause for validation | Per-plan |
**Key insight**: Research produces artifacts. Implementation produces commits. Commits are the review boundary.
## Directory Structure
```
project/
├── .beads/ # Beads database (git-synced)
│ ├── beads.db
│ ├── config.yaml
│ └── issues.jsonl
├── thoughts/ # Artifacts (local or symlink)
│ ├── beads-{id}/ # Per-bead artifacts
│ │ ├── research.md
│ │ ├── plan.md
│ │ └── plan-v1.md # Iteration history
│ └── shared/ # Legacy/non-bead artifacts
│ ├── research/
│ └── plans/
└── home/roles/development/skills/ # Skill definitions
├── beads_research.md
├── beads_plan.md
├── beads_implement.md
└── beads_iterate.md
```
## When to Use What
### Use Beads When:
- Work spans multiple sessions
- Work has dependencies or blockers
- You need to track status across interruptions
- Multiple related tasks need coordination
- Context recovery after compaction matters
### Use TodoWrite When:
- Single-session execution tracking
- Breaking down work within a session
- Tracking progress on a single bead
### Use Both Together:
- Beads track the overall work items
- TodoWrite tracks progress within a session
- Example: Bead for "Implement auth", TodoWrite for each file being edited
## Workflow Patterns
### Pattern 1: Research-First Approach
```
1. Create research bead
bd create --title="Research auth patterns" --type=research --priority=1
2. Run research
/beads:research {bead-id}
→ Agent researches, writes to thoughts/beads-{id}/research.md
→ Agent closes bead when satisfied
3. Create implementation bead
bd create --title="Implement auth" --type=feature --priority=1
4. Plan the implementation
/beads:plan {bead-id}
→ Agent reads prior research, creates plan
→ Plan saved to thoughts/beads-{id}/plan.md
5. Implement
/beads:implement {bead-id}
→ Agent follows plan, pauses for manual verification
→ You validate, agent closes bead
```
### Pattern 2: Direct Implementation
For well-understood tasks without research:
```
1. Create bead
bd create --title="Fix login bug" --type=bug --priority=0
2. Plan and implement
/beads:plan {bead-id}
→ Quick planning based on bead description
/beads:implement {bead-id}
→ Follow plan, pause at checkpoint
```
### Pattern 3: Iterative Planning
When requirements evolve:
```
1. Initial plan
/beads:plan {bead-id}
2. Iterate based on feedback
/beads:iterate {bead-id} - add error handling phase
3. Iterate again if needed
/beads:iterate {bead-id} - split phase 2 into backend/frontend
4. Implement when plan is solid
/beads:implement {bead-id}
```
### Pattern 4: Parallel Work
Using parallel_beads skill for multiple independent tasks:
```
1. Check what's ready
bd ready
2. Select multiple beads
/parallel_beads
→ Select beads to work on
→ Each gets worktree, PR, review
3. Reconcile after PRs merge
/reconcile_beads
```
## Skills Reference
### /beads:research {bead-id}
- Conducts comprehensive codebase research
- Uses parallel sub-agents for efficiency
- Outputs to `thoughts/beads-{id}/research.md`
- **Autonomy**: Can close research beads automatically
### /beads:plan {bead-id}
- Creates detailed implementation plans
- Interactive process with checkpoints
- Outputs to `thoughts/beads-{id}/plan.md`
- Can create dependent implementation beads
### /beads:implement {bead-id}
- Follows plans from thoughts/
- Updates plan checkboxes for resumability
- **Checkpoint**: Pauses after plan completion for manual verification
- Only closes bead after human confirms
### /beads:iterate {bead-id}
- Updates existing plans based on feedback
- Preserves plan structure while making targeted changes
- Saves iteration history as `plan-v{N}.md`
### /parallel_beads
- Orchestrates parallel bead processing
- Creates worktrees, PRs, reviews for multiple beads
- Good for batching independent work
### /reconcile_beads
- Closes beads whose PRs have merged
- Run after merging PRs to keep beads in sync
## Session Protocols
### Starting a Session
```bash
# Check what's available
bd ready
# Pick work and start
bd update {bead-id} --status=in_progress
```
### Ending a Session
```bash
# Always run this checklist:
[ ] git status # Check changes
[ ] git add <files> # Stage code changes
[ ] bd sync # Sync beads
[ ] git commit -m "..." # Commit code
[ ] git push # Push to remote
```
### Resuming Work
```bash
# Find in-progress work
bd list --status=in_progress
# Check bead notes for context
bd show {bead-id}
# Check for partial plan progress
cat thoughts/beads-{id}/plan.md | grep "\[x\]"
```
## Thoughts Directory Patterns
### For Work Repos (via symlink)
```
project/thoughts → ~/thoughts/repos/{repo-name}/
```
- Syncs via codelayer to work remote
- Shared across projects on same machine
### For Personal Repos (local)
```
project/thoughts/ # Regular directory, not symlink
```
- Stays local to project
- Committed with project or gitignored
### Determining Which Pattern
```bash
# Check if thoughts is a symlink
ls -la thoughts
# If symlink, it points to ~/thoughts/repos/{repo}/
# If directory, it's local to this project
```
## Best Practices
### 1. Bead Descriptions Matter
Write clear descriptions - they're the input for research and planning:
```bash
bd create --title="Implement user preferences" --type=feature \
--description="Add user preferences storage and UI.
Requirements:
- Store preferences in SQLite
- Expose via REST API
- Add settings page in UI
See related: thoughts/shared/research/preferences-patterns.md"
```
### 2. Link Artifacts in Beads
Always update bead notes with artifact locations:
```bash
bd update {id} --notes="Research: thoughts/beads-{id}/research.md
Plan: thoughts/beads-{id}/plan.md"
```
### 3. Use Dependencies
Structure work with dependencies:
```bash
# Research blocks planning
bd dep add {plan-bead} {research-bead}
# Planning blocks implementation
bd dep add {impl-bead} {plan-bead}
```
### 4. Trust the Checkpoint Model
- Research beads: Let agent close them
- Implementation beads: Always validate before closing
- If in doubt, err on the side of checkpoints
### 5. Keep Plans Updated
- Check off completed items as you go
- Update notes with progress
- This enables seamless resume across sessions
## Troubleshooting
### "What bead should I work on?"
```bash
bd ready # Shows unblocked work
```
### "Where did the research go?"
```bash
ls thoughts/beads-{id}/
bd show {id} # Check notes for artifact links
```
### "Plan doesn't match reality"
```bash
/beads:iterate {id} # Update plan based on findings
```
### "Session ended mid-implementation"
```bash
bd show {id} # Check notes for progress
cat thoughts/beads-{id}/plan.md | grep "\[x\]" # See completed items
/beads:implement {id} # Resume - will pick up from last checkpoint
```
### "Bead is blocked"
```bash
bd show {id} # See what's blocking
bd blocked # See all blocked beads
```
## Migration Notes
### From Pure Humanlayer to Beads+Humanlayer
Old pattern:
```
thoughts/shared/research/2025-01-01-topic.md
thoughts/shared/plans/2025-01-01-feature.md
```
New pattern:
```
thoughts/beads-{id}/research.md
thoughts/beads-{id}/plan.md
```
The `shared/` structure still works for non-bead artifacts, but prefer per-bead directories for tracked work.
### Existing Content
- Keep existing `thoughts/shared/` content
- New bead-tracked work uses `thoughts/beads-{id}/`
- Reference old research from bead descriptions when relevant
## Design Decisions
### Phase Tracking: Artifacts vs Statuses
**Current approach**: Skills infer workflow phase from artifact presence:
- Has `research.md` → research done
- Has `plan.md` → planning done
- No artifacts → needs research/planning
**Alternative considered**: Explicit phase statuses (`needs_research`, `needs_plan`, `implementing`, etc.)
**Why artifacts win**:
1. **Single source of truth** - Status can't drift from reality
2. **Less state to maintain** - No need to update status when creating artifacts
3. **Works across repos** - No custom status config needed
4. **Skills already check artifacts** - Natural fit with existing behavior
**When explicit statuses would help**:
- Pipeline visualization (e.g., `bd list --status=needs_plan`)
- Agent self-selection by phase
- Team coordination dashboards
**Recommendation**: Keep artifact-inference as primary mechanism. If pipeline visibility becomes important, consider adding statuses that skills auto-set when creating artifacts (advisory, not enforced).
### One Bead Per Feature (Default)
**Current approach**: File one bead per logical feature. Skills handle phases internally.
**Alternative considered**: Separate beads for research → planning → implementation, linked by dependencies.
**Why single bead wins for most work**:
1. **Lower friction** - Quick idea dump without filing 3 tickets
2. **Simpler tracking** - One status to check
3. **Natural grouping** - Artifacts stay together in `thoughts/beads-{id}/`
**When to split into multiple beads**:
- Research reveals the work should be multiple features
- Different phases need different assignees
- Explicit dependency tracking matters (e.g., "auth must ship before payments")
**The discovered-work pattern**: Start with one bead. If research reveals split work, file additional beads with dependencies. Skills guide this naturally.
### Plan Requirements by Type
**Bug fixes** (`type=bug`): Can proceed without plans - usually well-scoped from bug report.
**Features/tasks** (`type=feature`, `type=task`): Should have plans - helps ensure design is sound before implementation.
This is advisory, not enforced. Skills warn but allow override for simple changes.

472
home/roles/development/commands/gitea_pr_review.md Normal file
View File

@@ -0,0 +1,472 @@
---
description: Address Gitea/Forgejo PR review comments with code changes
---
# Gitea PR Review
You are tasked with **addressing** PR review comments by making code changes, then summarizing what was done. This skill drives PR progress, not just conversation.
## Philosophy
**Comments are work items, not conversation starters.**
When a reviewer leaves a comment, they're identifying something that needs attention. This skill:
1. Categorizes comments by actionability
2. Makes code changes to address actionable comments
3. Commits and pushes those changes
4. Posts a single summary comment describing what was done
## Prerequisites
- `tea` CLI configured with a Gitea/Forgejo instance
- Access token from tea config: `~/.config/tea/config.yml`
- Repository must be a Gitea/Forgejo remote (not GitHub)
- **Nix users**: All tools available via nixpkgs (`nix run nixpkgs#tea`)
## Initial Setup
When this command is invoked:
1. **Parse the input for PR number**:
- If a PR number is provided as argument, use it
- If no PR number, detect from current branch (see PR Detection section)
2. **Verify required tools are available**:
```bash
which tea
```
If tea is missing:
```
Error: `tea` CLI not found.
Please install:
- Nix: nix run nixpkgs#tea
- Other: https://gitea.com/gitea/tea
```
**STOP** if tea is missing.
3. **Extract configuration from tea config**:
```bash
# Read tea config (it's YAML but simple enough to grep)
TEA_CONFIG="$HOME/.config/tea/config.yml"
GITEA_URL=$(grep -A1 'logins:' "$TEA_CONFIG" | grep 'url:' | head -1 | sed 's/.*url: //')
TOKEN=$(grep -A5 'logins:' "$TEA_CONFIG" | grep 'token:' | head -1 | sed 's/.*token: //')
```
If config is missing or invalid:
```
Error: Could not read tea config at ~/.config/tea/config.yml
Please ensure `tea` is installed and configured:
1. Install tea
2. Log in: tea login add --url https://your-gitea-instance --token YOUR_TOKEN
```
**STOP** if config is invalid.
4. **Detect repository info from git remote**:
```bash
REMOTE_URL=$(git remote get-url origin)
# Parse owner and repo from URL (handles both SSH and HTTPS)
OWNER=$(echo "$REMOTE_URL" | sed -E 's#.*[:/]([^/]+)/[^/]+\.git$#\1#')
REPO=$(echo "$REMOTE_URL" | sed -E 's#.*/([^/]+)\.git$#\1#')
```
5. **Ensure we're on the PR branch**:
```bash
CURRENT_BRANCH=$(git branch --show-current)
# Verify this branch corresponds to the PR
```
6. **Respond with**:
```
Addressing PR review comments for PR #{PR_NUMBER}...
Repository: {OWNER}/{REPO}
Branch: {CURRENT_BRANCH}
Gitea URL: {GITEA_URL}
```
## PR Detection
If no PR number is provided, detect from the current branch:
```bash
CURRENT_BRANCH=$(git branch --show-current)
tea pr list --fields index,head --output simple | grep "$CURRENT_BRANCH"
```
If no PR exists for the current branch, use `AskUserQuestion`:
```
No PR found for branch '{CURRENT_BRANCH}'.
Would you like to:
1. Enter a PR number manually
2. Cancel
```
## Workflow
### Step 1: Fetch and Parse Comments
Fetch all reviews and their comments:
```bash
# Fetch reviews (filter out dismissed reviews)
curl -s -H "Authorization: token $TOKEN" \
"$GITEA_URL/api/v1/repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews" \
| jq '[.[] | select(.dismissed != true)]'
# For each review, fetch comments
curl -s -H "Authorization: token $TOKEN" \
"$GITEA_URL/api/v1/repos/$OWNER/$REPO/pulls/$PR_NUMBER/reviews/$REVIEW_ID/comments"
```
**Filter resolved comments**: When processing comments, skip any that have been marked as resolved. Check the `resolver` field in the comment response - if it's not null, the comment has been resolved and should be skipped.
```bash
# Example: Filter to only unresolved comments
jq '[.[] | select(.resolver == null)]'
```
If no reviews found or all comments are resolved:
```
No unresolved reviews found for PR #{PR_NUMBER}.
Nothing to address.
```
**STOP** here.
### Step 2: Categorize Comments
For each comment, categorize it as one of:
| Category | Description | Action |
|----------|-------------|--------|
| **actionable** | Requests a code change, addition, or fix | Launch subagent to make change |
| **question** | Asks for clarification or explanation | Include answer in summary |
| **acknowledged** | FYI, self-resolved, or "no action needed" noted | Note in summary |
| **blocked** | Requires external input or is out of scope | Flag for user |
**Categorization heuristics**:
- Contains "add", "change", "fix", "update", "consider adding", "should be" → **actionable**
- Contains "?" or "why", "how", "what" → **question**
- Contains "no need to update", "will be separate", "acknowledged" → **acknowledged**
- Contains "discuss", "later", "out of scope", "blocked by" → **blocked**
Display the categorization:
```
## Comment Analysis
### Actionable (will make changes):
1. {file}:{line} - "{comment_summary}" → Will add nix note to prerequisites
### Questions (will answer in summary):
2. {file}:{line} - "{comment_summary}" → Explain CI token approach
### Acknowledged (no action needed):
3. {file}:{line} - "{comment_summary}" → Reviewer noted separate skill
### Blocked (needs input):
(none)
```
### Step 3: User Confirmation
Use `AskUserQuestion` to confirm the plan:
```
I've categorized {N} comments. My plan:
**Will make changes for:**
- {file}:{line}: {planned_change}
**Will explain in summary:**
- {file}:{line}: {planned_explanation}
**No action needed:**
- {file}:{line}: {reason}
Proceed with this plan?
```
Options:
1. **Proceed** - Execute the plan
2. **Modify** - Let user adjust categorization
3. **Cancel** - Exit without changes
### Step 4: Address Actionable Comments (Parallel Subagents)
For each actionable comment, launch a subagent using the Task tool:
```
Launch Task subagent with:
- subagent_type: "general-purpose"
- prompt: |
You are addressing a PR review comment. Make the requested change and nothing else.
**File**: {file_path}
**Line**: {line_number}
**Comment**: {comment_body}
**Diff context**:
```
{diff_hunk}
```
Instructions:
1. Read the file to understand context
2. Make the minimal change to address the comment
3. Do NOT commit - just make the edit
4. Report what you changed
Be precise. Only change what's needed to address this specific comment.
```
**Important**: Launch actionable comment subagents in parallel when they touch different files. For comments on the same file, run sequentially to avoid conflicts.
Wait for all subagents to complete and collect their results.
### Step 5: Commit and Push
After all subagents complete:
1. **Stage changes**:
```bash
git add -A
```
2. **Create commit with summary**:
```bash
git commit -m "Address PR review comments
Changes made:
- {file1}: {change_summary}
- {file2}: {change_summary}
Addresses comments from review by {reviewer}"
```
3. **Push to remote**:
```bash
git push
```
### Step 6: Post Summary Comment
Post a single comment summarizing all actions taken:
```bash
tea comment $PR_NUMBER "$(cat <<'EOF'
## Review Comments Addressed
cc @{reviewer1} @{reviewer2}
**Changes made** (commit {SHORT_SHA}):
- `{file1}:{line}`: {what_was_changed}
- `{file2}:{line}`: {what_was_changed}
**Responses to questions**:
- `{file3}:{line}`: {answer_to_question}
**Acknowledged** (no action needed):
- `{file4}:{line}`: {reason_no_action}
---
*Automated response via /gitea_pr_review*
EOF
)"
```
### Step 7: Final Summary
Display to user:
```
## PR Review Complete
**Commit**: {SHA}
**Changes**: {N} files modified
### Actions Taken:
- [x] {file1}:{line} - Added nix prerequisite note
- [x] {file2}:{line} - Explained CI approach in comment
- [ ] {file3}:{line} - Acknowledged (separate skill)
**Reviewers tagged**: @{reviewer1}, @{reviewer2}
**Comment posted**: {comment_url}
PR URL: {GITEA_URL}/{OWNER}/{REPO}/pulls/{PR_NUMBER}
```
**Note**: When posting the summary comment, tag all reviewers who left comments so they receive notifications about the changes.
## Error Handling
### Subagent failed to make change
If a subagent fails:
```
Warning: Could not address comment on {file}:{line}
Reason: {error}
Options:
1. Skip this comment and continue
2. Retry with manual guidance
3. Abort all changes
```
### Push failed
```
Error pushing changes: {error}
Your changes are committed locally. You may need to:
1. Pull and resolve conflicts: git pull --rebase
2. Push again: git push
```
### No actionable comments
If all comments are questions/acknowledged:
```
No code changes needed.
All comments are either questions or acknowledged items.
Posting summary comment with explanations...
```
## API Reference
### Endpoints Used
| Action | Method | Endpoint |
|--------|--------|----------|
| List reviews | GET | `/api/v1/repos/{owner}/{repo}/pulls/{index}/reviews` |
| Get review comments | GET | `/api/v1/repos/{owner}/{repo}/pulls/{index}/reviews/{id}/comments` |
| Create issue comment | POST | via `tea comment` |
### Review States
- `PENDING` - Draft review not yet submitted
- `COMMENT` - General comment without approval/rejection
- `APPROVE` - Approving the changes
- `REQUEST_CHANGES` - Requesting changes before merge
## Shell Command Patterns
Claude Code's bash execution has quirks. Use these patterns for reliability:
### curl requests
**DO** - Use single quotes for URL and header separately:
```bash
curl -s 'https://git.example.com/api/v1/repos/owner/repo/pulls/1/reviews' \
-H 'Authorization: token YOUR_TOKEN_HERE' | jq .
```
**DON'T** - Variable expansion in `-H` flag often fails:
```bash
# This may fail with "blank argument" errors
curl -s -H "Authorization: token $TOKEN" "$URL"
```
### Iterating over reviews
**DO** - Run separate commands for each review ID:
```bash
echo "=== Review 4 ===" && curl -s 'URL/reviews/4/comments' -H 'Authorization: token ...' | jq .
echo "=== Review 5 ===" && curl -s 'URL/reviews/5/comments' -H 'Authorization: token ...' | jq .
```
**DON'T** - For loops with multiline bodies often fail:
```bash
# This may cause syntax errors
for id in 4 5 6; do
curl -s "URL/reviews/$id/comments"
done
```
### tea comment
**DO** - Use single-quoted string for comment body:
```bash
tea comment 26 '## Summary
Changes made:
- Item 1
- Item 2'
```
**DON'T** - Heredocs may hang or timeout:
```bash
# This may hang indefinitely
tea comment 26 "$(cat <<'EOF'
...
EOF
)"
```
## Limitations
1. **Thread replies**: Gitea API doesn't support inline thread replies. We post a single summary comment instead.
2. **Complex changes**: For comments requiring significant refactoring, the subagent may need guidance. The skill will flag these as "blocked" for user input.
3. **Merge conflicts**: If the branch is behind, you may need to rebase before changes can be pushed.
## Example Session
```
User: /gitea_pr_review 26
Assistant: Addressing PR review comments for PR #26...
Repository: johno/nixos-configs
Branch: bead/nixos-configs-vru
Gitea URL: https://git.johnogle.info
## Comment Analysis
### Actionable (will make changes):
1. gitea_pr_review.md:12 - "could we indicate nix+nixpkgs satisfies this?"
→ Will add note that nix users can get tools via nixpkgs
### Questions (will answer in summary):
(none)
### Acknowledged (no action needed):
2. gitea_pr_review.md:50 - "we eventually want to run this in CI..."
→ Reviewer noted this will be a separate skill
Proceed with this plan? [Proceed]
Launching subagent to address comment 1...
[Subagent completes edit]
Committing changes...
[abc1234] Address PR review comments
Pushing to remote...
Done.
Posting summary comment...
## PR Review Complete
**Commit**: abc1234
**Changes**: 1 file modified
### Actions Taken:
- [x] gitea_pr_review.md:12 - Added nix prerequisite note
- [ ] gitea_pr_review.md:50 - Acknowledged (separate skill)
**Comment posted**: https://git.johnogle.info/.../pulls/26#issuecomment-XXX
PR URL: https://git.johnogle.info/johno/nixos-configs/pulls/26
```
## See Also
- `tea` CLI: https://gitea.com/gitea/tea
- Gitea API: https://docs.gitea.com/api/
- `/beads_workflow` for full development workflow

130
home/roles/development/commands/import_gitea_issues.md Normal file
View File

@@ -0,0 +1,130 @@
---
description: Import open Gitea issues as beads, skipping already-imported ones
---
# Import Gitea Issues as Beads
This skill imports open Gitea issues as beads, checking for duplicates to avoid re-importing already tracked issues.
## Prerequisites
- `tea` CLI must be installed and configured for the repository
- `bd` (beads) CLI must be installed
- Must be in a git repository with a Gitea/Forgejo remote
## Workflow
### Step 1: Get open Gitea issues
List all open issues using `tea`:
```bash
tea issues
```
This returns a table with columns: INDEX, TITLE, LABELS, MILESTONE
### Step 2: Get existing beads
List all current beads to check what's already imported:
```bash
bd list
```
Also check bead notes for issue URLs to identify imports:
```bash
bd list --json | jq -r '.[] | select(.notes != null) | .notes' | grep -oP 'issues/\K\d+'
```
### Step 3: Check for already-linked PRs
Check if any open PRs reference beads (skip these issues as they're being worked on):
```bash
tea pr list
```
Look for PRs with:
- Bead ID in title: `[nixos-configs-xxx]`
- Bead reference in body: `Implements bead:` or `Bead ID:`
### Step 4: For each untracked issue, create a bead
For each issue not already tracked:
1. **Get full issue details**:
```bash
tea issue [ISSUE_NUMBER]
```
2. **Determine bead type** based on issue content:
- "bug" - if issue mentions bug, error, broken, fix, crash
- "feature" - if issue mentions feature, add, new, enhancement
- "task" - default for other issues
3. **Create the bead**:
```bash
bd add "[ISSUE_TITLE]" \
--type=[TYPE] \
--priority=P2 \
--notes="Gitea issue: [ISSUE_URL]
Original issue description:
[ISSUE_BODY]"
```
Note: The `--notes` flag accepts multi-line content.
### Step 5: Report results
Present a summary:
```
## Gitea Issues Import Summary
### Imported as Beads
| Issue | Title | Bead ID | Type |
|-------|-------|---------|------|
| #5 | Add dark mode | nixos-configs-abc | feature |
| #3 | Config broken on reboot | nixos-configs-def | bug |
### Skipped (Already Tracked)
| Issue | Title | Reason |
|-------|-------|--------|
| #4 | Update flake | Existing bead: nixos-configs-xyz |
| #2 | Refactor roles | PR #7 references bead |
### Skipped (Other)
| Issue | Title | Reason |
|-------|-------|--------|
| #1 | Discussion: future plans | No actionable work |
```
## Type Detection Heuristics
Keywords to detect issue type:
**Bug indicators** (case-insensitive):
- bug, error, broken, fix, crash, fail, issue, problem, wrong, not working
**Feature indicators** (case-insensitive):
- feature, add, new, enhancement, implement, support, request, want, would be nice
**Task** (default):
- Anything not matching bug or feature patterns
## Error Handling
- **tea not configured**: Report error and exit
- **bd not available**: Report error and exit
- **Issue already has bead**: Skip and report in summary
- **Issue is a PR**: Skip (tea shows PRs and issues separately)
## Notes
- Default priority is P2; adjust manually after import if needed
- Issue labels from Gitea are not automatically mapped to bead tags
- Run this periodically to catch new issues
- After import, use `bd ready` to see which beads can be worked on

409
home/roles/development/commands/parallel_beads.md Normal file
View File

@@ -0,0 +1,409 @@
---
description: Orchestrate parallel bead processing with worktrees, PRs, and reviews
---
# Parallel Beads Workflow
This skill orchestrates parallel bead processing using subagents. Each bead gets its own worktree, implementation, PR, and review.
## Phase 1: Selection
1. **Get ready beads**: Run `bd ready` to list all beads with no blockers
2. **Filter by plan readiness**:
For each ready bead, check if it's ready for batch implementation:
- **Has plan** (`thoughts/beads-{id}/plan.md` exists): Include
- **type=bug** without plan: Include (simple bugs can implement directly)
- **type=feature/task** without plan: Exclude with warning
```bash
# Check for plan existence
ls thoughts/beads-{bead-id}/plan.md 2>/dev/null
```
3. **Report skipped beads**:
If any beads were skipped, inform the user:
```
Skipped beads (no plan):
- {bead-id}: {title} (type: feature) - Run /beads_plan {bead-id} first
- {bead-id}: {title} (type: task) - Run /beads_plan {bead-id} first
```
4. **Present selection**: Use `AskUserQuestion` with `multiSelect: true` to let the user choose which beads to work on
- Include bead ID and title for each option
- Only show beads that passed the plan check
- Allow selection of multiple beads
Example:
```
AskUserQuestion with:
- question: "Which beads do you want to work on in parallel?"
- multiSelect: true
- options from filtered bd ready output
```
## Phase 2: Worktree Setup
Before launching implementation subagents, create worktrees for all selected beads:
1. **Get repository name**:
```bash
REPO_NAME=$(git remote get-url origin | sed 's|.*/||' | sed 's/\.git$//')
```
2. **For each selected bead**, create its worktree:
```bash
BEAD_ID="[bead-id]"
# Check if worktree already exists
if [ -d "$HOME/wt/${REPO_NAME}/${BEAD_ID}" ]; then
echo "Worktree already exists: ~/wt/${REPO_NAME}/${BEAD_ID}"
# Ask user: remove and recreate, or skip this bead?
else
git worktree add -b "bead/${BEAD_ID}" "$HOME/wt/${REPO_NAME}/${BEAD_ID}"
fi
```
3. **Track created worktrees**:
Maintain a list of (bead_id, worktree_path) pairs for use in subagent instructions.
4. **Report status**:
```
Created worktrees:
- nixos-configs-abc → ~/wt/nixos-configs/nixos-configs-abc (branch: bead/nixos-configs-abc)
- nixos-configs-xyz → ~/wt/nixos-configs/nixos-configs-xyz (branch: bead/nixos-configs-xyz)
Skipped (existing worktree):
- nixos-configs-123 → Ask user for resolution
```
**Note**: If a worktree or branch already exists, ask the user before proceeding:
- Remove existing worktree and branch, then recreate
- Skip this bead
- Use existing worktree as-is (risky - branch may have diverged)
## Phase 3: Parallel Implementation
For each selected bead, launch a subagent using the Task tool. All subagents should be launched in parallel (single message with multiple Task tool calls).
### Subagent Instructions Template
Each implementation subagent should receive these instructions:
```
Work on bead [BEAD_ID]: [BEAD_TITLE]
Worktree path: [WORKTREE_PATH]
## CRITICAL: Branch Verification (MUST DO FIRST)
1. **Navigate to worktree**:
```bash
cd [WORKTREE_PATH]
```
2. **Verify branch** (MANDATORY before ANY modifications):
```bash
CURRENT_BRANCH=$(git branch --show-current)
echo "Current branch: $CURRENT_BRANCH"
pwd
```
**ABORT CONDITIONS** - If ANY of these are true, STOP IMMEDIATELY:
- Branch is `main` or `master`
- Branch does not match `bead/[BEAD_ID]`
If you detect any abort condition:
```
ABORTING: Branch verification failed.
Expected branch: bead/[BEAD_ID]
Actual branch: [CURRENT_BRANCH]
Working directory: [pwd output]
DO NOT PROCEED. Report this error to the orchestrator.
```
## After Verification Passes
3. **Review the bead requirements**:
- Run `bd show [BEAD_ID]` to understand the acceptance criteria
- Note any external issue references (GitHub issues, Linear tickets, etc.)
4. **Extract validation criteria**:
- Check for a plan: `thoughts/beads-[BEAD_ID]/plan.md`
- If plan exists:
- Read the plan and find the "Automated Verification" section
- Extract each verification command (lines starting with `- [ ]` followed by a command)
- Example: `- [ ] Tests pass: \`make test\`` → extract `make test`
- Note any "Per CONTRIBUTING.md:" requirements for additional validation
- Also read the "Manual Verification" section from the plan if present
- Save manual verification items for inclusion in the PR description (they won't be executed)
- If no plan exists, use best-effort validation:
- Check if `Makefile` exists → try `make test` and `make lint`
- Check if `flake.nix` exists → try `nix flake check`
- Check if `package.json` exists → try `npm test`
- **Check for CONTRIBUTING.md** → read and extract testing/linting requirements
- Track which requirements can be automated vs need manual review
- Automated: commands that can be run (e.g., "run `make test`")
- Manual: qualitative checks (e.g., "ensure documentation is updated")
- If none found, note "No validation criteria found"
5. **Implement the changes**:
- Work in the worktree directory
- Complete all acceptance criteria listed in the bead
After implementation, run validation:
- Execute each validation command from step 4
- Track results in this format:
```
VALIDATION_RESULTS:
- make test: PASS
- make lint: FAIL (exit code 1: src/foo.ts:23 - missing semicolon)
- nix flake check: SKIP (not applicable - no flake.nix)
- cargo test: ERROR (command not found)
```
**Status definitions:**
- **PASS**: Check executed successfully with no issues
- **FAIL**: Check executed but found issues that need attention
- **SKIP**: Check not applicable to this project (e.g., no Makefile for `make test`)
- **ERROR**: Check could not execute (missing tool, permission error, command not found)
- If any validation fails:
- Continue with PR creation (don't block)
- Document failures in bead notes: `bd update [BEAD_ID] --notes="Validation failures: [list]"`
6. **Commit and push**:
- Stage all changes: `git add -A`
- Create a descriptive commit message
- Push the branch: `git push -u origin bead/[BEAD_ID]`
7. **Create a PR**:
- Detect hosting provider from origin URL: `git remote get-url origin`
- If URL contains `github.com`, use `gh`; otherwise use `tea` (Gitea/Forgejo)
- PR title: "[BEAD_ID] [BEAD_TITLE]"
- PR body must include:
- Reference to bead ID: "Implements bead: [BEAD_ID]"
- Any external issue references from the bead (e.g., "Closes #123")
- Summary of changes
- For GitHub (`gh`):
```bash
gh pr create --title "[BEAD_ID] [BEAD_TITLE]" --body "$(cat <<'EOF'
## Summary
[Brief description of changes]
## Bead Reference
Implements bead: [BEAD_ID]
## External Issues
[Any linked issues from the bead]
## Changes
- [List of changes made]
## Validation Steps Completed
### Automated Checks
| Check | Status | Details |
|-------|--------|---------|
| make test | PASS | |
| make lint | FAIL | src/foo.ts:23 - missing semicolon |
| nix flake check | SKIP | not applicable - no flake.nix |
| cargo test | ERROR | command not found |
### Manual Verification Required
[If plan has Manual Verification items, list them as unchecked boxes:]
- [ ] Verify UI changes match design mockups
- [ ] Test on mobile viewport sizes
[If no manual verification items: "None specified in plan."]
### CONTRIBUTING.md Compliance
[If CONTRIBUTING.md requirements were extracted:]
- [x] Tests pass (verified via `make test`)
- [ ] Documentation updated (needs manual review)
[If no CONTRIBUTING.md: "No contribution guidelines found."]
EOF
)"
```
- For Gitea (`tea`):
```bash
tea pr create --head bead/[BEAD_ID] --base main \
--title "[BEAD_ID] [BEAD_TITLE]" \
--description "## Summary
[Brief description of changes]
## Bead Reference
Implements bead: [BEAD_ID]
## External Issues
[Any linked issues from the bead]
## Changes
- [List of changes made]
## Validation Steps Completed
### Automated Checks
| Check | Status | Details |
|-------|--------|---------|
| make test | PASS | |
| make lint | FAIL | src/foo.ts:23 - missing semicolon |
| nix flake check | SKIP | not applicable - no flake.nix |
| cargo test | ERROR | command not found |
### Manual Verification Required
[If plan has Manual Verification items, list them as unchecked boxes:]
- [ ] Verify UI changes match design mockups
- [ ] Test on mobile viewport sizes
[If no manual verification items: None specified in plan.]
### CONTRIBUTING.md Compliance
[If CONTRIBUTING.md requirements were extracted:]
- [x] Tests pass (verified via make test)
- [ ] Documentation updated (needs manual review)
[If no CONTRIBUTING.md: No contribution guidelines found.]"
```
8. **Update bead status**:
- Mark the bead as "in_review": `bd update [BEAD_ID] --status=in_review`
- Add the PR URL to the bead notes: `bd update [BEAD_ID] --notes="$(bd show [BEAD_ID] --json | jq -r '.notes')
PR: [PR_URL]"`
9. **Report results**:
- Return:
- PR URL
- Bead ID
- Implementation status (success/failure/blocked)
- Validation summary: `X passed, Y failed, Z skipped, W errors`
- List of any validation failures or errors with details
- If blocked or unable to complete, explain what's blocking progress
- If validation failed, include the specific failures so the main agent can summarize them for the user
```
### Launching Subagents
For each bead, substitute into the template:
- `[BEAD_ID]` - the bead ID
- `[BEAD_TITLE]` - the bead title
- `[WORKTREE_PATH]` - the worktree path created in Phase 2
Use `subagent_type: "general-purpose"` for implementation subagents. Launch all selected beads' subagents in a single message for parallel execution:
```
<Task calls for each selected bead - all in one message>
```
**Important**: The worktree paths were created in Phase 2. Use the exact paths that were created, e.g.:
- `~/wt/nixos-configs/nixos-configs-abc`
- `~/wt/nixos-configs/nixos-configs-xyz`
Collect results from all subagents before proceeding.
## Phase 4: Parallel Review
After all implementation subagents complete, launch review subagents for each PR.
### Review Subagent Instructions Template
```
Review PR for bead [BEAD_ID]
1. **Detect hosting provider**: Run `git remote get-url origin` - if it contains `github.com` use `gh`, otherwise use `tea`
2. **Read the PR**:
- For GitHub: `gh pr view [PR_NUMBER] --json title,body,additions,deletions,files`
- For Gitea: `tea pr view [PR_NUMBER]`
- View the diff: `git diff main...bead/[BEAD_ID]`
3. **Review against acceptance criteria**:
- Run `bd show [BEAD_ID]` to get the acceptance criteria
- Verify each criterion is addressed
4. **Leave review comments**:
- For GitHub: `gh pr review [PR_NUMBER] --comment --body "[COMMENTS]"`
- For Gitea: `tea pr review [PR_NUMBER] --comment "[COMMENTS]"`
- Include:
- Acceptance criteria checklist (which are met, which might be missing)
- Code quality observations
- Suggestions for improvement
5. **Return summary**:
- Overall assessment (ready to merge / needs changes)
- Key findings
```
Launch all review subagents in parallel.
## Phase 5: Cleanup and Summary
After reviews complete:
1. **Clean up worktrees**:
```bash
git worktree remove ~/wt/[REPO_NAME]/[BEAD_ID] --force
```
Do this for each bead's worktree.
2. **Provide final summary**:
Present a table or list with:
- Bead ID
- PR URL
- Status (success / failed / blocked)
- Validation summary (X/Y passed)
- Review summary
- Any failures or blockers encountered
If any validation failures occurred, list them in a "Validation Failures" section so the user can address them.
Example output:
```
## Parallel Beads Summary
| Bead | PR | Bead Status | Validation | Review |
|------|-----|-------------|------------|--------|
| beads-abc | #123 | in_review | 3/3 passed | Approved |
| beads-xyz | #124 | in_review | 2/3 passed | Needs changes |
| beads-123 | - | open (failed) | - | Blocked by missing dependency |
### Validation Failures
- beads-xyz: `make lint` failed - src/foo.ts:23 missing semicolon
### Failures/Blockers
- beads-123: Could not complete because [reason]
### Next Steps
- Fix validation failures before merging
- Review PRs that need changes
- Address blockers for failed beads
- Run `/reconcile_beads` after PRs are merged to close beads
```
## Error Handling
- **Worktree creation failures** (Phase 2):
- If `git worktree add` fails (branch exists, path exists), prompt user:
- Remove existing and retry
- Skip this bead
- Use existing (with warning about potential divergence)
- Do NOT proceed to subagent launch until worktree is confirmed
- **Branch verification failures** (subagent reports):
- If subagent reports it's on `main` or `master`, do NOT retry
- Mark bead as failed with reason "Branch verification failed"
- Continue with other beads but flag this as a critical issue
- Investigation required: the worktree may have been corrupted or not created properly
- **Subagent failures**: If a subagent fails or times out, note it in the summary but continue with other beads
- **PR creation failures**: Report the error but continue with reviews of successful PRs
## Resource Limits
- Consider limiting concurrent subagents to 3-5 to avoid overwhelming system resources
- If user selects more beads than the limit, process them in batches
## Notes
- This workflow integrates with the beads system (`bd` commands)
- Worktrees are created in `~/wt/[REPO_NAME]/` by convention
- Each bead gets its own isolated branch and worktree
- PRs automatically reference the bead ID for traceability

129
home/roles/development/commands/reconcile_beads.md Normal file
View File

@@ -0,0 +1,129 @@
---
description: Reconcile beads with merged PRs and close completed beads
---
# Reconcile Beads Workflow
This skill reconciles beads that are in `in_review` status with their corresponding PRs. If a PR has been merged, the bead is closed and any linked Gitea issue is also closed.
## Prerequisites
- Custom status `in_review` must be configured: `bd config set status.custom "in_review"`
- Beads in `in_review` status should have a PR URL in their notes
- `tea` CLI must be configured for closing Gitea issues
## Workflow
### Step 1: Find beads in review
```bash
bd list --status=in_review
```
### Step 2: For each bead, check PR status
1. **Get the PR URL from bead notes**:
```bash
bd show [BEAD_ID] --json | jq -r '.[0].notes'
```
Note: `bd show --json` returns an array, so use `.[0]` to access the first element.
Extract the PR URL (look for lines starting with "PR:" or containing pull request URLs).
Extract the PR number: `echo "$NOTES" | grep -oP '/pulls/\K\d+'`
2. **Detect hosting provider**:
- Run `git remote get-url origin`
- If URL contains `github.com`, use `gh`; otherwise use `tea` (Gitea/Forgejo)
3. **Check PR status**:
- For GitHub:
```bash
gh pr view [PR_NUMBER] --json state,merged
```
- For Gitea:
```bash
tea pr list --state=closed
```
Look for the PR number in the INDEX column with STATE "merged".
Note: `tea pr view [PR_NUMBER]` lists all PRs, not a specific one. Use `tea pr list --state=closed` and look for your PR number in the results.
### Step 3: Close merged beads
If the PR is merged:
```bash
bd close [BEAD_ID] --reason="PR merged: [PR_URL]"
```
### Step 3.1: Close corresponding Gitea issue (if any)
After closing a bead, check if it has a linked Gitea issue:
1. **Check for Gitea issue URL in bead notes**:
Look for the pattern `Gitea issue: <URL>` in the notes. Extract the URL.
2. **Extract issue number from URL**:
```bash
# Example: https://git.johnogle.info/johno/nixos-configs/issues/16 -> 16
echo "$GITEA_URL" | grep -oP '/issues/\K\d+'
```
3. **Close the Gitea issue**:
```bash
tea issues close [ISSUE_NUMBER]
```
4. **Handle errors gracefully**:
- If issue is already closed: Log warning, continue
- If issue not found: Log warning, continue
- If `tea` fails: Log error, continue with other beads
Example warning output:
```
Warning: Could not close Gitea issue #16: issue already closed
```
### Step 4: Report summary
Present results:
```
## Beads Reconciliation Summary
### Closed (PR Merged)
| Bead | PR | Gitea Issue | Title |
|------|-----|-------------|-------|
| beads-abc | #123 | #16 closed | Feature X |
| beads-xyz | #456 | (none) | Bug fix Y |
### Gitea Issues Closed
| Issue | Bead | Status |
|-------|------|--------|
| #16 | beads-abc | Closed successfully |
| #17 | beads-def | Already closed (skipped) |
| #99 | beads-ghi | Error: issue not found |
### Still in Review
| Bead | PR | Status | Title |
|------|-----|--------|-------|
| beads-def | #789 | Open | Feature Z |
### Issues Found
- beads-ghi: No PR URL found in notes
- beads-jkl: PR #999 not found (may have been deleted)
```
## Error Handling
- **Missing PR URL**: Skip the bead and report it
- **PR not found**: Report the error but continue with other beads
- **API errors**: Report and continue
- **Gitea issue already closed**: Log warning, continue (not an error)
- **Gitea issue not found**: Log warning, continue (issue may have been deleted)
- **No Gitea issue linked**: Normal case, no action needed
- **tea command fails**: Log error with output, continue with other beads
## Notes
- This skill complements `/parallel_beads` which sets beads to `in_review` status
- Run this skill periodically or after merging PRs to keep beads in sync
- Beads with closed (but not merged) PRs are not automatically closed - they may need rework
- Gitea issues are only closed for beads that have a `Gitea issue: <URL>` in their notes