codexkit 1.0.0

package/.codex/skills/beads/references/BOUNDARIES.md

@@ -0,0 +1,219 @@
+# Boundaries: When to Use br vs TodoWrite
+
+Decision criteria for choosing between beads tools and TodoWrite.
+
+## The Core Question
+
+**"Could I resume this work after 2 weeks away?"**
+
+- If beads would help you resume → **use br**
+- If markdown skim would suffice → **TodoWrite is fine**
+
+## Decision Matrix
+
+### Use br for:
+
+**Multi-Session Work**
+
+- Strategic document development
+- Feature implementation across sessions
+- Bug investigation over time
+- Architecture design iterations
+
+**Complex Dependencies**
+
+- OAuth integration requiring DB, endpoints, frontend
+- Research with parallel investigation threads
+- Refactoring with dependencies between areas
+- Migration requiring sequential steps
+
+**Knowledge Work**
+
+- Architecture decisions requiring research
+- API design with multiple options
+- Performance optimization experiments
+- Documentation requiring system understanding
+
+**Side Quests**
+
+- Found better pattern during feature work
+- Noticed architectural issue while debugging
+- Identified improvement during code review
+- Edge case requiring research during tests
+
+**Multi-Agent Coordination**
+
+- Multiple agents editing same codebase
+- File locking needed
+- Cross-team communication
+
+### Use TodoWrite for:
+
+**Single-Session Tasks**
+
+- Implementing single function from spec
+- Fixing bug with known root cause
+- Adding unit tests for existing code
+- Updating documentation
+
+**Linear Execution**
+
+- Database migration with clear sequence
+- Deployment checklist
+- Code style cleanup
+- Dependency updates
+
+**Immediate Context**
+
+- User provides complete spec
+- Bug report with reproduction and fix
+- Refactoring with clear before/after
+- Config changes from preferences
+
+**Simple Tracking**
+
+- Breaking down implementation
+- Showing validation progress
+- Demonstrating systematic approach
+
+## Detailed Comparison
+
+| Aspect           | br CLI                            | TodoWrite              |
+| ---------------- | --------------------------------- | ---------------------- |
+| **Persistence**  | Git-backed, survives compaction   | Session-only           |
+| **Dependencies** | Graph-based, auto ready detection | Manual                 |
+| **File Locking** | Yes, prevents conflicts           | No                     |
+| **Multi-Agent**  | Yes, coordination tools           | No                     |
+| **Visibility**   | Background structure              | Visible in chat        |
+| **Best for**     | Complex, multi-session            | Simple, single-session |
+
+## Integration Patterns
+
+### Pattern 1: br as Strategic, TodoWrite as Tactical
+
+```
+br task: "Implement user authentication" (epic)
+  ├─ Child: "Create login endpoint"
+  ├─ Child: "Add JWT validation"  ← Currently working
+  └─ Child: "Implement logout"
+
+TodoWrite (for JWT validation):
+- [ ] Install JWT library
+- [ ] Create validation middleware
+- [ ] Add tests for expiry
+- [ ] Update docs
+```
+
+### Pattern 2: TodoWrite as Working Copy
+
+```
+Session start:
+- br ready gets "Add JWT validation"
+- br update <id> --status in_progress
+- Extract acceptance criteria into TodoWrite
+- Work through TodoWrite items
+- Update br notes as you learn
+- br close <id> when TodoWrite complete
+```
+
+### Pattern 3: Transition Mid-Session
+
+**From TodoWrite to br:**
+
+Trigger signals:
+
+- Discovering blockers or dependencies
+- Work won't complete this session
+- Finding side quests
+- Need to pause and resume later
+
+**How to transition:**
+
+```
+1. br create with current TodoWrite content
+2. Note: "Discovered multi-session work"
+3. Add dependencies as discovered
+4. Keep TodoWrite for current session
+5. Update br notes before session ends
+```
+
+## Common Mistakes
+
+### Mistake 1: TodoWrite for Multi-Session Work
+
+**What happens:**
+
+- Next session, forget what was done
+- Scroll history to reconstruct
+- Lose design decisions
+- Duplicate work
+
+**Solution:** Use br instead.
+
+### Mistake 2: br for Simple Linear Tasks
+
+**What happens:**
+
+- Overhead not justified
+- User can't see progress
+- Extra tool use for no benefit
+
+**Solution:** Use TodoWrite.
+
+### Mistake 3: Not Transitioning When Complexity Emerges
+
+**What happens:**
+
+- Start with TodoWrite
+- Discover blockers mid-way
+- Keep using TodoWrite despite poor fit
+- Lose context when session ends
+
+**Solution:** Transition to br when complexity appears.
+
+### Mistake 4: Creating Too Many br Issues
+
+**What happens:**
+
+- Every tiny task gets an issue
+- Database cluttered
+- Hard to find meaningful work
+
+**Solution:** Use 2-week test. Would br help after 2 weeks? If no, skip.
+
+## The Transition Point
+
+**Transition signals:**
+
+- "This is taking longer than expected"
+- "I've discovered a blocker"
+- "This needs more research"
+- "I should investigate X first"
+- "User might not continue today"
+- "Found three related issues"
+
+When you notice these: Create br issue, preserve context.
+
+## Summary Heuristics
+
+**Time horizon:**
+
+- Same session → TodoWrite
+- Multiple sessions → br
+
+**Dependency structure:**
+
+- Linear steps → TodoWrite
+- Blockers/prerequisites → br
+
+**Scope clarity:**
+
+- Well-defined → TodoWrite
+- Exploratory → br
+
+**Multi-agent:**
+
+- Single agent → Either
+- Multiple agents → br
+
+**When in doubt:** Use the 2-week test.

package/.codex/skills/beads/references/DEPENDENCIES.md

@@ -0,0 +1,124 @@
+# Dependency Types Guide
+
+Beads supports task dependencies for ordering work.
+
+## Overview
+
+Dependencies affect what work is "ready" - tasks with unmet dependencies won't appear in `br ready` results.
+
+## Creating Dependencies
+
+```bash
+br create --title "Implement API endpoint" --blocked-by setup-db
+# This task depends on setup-db completing first
+```
+
+## Dependency Patterns
+
+### Sequential Work
+
+```
+setup-db → implement-api → add-tests → deploy
+```
+
+Each task depends on the previous. `br ready` shows only the current step.
+
+### Parallel Then Merge
+
+```
+research-a ─┐
+research-b ─┼→ decision
+research-c ─┘
+```
+
+Multiple parallel tasks, then one that needs all of them.
+
+### Foundation First
+
+```
+setup ─┬→ feature-a
+       ├→ feature-b
+       └→ feature-c
+```
+
+One foundational task blocks multiple features.
+
+## Epic with Children
+
+```bash
+# Create epic
+br create --title "OAuth Integration" --type epic --priority 1
+# Returns: oauth-abc
+
+# Create children with parent
+br create --title "Setup credentials" --parent oauth-abc
+br create --title "Implement flow" --parent oauth-abc --blocked-by credentials
+br create --title "Add UI" --parent oauth-abc --blocked-by flow
+```
+
+## Automatic Unblocking
+
+When you close a task that's blocking others:
+
+```
+1. br close setup-db --reason "Schema created"
+2. Beads automatically updates: implement-api is now ready
+3. br ready returns implement-api
+4. No manual unblocking needed
+```
+
+## Common Mistakes
+
+### Using Dependencies for Preferences
+
+**Wrong:**
+
+```
+docs depends on feature  // "prefer to update docs after"
+```
+
+**Problem:** Documentation doesn't actually need feature complete.
+
+**Right:** Only use dependencies for actual blockers.
+
+### Wrong Direction
+
+**Wrong:**
+
+```bash
+br create --title "API" --blocked-by tests  # API depends on tests?
+```
+
+**Problem:** Usually tests depend on API, not the other way.
+
+**Right:** Think "X needs Y complete first" → X depends on Y.
+
+### Over-Using Dependencies
+
+**Problem:** Everything depends on everything. No parallel work possible.
+
+**Right:** Only add dependencies for actual technical blockers.
+
+## Decision Guide
+
+**Add dependency when:**
+
+- Task literally cannot start without other task complete
+- Code won't compile/run without prerequisite
+- Data/schema must exist first
+
+**Skip dependency when:**
+
+- Just a preference for order
+- Both can proceed independently
+- Just want to note relationship
+
+## Viewing Dependencies
+
+```bash
+br show <id>
+# Shows what blocks this task and what this task blocks
+
+br list --status open
+# Shows all open tasks, check dependencies in details
+```

package/.codex/skills/beads/references/EXAMPLES.md

@@ -0,0 +1,45 @@
+# Examples
+
+## Example 1: Standard Session
+
+```bash
+# 1. Find and claim work
+br ready
+br update auth-123 --status in_progress
+
+# 2. Get context
+br show auth-123
+
+# 3. Do the work...
+# [implementation]
+
+# 4. Complete and sync
+br close auth-123 --reason "Login form with validation, hooks for auth state"
+br sync --flush-only
+git add .beads/
+git commit -m "close auth-123"
+# RESTART SESSION
+```
+
+## Example 2: Discovered Work
+
+```bash
+# Working on task, found more work
+br create --title "Fix edge case in validation" --type bug --priority 1 \
+  --description "Empty strings bypass email check - discovered while implementing login"
+# Continue current task, new task tracked for later
+```
+
+## Example 3: Creating Dependencies
+
+```bash
+# Create tasks with dependencies
+br create --title "Setup database" --type task --priority 1
+# Returns: setup-db
+
+br create --title "Implement API" --type task --priority 2 --blocked-by setup-db
+# Returns: impl-api (blocked until setup-db closes)
+
+br create --title "Add tests" --type task --priority 2 --blocked-by impl-api
+# Returns: add-tests
+```

package/.codex/skills/beads/references/FILE_CLAIMING.md

@@ -0,0 +1,101 @@
+# File Path Claiming (Multi-Agent Safety)
+
+At multi-agent scale, agents editing the same files cause merge conflicts. File path claiming prevents this by making ownership explicit before any edit happens.
+
+## When to Use
+
+- **Single agent**: Optional — no conflicts possible
+- **2-10 agents**: Recommended for files touched by multiple tasks
+- **10+ agents**: Required — every file must be claimed before editing
+
+## The Claim/Edit/Release Cycle
+
+```bash
+# 1. CLAIM: Declare intent to edit before touching the file
+br reserve <bead-id> --files "src/auth/service.ts,src/auth/types.ts"
+# → Marks files as owned by this bead
+# → Other agents see the reservation and must wait
+
+# 2. EDIT: Make your changes
+# (edit files as normal)
+
+# 3. VERIFY: Run gates before releasing
+npm run typecheck && npm run lint
+
+# 4. CLOSE: Release ownership when done
+br close <bead-id> --reason "Auth service implemented. Gates passed."
+# → Ownership released automatically on close
+```
+
+## File Claiming Checklist
+
+- [ ] Check for conflicts: `br list --status in_progress --json | jq '.[].reserved_files'`
+- [ ] Reserve files before editing: `br reserve <id> --files "..."`
+- [ ] Run gates before closing: `npm run typecheck && npm run lint`
+- [ ] Close bead to release ownership
+
+## Checking for Conflicts Before Claiming
+
+Before claiming, check if another bead already owns the file:
+
+```bash
+# See all reserved files across active beads
+br list --status in_progress --json | jq '.[].reserved_files'
+
+# If conflict detected:
+# → Wait for the other bead to close
+# → Or coordinate with the agent owning that bead
+```
+
+## Claiming in Delegation Packets
+
+Workers MUST declare file claims in their delegation packet:
+
+```markdown
+# Delegation Packet
+
+- TASK: task-1 - Implement auth service
+- FILES TO CLAIM BEFORE EDITING:
+  - src/auth/service.ts
+  - src/auth/types.ts
+  - src/auth/middleware.ts
+- MUST NOT EDIT (owned by other tasks):
+  - src/db/schema.ts (owned by task-0)
+  - src/config.ts (owned by task-2)
+```
+
+## Conflict Resolution Protocol
+
+When two agents want the same file:
+
+| Scenario                             | Resolution                                      |
+| ------------------------------------ | ----------------------------------------------- |
+| File not claimed                     | Claim it and proceed                            |
+| File claimed by completed bead       | Safe to claim (no active owner)                 |
+| File claimed by in_progress bead     | Wait for bead to close, then claim              |
+| Urgent: same file, different workers | Escalate to lead agent to split the file change |
+
+## Anti-Pattern: Claiming After Editing
+
+```bash
+# WRONG — edit first, claim after → conflict already happened
+edit src/auth/service.ts
+br reserve bead-1 --files "src/auth/service.ts"
+
+# RIGHT — claim first, then edit
+br reserve bead-1 --files "src/auth/service.ts"
+edit src/auth/service.ts
+```
+
+## Quick Reference: File Claiming
+
+```
+BEFORE EDITING (multi-agent):
+  br reserve <id> --files "src/file.ts"
+
+CHECK OWNERSHIP:
+  br list --status in_progress --json | jq '.[].reserved_files'
+
+RELEASE:
+  br close <id> --reason "..."  ← auto-releases files
+```

package/.codex/skills/beads/references/GIT_SYNC.md

@@ -0,0 +1,25 @@
+# Git Sync
+
+## Manual Sync (Non-Invasive)
+
+**Important:** `br` never executes git commands. You must manually commit changes.
+
+```bash
+# Export changes to JSONL
+br sync --flush-only
+
+# Then manually commit
+git add .beads/
+git commit -m "sync beads"
+git push
+```
+
+**Use when**: End of session, before handoff, after major progress.
+
+## Cleanup Old Issues
+
+```bash
+br cleanup --days 7
+```
+
+Removes closed issues older than N days. Run weekly.

package/.codex/skills/beads/references/HIERARCHY.md

@@ -0,0 +1,71 @@
+# Hierarchical Structure: Epic → Task → Subtask
+
+Beads supports up to 3 levels of hierarchy using hierarchical IDs:
+
+```
+br-a3f8        (Epic - parent feature)
+├── br-a3f8.1  (Task - first child)
+├── br-a3f8.2  (Task - second child)
+│   ├── br-a3f8.2.1  (Subtask - child of .2)
+│   └── br-a3f8.2.2  (Subtask - child of .2)
+└── br-a3f8.3  (Task - third child)
+```
+
+## When to Decompose
+
+| Scenario                     | Structure                            |
+| ---------------------------- | ------------------------------------ |
+| Bug fix, config change       | Single bead                          |
+| Small feature (1-2 files)    | Single bead                          |
+| Feature crossing FE/BE       | Epic + tasks by domain               |
+| New system/service           | Epic + tasks by component            |
+| Multi-day work               | Epic + tasks for parallelization     |
+| Work needing multiple agents | Epic + tasks (agents claim children) |
+
+## Creating Hierarchical Beads
+
+```bash
+# Step 1: Create Epic (parent)
+br create --title "User Authentication System" --type epic --priority 1 \
+  --description "Complete auth with OAuth, sessions, and protected routes"
+# Returns: br-a3f8
+
+# Step 2: Create child tasks with parent
+br create --title "Database schema for auth" --type task --priority 2 \
+  --parent br-a3f8 --description "Create user and session tables"
+# Returns: br-a3f8.1  ← Hierarchical ID!
+
+# Step 3: Create dependent tasks
+br create --title "OAuth integration" --type task --priority 2 \
+  --parent br-a3f8 --blocked-by br-a3f8.1
+# Returns: br-a3f8.2
+```
+
+## Parallel Execution with Dependencies
+
+```
+br-a3f8.1 [Database] ──┬──> br-a3f8.2 [Backend] ──┐
+     (READY)           │                          │
+                       │                          ▼
+                       └──> br-a3f8.3 [Frontend]  br-a3f8.5 [Testing]
+                       │         │                     ▲
+                       └──> br-a3f8.4 [Docs] ──────────┘
+
+Parallel tracks:
+• Agent 1 (backend): .1 → .2
+• Agent 2 (frontend): wait for .1, then .3
+• Agent 3 (qa): wait for .2 and .3, then .5
+```
+
+**Key insight**: After br-a3f8.1 completes, .2, .3, and .4 all become READY simultaneously. Multiple agents can claim them in parallel.
+
+## Querying Hierarchy
+
+```bash
+# See all open issues
+br list --status open
+
+# See ready work (unblocked tasks)
+br ready
+# Returns tasks where all dependencies are closed
+```

package/.codex/skills/beads/references/MULTI_AGENT.md

@@ -0,0 +1,40 @@
+# Multi-Agent Coordination (Swarm Mode)
+
+For parallel execution with multiple subagents, use the **beads-bridge** skill:
+
+```typescript
+skill({ name: "beads-bridge" });
+```
+
+**beads-bridge** provides (via unified `swarm` tool):
+
+- `swarm({ operation: "sync" })` - Sync Beads tasks to Codex todos for subagent visibility
+- `swarm({ operation: "monitor" })` - Real-time progress tracking and visualization
+- `swarm({ operation: "plan" })` - Task classification and dependency analysis
+- `swarm({ operation: "delegate" })` - Create delegation packets for workers
+
+**When to use beads vs beads-bridge:**
+
+| Scenario                       | Use                              |
+| ------------------------------ | -------------------------------- |
+| Single agent, linear work      | `beads` skill only               |
+| Multiple agents in parallel    | `beads-bridge` + `beads`         |
+| Need subagents to see tasks    | `beads-bridge` (swarm sync push) |
+| Track worker progress visually | `beads-bridge` (swarm monitor)   |
+
+**Example swarm workflow:**
+
+```typescript
+// 1. Push beads to Codex todos (subagents can see via todoread)
+swarm({ operation: "sync", action: "push" });
+
+// 2. Spawn workers in parallel using Task tool
+Task({ subagent_type: "general", description: "Worker 1", prompt: "..." });
+Task({ subagent_type: "general", description: "Worker 2", prompt: "..." });
+
+// 3. Monitor progress
+swarm({ operation: "monitor", action: "render_block", team_name: "my-swarm" });
+
+// 4. Pull completed work back to beads
+swarm({ operation: "sync", action: "pull" });
+```