eagle-mem 4.7.0 → 4.8.0

package/skills/eagle-mem-orchestrate/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: eagle-mem-orchestrate
+description: >
+  Coordinate multi-agent work with Eagle Mem's durable orchestrator/worker
+  lanes. Use when the user wants an orchestrator model, parallel lanes,
+  Claude Code and Codex sharing worker status, worktree coordination,
+  handoffs, or long-running implementation split across agents.
+---
+
+# Eagle Mem — Orchestrator/Worker Lanes
+
+## Purpose
+
+Use this skill when work is too broad for one agent turn and needs durable
+coordination across Claude Code, Codex, or both.
+
+The commands in this skill are for **you, the active agent**, to run from the
+terminal. Do not hand them to the user as setup steps. The user should only see
+brief progress updates or the final handoff when that helps them.
+
+Eagle Mem stores each lane in shared SQLite tables and mirrors it into
+`agent_tasks`, so SessionStart can re-inject in-flight lane state after
+compaction or when another agent opens the same project.
+
+By default, Eagle Mem routes work to the opposite agent:
+- Codex coordinator -> Claude Code worker (`claude-opus-4-7`, `xhigh`)
+- Claude Code coordinator -> Codex worker (`gpt-5.5`, `xhigh`)
+
+Workers run in git worktrees so their edits stay isolated until the coordinator
+reviews and integrates them. The worker wrapper preserves the original Eagle
+Mem project name, so memories and observations recorded inside the worktree
+still attach to the main project.
+
+## When To Use
+
+Use orchestration when:
+- The work has separate independent lanes, such as API, database, UI, docs, or
+  release validation.
+- Claude Code and Codex may work in the same repo and must not duplicate work.
+- A lane needs its own worktree, validation command, or owner.
+- The user asks for an orchestrator/worker model, agent lanes, subagent lanes,
+  or durable handoff.
+
+Use `eagle-mem tasks` instead when the work is a simple sequential checklist
+that one agent will execute in order.
+
+## Workflow
+
+### 1. Start The Orchestration Yourself
+
+```bash
+eagle-mem orchestrate init "Ship the release safely"
+```
+
+This records the goal and current git baseline for the project.
+
+### 2. Add Worker Lanes Yourself
+
+Create one lane per independent workstream. The description should be
+self-contained enough for a fresh agent context.
+
+```bash
+eagle-mem orchestrate lane add api \
+  --agent codex \
+  --title "API fixes" \
+  --desc "Fix release-boundary checks and add shell-hook regression tests." \
+  --validate "npm test"
+
+eagle-mem orchestrate lane add docs \
+  --agent claude-code \
+  --title "Docs and release notes" \
+  --desc "Update README and usage docs after implementation is verified."
+```
+
+### 3. Spawn Worker Lanes Yourself
+
+After adding a lane, launch the worker yourself. Do not ask the user to run
+this command.
+
+```bash
+eagle-mem orchestrate spawn api
+```
+
+This creates a git worktree, writes a lane prompt, launches the target CLI, and
+records the worker process/log/exit paths in Eagle Mem. Use `--foreground` when
+you need to watch a short worker run inline, `--no-launch` when you only want
+the worktree and prompt prepared, and `--dry-run` to inspect the planned worker
+without creating a worktree.
+
+### 4. Sync Or Mark Lane State As Work Proceeds
+
+```bash
+eagle-mem orchestrate sync
+eagle-mem orchestrate lane start api
+eagle-mem orchestrate lane block api --notes "Waiting for failing test output."
+eagle-mem orchestrate lane complete api --notes "npm test passed."
+```
+
+Lane state should reflect reality. If a lane is blocked, record the blocker so
+the next agent does not repeat the same attempt.
+
+### 5. Check Status Before Taking Work
+
+```bash
+eagle-mem orchestrate
+eagle-mem tasks
+```
+
+Use the lane owner and status to decide what you should work on. Do not take a
+lane that another agent already owns unless the user explicitly redirects it.
+
+### 6. Create A Durable Handoff
+
+```bash
+eagle-mem orchestrate handoff --write docs/handoff-context.md
+```
+
+Use this before compaction, before handing work to another agent, or before
+ending a broad session.
+
+## Rules For Agents
+
+- Main agent acts as coordinator: define lanes, avoid duplicate work, integrate
+  results, and run final validation.
+- The agent runs orchestration commands, including `spawn` and `sync`. Do not
+  tell the user to run them.
+- Workers own their lane only. They should not rewrite unrelated lanes or
+  revert other agents' changes.
+- Every lane should have a validation command when one is obvious.
+- If a lane is blocked, update the lane with a concrete note rather than
+  silently stopping.
+- After completing a lane, emit an `<eagle-summary>` so Eagle Mem captures the
+  decision and files touched.
+
+## Reference
+
+```bash
+eagle-mem orchestrate                           # status
+eagle-mem orchestrate --json                    # lane JSON
+eagle-mem orchestrate init "Goal"
+eagle-mem orchestrate lane add <key> --agent codex --desc "Scope"
+eagle-mem orchestrate spawn <key>                # worktree + worker process
+eagle-mem orchestrate sync [key]                 # reconcile worker state
+eagle-mem orchestrate lane start <key>
+eagle-mem orchestrate lane block <key> --notes "Blocker"
+eagle-mem orchestrate lane complete <key> --notes "Validation passed"
+eagle-mem orchestrate complete
+eagle-mem orchestrate handoff --write docs/handoff-context.md
+```

package/skills/eagle-mem-tasks/SKILL.md

@@ -10,9 +10,9 @@ description: >
 
 ## Purpose
 
-**For the user:** Multi-step work doesn't get lost when Claude Code compacts. A 6-task implementation plan survives intact across compactions — no re-explaining what was decided, no drift from the original direction.
+**For the user:** Multi-step work doesn't get lost when Claude Code or Codex compacts. A 6-task implementation plan survives intact across compactions — no re-explaining what was decided, no drift from the original direction.
 
-**For you (Claude Code):** Each task description is a message to a future context window with ZERO memory of what happened before. After compaction, SessionStart re-injects pending/in-progress tasks from Eagle Mem's `claude_tasks` table. That re-injected text is all the next context window gets. If the description says "implement auth middleware," the next window has nothing to work with. If it says "implement auth middleware — JWT with RS256, sessions in Redis, errors use RFC 7807 format (decided in task 1)," the next window can execute immediately.
+**For you:** Each task description is a message to a future context window with ZERO memory of what happened before. After compaction, SessionStart re-injects pending/in-progress tasks from Eagle Mem's `agent_tasks` table. That re-injected text is all the next context window gets. If the description says "implement auth middleware," the next window has nothing to work with. If it says "implement auth middleware — JWT with RS256, sessions in Redis, errors use RFC 7807 format (decided in task 1)," the next window can execute immediately.
 
 ## Judgment
 
@@ -26,6 +26,8 @@ description: >
 - The work fits in one context window — just do it directly
 - It's a single-file fix or a quick question
 - The user is exploring, not building (use search/overview instead)
+- The work needs parallel agent lanes or ownership across Claude Code and Codex
+  (use `eagle-mem-orchestrate` instead)
 
 ## Steps
 
@@ -42,12 +44,12 @@ Break the request into tasks that are each completable in one context window. Th
 
 ### 2. Create — write self-contained descriptions
 
-Use `TaskCreate` for each task. The description is the most important field — it must carry forward every decision from the planning conversation.
+Use the agent-native task mechanism when available. In Claude Code, use `TaskCreate`. In Codex, use `update_plan` for the live UI and `eagle-mem tasks add --agent codex` for durable cross-session task records. The description is the most important field — it must carry forward every decision from the planning conversation.
 
 **Context transfer pattern:** For each task, ask: "If I read only this description with zero prior context, can I execute it?" If not, add what's missing.
 
 ```
-TaskCreate:
+TaskCreate / eagle-mem tasks add:
   subject: "Add JWT auth middleware"
   description: "Add Express middleware that validates JWT tokens on protected
     routes. Decisions: RS256 algorithm, public key from env JWT_PUBLIC_KEY,
@@ -60,15 +62,15 @@ TaskCreate:
 
 ### 3. Execute — one task at a time
 
-`TaskUpdate(in_progress)` on the current task. Do the work. Stay focused on that task — don't drift into adjacent tasks.
+Mark the current task in progress (`TaskUpdate(in_progress)` in Claude Code, or `eagle-mem tasks start <id> --agent codex` in Codex). Do the work. Stay focused on that task — don't drift into adjacent tasks.
 
 ### 4. Complete — record what happened
 
-`TaskUpdate(completed)`. Emit `<eagle-summary>` so Eagle Mem captures what was accomplished.
+Mark the task completed (`TaskUpdate(completed)` in Claude Code, or `eagle-mem tasks complete <id> --agent codex` in Codex). Emit `<eagle-summary>` so Eagle Mem captures what was accomplished.
 
 If the task produced decisions that downstream tasks need, update those task descriptions now:
 ```
-TaskUpdate:
+TaskUpdate / update durable task description:
   taskId: "3"
   description: "...original description... Note from task 2: the user table
     uses UUID primary keys, not auto-increment. Auth tokens table FKs to
@@ -90,7 +92,7 @@ After compaction, SessionStart re-injects all pending/in-progress tasks. Pick th
 **A task fails or produces unexpected results:** Update the task description with what was learned and what went wrong. Don't just retry blindly — the description should carry the failure context so the next attempt (or the next context window) doesn't repeat the same mistake.
 
 ```
-TaskUpdate:
+TaskUpdate / task record update:
   taskId: "4"
   description: "...original description... FAILED ATTEMPT: Prisma migrate
     errored because the users table already has a conflicting unique
@@ -102,11 +104,11 @@ TaskUpdate:
 
 ## The compact cycle — how task state survives
 
-1. You call `TaskCreate`/`TaskUpdate` (Claude Code's native task tools)
-2. Claude Code writes task JSON to `~/.claude/tasks/$session_id/*.json`
-3. Eagle Mem's PostToolUse hook fires, mirrors the task into the `claude_tasks` FTS5 table
-4. SessionEnd hook does a final sweep to catch any status changes missed by hooks
-5. On compaction (or new session), SessionStart queries `claude_tasks` for pending/in-progress tasks from the last 7 days and injects them into context
+1. Claude Code path: you call `TaskCreate`/`TaskUpdate`; Claude Code writes task JSON to `~/.claude/tasks/$session_id/*.json`; Eagle Mem mirrors it.
+2. Codex path: you call `update_plan` for live progress and `eagle-mem tasks add/start/complete --agent codex` for durable records.
+3. Eagle Mem stores both paths in the shared `agent_tasks` FTS5 table with `origin_agent`.
+4. SessionEnd does a final Claude Code task sweep where native task files exist.
+5. On compaction (or new session), SessionStart queries `agent_tasks` for pending/in-progress tasks from the last 7 days and injects them into context.
 
 The task descriptions you write ARE the context that survives. Everything else — your reasoning, the conversation, the files you read — gets compacted away.
 
@@ -126,14 +128,20 @@ The bad version forces the next context window to re-discover every decision. Th
 ## Reference
 
 ```bash
-# Viewing tasks (read-only — Eagle Mem mirrors, doesn't manage)
+# Viewing tasks
 eagle-mem tasks                # pending/in-progress for current project
 eagle-mem tasks list           # all tasks (including completed)
 eagle-mem tasks completed      # completed tasks only
 eagle-mem tasks search <q>     # FTS5 search across task history
 eagle-mem tasks --json         # JSON output for scripting
 
-# Claude Code task tools (these are what you actually use)
+# Codex durable task records
+eagle-mem tasks add "Implement auth middleware" --agent codex --desc "Use RS256, Redis sessions, RFC 7807 errors"
+eagle-mem tasks update <id> --agent codex --desc "New context or failure details"
+eagle-mem tasks start <id> --agent codex
+eagle-mem tasks complete <id> --agent codex
+
+# Claude Code task tools
 TaskCreate                     # create a new task
 TaskUpdate                     # update status, description, dependencies
 ```