panopticon-cli 0.4.6 → 0.4.8

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>
+```