panopticon-cli 0.4.6 → 0.4.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panopticon-cli",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Multi-agent orchestration for AI coding assistants (Claude Code, Codex, Cursor, Gemini CLI)",
   "keywords": [
     "ai-agents",
@@ -38,6 +38,7 @@
   "files": [
     "dist",
     "templates",
+    "skills",
     "scripts/git-hooks",
     "README.md",
     "LICENSE"

package/skills/beads/README.md

@@ -0,0 +1,120 @@
+# Beads Skill for Claude Code
+
+A comprehensive skill for using [beads](https://github.com/steveyegge/beads) (bd) issue tracking with Claude Code.
+
+## What This Skill Does
+
+This skill teaches Claude Code how to use bd effectively for:
+- **Multi-session work tracking** - Persistent memory across conversation compactions
+- **Dependency management** - Graph-based issue relationships
+- **Session handoff** - Writing notes that survive context resets
+- **Molecules and wisps** (v0.34.0+) - Reusable work templates and ephemeral workflows
+
+## Installation
+
+Copy the `beads/` directory to your Claude Code skills location:
+
+```bash
+# Global installation
+cp -r beads ~/.claude/skills/
+
+# Or project-local
+cp -r beads .claude/skills/
+```
+
+## When Claude Uses This Skill
+
+The skill activates when conversations involve:
+- "multi-session", "complex dependencies", "resume after weeks"
+- "project memory", "persistent context", "side quest tracking"
+- Work that spans multiple days or compaction cycles
+- Tasks too complex for simple TodoWrite lists
+
+## File Structure
+
+```
+beads/
+├── SKILL.md                 # Main skill file (Claude reads this first)
+├── CLAUDE.md                # Maintenance guide for updating the skill
+├── README.md                # This file (for humans)
+├── adr/                     # Architectural Decision Records
+│   └── 0001-bd-prime-as-source-of-truth.md
+└── resources/               # Detailed documentation (loaded on demand)
+    ├── BOUNDARIES.md        # When to use bd vs TodoWrite
+    ├── CLI_REFERENCE.md     # CLI command reference
+    ├── DEPENDENCIES.md      # Dependency semantics (A blocks B vs B blocks A)
+    ├── INTEGRATION_PATTERNS.md # TodoWrite and other tool integration
+    ├── ISSUE_CREATION.md    # When and how to create issues
+    ├── MOLECULES.md         # Protos, mols, wisps (v0.34.0+)
+    ├── PATTERNS.md          # Common usage patterns
+    ├── RESUMABILITY.md      # Writing notes for post-compaction recovery
+    ├── STATIC_DATA.md       # Using bd for reference databases
+    ├── TROUBLESHOOTING.md   # Common issues and fixes
+    ├── WORKFLOWS.md         # Step-by-step workflow guides
+    ├── AGENTS.md            # Agent bead tracking (v0.40+)
+    ├── ASYNC_GATES.md       # Human-in-the-loop gates
+    ├── CHEMISTRY_PATTERNS.md # Mol vs Wisp decision tree
+    └── WORKTREES.md         # Parallel development patterns
+```
+
+## Key Concepts
+
+### bd vs TodoWrite
+
+| Use bd when... | Use TodoWrite when... |
+|----------------|----------------------|
+| Work spans multiple sessions | Single-session tasks |
+| Complex dependencies exist | Linear step-by-step work |
+| Need to resume after weeks | Just need a quick checklist |
+| Knowledge work with fuzzy boundaries | Clear, immediate tasks |
+
+### The Dependency Direction Trap
+
+`bd dep add A B` means **"A depends on B"** (B must complete before A can start).
+
+```bash
+# Want: "Setup must complete before Implementation"
+bd dep add implementation setup  # ✓ CORRECT
+# NOT: bd dep add setup implementation  # ✗ WRONG
+```
+
+### Surviving Compaction
+
+When Claude's context gets compacted, conversation history is lost but bd state survives. Write notes as if explaining to a future Claude with zero context:
+
+```bash
+bd update issue-123 --notes "COMPLETED: JWT auth with RS256
+KEY DECISION: RS256 over HS256 for key rotation
+IN PROGRESS: Password reset flow
+NEXT: Implement rate limiting"
+```
+
+## Requirements
+
+- [bd CLI](https://github.com/steveyegge/beads) installed (`brew install steveyegge/beads/bd`)
+- A git repository (bd requires git for sync)
+- Initialized database (`bd init` in project root)
+
+## Version Compatibility
+
+| Version | Features |
+|---------|----------|
+| v0.43.0+ | Full support: agents, gates, worktrees, chemistry patterns |
+| v0.40.0+ | Agent beads, async gates, worktree management |
+| v0.34.0+ | Molecules, wisps, cross-project dependencies |
+| v0.15.0+ | Core: dependencies, notes, status tracking |
+| Earlier | Basic functionality, some features missing |
+
+## Contributing
+
+This skill is maintained at [github.com/steveyegge/beads](https://github.com/steveyegge/beads) in the `skills/beads/` directory.
+
+Issues and PRs welcome for:
+- Documentation improvements
+- New workflow patterns
+- Bug fixes in examples
+- Additional troubleshooting scenarios
+
+## License
+
+MIT (same as beads)

package/skills/beads/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: beads
+description: >
+  Git-backed issue tracker for multi-session work with dependencies and persistent
+  memory across conversation compaction. Use when work spans sessions, has blockers,
+  or needs context recovery after compaction.
+allowed-tools: "Read,Bash(bd:*)"
+version: "0.43.0"
+author: "Steve Yegge <https://github.com/steveyegge>"
+license: "MIT"
+---
+
+# Beads - Persistent Task Memory for AI Agents
+
+Graph-based issue tracker that survives conversation compaction. Provides persistent memory for multi-session work with complex dependencies.
+
+## bd vs TodoWrite
+
+| bd (persistent) | TodoWrite (ephemeral) |
+|-----------------|----------------------|
+| Multi-session work | Single-session tasks |
+| Complex dependencies | Linear execution |
+| Survives compaction | Conversation-scoped |
+| Git-backed, team sync | Local to session |
+
+**Decision test**: "Will I need this context in 2 weeks?" → YES = bd
+
+## ID Systems
+
+**Beads uses a unique ID format** that differs from GitHub/Linear issue IDs:
+
+| System | Format | Example |
+|--------|--------|---------|
+| **Beads** | `repo-hash` | `panopticon-3eb7`, `panopticon-6ax` |
+| **Beads (hierarchical)** | `repo-hash.N` | `panopticon-3eb7.4` |
+| **GitHub Issues** | `PREFIX-number` | `PAN-84`, `PAN-73` |
+| **Linear Issues** | `PREFIX-number` | `MIN-123`, `HH-456` |
+
+**CRITICAL**: Commands like `bd dep add`, `--parent`, and `--deps` expect **beads IDs** (e.g., `panopticon-abc1`), NOT external tracker IDs (e.g., `PAN-5`).
+
+### Linking to External Trackers
+
+To link a beads issue to a GitHub or Linear issue, use `--external-ref` when creating:
+
+```bash
+# Link beads issue to GitHub issue PAN-84
+bd create "Fix auth bug" --external-ref PAN-84 --json
+
+# Link to Linear issue
+bd create "Add feature" --external-ref MIN-123 --json
+```
+
+**Current limitation**: No `bd list --external-ref PAN-84` filter exists. Use labels or title conventions as workaround until upstream feature is available.
+
+**When to use bd**:
+- Work spans multiple sessions or days
+- Tasks have dependencies or blockers
+- Need to survive conversation compaction
+- Exploratory/research work with fuzzy boundaries
+- Collaboration with team (git sync)
+
+**When to use TodoWrite**:
+- Single-session linear tasks
+- Simple checklist for immediate work
+- All context is in current conversation
+- Will complete within current session
+
+## Prerequisites
+
+```bash
+bd --version  # Requires v0.34.0+
+```
+
+- **bd CLI** installed and in PATH
+- **Git repository** (bd requires git for sync)
+- **Initialization**: `bd init` run once (humans do this, not agents)
+
+## CLI Reference
+
+**Run `bd prime`** for AI-optimized workflow context (auto-loaded by hooks).
+**Run `bd <command> --help`** for specific command usage.
+
+Essential commands: `bd ready`, `bd create`, `bd show`, `bd update`, `bd close`, `bd sync`
+
+## Session Protocol
+
+1. `bd ready` — Find unblocked work
+2. `bd show <id>` — Get full context
+3. `bd update <id> --status in_progress` — Start work
+4. Add notes as you work (critical for compaction survival)
+5. `bd close <id> --reason "..."` — Complete task
+6. `bd sync` — Persist to git (always run at session end)
+
+## Quick Reference (Exact Syntax)
+
+**DO NOT GUESS FLAGS** - use exactly these commands.
+
+For advanced commands not listed here:
+1. Run `bd --help` to see all available commands
+2. Run `bd <command> --help` for specific command syntax
+
+### Find Work
+```bash
+bd ready --json                  # Find unblocked work (no blockers)
+bd stale --days 30 --json        # Find stale issues
+bd prime                         # AI-optimized workflow context
+```
+
+### Create Issues
+```bash
+bd create "Title" -t bug|feature|task -p 0-4 -d "Description" --json
+bd create "Title" -t task -p 2 -l label1,label2 --json  # with labels
+bd create "Title" --deps blocks:pan-1 --json            # with dependency
+```
+
+### Dependencies (Blocked-By)
+```bash
+# Make issue-A blocked by issue-B (A cannot start until B is done)
+bd dep add <blocked-issue> <blocker-issue> --type blocks
+
+# Example: panopticon-abc1 is blocked by panopticon-def2
+bd dep add panopticon-abc1 panopticon-def2 --type blocks
+
+# View dependency tree
+bd dep tree <id>
+```
+
+### Related Issues (No Blocking)
+```bash
+bd dep add <issue-a> <issue-b> --type related
+```
+
+### Update Issues
+```bash
+bd update <id> --status in_progress|open|closed --json
+bd update <id> --priority 0-4 --json
+bd update <id> --assignee "name" --json
+bd update <id> --notes "Progress notes here" --json
+bd update <id> --design "Design decisions" --json
+bd update <id> --due "+2d" --json                # Due in 2 days
+bd update <id> --claim --json                    # Claim issue (atomic)
+
+# NOTE: No --blocked-by flag exists! Use 'bd dep add' instead
+```
+
+### Comments (For Progress Notes)
+```bash
+bd comments <id> --json                          # List comments
+bd comments add <id> "Comment text" --json       # Add comment
+```
+
+### Labels
+```bash
+bd label add <id> <label> --json
+bd label remove <id> <label> --json
+bd update <id> --add-label urgent --json         # Alternative
+bd update <id> --remove-label wip --json
+```
+
+### View & Search
+```bash
+bd show <id> --json              # Full issue details
+bd list --status open --json     # Filter by status
+bd list --label bug --json       # Filter by label
+bd list --assignee me --json     # My issues
+bd search "keyword" --json       # Full-text search
+bd count --status open --json    # Count issues
+```
+
+### Close & Reopen
+```bash
+bd close <id> --reason "Completed" --json
+bd reopen <id> --reason "Need more work" --json
+```
+
+### Sync (End of Session)
+```bash
+bd sync                          # Commit and push to git (ALWAYS run at session end)
+```
+
+## Advanced Features
+
+| Feature | CLI | Resource |
+|---------|-----|----------|
+| Molecules (templates) | `bd mol --help` | [MOLECULES.md](resources/MOLECULES.md) |
+| Chemistry (pour/wisp) | `bd pour`, `bd wisp` | [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md) |
+| Agent beads | `bd agent --help` | [AGENTS.md](resources/AGENTS.md) |
+| Async gates | `bd gate --help` | [ASYNC_GATES.md](resources/ASYNC_GATES.md) |
+| Worktrees | `bd worktree --help` | [WORKTREES.md](resources/WORKTREES.md) |
+
+## Resources
+
+| Resource | Content |
+|----------|---------|
+| [BOUNDARIES.md](resources/BOUNDARIES.md) | bd vs TodoWrite detailed comparison |
+| [CLI_REFERENCE.md](resources/CLI_REFERENCE.md) | Complete command syntax |
+| [DEPENDENCIES.md](resources/DEPENDENCIES.md) | Dependency system deep dive |
+| [INTEGRATION_PATTERNS.md](resources/INTEGRATION_PATTERNS.md) | TodoWrite and tool integration |
+| [ISSUE_CREATION.md](resources/ISSUE_CREATION.md) | When and how to create issues |
+| [MOLECULES.md](resources/MOLECULES.md) | Proto definitions, component labels |
+| [PATTERNS.md](resources/PATTERNS.md) | Common usage patterns |
+| [RESUMABILITY.md](resources/RESUMABILITY.md) | Compaction survival guide |
+| [STATIC_DATA.md](resources/STATIC_DATA.md) | Database schema reference |
+| [TROUBLESHOOTING.md](resources/TROUBLESHOOTING.md) | Error handling and fixes |
+| [WORKFLOWS.md](resources/WORKFLOWS.md) | Step-by-step workflow patterns |
+| [AGENTS.md](resources/AGENTS.md) | Agent bead tracking (v0.40+) |
+| [ASYNC_GATES.md](resources/ASYNC_GATES.md) | Human-in-the-loop gates |
+| [CHEMISTRY_PATTERNS.md](resources/CHEMISTRY_PATTERNS.md) | Mol vs Wisp decision tree |
+| [WORKTREES.md](resources/WORKTREES.md) | Parallel development patterns |
+
+## Full Documentation
+
+- **bd prime**: AI-optimized workflow context
+- **GitHub**: [github.com/steveyegge/beads](https://github.com/steveyegge/beads)

package/skills/beads/adr/0001-bd-prime-as-source-of-truth.md

@@ -0,0 +1,59 @@
+# ADR-0001: Use bd prime as CLI Reference Source of Truth
+
+## Status
+
+Accepted
+
+## Context
+
+The beads skill maintained CLI reference documentation in multiple locations:
+
+- `SKILL.md` inline (~2,000+ words of CLI reference)
+- `references/CLI_REFERENCE.md` (~2,363 words)
+- Scattered examples throughout resource files
+
+This created:
+- **Duplication**: Same commands documented 2-3 times
+- **Drift risk**: Documentation can fall behind bd versions
+- **Token overhead**: ~3,000+ tokens loaded even for simple operations
+
+Meanwhile, bd provides `bd prime` which generates AI-optimized workflow context automatically.
+
+## Decision
+
+Use `bd prime` as the single source of truth for CLI commands:
+
+1. **SKILL.md** contains only value-add content (decision frameworks, cognitive patterns)
+2. **CLI reference** points to `bd prime` (auto-loaded by hooks) and `bd --help`
+3. **Resources** provide depth for advanced features (molecules, agents, gates)
+
+## Consequences
+
+### Positive
+
+- **Zero maintenance**: CLI docs auto-update with bd versions
+- **DRY**: Single source of truth
+- **Accurate**: No version drift possible
+- **Lighter SKILL.md**: ~500 words vs ~3,300
+
+### Negative
+
+- **Dependency on bd prime format**: If output changes significantly, may need adaptation
+- **External tool requirement**: Skill assumes bd is installed
+
+## Implementation
+
+Files restructured:
+- `SKILL.md` — Reduced from 3,306 to ~500 words
+- `references/` → `resources/` — Directory rename for consistency
+- New resources added: `agents.md`, `async-gates.md`, `chemistry-patterns.md`, `worktrees.md`
+- Existing resources preserved with path updates
+
+## Related
+
+- Claude Code skill progressive disclosure guidelines
+- Similar pattern implemented in other Claude Code skill ecosystems
+
+## Date
+
+2025-01-02

package/skills/beads/resources/AGENTS.md

@@ -0,0 +1,62 @@
+# Agent Beads
+
+> Adapted from ACF beads skill
+
+**v0.40+**: First-class support for agent tracking via `type=agent` beads.
+
+## When to Use Agent Beads
+
+| Scenario | Agent Bead? | Why |
+|----------|-------------|-----|
+| Multi-agent orchestration | Yes | Track state, assign work via slots |
+| Single Claude session | No | Overkill—just use regular beads |
+| Long-running background agents | Yes | Heartbeats enable liveness detection |
+| Role-based agent systems | Yes | Role beads define agent capabilities |
+
+## Bead Types
+
+| Type | Purpose | Has Slots? |
+|------|---------|------------|
+| `agent` | AI agent tracking | Yes (hook, role) |
+| `role` | Role definitions for agents | No |
+
+Other types (`task`, `bug`, `feature`, `epic`) remain unchanged.
+
+## State Machine
+
+Agent beads track state for coordination:
+
+```
+idle → spawning → running/working → done → idle
+                       ↓
+                    stuck → (needs intervention)
+```
+
+**Key states**: `idle`, `spawning`, `running`, `working`, `stuck`, `done`, `stopped`, `dead`
+
+The `dead` state is set by Witness (monitoring system) via heartbeat timeout—agents don't set this themselves.
+
+## Slot Architecture
+
+Slots are named references from agent beads to other beads:
+
+| Slot | Cardinality | Purpose |
+|------|-------------|---------|
+| `hook` | 0..1 | Current work attached to agent |
+| `role` | 1 | Role definition bead (required) |
+
+**Why slots?** They enforce constraints (one work item at a time) and enable queries like "what is agent X working on?" or "which agent has this work?"
+
+## Monitoring Integration
+
+Agent beads enable:
+
+- **Witness System**: Monitors agent health via heartbeats
+- **State Coordination**: ZFC-compliant state machine for multi-agent systems
+- **Work Attribution**: Track which agent owns which work
+
+## CLI Reference
+
+Run `bd agent --help` for state/heartbeat/show commands.
+Run `bd slot --help` for set/clear/show commands.
+Run `bd create --help` for `--type=agent` and `--type=role` options.

package/skills/beads/resources/ASYNC_GATES.md

@@ -0,0 +1,168 @@
+# Async Gates for Workflow Coordination
+
+> Adapted from ACF beads skill
+
+`bd gate` provides async coordination primitives for cross-session and external-condition workflows. Gates are **wisps** (ephemeral issues) that block until a condition is met.
+
+---
+
+## Gate Types
+
+| Type | Await Syntax | Use Case |
+|------|--------------|----------|
+| Human | `human:<prompt>` | Cross-session human approval |
+| CI | `gh:run:<id>` | Wait for GitHub Actions completion |
+| PR | `gh:pr:<id>` | Wait for PR merge/close |
+| Timer | `timer:<duration>` | Deployment propagation delay |
+| Mail | `mail:<pattern>` | Wait for matching email |
+
+---
+
+## Creating Gates
+
+```bash
+# Human approval gate
+bd gate create --await human:deploy-approval \
+  --title "Approve production deploy" \
+  --timeout 4h
+
+# CI gate (GitHub Actions)
+bd gate create --await gh:run:123456789 \
+  --title "Wait for CI" \
+  --timeout 30m
+
+# PR merge gate
+bd gate create --await gh:pr:42 \
+  --title "Wait for PR approval" \
+  --timeout 24h
+
+# Timer gate (deployment propagation)
+bd gate create --await timer:15m \
+  --title "Wait for deployment propagation"
+```
+
+**Required options**:
+- `--await <spec>` — Gate condition (see types above)
+- `--timeout <duration>` — Recommended: prevents forever-open gates
+
+**Optional**:
+- `--title <text>` — Human-readable description
+- `--notify <recipients>` — Email/beads addresses to notify
+
+---
+
+## Monitoring Gates
+
+```bash
+bd gate list              # All open gates
+bd gate list --all        # Include closed
+bd gate show <gate-id>    # Details for specific gate
+bd gate eval              # Auto-close elapsed/completed gates
+bd gate eval --dry-run    # Preview what would close
+```
+
+**Auto-close behavior** (`bd gate eval`):
+- `timer:*` — Closes when duration elapsed
+- `gh:run:*` — Checks GitHub API, closes on success/failure
+- `gh:pr:*` — Checks GitHub API, closes on merge/close
+- `human:*` — Requires explicit `bd gate approve`
+
+---
+
+## Closing Gates
+
+```bash
+# Human gates require explicit approval
+bd gate approve <gate-id>
+bd gate approve <gate-id> --comment "Reviewed and approved by Steve"
+
+# Manual close (any gate)
+bd gate close <gate-id>
+bd gate close <gate-id> --reason "No longer needed"
+
+# Auto-close via evaluation
+bd gate eval
+```
+
+---
+
+## Best Practices
+
+1. **Always set timeouts**: Prevents forever-open gates
+   ```bash
+   bd gate create --await human:... --timeout 24h
+   ```
+
+2. **Clear titles**: Title should indicate what's being gated
+   ```bash
+   --title "Approve Phase 2: Core Implementation"
+   ```
+
+3. **Eval periodically**: Run at session start to close elapsed gates
+   ```bash
+   bd gate eval
+   ```
+
+4. **Clean up obsolete gates**: Close gates that are no longer needed
+   ```bash
+   bd gate close <id> --reason "superseded by new approach"
+   ```
+
+5. **Check before creating**: Avoid duplicate gates
+   ```bash
+   bd gate list | grep "spec-myfeature"
+   ```
+
+---
+
+## Gates vs Issues
+
+| Aspect | Gates (Wisp) | Issues |
+|--------|--------------|--------|
+| Persistence | Ephemeral (not synced) | Permanent (synced to git) |
+| Purpose | Block on external condition | Track work items |
+| Lifecycle | Auto-close when condition met | Manual close |
+| Visibility | `bd gate list` | `bd list` |
+| Use case | CI, approval, timers | Tasks, bugs, features |
+
+Gates are designed to be temporary coordination primitives—they exist only until their condition is satisfied.
+
+---
+
+## Troubleshooting
+
+### Gate won't close
+
+```bash
+# Check gate details
+bd gate show <gate-id>
+
+# For gh:run gates, verify the run exists
+gh run view <run-id>
+
+# Force close if stuck
+bd gate close <gate-id> --reason "manual override"
+```
+
+### Can't find gate ID
+
+```bash
+# List all gates (including closed)
+bd gate list --all
+
+# Search by title pattern
+bd gate list | grep "Phase 2"
+```
+
+### CI run ID detection fails
+
+```bash
+# Check GitHub CLI auth
+gh auth status
+
+# List runs manually
+gh run list --branch <branch>
+
+# Use specific workflow
+gh run list --workflow ci.yml --branch <branch>
+```