panopticon-cli 0.4.5 → 0.4.7

package/skills/beads/resources/BOUNDARIES.md

@@ -0,0 +1,469 @@
+# Boundaries: When to Use bd vs TodoWrite
+
+This reference provides detailed decision criteria for choosing between bd issue tracking and TodoWrite for task management.
+
+## Contents
+
+- [The Core Question](#the-core-question)
+- [Decision Matrix](#decision-matrix)
+  - [Use bd for](#use-bd-for): Multi-Session Work, Complex Dependencies, Knowledge Work, Side Quests, Project Memory
+  - [Use TodoWrite for](#use-todowrite-for): Single-Session Tasks, Linear Execution, Immediate Context, Simple Tracking
+- [Detailed Comparison](#detailed-comparison)
+- [Integration Patterns](#integration-patterns)
+  - Pattern 1: bd as Strategic, TodoWrite as Tactical
+  - Pattern 2: TodoWrite as Working Copy of bd
+  - Pattern 3: Transition Mid-Session
+- [Real-World Examples](#real-world-examples)
+  - Strategic Document Development, Simple Feature Implementation, Bug Investigation, Refactoring with Dependencies
+- [Common Mistakes](#common-mistakes)
+  - Using TodoWrite for multi-session work, using bd for simple tasks, not transitioning when complexity emerges, creating too many bd issues, never using bd
+- [The Transition Point](#the-transition-point)
+- [Summary Heuristics](#summary-heuristics)
+
+## The Core Question
+
+**"Could I resume this work after 2 weeks away?"**
+
+- If bd would help you resume → **use bd**
+- If markdown skim would suffice → **TodoWrite is fine**
+
+This heuristic captures the essential difference: bd provides structured context that persists across long gaps, while TodoWrite excels at immediate session tracking.
+
+## Decision Matrix
+
+### Use bd for:
+
+#### Multi-Session Work
+Work spanning multiple compaction cycles or days where context needs to persist.
+
+**Examples:**
+- Strategic document development requiring research across multiple sessions
+- Feature implementation split across several coding sessions
+- Bug investigation requiring experimentation over time
+- Architecture design evolving through multiple iterations
+
+**Why bd wins**: Issues capture context that survives compaction. Return weeks later and see full history, design decisions, and current status.
+
+#### Complex Dependencies
+Work with blockers, prerequisites, or hierarchical structure.
+
+**Examples:**
+- OAuth integration requiring database setup, endpoint creation, and frontend changes
+- Research project with multiple parallel investigation threads
+- Refactoring with dependencies between different code areas
+- Migration requiring sequential steps in specific order
+
+**Why bd wins**: Dependency graph shows what's blocking what. `bd ready` automatically surfaces unblocked work. No manual tracking required.
+
+#### Knowledge Work
+Tasks with fuzzy boundaries, exploration, or strategic thinking.
+
+**Examples:**
+- Architecture decision requiring research into frameworks and trade-offs
+- API design requiring research into multiple options
+- Performance optimization requiring measurement and experimentation
+- Documentation requiring understanding system architecture
+
+**Why bd wins**: `design` and `acceptance_criteria` fields capture evolving understanding. Issues can be refined as exploration reveals more information.
+
+#### Side Quests
+Exploratory work that might pause the main task.
+
+**Examples:**
+- During feature work, discover a better pattern worth exploring
+- While debugging, notice related architectural issue
+- During code review, identify potential improvement
+- While writing tests, find edge case requiring research
+
+**Why bd wins**: Create issue with `discovered-from` dependency, pause main work safely. Context preserved for both tracks. Resume either one later.
+
+#### Project Memory
+Need to resume work after significant time with full context.
+
+**Examples:**
+- Open source contributions across months
+- Part-time projects with irregular schedule
+- Complex features split across sprints
+- Research projects with long investigation periods
+
+**Why bd wins**: Git-backed database persists indefinitely. All context, decisions, and history available on resume. No relying on conversation scrollback or markdown files.
+
+---
+
+### Use TodoWrite for:
+
+#### Single-Session Tasks
+Work that completes within current conversation.
+
+**Examples:**
+- Implementing a single function based on clear spec
+- Fixing a bug with known root cause
+- Adding unit tests for existing code
+- Updating documentation for recent changes
+
+**Why TodoWrite wins**: Simple checklist is perfect for linear execution. No need for persistence or dependencies. Clear completion within session.
+
+#### Linear Execution
+Straightforward step-by-step tasks with no branching.
+
+**Examples:**
+- Database migration with clear sequence
+- Deployment checklist
+- Code style cleanup across files
+- Dependency updates following upgrade guide
+
+**Why TodoWrite wins**: Steps are predetermined and sequential. No discovery, no blockers, no side quests. Just execute top to bottom.
+
+#### Immediate Context
+All information already in conversation.
+
+**Examples:**
+- User provides complete spec and asks for implementation
+- Bug report with reproduction steps and fix approach
+- Refactoring request with clear before/after vision
+- Config changes based on user preferences
+
+**Why TodoWrite wins**: No external context to track. Everything needed is in current conversation. TodoWrite provides user visibility, nothing more needed.
+
+#### Simple Tracking
+Just need a checklist to show progress to user.
+
+**Examples:**
+- Breaking down implementation into visible steps
+- Showing validation workflow progress
+- Demonstrating systematic approach
+- Providing reassurance work is proceeding
+
+**Why TodoWrite wins**: User wants to see thinking and progress. TodoWrite is visible in conversation. bd is invisible background structure.
+
+---
+
+## Detailed Comparison
+
+| Aspect | bd | TodoWrite |
+|--------|-----|-----------|
+| **Persistence** | Git-backed, survives compaction | Session-only, lost after conversation |
+| **Dependencies** | Graph-based, automatic ready detection | Manual, no automatic tracking |
+| **Discoverability** | `bd ready` surfaces work | Scroll conversation for todos |
+| **Complexity** | Handles nested epics, blockers | Flat list only |
+| **Visibility** | Background structure, not in conversation | Visible to user in chat |
+| **Setup** | Requires `.beads/` directory in project | Always available |
+| **Best for** | Complex, multi-session, explorative | Simple, single-session, linear |
+| **Context capture** | Design notes, acceptance criteria, links | Just task description |
+| **Evolution** | Issues can be updated, refined over time | Static once written |
+| **Audit trail** | Full history of changes | Only visible in conversation |
+
+## Integration Patterns
+
+bd and TodoWrite can coexist effectively in a session. Use both strategically.
+
+### Pattern 1: bd as Strategic, TodoWrite as Tactical
+
+**Setup:**
+- bd tracks high-level issues and dependencies
+- TodoWrite tracks current session's execution steps
+
+**Example:**
+```
+bd issue: "Implement user authentication" (epic)
+  ├─ Child issue: "Create login endpoint"
+  ├─ Child issue: "Add JWT token validation"  ← Currently working on this
+  └─ Child issue: "Implement logout"
+
+TodoWrite (for JWT validation):
+- [ ] Install JWT library
+- [ ] Create token validation middleware
+- [ ] Add tests for token expiry
+- [ ] Update API documentation
+```
+
+**When to use:**
+- Complex features with clear implementation steps
+- User wants to see current progress but larger context exists
+- Multi-session work currently in single-session execution phase
+
+### Pattern 2: TodoWrite as Working Copy of bd
+
+**Setup:**
+- Start with bd issue containing full context
+- Create TodoWrite checklist from bd issue's acceptance criteria
+- Update bd as TodoWrite items complete
+
+**Example:**
+```
+Session start:
+- Check bd: "issue-auth-42: Add JWT token validation" is ready
+- Extract acceptance criteria into TodoWrite
+- Mark bd issue as in_progress
+- Work through TodoWrite items
+- Update bd design notes as you learn
+- When TodoWrite completes, close bd issue
+```
+
+**When to use:**
+- bd issue is ready but execution is straightforward
+- User wants visible progress tracking
+- Need structured approach to larger issue
+
+### Pattern 3: Transition Mid-Session
+
+**From TodoWrite to bd:**
+
+Recognize mid-execution that work is more complex than anticipated.
+
+**Trigger signals:**
+- Discovering blockers or dependencies
+- Realizing work won't complete this session
+- Finding side quests or related issues
+- Needing to pause and resume later
+
+**How to transition:**
+```
+1. Create bd issue with current TodoWrite content
+2. Note: "Discovered this is multi-session work during implementation"
+3. Add dependencies as discovered
+4. Keep TodoWrite for current session
+5. Update bd issue before session ends
+6. Next session: resume from bd, create new TodoWrite if needed
+```
+
+**From bd to TodoWrite:**
+
+Rare, but happens when bd issue turns out simpler than expected.
+
+**Trigger signals:**
+- All context already clear
+- No dependencies discovered
+- Can complete within session
+- User wants execution visibility
+
+**How to transition:**
+```
+1. Keep bd issue for historical record
+2. Create TodoWrite from issue description
+3. Execute via TodoWrite
+4. Close bd issue when done
+5. Note: "Completed in single session, simpler than expected"
+```
+
+## Real-World Examples
+
+### Example 1: Database Migration Planning
+
+**Scenario**: Planning migration from MySQL to PostgreSQL for production application.
+
+**Why bd**:
+- Multi-session work across days/weeks
+- Fuzzy boundaries - scope emerges through investigation
+- Side quests - discover schema incompatibilities requiring refactoring
+- Dependencies - can't migrate data until schema validated
+- Project memory - need to resume after interruptions
+
+**bd structure**:
+```
+db-epic: "Migrate production database to PostgreSQL"
+  ├─ db-1: "Audit current MySQL schema and queries"
+  ├─ db-2: "Research PostgreSQL equivalents for MySQL features" (blocks schema design)
+  ├─ db-3: "Design PostgreSQL schema with type mappings"
+  └─ db-4: "Create migration scripts and test data integrity" (blocked by db-3)
+```
+
+**TodoWrite role**: None initially. Might use TodoWrite for single-session testing sprints once migration scripts ready.
+
+### Example 2: Simple Feature Implementation
+
+**Scenario**: Add logging to existing endpoint based on clear specification.
+
+**Why TodoWrite**:
+- Single session work
+- Linear execution - add import, call logger, add test
+- All context in user message
+- Completes within conversation
+
+**TodoWrite**:
+```
+- [ ] Import logging library
+- [ ] Add log statements to endpoint
+- [ ] Add test for log output
+- [ ] Run tests
+```
+
+**bd role**: None. Overkill for straightforward task.
+
+### Example 3: Bug Investigation
+
+**Initial assessment**: Seems simple, try TodoWrite first.
+
+**TodoWrite**:
+```
+- [ ] Reproduce bug
+- [ ] Identify root cause
+- [ ] Implement fix
+- [ ] Add regression test
+```
+
+**What actually happens**: Reproducing bug reveals it's intermittent. Root cause investigation shows multiple potential issues. Needs time to investigate.
+
+**Transition to bd**:
+```
+Create bd issue: "Fix intermittent auth failure in production"
+  - Description: Initially seemed simple but reproduction shows complex race condition
+  - Design: Three potential causes identified, need to test each
+  - Created issues for each hypothesis with discovered-from dependency
+
+Pause for day, resume next session from bd context
+```
+
+### Example 4: Refactoring with Dependencies
+
+**Scenario**: Extract common validation logic from three controllers.
+
+**Why bd**:
+- Dependencies - must extract before modifying callers
+- Multi-file changes need coordination
+- Potential side quest - might discover better pattern during extraction
+- Need to track which controllers updated
+
+**bd structure**:
+```
+refactor-1: "Create shared validation module"
+  → blocks refactor-2, refactor-3, refactor-4
+
+refactor-2: "Update auth controller to use shared validation"
+refactor-3: "Update user controller to use shared validation"
+refactor-4: "Update payment controller to use shared validation"
+```
+
+**TodoWrite role**: Could use TodoWrite for individual controller updates as implementing.
+
+**Why this works**: bd ensures you don't forget to update a controller. `bd ready` shows next available work. Dependencies prevent starting controller update before extraction complete.
+
+## Common Mistakes
+
+### Mistake 1: Using TodoWrite for Multi-Session Work
+
+**What happens**:
+- Next session, forget what was done
+- Scroll conversation history to reconstruct
+- Lose design decisions made during implementation
+- Start over or duplicate work
+
+**Solution**: Create bd issue instead. Persist context across sessions.
+
+### Mistake 2: Using bd for Simple Linear Tasks
+
+**What happens**:
+- Overhead of creating issue not justified
+- User can't see progress in conversation
+- Extra tool use for no benefit
+
+**Solution**: Use TodoWrite. It's designed for exactly this case.
+
+### Mistake 3: Not Transitioning When Complexity Emerges
+
+**What happens**:
+- Start with TodoWrite for "simple" task
+- Discover blockers and dependencies mid-way
+- Keep using TodoWrite despite poor fit
+- Lose context when conversation ends
+
+**Solution**: Transition to bd when complexity signal appears. Not too late mid-session.
+
+### Mistake 4: Creating Too Many bd Issues
+
+**What happens**:
+- Every tiny task gets an issue
+- Database cluttered with trivial items
+- Hard to find meaningful work in `bd ready`
+
+**Solution**: Reserve bd for work that actually benefits from persistence. Use "2 week test" - would bd help resume after 2 weeks? If no, skip it.
+
+### Mistake 5: Never Using bd Because TodoWrite is Familiar
+
+**What happens**:
+- Multi-session projects become markdown swamps
+- Lose track of dependencies and blockers
+- Can't resume work effectively
+- Rotten half-implemented plans
+
+**Solution**: Force yourself to use bd for next multi-session project. Experience the difference in organization and resumability.
+
+### Mistake 6: Always Asking Before Creating Issues (or Never Asking)
+
+**When to create directly** (no user question needed):
+- **Bug reports**: Clear scope, specific problem ("Found: auth doesn't check profile permissions")
+- **Research tasks**: Investigative work ("Research workaround for Slides export")
+- **Technical TODOs**: Discovered during implementation ("Add validation to form handler")
+- **Side quest capture**: Discoveries that need tracking ("Issue: MCP can't read Shared Drive files")
+
+**Why create directly**: Asking slows discovery capture. User expects proactive issue creation for clear-cut problems.
+
+**When to ask first** (get user input):
+- **Strategic work**: Fuzzy boundaries, multiple valid approaches ("Should we implement X or Y pattern?")
+- **Potential duplicates**: Might overlap with existing work
+- **Large epics**: Multiple approaches, unclear scope ("Plan migration strategy")
+- **Major scope changes**: Changing direction of existing issue
+
+**Why ask**: Ensures alignment on fuzzy work, prevents duplicate effort, clarifies scope before investment.
+
+**Rule of thumb**: If you can write a clear, specific issue title and description in one sentence, create directly. If you need user input to clarify the work, ask first.
+
+**Examples**:
+- ✅ Create directly: "workspace MCP: Google Doc → .docx export fails with UTF-8 encoding error"
+- ✅ Create directly: "Research: Workarounds for reading Google Slides from Shared Drives"
+- ❓ Ask first: "Should we refactor the auth system now or later?" (strategic decision)
+- ❓ Ask first: "I found several data validation issues, should I file them all?" (potential overwhelming)
+
+## The Transition Point
+
+Most work starts with an implicit mental model:
+
+**"This looks straightforward"** → TodoWrite
+
+**As work progresses:**
+
+✅ **Stays straightforward** → Continue with TodoWrite, complete in session
+
+⚠️ **Complexity emerges** → Transition to bd, preserve context
+
+The skill is recognizing the transition point:
+
+**Transition signals:**
+- "This is taking longer than expected"
+- "I've discovered a blocker"
+- "This needs more research"
+- "I should pause this and investigate X first"
+- "The user might not be available to continue today"
+- "I found three related issues while working on this"
+
+**When you notice these signals**: Create bd issue, preserve context, work from structured foundation.
+
+## Summary Heuristics
+
+Quick decision guides:
+
+**Time horizon:**
+- Same session → TodoWrite
+- Multiple sessions → bd
+
+**Dependency structure:**
+- Linear steps → TodoWrite
+- Blockers/prerequisites → bd
+
+**Scope clarity:**
+- Well-defined → TodoWrite
+- Exploratory → bd
+
+**Context complexity:**
+- Conversation has everything → TodoWrite
+- External context needed → bd
+
+**User interaction:**
+- User watching progress → TodoWrite visible in chat
+- Background work → bd invisible structure
+
+**Resume difficulty:**
+- Easy from markdown → TodoWrite
+- Need structured history → bd
+
+When in doubt: **Use the 2-week test**. If you'd struggle to resume this work after 2 weeks without bd, use bd.

package/skills/beads/resources/CHEMISTRY_PATTERNS.md

@@ -0,0 +1,197 @@
+# Chemistry Patterns
+
+> Adapted from ACF beads skill
+
+Beads uses a chemistry metaphor for work templates. This guide covers when and how to use each phase.
+
+## Phase Transitions
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    PROTO (Solid)                            │
+│              Frozen template, reusable pattern              │
+│                    .beads/ with template label              │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+          ┌───────────────┼───────────────┐
+          │               │               │
+          ▼               │               ▼
+┌─────────────────┐       │       ┌─────────────────┐
+│   MOL (Liquid)  │       │       │  WISP (Vapor)   │
+│   bd pour       │       │       │  bd wisp create │
+│                 │       │       │                 │
+│  Persistent     │       │       │  Ephemeral      │
+│  .beads/        │       │       │  .beads-wisp/   │
+│  Git synced     │       │       │  Gitignored     │
+└────────┬────────┘       │       └────────┬────────┘
+         │                │                │
+         │                │        ┌───────┴───────┐
+         │                │        │               │
+         ▼                │        ▼               ▼
+   ┌──────────┐           │   ┌─────────┐    ┌─────────┐
+   │  CLOSE   │           │   │ SQUASH  │    │  BURN   │
+   │ normally │           │   │ → digest│    │ → gone  │
+   └──────────┘           │   └─────────┘    └─────────┘
+                          │
+                          ▼
+                  ┌───────────────┐
+                  │   DISTILL     │
+                  │ Extract proto │
+                  │ from ad-hoc   │
+                  │ epic          │
+                  └───────────────┘
+```
+
+## Decision Tree: Mol vs Wisp
+
+```
+Will this work be referenced later?
+│
+├─ YES → Does it need audit trail / git history?
+│        │
+│        ├─ YES → MOL (bd pour)
+│        │        Examples: Features, bugs, specs
+│        │
+│        └─ NO  → Could go either way
+│                 Consider: Will someone else see this?
+│                 │
+│                 ├─ YES → MOL
+│                 └─ NO  → WISP (then squash if valuable)
+│
+└─ NO  → WISP (bd wisp create)
+         Examples: Grooming, health checks, scratch work
+         End state: burn (no value) or squash (capture learnings)
+```
+
+## Quick Reference
+
+| Scenario | Use | Command | End State |
+|----------|-----|---------|-----------|
+| New feature work | Mol | `bd pour spec` | Close normally |
+| Bug fix | Mol | `bd pour bug` | Close normally |
+| Grooming session | Wisp | `bd wisp create grooming` | Squash → digest |
+| Code review | Wisp | `bd wisp create review` | Squash findings |
+| Research spike | Wisp | `bd wisp create spike` | Squash or burn |
+| Session health check | Wisp | `bd wisp create health` | Burn |
+| Agent coordination | Wisp | `bd wisp create coordinator` | Burn |
+
+## Common Patterns
+
+### Pattern 1: Grooming Wisp
+
+Use for periodic backlog maintenance.
+
+```bash
+# Start grooming
+bd wisp create grooming --var date="2025-01-02"
+
+# Work through checklist (stale, duplicates, verification)
+# Track findings in wisp notes
+
+# End: capture summary
+bd mol squash <wisp-id>  # Creates digest: "Closed 3, added 5 relationships"
+```
+
+**Why wisp?** Grooming is operational—you don't need permanent issues for "reviewed stale items."
+
+### Pattern 2: Code Review Wisp
+
+Use for PR review checklists.
+
+```bash
+# Start review
+bd wisp create pr-review --var pr="123" --var repo="myproject"
+
+# Track review findings (security, performance, style)
+# Each finding is a child issue in the wisp
+
+# End: promote real issues, discard noise
+bd mol squash <wisp-id>  # Creates permanent issues for real findings
+```
+
+**Why wisp?** Review checklists are ephemeral. Only actual findings become permanent issues.
+
+### Pattern 3: Research Spike Wisp
+
+Use for time-boxed exploration.
+
+```bash
+# Start spike (2 hour timebox)
+bd wisp create spike --var topic="GraphQL pagination"
+
+# Explore, take notes in wisp issues
+# Track sources, findings, dead ends
+
+# End: decide outcome
+bd mol squash <wisp-id>  # If valuable → creates research summary issue
+# OR
+bd mol burn <wisp-id>    # If dead end → no trace
+```
+
+**Why wisp?** Research might lead nowhere. Don't pollute the database with abandoned explorations.
+
+## Commands Reference
+
+### Creating Work
+
+```bash
+# Persistent mol (solid → liquid)
+bd pour <proto>                    # Synced to git
+bd pour <proto> --var key=value
+
+# Ephemeral wisp (solid → vapor)
+bd wisp create <proto>             # Not synced
+bd wisp create <proto> --var key=value
+```
+
+### Ending Work
+
+```bash
+# Mol: close normally
+bd close <mol-id>
+
+# Wisp: squash (condense to digest)
+bd mol squash <wisp-id>            # Creates permanent digest issue
+
+# Wisp: burn (evaporate, no trace)
+bd mol burn <wisp-id>              # Deletes with no record
+```
+
+### Managing
+
+```bash
+# List wisps
+bd wisp list
+
+# Garbage collect orphaned wisps
+bd wisp gc
+
+# View proto/mol structure
+bd mol show <id>
+
+# List available protos
+bd mol catalog
+```
+
+## Storage Locations
+
+| Type | Location | Git Behavior |
+|------|----------|--------------|
+| Proto | `.beads/` | Synced (template label) |
+| Mol | `.beads/` | Synced |
+| Wisp | `.beads-wisp/` | Gitignored |
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Create mol for one-time diagnostic | Use wisp, then burn |
+| Create wisp for real feature work | Use mol (needs audit trail) |
+| Burn wisp with valuable findings | Squash first (captures digest) |
+| Let wisps accumulate | Burn or squash at session end |
+| Create ad-hoc epics for repeatable patterns | Distill into proto |
+
+## Related Resources
+
+- [MOLECULES.md](MOLECULES.md) — Proto definitions
+- [WORKFLOWS.md](WORKFLOWS.md) — General beads workflows