codexkit 1.0.0

package/.codex/skills/beads-bridge/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: beads-bridge
+description: >
+  Multi-agent task coordination using br (beads_rust) and Codex tools. Use when work spans multiple sessions,
+  has dependencies, needs file locking, or requires agent coordination. Covers claim/reserve/done cycle,
+  dependency management, hierarchical decomposition, and session protocols.
+version: "2.0.0"
+license: MIT
+tags: [agent-coordination, workflow]
+dependencies: [beads]
+---
+
+# Beads Bridge - Cross-Session Task Coordination
+
+## When to Use
+
+- Work spans multiple sessions and needs persistent task tracking
+- Multiple agents must coordinate via Beads, swarm, and Codex todos
+
+## When NOT to Use
+
+- Single-session, single-agent work with no dependencies
+- Simple tasks that don’t require Beads or swarm coordination
+
+## Overview
+
+**Beads Bridge = Beads (br) + Codex Todos + Swarm Monitor**
+
+- **Beads (br)**: Git-backed task tracking with dependency management
+- **Codex Todos**: Native session-scoped task lists for subagents
+- **Swarm Monitor**: Real-time progress tracking (visualization only)
+
+**Key Tools**:
+
+| Tool    | Purpose                     | When to Use                                          |
+| ------- | --------------------------- | ---------------------------------------------------- |
+| `swarm` | Unified swarm coordination  | All swarm operations (sync, monitor, plan, delegate) |
+| `Task`  | Parallel subagent execution | Spawning worker swarms                               |
+
+**swarm operations:**
+
+- `sync`: Sync Beads ↔ Codex todos (start of session, before spawning)
+- `monitor`: Progress tracking/visualization (during swarm execution)
+- `plan`: Task classification + dependency graphs (before spawning workers)
+- `delegate`: Create delegation packets (assigning work to workers)
+
+## Core Workflows
+
+### 1. Session Start: Load Beads into Todos
+
+Make Beads tasks visible to subagents:
+
+```typescript
+// Push Beads to Codex todos
+const result = await swarm({
+  operation: "sync",
+  action: "push",
+  filter: "open", // or "in_progress", "all"
+});
+
+// Subagents can now use todoread to see tasks
+// [Bead] task-title will appear in their todo list
+```
+
+### 2. Check Swarm Status
+
+Check current swarm progress:
+
+```typescript
+// Check swarm status
+const status = await swarm({
+  operation: "monitor",
+  action: "status",
+  team_name: "api-refactor-swarm",
+});
+
+const stats = JSON.parse(status).summary;
+console.log(`Workers: ${stats.total_workers}, Completed: ${stats.completed}`);
+
+// Render TUI for visualization
+const ui = await swarm({
+  operation: "monitor",
+  action: "render_block",
+  team_name: "api-refactor-swarm",
+});
+console.log(ui);
+```
+
+### 3. Shared Task Lists for Cross-Session Work
+
+For work that spans multiple sessions, use shared task lists:
+
+```typescript
+// Create a shared list that persists across sessions
+const list = await swarm({
+  operation: "sync",
+  action: "create_shared",
+  name: "api-refactor-swarm",
+  tasks: JSON.stringify([
+    { id: "task-1", content: "Refactor auth endpoint", status: "pending", priority: "high" },
+    { id: "task-2", content: "Update user routes", status: "pending", priority: "medium" },
+  ]),
+});
+
+// Workers update the shared list as they complete work
+await swarm({
+  operation: "sync",
+  action: "update_shared",
+  list_id: list.list_id,
+  tasks: JSON.stringify([{ id: "task-1", status: "completed" }]),
+});
+```
+
+### 4. Create Shared Task Lists for Swarms
+
+Create persistent task lists that survive session boundaries:
+
+```typescript
+// Create a shared list for a swarm
+const list = await swarm({
+  operation: "sync",
+  action: "create_shared",
+  name: "api-refactor-swarm",
+  tasks: JSON.stringify([
+    { id: "task-1", content: "Refactor auth endpoint", status: "pending", priority: "high" },
+    { id: "task-2", content: "Update user routes", status: "pending", priority: "medium" },
+    { id: "task-3", content: "Fix validation", status: "pending", priority: "medium" },
+  ]),
+});
+
+// Share the list ID with workers
+console.log(`List ID: ${list.list_id}`);
+// Workers can access via: swarm({ operation: "sync", action: "get_shared", list_id: "..." })
+```
+
+### 5. Worker Updates to Shared List
+
+Workers can update their task status:
+
+```typescript
+// Worker completes a task
+await swarm({
+  operation: "sync",
+  action: "update_shared",
+  list_id: "shl_abc123",
+  tasks: JSON.stringify([{ id: "task-1", status: "completed" }]),
+});
+```
+
+## Integration Patterns
+
+### Pattern A: Beads → Swarm → Beads
+
+Full cycle from Beads task to swarm execution and back:
+
+```typescript
+// 1. Start: Push Beads to todos
+await swarm({ operation: "sync", action: "push" });
+
+// 2. Claim the parent Bead
+await bash("br update parent-task --status in_progress");
+
+// 3. Analyze and spawn swarm
+const analysis = await swarm({
+  operation: "plan",
+  action: "analyze",
+  task: "Implement API refactor",
+  files: "src/api/users.ts,src/api/posts.ts,src/api/auth.ts",
+});
+
+// 4. Execute swarm (see swarm-coordination skill)
+// ... spawn workers, monitor progress ...
+
+// 5. Complete: Pull completed todos back to Beads
+await swarm({ operation: "sync", action: "pull" });
+
+// 6. Clear swarm state
+await swarm({
+  operation: "monitor",
+  action: "clear",
+  team_name: "api-refactor-swarm",
+});
+
+// 7. Close parent Bead and sync
+await bash("br close parent-task --reason 'Swarm completed all subtasks'");
+await bash("br sync --flush-only");
+await bash("git add .beads/ && git commit -m 'close parent-task'");
+```
+
+### Pattern B: Dependency-Aware Task Scheduling
+
+Use swarm tool's dependency graph for proper ordering:
+
+```typescript
+// Get full analysis with dependency graph
+const analysis = await swarm({
+  operation: "plan",
+  action: "analyze",
+  task: "Refactor authentication system",
+  files: "src/auth/service.ts,src/auth/types.ts,src/routes/auth.ts,src/middleware/auth.ts",
+});
+
+const plan = JSON.parse(analysis);
+
+// Use parallelizable_groups for spawn order
+for (const group of plan.dependency_graph.parallelizable_groups) {
+  // Spawn all tasks in this group in parallel
+  for (const taskId of group) {
+    const node = plan.dependency_graph.nodes.find((n) => n.id === taskId);
+    Task({
+      subagent_type: "general",
+      description: `Execute ${taskId}`,
+      prompt: `Execute task ${taskId}: ${node.content}
+      
+Files: ${node.assignedFiles.join(", ")}
+Blocked by: ${node.blockedBy.join(", ") || "none"}
+Team: auth-refactor-swarm
+Worker: ${node.worker}`,
+    });
+  }
+
+  // Wait for this group to complete before starting next
+  // (dependency ordering)
+}
+```
+
+### Pattern C: Cross-Session Handoff
+
+When work needs to continue in a new session:
+
+```typescript
+// End of session 1: Save state to memory and shared list
+await swarm({
+  operation: "sync",
+  action: "update_shared",
+  list_id: "api-refactor-swarm",
+  tasks: JSON.stringify([
+    { id: "worker-1", content: "Auth service", status: "completed" },
+    { id: "worker-2", content: "User routes", status: "completed" },
+    { id: "worker-3", content: "Validation", status: "in_progress" },
+  ]),
+});
+
+await memory_update({
+  file: "handoffs/swarm-state",
+  content: `
+## Swarm Handoff
+
+Team: api-refactor-swarm
+Progress: 60% complete (3/5 workers done)
+Remaining: worker-4 (blocked), worker-5 (pending)
+Blockers: worker-4 needs auth types from worker-1
+
+Next steps:
+1. Check shared task list for current status
+2. Unblock worker-4 with completed types
+3. Spawn remaining workers
+`,
+  mode: "replace",
+});
+
+// Sync beads before ending session
+await bash("br sync --flush-only");
+await bash("git add .beads/ && git commit -m 'session handoff'");
+
+// Start of session 2: Check status and continue
+const status = await swarm({
+  operation: "monitor",
+  action: "status",
+  team_name: "api-refactor-swarm",
+});
+
+const shared = await swarm({
+  operation: "sync",
+  action: "get_shared",
+  list_id: "api-refactor-swarm",
+});
+
+console.log(`Continuing swarm with ${shared.tasks.length} tasks...`);
+```
+
+## Data Locations
+
+| Data Type         | Location                                        | Persistence   |
+| ----------------- | ----------------------------------------------- | ------------- |
+| Beads tasks       | `.beads/issues/*.md`                            | Git-backed    |
+| Swarm progress    | `.beads/swarm-progress.jsonl`                   | Session       |
+| Shared task lists | `~/.local/share/codex/storage/shared-tasks/` | Cross-session |
+| Codex todos    | `~/.local/share/codex/storage/todo/`         | Session       |
+
+## Quick Reference
+
+```
+SESSION START:
+  swarm({ operation: "sync", action: "push" })  // Make Beads visible to subagents
+  swarm({ operation: "monitor", action: "status", team_name: "..." })  // Check swarm status
+
+DURING WORK:
+  swarm({ operation: "monitor", action: "progress_update", ... })  // Track worker progress
+  swarm({ operation: "monitor", action: "render_block", ... })  // TUI visualization
+  swarm({ operation: "sync", action: "update_shared", ... })  // Cross-session updates
+
+SESSION END:
+  swarm({ operation: "sync", action: "pull" })  // Sync completed todos back to Beads
+  swarm({ operation: "monitor", action: "clear", team_name: "..." })  // Cleanup swarm state
+  br sync --flush-only  // Export Beads changes
+  git add .beads/ && git commit -m "..."  // Commit changes to git
+
+RECOVERY:
+  swarm({ operation: "sync", action: "get_shared", list_id: "..." })  // Get shared task list
+  swarm({ operation: "monitor", action: "status", team_name: "..." })  // Check swarm status
+```
+
+## Rules
+
+1. **Always push Beads at session start** - Subagents need visibility via todoread
+2. **Use shared lists for long-running swarms** - Cross-session persistence via swarm sync
+3. **Pull completed todos back to Beads** - Keep tracking system in sync
+4. **Check swarm status before spawning** - Avoid duplicate work
+5. **Clear swarm state when done** - Cleanup after completion
+6. **Always sync and commit before session end** - `br sync --flush-only` then `git add .beads/ && git commit`

package/.codex/skills/brainstorming/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: brainstorming
+description: Use when creating or developing, before writing code or implementation plans - refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation. Don't use during clear 'mechanical' processes
+version: 1.0.0
+tags: [planning, workflow]
+dependencies: []
+---
+
+# Brainstorming Ideas Into Designs
+
+> **Replaces** jumping straight to implementation without exploring alternatives, constraints, or edge cases
+## When to Use
+
+- You have a rough idea that needs clarification into a design or spec
+- You need to explore multiple approaches and validate trade-offs before coding
+
+## When NOT to Use
+
+- Requirements are already clear and execution is mechanical
+- You are already in implementation with a validated plan or PRD
+
+## Overview
+
+Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
+
+Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far.
+
+**Part of:** `development-lifecycle` skill (Phase 1: Ideation)
+
+**Output template:** `.codex/context/design.md`
+
+## The Process
+
+**Understanding the idea:**
+
+- Check out the current project state first (files, docs, recent commits)
+- Ask questions one at a time to refine the idea
+- Prefer multiple choice questions when possible, but open-ended is fine too
+- Only one question per message - if a topic needs more exploration, break it into multiple questions
+- Focus on understanding: purpose, constraints, success criteria
+
+**Exploring approaches:**
+
+- Propose 2-3 different approaches with trade-offs
+- Present options conversationally with your recommendation and reasoning
+- Lead with your recommended option and explain why
+
+**Presenting the design:**
+
+- Once you believe you understand what you're building, present the design
+- Break it into sections of 200-300 words
+- Ask after each section whether it looks right so far
+- Cover: architecture, components, data flow, error handling, testing
+- Be ready to go back and clarify if something doesn't make sense
+
+## After the Design
+
+**Documentation:**
+
+- Write the validated design to `.beads/artifacts/<bead-id>/design.md`
+- Use template from `.codex/context/design.md`
+- Use elements-of-style:writing-clearly-and-concisely skill if available
+- Commit the design document to git
+
+**Next Phase (if continuing):**
+
+- Ask: "Ready to create the PRD?"
+- Load next skill: `skill({ name: "prd" })`
+- This moves to Phase 2: Specification
+
+**Alternative paths:**
+
+- Use `skill({ name: "using-git-worktrees" })` to create isolated workspace first
+- Use `skill({ name: "writing-plans" })` if skipping formal PRD
+
+**Full lifecycle reference:**
+
+- Use `skill({ name: "development-lifecycle" })` to see all phases
+
+## Key Principles
+
+- **One question at a time** - Don't overwhelm with multiple questions
+- **Multiple choice preferred** - Easier to answer than open-ended when possible
+- **YAGNI ruthlessly** - Remove unnecessary features from all designs
+- **Explore alternatives** - Always propose 2-3 approaches before settling
+- **Incremental validation** - Present design in sections, validate each
+- **Be flexible** - Go back and clarify when something doesn't make sense
+
+## Example Flow
+
+**User request**: "Add dark mode to the app"
+
+**Good brainstorming questions**:
+1. "Should dark mode be system-preference-aware, manual toggle, or both?"
+2. "Where does theme state live — CSS variables, React context, localStorage?"
+3. "Are there existing color tokens, or do we need to create a design token system?"
+4. "What about images/icons — do they need dark variants?"
+
+**Bad brainstorming** (jumping to solution):
+1. "I'll add a ThemeContext with useState and toggle button" ← skipped alternatives
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+| --- | --- | --- |
+| Asking questions the codebase can answer (search first) | Wastes turns and slows decisions; signals weak preparation | Do quick repo/docs lookup first, then ask only unresolved questions |
+| Brainstorming during mechanical/routine tasks | Adds overhead when execution is already clear | Skip to execution using the relevant implementation skill |
+| Generating 10+ alternatives without narrowing criteria | Creates analysis paralysis and no decision pressure | Present 2-3 viable options with explicit decision criteria |
+| Continuing to brainstorm after a clear direction emerges | Burns time and erodes momentum | Confirm direction, summarize decisions, transition to PRD/plan |
+
+## See Also
+
+- `writing-plans` - Turn validated direction into zero-ambiguity implementation tasks
+- `prd` - Capture behavioral requirements before implementation

package/.codex/skills/bug-triage/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: bug-triage
+description: Structured bug triage process covering severity, reproduction, categorization, and fix sizing.
+---
+# bug-triage
+
+## Purpose
+Classify and prioritize bugs quickly using reproducible evidence, consistent severity rules, and clear routing.
+
+## Use This Skill When
+- New defect reports arrive
+- Incident intake needs prioritization
+- Backlog grooming includes unresolved defects
+- Multiple reports may describe the same root issue
+
+## Workflow Phases
+1. Intake
+2. Reproduce
+3. Classify
+4. Estimate and route
+
+## Expected Outputs
+- Severity/priority label
+- Reproduction status with minimal repro
+- Root-cause category hypothesis
+- Owner, size estimate, and next action
+
+## Success Indicators
+- Accepted bugs have reproducible evidence or explicit repro gap
+- Severity matches user impact and blast radius
+- Duplicates are merged into canonical report
+- Routing outcome is actionable and time-bound
+
+## Intake Inputs
+- Report source (user, CI, monitoring)
+- Affected version or commit range
+- Environment details (local/CI/production)
+- Related incidents or tickets
+
+## Severity Classification
+| Severity | Label | User Impact | Technical Impact | Response Target |
+|---|---|---|---|---|
+| P0 | Blocker | Core workflow unavailable/unsafe | Outage, data loss, security exposure | Immediate |
+| P1 | High | Major workflow broken, no workaround | Persistent production-path failure | Same day |
+| P2 | Medium | Important issue with workaround | Localized defect/edge-case failure | 3-7 days |
+| P3 | Low | Minor or infrequent issue | No systemic risk | Planned backlog |
+
+## Priority Overrides
+Raise one level when:
+- High-volume or business-critical users are affected
+- Security/compliance exposure exists
+- Issue is a confirmed recent regression
+- Release-critical path is blocked
+
+## Reproduction Checklist
+- [ ] Environment captured (OS/runtime/toolchain)
+- [ ] Exact trigger input/command documented
+- [ ] Expected vs actual behavior listed
+- [ ] Error output/logs/stack trace attached
+- [ ] Repro validated at least twice
+- [ ] Scope identified (local only, CI only, production, all)
+
+## Minimal Repro Template
+```markdown
+### Preconditions
+- Runtime:
+- Branch/commit:
+- Config state:
+
+### Steps
+1.
+2.
+3.
+
+### Expected
+-
+
+### Actual
+-
+
+### Evidence
+- Logs:
+- Stack trace:
+- Output/screenshot:
+```
+
+## Root Cause Categories
+| Category | Typical Signal | Next Check |
+|---|---|---|
+| Logic error | Wrong output for valid input | Focused unit repro around branch logic |
+| Data contract mismatch | Parse/shape failures at boundary | Verify schemas/types at boundary |
+| Race/timing issue | Intermittent/order-sensitive failures | Add ordering traces and deterministic sync |
+| Environment/config issue | Works only in specific env | Diff env vars, paths, tool versions |
+| Dependency regression | Failure after upgrades | Bisect lockfile/version history |
+| Missing validation | Invalid data reaches deep layers | Add boundary validation and explicit errors |
+
+## Intake Questions
+1. What user behavior is broken?
+2. Who is affected and how broadly?
+3. Is there a workaround?
+4. Is this a regression? Since when?
+5. Is reproduction deterministic?
+
+## Duplicate Detection Heuristics
+Likely duplicate when reports share:
+- Same top stack frames/error code
+- Same trigger command/input pattern
+- Same environment constraints
+- Same first-bad commit window
+
+When merging duplicates:
+- Keep oldest report canonical
+- Link related reports
+- Consolidate best repro steps in canonical ticket
+
+## Estimation and Routing Matrix
+| Size | Typical Scope | Suggested Owner |
+|---|---|---|
+| S | Single-file obvious fix with nearby tests | Feature owner/on-call |
+| M | 2-4 files, boundary updates, new tests | Module owner |
+| L | Cross-module changes with integration risk | Senior engineer + reviewer |
+| XL | Architectural changes required | Escalate for decision |
+
+Confidence:
+- High: deterministic repro + failing location known
+- Medium: deterministic repro + cause hypothesis
+- Low: non-deterministic or insufficient diagnostics
+
+## Routing Rules
+- P0/P1 production defects: assign immediately with mitigation path.
+- Security-adjacent bugs: route to security owner first.
+- Non-reproducible reports: mark `needs-repro` with artifact request.
+- Architectural-change fixes: escalate for design decision.
+
+## Practical Triage Commands
+```bash
+npm test -- <failing-spec>
+node --version
+npm --version
+git log --oneline -30
+grep -R "<error-fragment>" src test --line-number
+```
+
+## Bug Report Template (Actionable)
+```markdown
+## Summary
+- one-line user impact
+
+## Severity / Priority
+- P?
+- reason:
+
+## Reproduction
+- deterministic? yes/no
+- steps:
+
+## Impact Scope
+- users/workflows affected:
+- workaround:
+
+## Technical Signals
+- error output:
+- suspected module/path:
+- suspected category:
+
+## Proposed Next Action
+- owner:
+- size (S/M/L/XL):
+- ETA/target:
+```
+
+## Anti-Patterns
+| Anti-pattern | Consequence | Better approach |
+|---|---|---|
+| Severity by intuition | Priority churn | Use impact/workaround/blast-radius rubric |
+| Early “cannot reproduce” closure | Real defects linger | Request standardized repro artifacts |
+| Triage + full fix mixed | Intake bottleneck | Classify first, then fix workflow |
+| Ignoring duplicates | Fragmented evidence | Merge early into canonical report |
+| Vague “intermittent” label | No progress | Capture timing/order/environment matrix |
+
+## Escalation Triggers
+- Potential data loss, corruption, or security impact
+- Cross-system failures with unclear ownership
+- Non-deterministic failures blocking release gates
+- Issues without safe short-term mitigation
+
+## Triage Exit Criteria
+- Severity and priority are evidence-backed.
+- Reproduction state is explicit (`reproduced` or `needs-repro`).
+- Root-cause category is assigned (provisional allowed).
+- Owner, size, and next action are recorded.

package/.codex/skills/chrome-devtools/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: chrome-devtools
+description: Chrome DevTools for debugging, performance analysis, and browser automation. Use when debugging web apps, analyzing performance, inspecting network requests, or automating browser interactions.
+version: 1.0.0
+tags: [automation, debugging]
+dependencies: []
+---
+
+# Chrome DevTools (MCP)
+
+## When to Use
+
+- When you need to debug or inspect a live Chrome page via DevTools Protocol tools.
+
+## When NOT to Use
+
+- When cross-browser automation is required (use Playwright-based skills instead).
+
+
+## Available Tools
+
+- `take_snapshot` - Get accessibility tree snapshot with element UIDs
+- `take_screenshot` - Capture screenshot of page or element
+- `navigate_page` - Navigate to URL, back, forward, or reload
+- `new_page` - Open a new browser tab
+- `list_pages` - List all open pages/tabs
+- `click` - Click element by UID
+- `fill` - Type text into element
+- `hover` - Hover over element
+- `press_key` - Press keyboard key (Enter, Tab, etc.)
+- `evaluate_script` - Run JavaScript in page context
+- `wait_for` - Wait for text to appear
+
+## Workflow
+
+1. **Snapshot** the page using `take_snapshot` to get element UIDs
+2. **Navigate** to target URL using `navigate_page`
+3. **Interact** using `click`, `fill`, `hover` with UIDs from snapshot
+4. **Screenshot** to capture results using `take_screenshot`
+
+## Quick Start
+
+```
+# Get page structure with element UIDs
+skill_mcp(skill_name="chrome-devtools", tool_name="take_snapshot")
+
+# Navigate to URL
+skill_mcp(skill_name="chrome-devtools", tool_name="navigate_page", arguments='{"type": "url", "url": "https://example.com"}')
+
+# Click element (use UID from snapshot)
+skill_mcp(skill_name="chrome-devtools", tool_name="click", arguments='{"uid": "e123"}')
+
+# Fill input field
+skill_mcp(skill_name="chrome-devtools", tool_name="fill", arguments='{"uid": "e456", "value": "hello"}')
+
+# Take screenshot
+skill_mcp(skill_name="chrome-devtools", tool_name="take_screenshot")
+```
+
+## Tips
+
+- **Always `take_snapshot` first** to get element UIDs
+- **Element UIDs change** after navigation - take fresh snapshot
+- **Use `wait_for`** after actions that trigger page changes
+- **Use `evaluate_script`** for custom JS when tools don't cover your need
+
+## vs Playwright
+
+| Feature             | chrome-devtools      | playwright         |
+| ------------------- | -------------------- | ------------------ |
+| Browser support     | Chrome only          | Chrome, FF, WebKit |
+| Performance tracing | ✅ (full MCP has it) | ❌                 |
+| Network inspection  | ✅ (full MCP has it) | ❌                 |
+| Cross-browser       | ❌                   | ✅                 |
+
+> **Note**: This skill loads 11 essential tools. For full 26+ tools (performance, network, console), modify `mcp.json` to remove `includeTools` filter.