Initial commit
This commit is contained in:
Zhongwei Li
15
.claude-plugin/plugin.json
Normal file
15
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"name": "beads",
|
||||
"description": "Beads (bd) integration for dependency-aware issue tracking in AI workflows. Provides workflow guidance for issue lifecycle management, dependency tracking, and ready work discovery. Designed for AI-supervised development with bd ready → work → close patterns.",
|
||||
"version": "0.3.0",
|
||||
"author": {
|
||||
"name": "Fred Amaral",
|
||||
"email": "fred@fredamaral.com.br"
|
||||
},
|
||||
"skills": [
|
||||
"./skills"
|
||||
],
|
||||
"hooks": [
|
||||
"./hooks"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# beads
|
||||
|
||||
Beads (bd) integration for dependency-aware issue tracking in AI workflows. Provides workflow guidance for issue lifecycle management, dependency tracking, and ready work discovery. Designed for AI-supervised development with bd ready → work → close patterns.
|
||||
35
hooks/hooks.json
Normal file
35
hooks/hooks.json
Normal file
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": [
|
||||
{
|
||||
"matcher": "startup|resume",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"matcher": "clear|compact",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"Stop": [
|
||||
{
|
||||
"matcher": "",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
120
hooks/session-start.sh
Executable file
120
hooks/session-start.sh
Executable file
@@ -0,0 +1,120 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
# Session start hook for beads plugin
|
||||
# Checks bd installation, repo initialization, and injects workflow context
|
||||
|
||||
# Check if bd is installed
|
||||
if ! command -v bd &>/dev/null; then
|
||||
cat <<'EOF'
|
||||
{
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "SessionStart",
|
||||
"additionalContext": "<beads-system>\n**Beads (bd) Not Installed**\n\nInstall beads for dependency-aware issue tracking:\nhttps://github.com/steveyegge/beads\n\nFor skill details: Skill tool with \"beads:using-beads\"\n</beads-system>"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Check if beads is initialized in current repo
|
||||
beads_initialized="false"
|
||||
beads_db_path=""
|
||||
info_json=""
|
||||
|
||||
if info_json=$(bd info --json 2>/dev/null); then
|
||||
if echo "$info_json" | grep -q '"database_path"'; then
|
||||
beads_initialized="true"
|
||||
if command -v jq &>/dev/null; then
|
||||
beads_db_path=$(echo "$info_json" | jq -r '.database_path // ""')
|
||||
fi
|
||||
fi
|
||||
fi
|
||||
|
||||
# Build context based on initialization status
|
||||
if [ "$beads_initialized" = "true" ]; then
|
||||
# Get counts using jq if available
|
||||
ready_count="0"
|
||||
in_progress_count="0"
|
||||
|
||||
if command -v jq &>/dev/null; then
|
||||
ready_count=$(bd ready --json 2>/dev/null | jq 'length' || echo "0")
|
||||
in_progress_count=$(bd list --status in_progress --json 2>/dev/null | jq 'length' || echo "0")
|
||||
fi
|
||||
|
||||
# Shorten path for display
|
||||
display_path="$beads_db_path"
|
||||
if [ -n "$beads_db_path" ]; then
|
||||
display_path=$(echo "$beads_db_path" | sed "s|$HOME|~|")
|
||||
fi
|
||||
|
||||
context="<beads-system>
|
||||
**Beads (bd) - Issue Tracking ACTIVE**
|
||||
|
||||
Database: ${display_path}
|
||||
Ready: ${ready_count} | In Progress: ${in_progress_count}
|
||||
|
||||
**START OF SESSION CHECKLIST:**
|
||||
1. Run \`bd ready\` to see what's actionable
|
||||
2. Run \`bd list --status in_progress\` to see claimed work
|
||||
3. Claim work with \`bd update ID --status in_progress\`
|
||||
|
||||
**Quick Commands:**
|
||||
| Action | Command |
|
||||
|--------|---------|
|
||||
| What's ready? | \`bd ready\` |
|
||||
| Start work | \`bd update ID --status in_progress\` |
|
||||
| Create issue | \`bd create \"title\"\` |
|
||||
| Add blocker | \`bd dep add BLOCKED BLOCKER\` |
|
||||
| Finish work | \`bd close ID --reason \"...\"\` |
|
||||
|
||||
**IMPORTANT:** Before ending session, leftover work (TODOs, FIXMEs, review issues) will be captured as beads issues.
|
||||
|
||||
For full workflow: Skill tool with \"beads:using-beads\"
|
||||
</beads-system>"
|
||||
else
|
||||
context="<beads-system>
|
||||
**Beads (bd) - NOT INITIALIZED IN THIS REPO**
|
||||
|
||||
Beads is installed but this repository has no .beads/ directory.
|
||||
|
||||
**ACTION REQUIRED:** Initialize beads for this project:
|
||||
\`\`\`bash
|
||||
bd init # Use directory name as prefix
|
||||
bd init --prefix myapp # Or specify custom prefix
|
||||
\`\`\`
|
||||
|
||||
After initialization:
|
||||
1. \`bd create \"First issue\"\` - Create your first issue
|
||||
2. \`bd ready\` - See what's ready to work on
|
||||
|
||||
**Why initialize?**
|
||||
- Track discovered work as you code
|
||||
- Manage dependencies between tasks
|
||||
- Never lose TODOs, FIXMEs, or review items
|
||||
- AI-friendly workflow with \`bd ready\`
|
||||
|
||||
For full workflow: Skill tool with \"beads:using-beads\"
|
||||
</beads-system>"
|
||||
fi
|
||||
|
||||
# Escape for JSON using jq
|
||||
if command -v jq &>/dev/null; then
|
||||
context_escaped=$(echo "$context" | jq -Rs . | sed 's/^"//;s/"$//')
|
||||
else
|
||||
context_escaped=$(printf '%s' "$context" | \
|
||||
sed 's/\\/\\\\/g' | \
|
||||
sed 's/"/\\"/g' | \
|
||||
sed 's/ /\\t/g' | \
|
||||
sed $'s/\r/\\\\r/g' | \
|
||||
sed 's/\f/\\f/g' | \
|
||||
awk '{printf "%s\\n", $0}')
|
||||
fi
|
||||
|
||||
cat <<EOF
|
||||
{
|
||||
"hookSpecificOutput": {
|
||||
"hookEventName": "SessionStart",
|
||||
"additionalContext": "${context_escaped}"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
104
hooks/stop-hook.sh
Executable file
104
hooks/stop-hook.sh
Executable file
@@ -0,0 +1,104 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
# Stop hook for beads plugin
|
||||
# Prompts Claude to capture leftover work as beads issues before ending session
|
||||
|
||||
# Check if bd is installed
|
||||
if ! command -v bd &>/dev/null; then
|
||||
# bd not installed - no action needed
|
||||
cat <<'EOF'
|
||||
{
|
||||
"decision": "approve",
|
||||
"reason": "beads not installed"
|
||||
}
|
||||
EOF
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Check if beads is initialized
|
||||
if ! bd info --json 2>/dev/null | grep -q '"database_path"'; then
|
||||
# Not initialized - no action needed
|
||||
cat <<'EOF'
|
||||
{
|
||||
"decision": "approve",
|
||||
"reason": "beads not initialized in this repo"
|
||||
}
|
||||
EOF
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Check if checkpoint has been completed
|
||||
# Strategy: If there are open issues OR no uncommitted changes with markers, approve exit
|
||||
OPEN_ISSUES=$(bd status 2>/dev/null | grep -E "Total Issues:|Open:" | head -2 | tail -1 | awk '{print $2}' || echo "0")
|
||||
RECENT_MARKERS=$(git diff --name-only HEAD~5 2>/dev/null | head -20 | xargs grep -c -E "(TODO|FIXME|HACK|XXX):" 2>/dev/null | awk '{sum+=$1} END {print sum}' || echo "0")
|
||||
|
||||
# If we have open issues capturing work, or no markers found, allow exit
|
||||
if [[ "$OPEN_ISSUES" -gt 0 ]] || [[ "$RECENT_MARKERS" -eq 0 ]]; then
|
||||
cat <<'EOF'
|
||||
{
|
||||
"decision": "approve",
|
||||
"reason": "beads checkpoint complete - work captured in issues or no markers found"
|
||||
}
|
||||
EOF
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Beads is active - inject prompt to capture leftover work
|
||||
prompt='**BEADS END-OF-SESSION CHECKPOINT**
|
||||
|
||||
Before ending this session, capture any leftover work as beads issues:
|
||||
|
||||
1. **Search for code markers** in files modified this session:
|
||||
```bash
|
||||
# Find TODOs, FIXMEs, HACKs, XXX in recent files
|
||||
git diff --name-only HEAD~5 2>/dev/null | head -20 | xargs grep -n -E "(TODO|FIXME|HACK|XXX):" 2>/dev/null | head -30
|
||||
```
|
||||
|
||||
2. **Check your TodoWrite list** - any incomplete items should become beads issues
|
||||
|
||||
3. **Review any code review findings** that were flagged but not yet addressed
|
||||
|
||||
4. **Create beads issues** for each piece of leftover work:
|
||||
```bash
|
||||
bd create "TODO: [description from code]" -t task -p 2
|
||||
bd create "FIXME: [description from code]" -t bug -p 1
|
||||
bd create "Code review: [finding]" -t task -p 2
|
||||
```
|
||||
|
||||
5. **Update in-progress issues** - if leaving work incomplete:
|
||||
```bash
|
||||
bd update ISSUE-ID --status open # Release claim if blocked
|
||||
bd comment ISSUE-ID "Session ended - progress: [summary]"
|
||||
```
|
||||
|
||||
6. **Run final status**:
|
||||
```bash
|
||||
bd status
|
||||
```
|
||||
|
||||
If there is NO leftover work (all tasks completed, no TODOs found), you may proceed to end the session.
|
||||
|
||||
**DO NOT** end the session without:
|
||||
- Checking for leftover work markers
|
||||
- Creating issues for any discovered work
|
||||
- Updating any in-progress issues with status'
|
||||
|
||||
# Escape for JSON using jq
|
||||
if command -v jq &>/dev/null; then
|
||||
prompt_escaped=$(echo "$prompt" | jq -Rs . | sed 's/^"//;s/"$//')
|
||||
else
|
||||
prompt_escaped=$(printf '%s' "$prompt" | \
|
||||
sed 's/\\/\\\\/g' | \
|
||||
sed 's/"/\\"/g' | \
|
||||
sed 's/ /\\t/g' | \
|
||||
sed $'s/\r/\\\\r/g' | \
|
||||
sed 's/\f/\\f/g' | \
|
||||
awk '{printf "%s\\n", $0}')
|
||||
fi
|
||||
|
||||
cat <<EOF
|
||||
{
|
||||
"decision": "approve",
|
||||
"reason": "${prompt_escaped}"
|
||||
}
|
||||
EOF
|
||||
57
plugin.lock.json
Normal file
57
plugin.lock.json
Normal file
@@ -0,0 +1,57 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:LerianStudio/ring:beads",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "ca8d0d358f83639667af52986d9f69b6f8d8e511",
|
||||
"treeHash": "ee1a31dd2222d2127c895cda5f02b8639ee60cde20c9bea4fe39b4b81ccdc2d7",
|
||||
"generatedAt": "2025-11-28T10:12:02.561737Z",
|
||||
"toolVersion": "publish_plugins.py@0.2.0"
|
||||
},
|
||||
"origin": {
|
||||
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||
"branch": "master",
|
||||
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||
},
|
||||
"manifest": {
|
||||
"name": "beads",
|
||||
"description": "Beads (bd) integration for dependency-aware issue tracking in AI workflows. Provides workflow guidance for issue lifecycle management, dependency tracking, and ready work discovery. Designed for AI-supervised development with bd ready → work → close patterns.",
|
||||
"version": "0.3.0"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "9a637b4e8ade28e91a3011d52a36d5838d52ed9368a9f23737f492091473a69f"
|
||||
},
|
||||
{
|
||||
"path": "hooks/stop-hook.sh",
|
||||
"sha256": "66b8e9d65c2d6bae8eed9444560dfcbdc46e196d25d3c1be1cf5b9e6852d7c44"
|
||||
},
|
||||
{
|
||||
"path": "hooks/session-start.sh",
|
||||
"sha256": "df82f3f5b1058d7a470c9e848ed2aeea2b0ce490b58fbb5188316889ea4914dd"
|
||||
},
|
||||
{
|
||||
"path": "hooks/hooks.json",
|
||||
"sha256": "9b5f145734e3bdabd7cd5f6a7b471209f8fa805d5b1e83ad54bba5b98896d95e"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "1777c6d797d420e44a4d3b68a3d52957a7faaa9da77b5f3c0a255d30596a0184"
|
||||
},
|
||||
{
|
||||
"path": "skills/using-beads/SKILL.md",
|
||||
"sha256": "193376b6abd7c167da91b9d55cf2087592ccaaa57b25d30e9da7a86cf8645716"
|
||||
}
|
||||
],
|
||||
"dirSha256": "ee1a31dd2222d2127c895cda5f02b8639ee60cde20c9bea4fe39b4b81ccdc2d7"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
211
skills/using-beads/SKILL.md
Normal file
211
skills/using-beads/SKILL.md
Normal file
@@ -0,0 +1,211 @@
|
||||
---
|
||||
name: using-beads
|
||||
description: |
|
||||
Beads (bd) workflow integration - dependency-aware issue tracking for AI agents.
|
||||
Teaches proper bd usage: ready work discovery, issue lifecycle, dependency management.
|
||||
|
||||
trigger: |
|
||||
- ALWAYS at session start (auto-injected via hook)
|
||||
- When working on tasks that need tracking
|
||||
- When discovering work that should be logged
|
||||
- When needing to find next actionable work
|
||||
|
||||
skip_when: |
|
||||
- Never skip - foundational workflow knowledge
|
||||
|
||||
related:
|
||||
complementary: [test-driven-development, systematic-debugging]
|
||||
---
|
||||
|
||||
# Using Beads (bd) - Dependency-Aware Issue Tracking
|
||||
|
||||
## Overview
|
||||
|
||||
Beads is a lightweight issue tracker with first-class dependency support, designed for AI-supervised workflows. Issues chain together like beads on a string.
|
||||
|
||||
**Key Concept:** `bd ready` shows unblocked work - issues with status 'open' AND no blocking dependencies.
|
||||
|
||||
## Essential Workflow
|
||||
|
||||
### 1. Check Ready Work First
|
||||
|
||||
```bash
|
||||
bd ready # What can I work on NOW?
|
||||
bd ready --json # Programmatic format
|
||||
bd list --status open # All open issues
|
||||
bd list --status in_progress # What's being worked on
|
||||
```
|
||||
|
||||
### 2. Claim and Work
|
||||
|
||||
```bash
|
||||
bd update ISSUE-ID --status in_progress # Claim work
|
||||
# ... do the work ...
|
||||
bd close ISSUE-ID --reason "Completed in commit abc123"
|
||||
```
|
||||
|
||||
### 3. Create Issues When Discovering Work
|
||||
|
||||
```bash
|
||||
bd create "Fix login bug" # Basic
|
||||
bd create "Add auth" -p 0 -t feature # Priority 0 (highest), type feature
|
||||
bd create "Write tests" -d "Unit tests for auth" # With description
|
||||
```
|
||||
|
||||
### 4. Manage Dependencies
|
||||
|
||||
```bash
|
||||
bd dep add ISSUE-A ISSUE-B # B blocks A (A depends on B)
|
||||
bd dep add ISSUE-A ISSUE-B --type related # Soft link (doesn't block)
|
||||
bd dep tree ISSUE-ID # Visualize dependency tree
|
||||
bd dep cycles # Detect circular dependencies
|
||||
```
|
||||
|
||||
## Priority Levels
|
||||
|
||||
| Priority | Meaning | Use When |
|
||||
|----------|---------|----------|
|
||||
| 0 | Critical | Blocking production, security issues |
|
||||
| 1 | High | Important bugs, key features |
|
||||
| 2 | Medium | Normal priority (default) |
|
||||
| 3 | Low | Nice-to-have, minor improvements |
|
||||
| 4 | Minimal | Backlog, someday/maybe |
|
||||
|
||||
## Issue Types
|
||||
|
||||
- `bug` - Something broken
|
||||
- `feature` - New functionality
|
||||
- `task` - General work item
|
||||
- `epic` - Large multi-issue work
|
||||
- `spike` - Research/investigation
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern: Start of Session
|
||||
```bash
|
||||
bd status # Overview of database
|
||||
bd ready # What's ready to work on
|
||||
bd list --status in_progress # What's already claimed
|
||||
```
|
||||
|
||||
### Pattern: Discover Blocking Work
|
||||
```bash
|
||||
# While working on ISSUE-A, discover ISSUE-B must be done first
|
||||
bd create "Fix dependency X" -t bug
|
||||
bd dep add ISSUE-A NEW-ISSUE-ID # NEW blocks ISSUE-A
|
||||
bd update ISSUE-A --status open # Back to open (now blocked)
|
||||
bd update NEW-ISSUE-ID --status in_progress # Work on blocker
|
||||
```
|
||||
|
||||
### Pattern: Close with Context
|
||||
```bash
|
||||
bd close ISSUE-ID --reason "Fixed in PR #42"
|
||||
bd close ISSUE-ID --reason "Resolved by implementing X in commit abc"
|
||||
```
|
||||
|
||||
### Pattern: Search and Find
|
||||
```bash
|
||||
bd search "authentication" # Text search
|
||||
bd list --label security # By label
|
||||
bd list --assignee alice # By assignee
|
||||
bd show ISSUE-ID # Full details
|
||||
```
|
||||
|
||||
## Database Setup
|
||||
|
||||
```bash
|
||||
bd init # Initialize in current directory
|
||||
bd init --prefix api # Custom prefix (api-1, api-2, ...)
|
||||
bd info # Show database location
|
||||
bd doctor # Health check
|
||||
```
|
||||
|
||||
## JSON Output (for programmatic use)
|
||||
|
||||
Most commands support `--json`:
|
||||
```bash
|
||||
bd ready --json # Ready issues as JSON
|
||||
bd list --json # All issues as JSON
|
||||
bd show ISSUE-ID --json # Single issue details
|
||||
```
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
1. **Don't create issues without checking existing ones first**
|
||||
```bash
|
||||
bd search "keyword" # Check before creating
|
||||
bd duplicates # Find potential duplicates
|
||||
```
|
||||
|
||||
2. **Don't leave issues in_progress when blocked**
|
||||
- If blocked, set back to `open` and create blocker issue
|
||||
|
||||
3. **Don't ignore dependencies**
|
||||
- Always use `bd dep add` when work has prerequisites
|
||||
|
||||
4. **Don't close without reason**
|
||||
- Always provide `--reason` for traceability
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Action | Command |
|
||||
|--------|---------|
|
||||
| What's ready? | `bd ready` |
|
||||
| Start work | `bd update ID --status in_progress` |
|
||||
| Create issue | `bd create "title"` |
|
||||
| Add blocker | `bd dep add BLOCKED BLOCKER` |
|
||||
| Finish work | `bd close ID --reason "..."` |
|
||||
| Show details | `bd show ID` |
|
||||
| Search | `bd search "query"` |
|
||||
| Overview | `bd status` |
|
||||
|
||||
## End-of-Session Checkpoint (Stop Hook)
|
||||
|
||||
The beads plugin includes a Stop hook that automatically runs when you attempt to end a session. This hook ensures no work is lost by prompting you to capture leftover work as beads issues.
|
||||
|
||||
**How the checkpoint works:**
|
||||
|
||||
1. **Hook triggers** when you try to exit the session
|
||||
2. **Checks completion criteria:**
|
||||
- Are there open beads issues? (work captured)
|
||||
- Are there TODO/FIXME markers in recent changes? (work not captured)
|
||||
3. **Decision:**
|
||||
- **Approve exit** if work is captured OR no markers found
|
||||
- **Block exit** if markers exist but no issues created (prompts you to capture work)
|
||||
|
||||
**The checkpoint prompts you to:**
|
||||
- Search for TODO/FIXME/HACK/XXX markers in modified files
|
||||
- Check TodoWrite list for incomplete items
|
||||
- Review code review findings not yet addressed
|
||||
- Create beads issues for each piece of leftover work
|
||||
- Update in-progress issues if leaving work incomplete
|
||||
|
||||
**Example checkpoint flow:**
|
||||
```bash
|
||||
# You try to exit - hook blocks with checkpoint prompt
|
||||
# You run the checkpoint steps:
|
||||
git diff --name-only HEAD~5 | xargs grep -E "(TODO|FIXME):"
|
||||
# Found 3 TODOs
|
||||
|
||||
# Create issues for each:
|
||||
bd create "TODO: Refactor auth module" -t task -p 2
|
||||
bd create "FIXME: Handle edge case in parser" -t bug -p 1
|
||||
bd create "TODO: Add integration tests" -t task -p 3
|
||||
|
||||
# Check status
|
||||
bd status # Shows 3 new open issues
|
||||
|
||||
# Try to exit again - hook sees open issues, approves exit
|
||||
```
|
||||
|
||||
**When the hook approves exit:**
|
||||
- Open beads issues exist (indicating work was captured)
|
||||
- No TODO/FIXME markers in recent git changes
|
||||
- Beads not installed or not initialized
|
||||
|
||||
## Remember
|
||||
|
||||
- **`bd ready`** is your starting point - it shows what's actually actionable
|
||||
- **Dependencies prevent duplicate effort** - always model blocking relationships
|
||||
- **Close with context** - future you will thank present you
|
||||
- **JSON for automation** - use `--json` when parsing output
|
||||
Reference in New Issue
Block a user