codexkit 1.0.0

package/.codex/skills/swarm-coordination/references/drift-check.md

@@ -0,0 +1,90 @@
+# Drift Check After Each Wave
+
+After every wave completes and before starting the next, run a **drift check** to verify the codebase has not deviated from the intended state. Accumulated drift between waves is the primary cause of cascading failures in large swarms.
+
+**Drift** = any difference between actual codebase state and the plan's expected state at a wave boundary.
+
+## What to Check
+
+| Check             | Command                                            | Passing Condition              |
+| ----------------- | -------------------------------------------------- | ------------------------------ |
+| Build gates       | `npm run typecheck && npm run lint`                | Zero errors                    |
+| Unexpected files  | `git diff --name-only HEAD`                        | Only planned files modified    |
+| Missing artifacts | Verify expected files exist                        | All declared outputs present   |
+| Scope adherence   | Compare `git status` vs wave's declared file scope | No out-of-scope files modified |
+
+## Drift Check Protocol
+
+Run after every wave, before spawning the next:
+
+```typescript
+async function driftCheckAfterWave(wave: Wave, expectedFiles: string[]) {
+  console.log(`\n=== DRIFT CHECK: Wave ${wave.number} ===`);
+
+  // 1. Build gates must pass
+  const gates = await bash("npm run typecheck && npm run lint");
+  if (!gates.success) {
+    throw new Error(`Wave ${wave.number} drift: build gates failed\n${gates.output}`);
+  }
+
+  // 2. Detect unexpected file modifications
+  const changedFiles = await bash("git diff --name-only HEAD");
+  const actualFiles = changedFiles.output.trim().split("\n").filter(Boolean);
+  const unexpected = actualFiles.filter((f) => !expectedFiles.includes(f));
+
+  if (unexpected.length > 0) {
+    console.warn(`⚠️  Unexpected files modified in wave ${wave.number}:`);
+    unexpected.forEach((f) => console.warn(`  - ${f}`));
+  }
+
+  // 3. Verify declared artifacts exist
+  for (const artifact of wave.expectedArtifacts ?? []) {
+    const exists = await bash(`test -f ${artifact} && echo "ok" || echo "missing"`);
+    if (exists.output.trim() === "missing") {
+      throw new Error(`Wave ${wave.number} drift: expected artifact missing: ${artifact}`);
+    }
+  }
+
+  console.log(`✓ Drift check passed: Wave ${wave.number}`);
+}
+```
+
+## Integration in Wave Execution
+
+Call drift check between every wave:
+
+```typescript
+for (let i = 0; i < waves.length; i++) {
+  const wave = waves[i];
+  const reconciler = runReconciler(teamName, "npm run typecheck && npm run lint");
+
+  await Promise.all(wave.tasks.map((task) => spawnWorker(task, teamName)));
+  await reconciler;
+
+  // MANDATORY: Drift check before next wave
+  await driftCheckAfterWave(
+    wave,
+    wave.tasks.flatMap((t) => t.assignedFiles),
+  );
+
+  console.log(`✓ Wave ${i + 1}/${waves.length} complete and verified`);
+}
+```
+
+## Drift Response Protocol
+
+| Drift Type               | Severity | Action                                           |
+| ------------------------ | -------- | ------------------------------------------------ |
+| Build gate failure       | Critical | Stop swarm, run reconciler, fix before next wave |
+| Unexpected file modified | Warning  | Review change, revert if out of scope            |
+| Missing artifact         | Critical | Re-run failed worker task, verify output         |
+| Scope creep              | Warning  | Escalate to user if >3 unexpected files changed  |
+
+## When Drift Is Unrecoverable
+
+If drift check fails twice in a row on the same wave:
+
+1. **Stop the swarm** - don't start next wave
+2. **Report to user**: exact drift details, failing gate output, list of unexpected files
+3. **Rollback option**: use `git reset --hard <wave-N-start-tag>` (see `executing-plans` skill)
+4. **Never paper over drift** - proceeding with known drift compounds into cascading failure

package/.codex/skills/swarm-coordination/references/integration-beads.md

@@ -0,0 +1,20 @@
+# Integration with Beads
+
+Swarm works on top of Beads:
+
+1. **Session start**: `swarm sync push` to make tasks visible
+2. **Leader claims parent** bead
+3. **Workers claim child** beads (via delegation packets)
+4. **Progress tracked** via `swarm monitor progress_update`
+5. **Completion syncs** back via `swarm sync pull`
+6. **Close parent** bead with `br close`
+
+```typescript
+// Full integration workflow
+await swarm({ operation: "sync", action: "push" }); // Make Beads visible
+// ... spawn swarm ...
+await swarm({ operation: "monitor", action: "render_block", team_name: "..." }); // Monitor progress
+// ... monitor completion ...
+await swarm({ operation: "sync", action: "pull" }); // Sync completed back
+await bash("br close parent-task --reason 'Swarm completed'");
+```

package/.codex/skills/swarm-coordination/references/launch-flow.md

@@ -0,0 +1,186 @@
+# Swarm Launch Flow - PARL Pattern (7 Steps)
+
+## Step 0: Task Analysis (Anti-Serial-Collapse + Dependency Graph)
+
+Analyze the user's actual task to determine optimal swarm strategy:
+
+```typescript
+// 1. Classify the task and build dependency graph
+const analysis = await swarm({
+  operation: "plan",
+  operation: "analyze",
+  task: "<user's request from input>",
+  files: "<detected files from glob/grep>",
+});
+
+// Returns:
+// - type: "search" | "batch" | "writing" | "sequential" | "mixed"
+// - recommended_agents: number
+// - phases: [{ name, role, agent_count, dependencies }]
+// - coupling: "high" | "medium" | "low"
+// - confidence: "high" | "medium" | "low"
+// - dependency_graph: { nodes, edges, critical_path, parallelizable_groups }
+
+const plan = JSON.parse(analysis);
+
+// 2. Check for serial collapse
+const check = await swarm({
+  operation: "plan",
+  operation: "check",
+  task: "<user's request>",
+  files: String(plan.file_count),
+  recommended_agents: plan.classification.recommended_agents,
+});
+
+// If serial collapse detected, force parallelization
+if (check.serial_collapse_detected) {
+  console.log(`⚠️ Serial collapse detected: ${check.warning_signs.join(", ")}`);
+  console.log(`✓ Adjusting to ${check.suggested_agents} agents`);
+}
+
+// 3. Use dependency graph for spawn ordering
+const { parallelizable_groups, critical_path } = plan.dependency_graph;
+console.log(`Critical path: ${critical_path.join(" → ")}`);
+console.log(`Parallel groups: ${parallelizable_groups.length}`);
+```
+
+## Step 1: Session Setup (Push Beads to Todos)
+
+Make Beads tasks visible to subagents:
+
+```typescript
+// Push Beads to Codex todos (subagents see via todoread)
+await swarm({ operation: "sync", operation: "push", filter: "open" });
+
+// Check for existing swarm state
+const status = await swarm({
+  operation: "monitor",
+  operation: "status",
+  team_name: "plan-implementation",
+});
+const stats = JSON.parse(status).summary;
+
+if (stats.total_workers > 0) {
+  console.log(`Found existing swarm with ${stats.total_workers} workers`);
+  // Render current progress
+  const ui = await swarm({
+    operation: "monitor",
+    operation: "render_block",
+    team_name: "plan-implementation",
+  });
+  console.log(ui);
+}
+```
+
+## Step 2: Create Delegation Packets
+
+For each task, create a delegation packet:
+
+```typescript
+swarm({
+  operation: "delegate",
+  bead_id: "task-1",
+  title: "Implement auth service",
+  expected_outcome: "Auth service with JWT tokens, tests pass",
+  required_tools: "read, grep, lsp, edit, bash",
+  must_do: "LSP before edits, run npm test after changes",
+  must_not_do: "No new dependencies, don't edit config files",
+  acceptance_checks: "typecheck: npm run typecheck, lint: npm run lint, test: npm test",
+  context: "See .beads/artifacts/task-1/spec.md for requirements",
+  write: true,
+});
+```
+
+## Step 3: Spawn Worker Agents (Using Dependency Groups)
+
+Use parallelizable_groups from dependency graph for proper ordering:
+
+```typescript
+// Spawn workers in dependency order
+for (const group of plan.dependency_graph.parallelizable_groups) {
+  // All tasks in this group can run in parallel
+  const spawnPromises = group.map((taskId) => {
+    const node = plan.dependency_graph.nodes.find((n) => n.id === taskId);
+    return Task({
+      subagent_type: "general",
+      description: `Execute ${taskId}`,
+      prompt: `Execute bead ${taskId}: ${node.content}
+
+Read delegation packet at: .beads/artifacts/${taskId}/delegation.md
+
+Files: ${node.assignedFiles.join(", ")}
+Phase: ${node.phase}
+Worker: ${node.worker}
+Team: plan-implementation
+
+Requirements:
+1. Follow all MUST DO constraints
+2. Avoid all MUST NOT DO items
+3. Run acceptance checks before claiming done
+4. Report progress via swarm monitor`,
+    });
+  });
+
+  // Wait for parallel group to complete before starting next
+  await Promise.all(spawnPromises);
+}
+```
+
+## Step 4: Monitor Progress (Real-time TUI + Persistence)
+
+Monitor with beautiful block UI, progress tracking, and auto-persistence:
+
+```typescript
+let allComplete = false;
+while (!allComplete) {
+  // Option A: Render beautiful TUI block
+  const ui = await swarm({
+    operation: "monitor",
+    operation: "render_block",
+    team_name: "plan-implementation",
+  });
+  console.log(ui); // Markdown block with tables, emojis, progress
+
+  // Option B: Get detailed status
+  const status = await swarm({
+    operation: "monitor",
+    operation: "status",
+    team_name: "plan-implementation",
+  });
+  const stats = JSON.parse(status).summary;
+  // Returns: total_workers, completed, working, errors, messages
+
+  // Check completion
+  allComplete = stats.completed === stats.total_workers;
+
+  if (!allComplete) {
+    // Wait before checking again
+    await new Promise((r) => setTimeout(r, 2000)); // Wait 2s
+  }
+}
+```
+
+## Step 5: Synthesize Results
+
+When all workers complete:
+
+```typescript
+// 1. Get final status
+const finalStatus = await swarm({
+  operation: "monitor",
+  operation: "status",
+  team_name: "plan-implementation",
+});
+
+// 2. Run full verification
+await bash("npm run typecheck && npm run lint && npm test");
+
+// 3. Pull completed todos back to Beads
+await swarm({ operation: "sync", operation: "pull" });
+
+// 4. Clear swarm data
+await swarm({ operation: "monitor", operation: "clear", team_name: "plan-implementation" });
+
+// 5. Close parent bead
+await bash("br close parent-task --reason 'Swarm completed all subtasks'");
+```

package/.codex/skills/swarm-coordination/references/reconciler.md

@@ -0,0 +1,172 @@
+# Reconciler Agent Pattern (Self-Healing)
+
+The reconciler is the key to scaling beyond 50+ agents. Without reconciliation, broken builds cascade and the swarm collapses. The reconciler provides **continuous self-healing** by watching for failures and spawning targeted fix tasks.
+
+## When to Use Reconciler
+
+- **50+ agents** running in parallel → **REQUIRED**
+- **10-50 agents** → Recommended
+- **<10 agents** → Optional (leader can handle)
+
+## Reconciler Responsibilities
+
+1. **Watch CI/Build Status**: Monitor build gates continuously
+2. **Detect Failures**: Identify which worker caused the failure
+3. **Analyze Root Cause**: Determine if it's a merge conflict, test failure, or type error
+4. **Spawn Fix Tasks**: Create targeted fix tasks with context about what failed
+5. **Verify Fix**: Wait for fix to pass gates before continuing
+
+## Reconciler vs Leader
+
+| Aspect         | Leader                        | Reconciler                    |
+| -------------- | ----------------------------- | ----------------------------- |
+| Focus          | Orchestration, spawning       | Recovery, fixing              |
+| Runs           | At swarm start, between waves | Continuously during execution |
+| On failure     | Spawns workers                | Spawns fix tasks              |
+| Failure impact | Can't start work              | Wave can't complete           |
+
+## Implementing Reconciler
+
+The reconciler runs in a loop during swarm execution:
+
+```typescript
+// Reconciler runs in background during swarm execution
+async function runReconciler(teamName: string, buildCommand: string) {
+  while (swarmActive) {
+    // 1. Check build status
+    const status = await swarm({
+      operation: "monitor",
+      operation: "status",
+      team_name: teamName,
+    });
+    const stats = JSON.parse(status).summary;
+
+    // 2. If there are errors, investigate
+    if (stats.errors > 0) {
+      // 3. Get error details
+      const errors = await getWorkerErrors(teamName);
+
+      for (const error of errors) {
+        // 4. Analyze root cause
+        const cause = await analyzeError(error);
+
+        // 5. Spawn fix task
+        const fixBead = await br create({
+          title: `Fix: ${cause.summary}`,
+          type: "bug",
+          description: `Detected by reconciler: ${error.message}. Root cause: ${cause.rootCause}. Suggested fix: ${cause.suggestion}`,
+        });
+
+        // 6. Assign to targeted worker
+        await Task({
+          subagent_type: "general",
+          description: `Fix ${error.worker}`,
+          prompt: `Fix the error in ${error.file}.
+
+Error: ${error.message}
+Root cause: ${cause.rootCause}
+Suggested fix: ${cause.suggestion}
+
+Run: ${buildCommand}
+Verify: npm run typecheck && npm run lint`,
+        });
+      }
+    }
+
+    // Wait before next check
+    await sleep(30000); // Check every 30 seconds
+  }
+}
+```
+
+## Error Analysis Patterns
+
+The reconciler categorizes errors:
+
+| Error Type     | Detection                        | Fix Strategy                 |
+| -------------- | -------------------------------- | ---------------------------- |
+| Merge conflict | "CONFLICT" in output, git status | Re-base, resolve, force push |
+| Type error     | "typecheck failed"               | Fix types, run typecheck     |
+| Test failure   | "test failed", "expect" mismatch | Fix test or implementation   |
+| Lint error     | "lint failed", formatting issues | Run lint:fix                 |
+| Build error    | "build failed", bundler errors   | Fix imports, dependencies    |
+
+## Spawning Fix Tasks
+
+When the reconciler spawns a fix task, it includes:
+
+```typescript
+// Create fix task with full context
+await br create({
+  title: `Fix: ${error.type} in ${error.file}`,
+  type: "bug",
+  description: `## Error Detected
+- Worker: ${error.worker}
+- File: ${error.file}
+- Error: ${error.message}
+- Timestamp: ${error.timestamp}
+
+## Root Cause Analysis
+${cause.explanation}
+
+## Suggested Fix
+${cause.suggestion}
+
+## Verification
+Run: ${buildCommand}
+Must pass before wave can complete.`,
+});
+```
+
+## Reconciler in Wave Execution
+
+Add reconciler monitoring to each wave:
+
+```typescript
+// Execute wave with reconciler
+async function executeWaveWithReconciler(wave, teamName) {
+  // Start reconciler in background
+  const reconciler = runReconciler(teamName, "npm run typecheck && npm run lint");
+
+  // Execute workers in this wave
+  await Promise.all(wave.tasks.map(spawnWorker));
+
+  // Wait for all workers + reconciler to complete
+  await reconciler;
+
+  // Verify wave output before proceeding
+  await bash("npm run typecheck && npm run lint");
+}
+```
+
+## Example: Full Swarm with Reconciler
+
+```typescript
+// Full swarm execution with reconciler
+async function runSwarmWithReconciler(tasks, teamName) {
+  // 1. Analyze and create waves
+  const waves = createWaves(tasks);
+
+  // 2. Execute each wave with reconciler
+  for (const wave of waves) {
+    console.log(`Executing wave ${wave.number} with ${wave.tasks.length} tasks`);
+
+    // Start reconciler for this wave
+    const reconcilerPromise = runReconciler(teamName, "npm run typecheck && npm run lint");
+
+    // Spawn workers
+    await Promise.all(wave.tasks.map((task) => spawnWorker(task, teamName)));
+
+    // Wait for reconciler to finish fixing any errors
+    await reconcilerPromise;
+
+    // Verify wave output
+    const result = await bash("npm run typecheck && npm run lint");
+    if (!result.success) {
+      throw new Error(`Wave ${wave.number} failed gates`);
+    }
+
+    console.log(`Wave ${wave.number} complete`);
+  }
+}
+```

package/.codex/skills/swarm-coordination/references/tier-enforcement.md

@@ -0,0 +1,78 @@
+# Tier Enforcement (Longshot Pattern)
+
+For multi-agent execution at scale (10+ agents), enforce explicit tier hierarchy. This is the Longshot pattern that enabled 200 agents to build Minecraft.
+
+## Tier System
+
+| Tier            | Role                  | Swarm Equivalent | Responsibility                                                 |
+| --------------- | --------------------- | ---------------- | -------------------------------------------------------------- |
+| **planner**     | Lead orchestrator     | Build agent      | Analyzes scope, decomposes into sub-tasks, coordinates workers |
+| **sub-planner** | Mid-level coordinator | N/A              | Takes planner output, further decomposes, assigns to workers   |
+| **worker**      | Execution agent       | Worker agents    | Executes assigned work, reports progress                       |
+
+## When Tiers Are Required
+
+- **<10 agents**: Optional - flat decomposition works
+- **10-50 agents**: Recommended - planner + workers
+- **50+ agents**: Required - planner + sub-planners + workers
+
+## Enforcing Tier Boundaries
+
+The swarm leader enforces tier boundaries:
+
+```typescript
+// Tier enforcement in swarm execution
+async function enforceTiers(waves, tierConfig) {
+  // Wave 1: Planner tasks only
+  const planners = waves.filter((w) => w.tier === "planner");
+  await executeWave(planners);
+
+  // Wave 2: Sub-planner tasks (if any)
+  const subPlanners = waves.filter((w) => w.tier === "sub-planner");
+  await executeWave(subPlanners);
+
+  // Wave 3+: Worker tasks
+  const workers = waves.filter((w) => w.tier === "worker");
+  await executeWave(workers);
+}
+```
+
+## Handoff Contracts Between Tiers
+
+Each tier must declare handoff contracts:
+
+```typescript
+// Planner declares what it produces for sub-planners
+const plannerHandoff = {
+  produces: [
+    { artifact: "docs/auth-design.md", format: "markdown" },
+    { artifact: "tasks/auth-tasks.json", format: "json" },
+  ],
+  consumedBy: ["sub-planner-auth"],
+};
+
+// Worker declares what it consumes from sub-planners
+const workerHandoff = {
+  consumes: [{ artifact: "tasks/auth-tasks.json", format: "json" }],
+  produces: [{ artifact: "src/auth/service.ts", format: "typescript" }],
+};
+```
+
+## Anti-Pattern: Flat Decomposition at Scale
+
+Without tiers, 20 agents get 20 flat tasks → chaos:
+
+- Workers step on each other
+- No coordination between related work
+- Merge conflicts everywhere
+- No clear ownership
+
+With tiers (Longshot pattern):
+
+```
+Lead Planner → Sub-planner A → Worker 1, 2, 3
+              → Sub-planner B → Worker 4, 5, 6
+              Sub-planner C → Worker 7, 8, 9
+```
+
+This mirrors real engineering orgs: lead → tech lead → IC. The architecture is the differentiator.

package/.codex/skills/swarm-coordination/references/tmux-integration.md

@@ -0,0 +1,134 @@
+# Tmux Integration (Visual Swarm Monitoring)
+
+Enable real-time visualization of swarm workers in separate tmux panes.
+
+## Setup
+
+1. Start Codex inside tmux:
+
+```bash
+tmux new -s codex
+codex
+```
+
+2. The tmux tool auto-detects when running inside tmux and uses these defaults:
+   - Layout: `main-vertical` (leader left, workers right)
+   - Main pane size: 60%
+   - Auto-cleanup: enabled
+
+## Detecting Tmux
+
+```typescript
+// Check if running inside tmux
+const status = await tmux({ operation: "detect" });
+const { available, inside_session } = JSON.parse(status);
+
+if (!inside_session) {
+  console.log("Tip: Run inside tmux for visual swarm monitoring");
+  console.log("Start with: tmux new -s codex");
+}
+```
+
+## Spawning Worker Panes
+
+When spawning workers, create visual panes:
+
+```typescript
+// Before spawning worker via Task tool
+if (inside_session) {
+  // Create pane for this worker
+  const pane = await tmux({
+    operation: "spawn",
+    worker_id: "worker-1",
+    title: "Explorer: auth.ts",
+    size: 40, // 40% width
+  });
+
+  const { pane_id } = JSON.parse(pane);
+
+  // Send command to pane (optional - for visual feedback)
+  await tmux({
+    operation: "send",
+    pane_id,
+    command: `echo "🔍 Worker-1: Exploring auth.ts..."`,
+  });
+}
+
+// Spawn the actual worker
+await Task({
+  subagent_type: "general",
+  description: "Execute worker-1",
+  prompt: `...`,
+});
+```
+
+## Layout Options
+
+| Layout            | Description                           | Best For                      |
+| ----------------- | ------------------------------------- | ----------------------------- |
+| `main-vertical`   | Main pane left, workers stacked right | Default, good for 2-4 workers |
+| `main-horizontal` | Main pane top, workers below          | Wide monitors                 |
+| `tiled`           | Equal grid for all panes              | Many workers (5+)             |
+| `even-horizontal` | Equal width columns                   | 2-3 workers                   |
+| `even-vertical`   | Equal height rows                     | 2-3 workers                   |
+
+```typescript
+// Change layout dynamically
+await tmux({
+  operation: "layout",
+  layout: "tiled", // When many workers spawn
+});
+```
+
+## Monitoring Worker Output
+
+```typescript
+// Capture output from a worker's pane
+const output = await tmux({
+  operation: "capture",
+  pane_id: "%5",
+});
+
+// Check what the worker is doing
+console.log(JSON.parse(output).output);
+```
+
+## Cleanup
+
+```typescript
+// Kill specific pane when worker completes
+await tmux({
+  operation: "kill",
+  pane_id: "%5",
+});
+
+// Or cleanup all spawned panes at end of swarm
+await tmux({
+  operation: "cleanup",
+});
+```
+
+## User Commands
+
+| Action                  | Keys          |
+| ----------------------- | ------------- |
+| Switch to next pane     | `Ctrl+B →`    |
+| Switch to previous pane | `Ctrl+B ←`    |
+| Zoom current pane       | `Ctrl+B z`    |
+| Detach (keep running)   | `Ctrl+B d`    |
+| Reattach                | `tmux attach` |
+| List all panes          | `Ctrl+B w`    |
+
+## Watch Command
+
+Use `/swarm-watch` for real-time progress monitoring:
+
+```bash
+/swarm-watch my-swarm-team
+```
+
+This renders the beautiful TUI block and shows:
+
+- Worker progress percentages
+- Current files being worked on
+- Completion status