codexkit 1.0.0

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

@@ -0,0 +1,177 @@
+# Making Tasks Resumable Across Sessions
+
+## When Resumability Matters
+
+**Use enhanced notes for:**
+
+- Multi-session features with API integration
+- Complex algorithms requiring code examples
+- Features with specific output format requirements
+- Work with undocumented APIs
+
+**Skip for:**
+
+- Simple bug fixes with clear scope
+- Well-understood patterns (CRUD, etc.)
+- Single-session tasks
+- Work with obvious criteria
+
+**The test:** Would a fresh agent (or you after 2 weeks) struggle to resume from the notes alone? If yes, add detail.
+
+## Anatomy of Resumable Notes
+
+### Minimal (Always Include)
+
+```
+COMPLETED: What's done
+IN PROGRESS: Current state
+NEXT: Concrete next step
+```
+
+### Enhanced (Complex Work)
+
+````
+COMPLETED: Specific deliverables
+IN PROGRESS: Current state + what's working
+NEXT: Concrete next step (not "continue")
+BLOCKERS: What's preventing progress
+KEY DECISIONS: Important context with rationale
+
+WORKING CODE:
+```python
+# Tested code that works
+result = api.query(fields='importFormats')
+# Returns: {'text/markdown': ['application/vnd.google-apps.document']}
+````
+
+DESIRED OUTPUT:
+
+```markdown
+# Example of what output should look like
+
+Actual structure, not just "return markdown"
+```
+
+````
+
+## Example: Before vs After
+
+### Not Resumable
+
+```
+Title: Add dynamic capabilities
+Notes: Working on it. Made some progress.
+````
+
+**Problem:** Future agent doesn't know:
+
+- Which API endpoints to call
+- What responses look like
+- What format to return
+
+### Resumable
+
+````
+Title: Add dynamic capabilities resources
+
+Notes:
+COMPLETED: API connection verified. Query working.
+IN PROGRESS: Formatting response as markdown.
+NEXT: Add caching for API responses.
+
+WORKING CODE:
+```python
+service = build('drive', 'v3', credentials=creds)
+about = service.about().get(fields='importFormats').execute()
+# Returns dict with 49 entries
+````
+
+DESIRED OUTPUT:
+
+```markdown
+# Drive Import Formats
+
+- **text/markdown** → Google Docs
+- text/plain → Google Docs
+```
+
+KEY DECISION: Using live API query because text/markdown support (July 2024) not in static docs.
+
+```
+
+**Result:** Fresh agent can:
+1. See working API code
+2. Understand response structure
+3. Know desired output format
+4. Implement with context
+
+## When to Add Detail
+
+**During task creation:**
+- Already have working code? Include it.
+- Clear output format? Show example.
+
+**During work:**
+- Got API working? Add to notes.
+- Discovered important context? Document it.
+- Made key decision? Explain rationale.
+
+**Session end:**
+- If resuming will be hard, add implementation guide.
+- If obvious, skip it.
+
+## Anti-Patterns
+
+### Over-Documenting Simple Work
+
+```
+
+Title: Fix typo in README
+Notes: IMPLEMENTATION GUIDE
+WORKING CODE: Open README.md, change "teh" to "the"...
+
+```
+
+**Problem:** Wastes tokens on obvious work.
+
+### Vague Progress
+
+```
+
+Notes: Made progress. Will continue later.
+
+```
+
+**Problem:** No context for resumption.
+
+### Raw Data Dumps
+
+```
+
+API RESPONSE:
+{giant unformatted JSON blob spanning 100 lines}
+
+```
+
+**Problem:** Hard to read. Extract relevant parts.
+
+### Right Balance
+
+```
+
+API returns dict with 49 entries. Examples:
+
+- 'text/markdown': ['application/vnd.google-apps.document']
+- 'text/plain': ['application/vnd.google-apps.document']
+
+```
+
+## The Principle
+
+Help your future self (or next agent) resume without rediscovering everything.
+
+Write notes as if explaining to someone with:
+- Zero conversation context
+- No memory of previous sessions
+- Only the task description and notes
+```

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

@@ -0,0 +1,61 @@
+# Session Start Protocol
+
+**Every session, follow these steps:**
+
+## Session Start Checklist
+
+- [ ] Run `br ready` to find unblocked work
+- [ ] If none, run `br list --status open` to see all open tasks
+- [ ] Claim the task: `br update <id> --status in_progress`
+- [ ] Load context: `br show <id>`
+
+## Step 1: Find Ready Work
+
+```bash
+br ready
+```
+
+Returns highest priority task with no blockers.
+
+If no tasks returned, check all open work:
+
+```bash
+br list --status open
+```
+
+## Step 2: Claim Task
+
+```bash
+br update <id> --status in_progress
+```
+
+## Step 3: Get Full Context
+
+```bash
+br show <id>
+```
+
+Shows full description, dependencies, notes, history.
+
+## Step 4: Do the Work
+
+Implement the task, adding notes as you learn.
+
+## Step 5: Complete and Sync
+
+```bash
+br close <id> --reason "Implemented auth with JWT tokens"
+br sync --flush-only
+git add .beads/
+git commit -m "sync beads"
+# RESTART SESSION - fresh context
+```
+
+Always restart session after closing a task. One task per session.
+
+## Session End Checklist
+
+- [ ] Close the bead with a clear reason: `br close <id> --reason "..."`
+- [ ] Sync Beads to JSONL: `br sync --flush-only`
+- [ ] Commit `.beads/` changes manually
+- [ ] Restart session (fresh context)

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

@@ -0,0 +1,38 @@
+# Task Creation
+
+## When to Create Tasks
+
+Create tasks when:
+
+- User mentions tracking work across sessions
+- User says "we should fix/build/add X"
+- Work has dependencies or blockers
+- Discovered work while implementing (>2 min effort)
+
+## Basic Task Creation
+
+```bash
+br create --title "Fix authentication bug" --priority 0 --type bug
+# Priority: 0=critical, 1=high, 2=normal, 3=low, 4=backlog
+# Types: task, bug, feature, epic, chore
+```
+
+## With Description
+
+```bash
+br create --title "Implement OAuth" --type feature --priority 1 \
+  --description "Add OAuth2 support for Google, GitHub. Use passport.js."
+```
+
+## Epic with Children
+
+```bash
+# Create parent epic
+br create --title "Epic: OAuth Implementation" --priority 0 --type epic
+# Returns: oauth-abc
+
+# Create child tasks with parent
+br create --title "Research OAuth providers" --priority 1 --parent oauth-abc
+br create --title "Implement auth endpoints" --priority 1 --parent oauth-abc
+br create --title "Add frontend login UI" --priority 2 --parent oauth-abc
+```

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

@@ -0,0 +1,38 @@
+# Error Handling
+
+## Common Issues
+
+**No ready tasks**
+
+- Run `br list --status open` to see all tasks
+- Some may be blocked - check dependencies with `br show <id>`
+
+**Sync failures**
+
+- Run `br doctor` to repair database
+- Check git remote access
+
+## Database Lock / WAL Conflicts
+
+**Symptoms:**
+
+- `SQLITE_BUSY` or `SQLITE_LOCKED` errors when reading beads
+- Stale `.beads/beads.db-wal` or `.beads/beads.db-journal` files after agent crash
+
+**Cause:**
+Agent interruption during bead operations can leave WAL/journal files in an inconsistent state.
+
+**Fix:**
+
+1. Ensure no agents are actively writing to beads.db
+2. Remove stale lock files:
+   ```bash
+   rm -f .beads/beads.db-wal .beads/beads.db-journal
+   ```
+3. Run `br sync --flush-only` to rebuild from JSONL source of truth
+4. Verify: `br ready` should work without errors
+
+**Prevention:**
+
+- The memory plugin now retries bead.db reads automatically (3 attempts, 500ms delay)
+- If persistent, check for zombie agent processes: `ps aux | grep codex`

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

@@ -0,0 +1,226 @@
+# Workflows and Checklists
+
+Detailed step-by-step workflows for common beads usage patterns.
+
+**Note:** `br` (beads_rust) is non-invasive and never executes git commands. After `br sync --flush-only`, you must manually run `git add .beads/ && git commit`.
+
+## Session Start Workflow
+
+**Every session when beads is available:**
+
+```
+Session Start:
+- [ ] br ready to find unblocked work
+- [ ] br update <id> --status in_progress to claim
+- [ ] If none ready, br list --status open
+- [ ] br show <id> for full context
+- [ ] Begin work
+```
+
+## Compaction Survival
+
+**Critical**: After compaction, conversation history is deleted but beads state persists.
+
+**Post-compaction recovery:**
+
+```
+After Compaction:
+- [ ] br list --status in_progress to see active work
+- [ ] br show <id> for each in_progress task
+- [ ] Read notes: COMPLETED, IN PROGRESS, BLOCKERS, KEY DECISIONS
+- [ ] Reconstruct TodoWrite from notes if needed
+```
+
+**Writing notes for compaction survival:**
+
+**Good note (enables recovery):**
+
+```
+COMPLETED: User auth - JWT tokens with 1hr expiry, refresh endpoint.
+IN PROGRESS: Password reset flow. Email service working.
+NEXT: Add rate limiting to reset endpoint.
+KEY DECISION: Using bcrypt 12 rounds per OWASP.
+```
+
+**Bad note:**
+
+```
+Working on auth. Made some progress.
+```
+
+## Discovery Workflow
+
+**When encountering new work during implementation:**
+
+```
+Discovery:
+- [ ] Notice bug, improvement, or follow-up
+- [ ] Assess: blocker or deferrable?
+- [ ] br create --title "..." --type bug --priority 1
+- [ ] If blocker: pause and switch
+- [ ] If deferrable: continue current work
+```
+
+## Epic Planning
+
+**For complex multi-step features, think in Ready Fronts.**
+
+A **Ready Front** is the set of tasks with all dependencies satisfied.
+
+**Walk backward from goal:**
+
+```
+"What's the final deliverable?"
+  ↓
+"Integration tests passing" → task-integration
+  ↓
+"What does that need?"
+  ↓
+"Streaming support" → task-streaming
+"Header display" → task-header
+  ↓
+"What do those need?"
+  ↓
+"Message rendering" → task-messages
+  ↓
+"Buffer layout" → task-buffer (foundation)
+```
+
+**Example: OAuth Integration**
+
+```bash
+# Create epic
+br create --title "OAuth integration" --type epic --priority 1
+
+# Walk backward: What does OAuth need?
+br create --title "Login/logout endpoints" --parent oauth-abc
+br create --title "Token storage and refresh" --parent oauth-abc
+br create --title "Authorization code flow" --parent oauth-abc
+br create --title "OAuth client credentials" --parent oauth-abc  # foundation
+```
+
+## Side Quest Handling
+
+```
+Side Quest:
+- [ ] During main work, discover problem
+- [ ] br create for side quest
+- [ ] Assess: blocker or deferrable?
+- [ ] If blocker: switch to side quest
+- [ ] If deferrable: note it, continue main work
+```
+
+## Session Handoff
+
+**At Session End:**
+
+```
+Session End:
+- [ ] Work reaching stopping point
+- [ ] Update notes with COMPLETED/IN PROGRESS/NEXT
+- [ ] br close <id> --reason "..." if task complete
+- [ ] Otherwise leave in_progress with notes
+- [ ] br sync --flush-only
+- [ ] git add .beads/ && git commit -m "session end"
+- [ ] RESTART SESSION
+```
+
+**At Session Start:**
+
+```
+Session Start with in_progress:
+- [ ] br list --status in_progress
+- [ ] br show <id> for each
+- [ ] Read notes field
+- [ ] Continue from notes context
+```
+
+## Unblocking Work
+
+**When ready list is empty:**
+
+```
+Unblocking:
+- [ ] br list --status open to see all tasks
+- [ ] Identify blocked tasks and their blockers
+- [ ] Work on blockers first
+- [ ] Closing blocker unblocks dependent work
+```
+
+## Integration with TodoWrite
+
+**Using both tools:**
+
+```
+Hybrid:
+- [ ] br ready to find high-level task
+- [ ] br update <id> --status in_progress
+- [ ] Create TodoWrite from acceptance criteria
+- [ ] Work through TodoWrite items
+- [ ] Update br notes as you learn
+- [ ] When TodoWrite complete, br close <id>
+```
+
+**Why hybrid**: br provides persistent structure, TodoWrite provides visible progress.
+
+## Common Patterns
+
+### Systematic Exploration
+
+```
+1. Create research task
+2. Update notes with findings
+3. br create for discoveries
+4. Close research with conclusion
+```
+
+### Bug Investigation
+
+```
+1. Create bug task
+2. Reproduce: note steps
+3. Investigate: track hypotheses in notes
+4. Fix: implement solution
+5. Close with root cause explanation
+```
+
+### Refactoring with Dependencies
+
+```
+1. Create tasks for each step
+2. Work through in dependency order
+3. br ready shows next step
+4. Each completion unblocks next
+```
+
+## Checklist Templates
+
+### Starting Any Session
+
+```
+- [ ] br ready
+- [ ] br update <id> --status in_progress
+- [ ] br show <id> for context
+- [ ] Begin work
+```
+
+### Creating Tasks During Work
+
+```
+- [ ] Notice new work needed
+- [ ] br create --title "..." with clear title
+- [ ] Add context in description
+- [ ] Assess blocker vs deferrable
+```
+
+### Completing Work
+
+```
+- [ ] Implementation done
+- [ ] Tests passing
+- [ ] br close <id> --reason "..."
+- [ ] br sync --flush-only
+- [ ] git add .beads/ && git commit
+- [ ] br ready for next work
+- [ ] RESTART SESSION
+```