Initial commit

.claude-plugin/plugin.json

@@ -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"
+  ]
+}

README.md

@@ -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.

hooks/hooks.json

@@ -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"
+          }
+        ]
+      }
+    ]
+  }
+}

hooks/session-start.sh

@@ -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

hooks/stop-hook.sh

@@ -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

plugin.lock.json

@@ -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": []
+  }
+}

skills/using-beads/SKILL.md

@@ -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