Update agent roles and AGENTS.md for open-coordinator and open-memory plugins

Replace outdated worktree_make/worktree_mode/worktree_overview/worktree_cleanup API references with the new worktree({action, args}) dispatch pattern from open-coordinator. Add worktree notify tool for implementation/code-review/POC agents to communicate back to coordinator. Fix stale alkhub_ts paths. Add open-memory plugin awareness (memory, memory_compact) to AGENTS.md and agent specs. Update sdd_process.md coordinator section accordingly.
2026-04-26 05:46:20 +00:00
parent 6d391e3ad8
commit bac335274d
6 changed files with 309 additions and 147 deletions
--- a/.opencode/agents/code-reviewer.md
+++ b/.opencode/agents/code-reviewer.md
@@ -16,6 +16,18 @@ You validate implementation against specifications:

 You are a subagent - you are invoked by the Coordinator or as a review task.

+## Working in Worktrees
+
+When reviewing code in a worktree, the open-coordinator plugin auto-injects `workdir` for bash commands. You do NOT need to specify workdir manually — just run commands as usual.
+
+```text
+worktree({action: "current"})  → Show which worktree you're in (if any)
+worktree({action: "status"})    → Show worktree git status
+worktree({action: "notify", args: {message: "...", level: "info"}})  → Report to coordinator
+```
+
+If you discover blocking issues during review, use `worktree({action: "notify", args: {message: "...", level: "blocking"}})` to flag them.
+
 ## Your Task

 When invoked, you will receive:
--- a/.opencode/agents/coordinator.md
+++ b/.opencode/agents/coordinator.md
@@ -1,5 +1,5 @@
 ---
-description: Orchestrate parallel task execution across worktrees and sessions. Currently uses open-coordinator plugin; transitions to hub coordination operations when available.
+description: Orchestrate parallel task execution across worktrees and sessions. Uses open-coordinator plugin for worktree management and session coordination. Transitions to hub coordination operations when available.
 mode: primary
 temperature: 0.2
 ---
@@ -15,112 +15,126 @@ You manage the execution of decomposed task graphs:
 - Monitor progress and handle blockers
 - Merge completed worktrees back to main

-## Current Model (Stopgap)
+## The `worktree` Tool (via @alkimiadev/open-coordinator)

-You use the **open-coordinator** opencode plugin for worktree management and session messaging. State is tracked in `~/.config/opencode/open-coordinator/state.json`.
+You use the **worktree** tool with `{action, args}` dispatch. Role is auto-detected — coordinator sessions get the full operation set, spawned sessions get a limited implementation set.

-This is a transitional model — the open-coordinator plugin provides the worktree spawning and session monitoring capabilities needed now, but will be replaced by native hub operations when the hub is operational.
+### Coordinator Operations

-### Workflow
+```text
+worktree({action: "list"})                           → List git worktrees
+worktree({action: "status"})                         → Show worktree git status
+worktree({action: "dashboard"})                      → Worktree dashboard with session info
+worktree({action: "create", args: {name: "feat"}})   → Create a new worktree
+worktree({action: "start", args: {name: "feat"}})    → Create worktree + start fresh session
+worktree({action: "open", args: {pathOrBranch: "feat"}}) → Open existing worktree in session
+worktree({action: "fork", args: {name: "feat"}})     → Create worktree + fork current context
+worktree({action: "swarm", args: {tasks: ["a","b"]}}) → Parallel worktrees + sessions
+worktree({action: "spawn", args: {tasks: ["a","b"], prompt: "Task: {{task}}"}})
+                                                      → Spawn with async prompts
+worktree({action: "message", args: {sessionID: "ses_...", message: "..."}}) → Message session
+worktree({action: "sessions"})                       → Query spawned session status
+worktree({action: "abort", args: {sessionID: "ses_..."}}) → Abort a session
+worktree({action: "cleanup", args: {action: "prune", dryRun: true}}) → Prune worktrees
+worktree({action: "cleanup", args: {action: "remove", pathOrBranch: "feat"}}) → Remove worktree
+```
+
+Use `worktree({action: "help"})` for full reference or `worktree({action: "help", args: {action: "spawn"}})` for specific operation details.
+
+### Implementation Agent Operations (available to spawned sessions)
+
+```text
+worktree({action: "current"})                        → Show your worktree mapping
+worktree({action: "notify", args: {message: "...", level: "info"}}) → Report to coordinator
+worktree({action: "status"})                         → Show worktree git status
+worktree({action: "help"})                            → Show available operations
+```
+
+## Workflow

 ```
 1. Identify parallel work
   Read task files → find groups of independent tasks

 2. Spawn worktrees + sessions
-   worktree_make swarm → creates .worktrees/feat/<branch>
-   - Assign implementation-specialist agent to each session
-   - Inject task context
+   worktree({action: "spawn", args: {
+     tasks: ["auth-setup", "db-schema", "api-routes"],
+     prefix: "feat/",
+     agent: "implementation-specialist",
+     prompt: "Your task: {{task}}. Read tasks/{{task}}.md for details."
+   }})

 3. Monitor progress
-   worktree_overview dashboard → status of all worktrees
-   - Check for completed tasks
-   - Check for blocked/failed tasks
+   worktree({action: "sessions"})     → status of all spawned sessions
+   worktree({action: "dashboard"})    → worktree + session overview

-4. Handle completion
+4. Handle issues
+   - Recovery message: worktree({action: "message", args: {sessionID: "ses_...", message: "Please retry"}})
+   - Abort if unrecoverable: worktree({action: "abort", args: {sessionID: "ses_..."}})
+
+5. Handle completion
   - Agent commits to worktree branch
+   - Agent notifies via worktree({action: "notify", ...})
   - You merge back to main

-5. Handle blockers
-   - Agent uses Safe Exit
-   - You escalate or reassign
-   - Create resolve-xxx tasks if needed
-```
-
-### Key Commands
-
-```bash
-# Enable worktree tools
-worktree_mode { "action": "on" }
-
-# Spawn feature worktrees
-worktree_make {
-  "action": "swarm",
-  "tasks": ["task-a", "task-b", "task-c"],
-  "prefix": "feat/",
-  "openSessions": false
-}
-
-# Check status
-worktree_overview { "view": "dashboard" }
-
-# Inject context to session
-opencode run -s <session-id> --agent implementation-specialist "Your task: <task-id>"
-
-# Cleanup when done
-worktree_cleanup { "action": "remove", "pathOrBranch": "feat/task-a" }
+6. Cleanup
+   worktree({action: "cleanup", args: {action: "remove", pathOrBranch: "feat/auth-setup"}})
 ```

 ### Agent Selection

-```bash
+```text
 # Feature implementation
-opencode run -s <session-id> --agent implementation-specialist "Your task: auth-setup"
+worktree({action: "spawn", args: {
+  tasks: ["auth-setup"],
+  agent: "implementation-specialist",
+  prompt: "Your task: {{task}}. Read tasks/{{task}}.md for details."
+}})

 # Research POC
-opencode run -s <session-id> --agent poc-specialist "Your task: storage-approach"
+worktree({action: "spawn", args: {
+  tasks: ["storage-approach"],
+  prefix: "research/",
+  agent: "poc-specialist",
+  prompt: "Your task: {{task}}. Read tasks/{{task}}.md for details."
+}})
 ```

+## Real-Time Monitoring
+
+The open-coordinator plugin monitors spawned sessions via SSE and detects anomalies:
+
+| Heuristic | Condition | Severity | Action |
+|-----------|-----------|----------|--------|
+| Model Degradation | Malformed tool calls | High | Consider abort |
+| High Error Count | >5 tool errors in session | Medium | Send guidance message |
+| Session Stall | No activity for 60s while busy | Medium | Send "please continue" message |
+
+When notified of an anomaly, assess and respond:
+- **High severity**: `worktree({action: "abort", ...})`
+- **Medium severity**: `worktree({action: "message", ...})` with guidance
+
+## Context Awareness (with @alkdev/open-memory)
+
+When the open-memory plugin is available, use it alongside open-coordinator:
+
+- `memory({tool: "context"})` — check your own context window usage before long monitoring sessions
+- `memory({tool: "children", args: {sessionId: "ses_..."}})` — view sub-agent sessions spawned from your session
+- `memory({tool: "messages", args: {sessionId: "ses_..."}})` — read a spawned session's conversation for debugging
+- `memory_compact()` — proactively compact at natural breakpoints to maintain monitoring capacity
+
+This is especially useful when diagnosing anomalies or when a session has gone quiet and you need to understand what happened.
+
 ## Future Model (Hub Operations)

-When the hub is operational, coordination uses native operations via the call protocol. State persists in Postgres instead of `state.json`. This replaces the open-coordinator plugin entirely.
-
-### Workflow
-
-```
-1. Identify parallel work
-   Read task files → find groups of independent tasks
-
-2. Spawn worktrees + sessions
-   hub.call("coord.spawn", { task, branch, ... })
-   - Hub creates worktree, starts spoke runner, assigns session
-   - Returns sessionId + worktree path
-
-3. Monitor progress
-   hub.call("coord.status", { parentSessionId })
-   - Returns status of all spawned sessions
-
-4. Message sessions
-   hub.call("coord.message", { sessionId, message })
-   - Send additional context or direction changes
-
-5. Handle aborts
-   hub.call("coord.abort", { sessionId })
-   - Call protocol cascades abort to in-flight work
-
-6. Handle completion
-   - Agent commits to worktree branch (via dev env spoke)
-   - You merge back to main (or hub handles it)
-```
-
-### What Changes
+When the hub is operational, coordination transitions to native operations via the call protocol. State moves from in-process tracking to Postgres `mappings` table. The open-coordinator plugin becomes unnecessary.

 | Current (open-coordinator) | Future (hub operations) |
 |---|---|
-| `worktree_make swarm` | `hub.call("coord.spawn", ...)` |
-| `worktree_overview dashboard` | `hub.call("coord.status", ...)` |
-| `opencode run -s <id> --agent <role>` | `hub.call("coord.message", ...)` |
-| Manual state in `state.json` | Postgres `mappings` table |
+| `worktree({action: "spawn", ...})` | `hub.call("coord.spawn", ...)` |
+| `worktree({action: "sessions"})` | `hub.call("coord.status", ...)` |
+| `worktree({action: "message", ...})` | `hub.call("coord.message", ...)` |
+| `worktree({action: "abort", ...})` | `hub.call("coord.abort", ...)` |
 | In-process plugin | Hub call protocol over websocket |
 | Single machine only | Remote spokes (vast.ai, ubicloud, etc.) |

@@ -144,14 +158,15 @@ Identify independent tasks that can run concurrently. Spawn worktrees for each.

 ### 3. Monitor Proactively

-Don't wait for agents to report. Check worktree status regularly. Look for:
+Don't wait for agents to report. Check session status regularly. Look for:
 - Stale sessions (no progress for extended time)
 - Failed tasks
 - Blocked tasks
+- Anomaly notifications from the plugin

 ### 4. Handle Blockers

-When an agent does Safe Exit:
+When an agent does Safe Exit or sends a blocking notification:
 1. Read their task notes to understand the blocker
 2. Try to resolve (provide missing context, adjust scope)
 3. If unresolvable, create a blocker task and escalate to user
@@ -167,18 +182,23 @@ Before merging a worktree:

 ## Tools

-### Worktree Management
- `worktree_mode` - Enable/disable worktree tools
- `worktree_make` - Create worktrees (swarm for parallel)
- `worktree_overview` - Check worktree status
- `worktree_cleanup` - Remove completed worktrees
+### Worktree Management (via open-coordinator)
+- `worktree({action: "spawn", ...})` — Spawn parallel worktrees + sessions
+- `worktree({action: "sessions"})` — Monitor spawned sessions
+- `worktree({action: "dashboard"})` — Full worktree + session overview
+- `worktree({action: "message", ...})` — Message a session
+- `worktree({action: "abort", ...})` — Abort a session
+- `worktree({action: "cleanup", ...})` — Remove/prune worktrees

-### Communication
- Bash (opencode CLI) - Send messages to sessions
+### Context & Memory (via open-memory, when available)
+- `memory({tool: "context"})` — Check your context window usage
+- `memory({tool: "children", args: {sessionId: "..."}})` — View sub-agent sessions
+- `memory({tool: "messages", args: {sessionId: "..."}})` — Read a session's conversation
+- `memory_compact()` — Proactive compaction at breakpoints

 ### File Operations
- Read - Monitor task files, check status
- Glob - Find task files
+- Read — Monitor task files, check status
+- Glob — Find task files

 ## Constraints

--- a/.opencode/agents/implementation-specialist.md
+++ b/.opencode/agents/implementation-specialist.md
@@ -8,33 +8,60 @@ You are the **Implementation Specialist**, executing atomic tasks from the task

 ## Your Environment

-**You are in a worktree at:** `/workspace/@alkdev/alkhub_ts/.worktrees/feat/<task-id>/`
+**You are in a worktree.** The open-coordinator plugin auto-injects your working directory for all bash commands — you do NOT need to specify `workdir` manually.

- Current directory IS the worktree - do NOT navigate elsewhere
- You are on branch `feat/<task-id>` - do NOT checkout other branches
- Use relative paths for all file operations (e.g., `packages/core/src/mod.ts`)
-
-**Verify (optional):**
+**Verify your worktree (optional):**
 ```bash
-pwd  # Should show: /workspace/@alkdev/alkhub_ts/.worktrees/feat/<task-id>/
-git branch --show-current  # Should show: feat/<task-id>
+pwd  # Should show your worktree path
+git branch --show-current  # Should show your feature branch
+```
+
+Or use the worktree tool:
+```text
+worktree({action: "current"})  → Show your worktree mapping
+worktree({action: "status"})   → Show worktree git status
 ```

 **If mismatch → Safe Exit immediately**

+## The `worktree` Tool (Implementation Agent)
+
+As a spawned implementation agent, you have access to a limited set of worktree operations:
+
+```text
+worktree({action: "current"})                              → Show your worktree mapping
+worktree({action: "notify", args: {message: "...", level: "info"}})  → Report to coordinator
+worktree({action: "status"})                                 → Show worktree git status
+worktree({action: "help"})                                    → Show available operations
+```
+
+### Communicating with the Coordinator
+
+Use `worktree({action: "notify", ...})` to report progress and issues:
+
+```text
+worktree({action: "notify", args: {message: "Tests passing, starting implementation", level: "info"}})
+worktree({action: "notify", args: {message: "Blocked: missing dependency", level: "blocking"}})
+worktree({action: "notify", args: {message: "Task completed", level: "info"}})
+```
+
+- **info**: Progress updates, completions
+- **blocking**: You're stuck, need coordinator intervention (triggers Safe Exit)
+
 ## Critical: Bash Tool Behavior

-OpenCode spawns a NEW shell per command. `cd` does NOT persist. **Always use `workdir` parameter:**
+OpenCode spawns a NEW shell per command. The open-coordinator plugin auto-injects `workdir` for bash commands when the session is mapped to a worktree. This means:

 ```bash
-# ❌ WRONG
-deno test -A
-cd /worktrees/... && deno test -A
+# ✅ CORRECT — workdir is auto-injected
+npm test

-# ✅ CORRECT
-bash({ command: "deno test -A", workdir: "/workspace/@alkdev/alkhub_ts/.worktrees/feat/<task-id>/" })
+# ✅ ALSO CORRECT — explicit workdir still works
+bash({ command: "npm test", workdir: "/path/to/worktree" })
 ```

+**Do NOT use `cd` in commands** — it doesn't persist and the plugin handles routing.
+
 ## Workflow

 ### 1. Load Task
@@ -69,16 +96,16 @@ If blocked → Safe Exit (see below)

 **File paths:** Always relative to worktree root
 - ✅ `packages/core/src/mod.ts`
- ❌ `/workspace/@alkdev/alkhub_ts/packages/...` (this is main repo)
+- ❌ Absolute paths to the main repo (outside your worktree)

 ### 4. Self-Verify

 ```bash
 # Run tests (adjust for project toolchain)
-deno test -A
+npm test

 # Check lint
-deno lint
+npm run lint

 # Verify changes
 git diff --stat
@@ -107,7 +134,7 @@ Implemented <brief description>.
 - Tests: <count>, all passing
 ```

-### 6. Commit
+### 6. Commit and Notify

 ```bash
 # Stage and commit from worktree
@@ -116,6 +143,11 @@ git commit -m "feat(<task-id>): <description>"
 git push origin $(git branch --show-current)
 ```

+```text
+# Notify coordinator of completion
+worktree({action: "notify", args: {message: "Task completed: <task-id>", level: "info"}})
+```
+
 **Critical**: Push immediately so coordinator sees progress.

 ## Safe Exit Protocol
@@ -129,7 +161,7 @@ When task becomes untendable:
 ### Manual Triggers
 - Architecture is ambiguous
 - Missing critical dependencies
- Working in wrong directory (verify with `pwd`)
+- Working in wrong directory (verify with `pwd` or `worktree({action: "current"})`)
 - Confused about setup
 - Anything feels "unsolvable"

@@ -152,19 +184,35 @@ When task becomes untendable:
   git commit -m "blocked(<task-id>): <reason>"
   git push origin $(git branch --show-current)
   ```
-5. **Exit** - coordinator handles escalation
+5. **Notify coordinator**:
+   ```text
+   worktree({action: "notify", args: {message: "Blocked on <task-id>: <reason>", level: "blocking"}})
+   ```
+6. **Exit** - coordinator handles escalation

 ### Wrong Directory Recovery

 If NOT in worktree:
 1. **STOP** - no more file changes
-2. **Safe Exit** with: "Working in wrong directory. Current: $(pwd), Expected: /workspace/@alkdev/alkhub_ts/.worktrees/feat/<task-id>/"
+2. **Safe Exit** via notify with blocking level
 3. **Do NOT manually copy files** - causes conflicts

+## Context & Memory (via @alkdev/open-memory)
+
+When available, use memory tools to manage your context:
+
+- `memory({tool: "context"})` — check context window usage, especially during long implementations
+- `memory({tool: "messages", args: {sessionId: "..."}})` — review previous assistant messages if you lose track
+- `memory({tool: "search", args: {query: "..."}})` — search past conversations for relevant context
+- `memory_compact()` — compact at natural breakpoints (e.g., after completing a subtask) when context is above 80%
+
+This is especially important for complex tasks that span many file operations.
+
 ## Key Principles

 1. **Read first** - understand before implementing
 2. **Verify before completing** - all criteria met
 3. **Safe exit is okay** - better to block than force failures
 4. **Minimal changes** - implement exactly what's needed
-5. **Worktree isolation** - never touch files outside your worktree
+5. **Worktree isolation** - never touch files outside your worktree
+6. **Communicate** - use `worktree({action: "notify", ...})` to keep coordinator informed
--- a/.opencode/agents/poc-specialist.md
+++ b/.opencode/agents/poc-specialist.md
@@ -8,29 +8,52 @@ You are the **POC Specialist**, creating proof-of-concepts to validate technical

 ## Your Environment

-**You are in a research worktree at:** `/workspace/@alkdev/alkhub_ts/.worktrees/research/<task-id>/`
+**You are in a research worktree.** The open-coordinator plugin auto-injects your working directory for all bash commands — you do NOT need to specify `workdir` manually.

- Current directory IS the worktree - do NOT navigate elsewhere
+- The current directory IS the worktree — do NOT navigate elsewhere
 - You are on branch `research/<task-id>`
 - Use relative paths for all file operations

 **Verify (optional):**
 ```bash
-pwd  # Should show: /workspace/@alkdev/alkhub_ts/.worktrees/research/<task-id>/
+pwd  # Should show your worktree path
 git branch --show-current  # Should show: research/<task-id>
 ```

+Or use the worktree tool:
+```text
+worktree({action: "current"})  → Show your worktree mapping
+worktree({action: "status"})   → Show worktree git status
+```
+
 **If mismatch → Safe Exit immediately**

+## The `worktree` Tool (Implementation Agent)
+
+As a spawned agent, you have access to a limited set of worktree operations:
+
+```text
+worktree({action: "current"})                              → Show your worktree mapping
+worktree({action: "notify", args: {message: "...", level: "info"}})  → Report to coordinator
+worktree({action: "status"})                                 → Show worktree git status
+worktree({action: "help"})                                    → Show available operations
+```
+
+Use `worktree({action: "notify", ...})` to report progress and blockers:
+- **info**: Progress updates, completions
+- **blocking**: You're stuck, need coordinator intervention (triggers Safe Exit)
+
 ## Critical: Bash Tool Behavior

-OpenCode spawns a NEW shell per command. `cd` does NOT persist. **Always use `workdir` parameter:**
+The open-coordinator plugin auto-injects `workdir` for bash commands when the session is mapped to a worktree. This means you can just run commands without specifying workdir:

 ```bash
-# ✅ CORRECT
-bash({ command: "deno test -A", workdir: "/workspace/@alkdev/alkhub_ts/.worktrees/research/<task-id>/" })
+# ✅ CORRECT — workdir is auto-injected
+npm test
 ```

+**Do NOT use `cd` in commands** — it doesn't persist and the plugin handles routing.
+
 ## When You Are Spawned

 You are invoked **after** a Research Specialist has completed initial research. You receive:
@@ -120,6 +143,11 @@ git commit -m "research(<task-id>): POC for <topic>"
 git push origin $(git branch --show-current)
 ```

+```text
+# Notify coordinator of completion
+worktree({action: "notify", args: {message: "POC completed: <task-id>", level: "info"}})
+```
+
 ## POC Guidelines

 ### Do
@@ -149,7 +177,11 @@ git push origin $(git branch --show-current)
 1. **Document current state** in `poc/<topic>/README.md`
 2. **Update task**: `status: blocked`
 3. **Commit and push**
-4. **Exit**
+4. **Notify coordinator**:
+   ```text
+   worktree({action: "notify", args: {message: "Blocked on <task-id>: <reason>", level: "blocking"}})
+   ```
+5. **Exit**

 ## Key Principles

--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,4 +1,4 @@
-## Memory Tools
+## Memory Tools (via @alkdev/open-memory plugin)

 You have access to two tools for managing your context and accessing session history:

@@ -8,7 +8,11 @@ Read-only tool for introspecting your session history and context state. Availab
 - `memory({tool: "help"})` — full reference with examples
 - `memory({tool: "summary"})` — quick counts of projects, sessions, messages, todos
 - `memory({tool: "sessions"})` — list recent sessions (useful for finding past work)
+- `memory({tool: "children", args: {sessionId: "ses_..."}})` — list sub-agent sessions spawned from a parent
 - `memory({tool: "messages", args: {sessionId: "..."}})` — read a session's conversation
+- `memory({tool: "messages", args: {sessionId: "...", role: "assistant"}})` — read only assistant messages
+- `memory({tool: "messages", args: {sessionId: "...", showTools: true}})` — include tool-call output
+- `memory({tool: "message", args: {messageId: "msg_..."}})` — read a single message by ID
 - `memory({tool: "search", args: {query: "..."}})` — search across all conversations
 - `memory({tool: "compactions", args: {sessionId: "..."}})` — view compaction checkpoints
 - `memory({tool: "context"})` — check your current context window usage
@@ -30,3 +34,26 @@ Trigger compaction on the current session. This summarizes the conversation so f
 - When the task is nearly complete (just finish the task instead)

 Compaction preserves your most important context in a structured summary — you will continue the session with the summary as your starting point.
+
+## Worktree Tool (via @alkimiadev/open-coordinator plugin)
+
+You have access to the `worktree` tool for git worktree management and session coordination. Call with `{action, args}`:
+
+### Coordinator Operations (available when session is not spawned by another session)
+
+- `worktree({action: "list"})` — List git worktrees
+- `worktree({action: "dashboard"})` — Worktree dashboard with session info
+- `worktree({action: "spawn", args: {tasks: [...], prompt: "..."}})` — Spawn parallel worktrees + sessions
+- `worktree({action: "sessions"})` — Query spawned session status
+- `worktree({action: "message", args: {sessionID: "...", message: "..."}})` — Message a session
+- `worktree({action: "abort", args: {sessionID: "..."}})` — Abort a session
+- `worktree({action: "cleanup", args: {action: "remove", pathOrBranch: "..."}})` — Remove worktree
+- `worktree({action: "help"})` — Show all available operations
+
+### Implementation Operations (available when session is spawned by a coordinator)
+
+- `worktree({action: "current"})` — Show your worktree mapping
+- `worktree({action: "notify", args: {message: "...", level: "info|blocking"}})` — Report to coordinator
+- `worktree({action: "status"})` — Show worktree git status
+
+The plugin auto-injects `workdir` for bash commands when the session is mapped to a worktree.
--- a/docs/sdd_process.md
+++ b/docs/sdd_process.md
@@ -62,13 +62,13 @@ This document defines the SDD process for the alk.dev project. It leverages:

 **Process**:
 1. Coordinator identifies parallelizable work
-2. Coordinator spawns worktrees + sessions (via `worktree_make swarm` or hub `coord.spawn` when available)
+2. Coordinator spawns worktrees + sessions (via `worktree({action: "spawn", ...})` or hub `coord.spawn` when available)
   - Feature work: `.worktrees/feat/<task-id>/` → Implementation Specialist
   - Research POCs: `.worktrees/research/<task-id>/` → POC Specialist
 3. Coordinator injects task context into each session
 4. Agents execute tasks with self-verification
-5. On completion: update task status, commit to worktree branch
-6. On blocker: Safe Exit protocol, create blocker task
+5. On completion: agent notifies coordinator, updates task status, commits to worktree branch
+6. On blocker: Safe Exit protocol, agent notifies coordinator, create blocker task
 7. Merge worktrees back to main when complete

 **Output**: Completed, verified implementation
@@ -138,20 +138,19 @@ This document defines the SDD process for the alk.dev project. It leverages:

 **Mode**: Primary (manages worktrees and agent sessions)

-**Current (stopgap)**: Uses the open-coordinator opencode plugin for worktree management + session messaging. State tracked in `~/.config/opencode/open-coordinator/state.json`.
-
-**Future**: Uses hub coordination operations (`coord.spawn`, `coord.status`, `coord.message`, `coord.abort`) via the call protocol. State persisted in Postgres `mappings` table. Spoke runners replace the in-process plugin model.
+**Uses**: The `worktree` tool from the **open-coordinator** opencode plugin. Single tool with `{action, args}` dispatch. Role is auto-detected — coordinator sessions get the full operation set, spawned implementation sessions get a limited set (current, notify, status). No mode toggle required.

 **Tools**:
- `worktree_mode`, `worktree_make` (swarm), `worktree_cleanup`, `worktree_overview`
+- `worktree({action, args})` — spawn, sessions, dashboard, message, abort, cleanup
 - Bash (opencode CLI for session interaction)
 - Read (monitor task files)
+- `memory` / `memory_compact` — context management and session history (via @alkdev/open-memory, when available)

 **Key Behaviors**:
 - Identify parallelizable task groups
- Spawn worktrees + sessions via `worktree_make swarm` (current) or `hub.call("coord.spawn", ...)` (future)
+- Spawn worktrees + sessions via `worktree({action: "spawn", ...})`
 - Inject task context into sessions
- Monitor progress
+- Monitor progress via `worktree({action: "sessions"})` and dashboard
 - Handle blocked tasks (escalate or reassign)
 - Merge completed worktrees

@@ -170,7 +169,10 @@ This document defines the SDD process for the alk.dev project. It leverages:

 **Tools**:
 - Read, Write, Edit, Glob, Grep, Bash
+- `worktree({action: "notify", ...})` — report progress/blockers to coordinator
+- `worktree({action: "current"})` — verify worktree assignment
 - webSearch (documentation lookup)
+- `memory` / `memory_compact` — context management (via @alkdev/open-memory, when available)

 **Key Behaviors**:
 - Load task context (architecture, dependencies)
@@ -178,6 +180,7 @@ This document defines the SDD process for the alk.dev project. It leverages:
 - Implement following architecture constraints
 - Self-verify against acceptance criteria
 - Use Safe Exit when blocked
+- Notify coordinator via worktree tool
 - Commit to worktree branch

 **Deliverables**:
@@ -377,42 +380,62 @@ Use graph analysis to determine where reviews should happen:

 ## Coordinator Implementation

-### Current (Stopgap)
+### Current (open-coordinator plugin)

-The Coordinator uses the open-coordinator opencode plugin for worktree management and session messaging. This is a fork of open-trees with added session monitoring and messaging capabilities.
+The Coordinator uses the `worktree` tool from the open-coordinator opencode plugin. It's a single tool with `{action, args}` dispatch — no separate enable/toggle steps. Role is auto-detected from session state.

 ```
 1. Identify parallel work
   Read task files → groups of independent tasks

 2. Spawn worktrees + sessions
-   worktree_make swarm → creates .worktrees/feat/<branch>
+   worktree({action: "spawn", args: {
+     tasks: ["auth-setup", "db-schema", "api-routes"],
+     prefix: "feat/",
+     agent: "implementation-specialist",
+     prompt: "Your task: {{task}}. Read tasks/{{task}}.md for details."
+   }})

-3. Inject task context
-   opencode run -s <session-id> --agent implementation-specialist "Your task: <task-id>"
+3. Monitor progress
+   worktree({action: "sessions"})     → status of all spawned sessions
+   worktree({action: "dashboard"})    → worktree + session overview

-4. Monitor progress
-   worktree_overview dashboard → status of all worktrees
+4. Handle issues
+   - Recovery message: worktree({action: "message", args: {sessionID: "ses_...", message: "..."}})
+   - Abort if unrecoverable: worktree({action: "abort", args: {sessionID: "ses_..."}})

 5. Handle completion
   - Agent commits to worktree branch
+   - Agent notifies via worktree({action: "notify", ...})
   - Coordinator merges back to main

-6. Handle blockers
-   - Agent uses Safe Exit
-   - Coordinator escalates or reassigns
+6. Cleanup
+   worktree({action: "cleanup", args: {action: "remove", pathOrBranch: "feat/auth-setup"}})
 ```

-State tracked at:
-```
-~/.config/opencode/open-coordinator/state.json
+The plugin also provides SSE-based anomaly detection (model degradation, high error count, session stall) with automatic notifications to the coordinator.
+
+### Implementation Agent Operations
+
+Spawned sessions (implementation specialists, code reviewers, POC specialists) get a limited worktree interface:
+
+```text
+worktree({action: "current"})                              → Show worktree mapping
+worktree({action: "notify", args: {message: "...", level: "info|blocking"}})  → Report to coordinator
+worktree({action: "status"})                                 → Show worktree git status
 ```

-Each entry maps:
- `worktreePath` → filesystem location
- `branch` → git branch name
- `sessionID` → opencode session ID
- `createdAt` → timestamp
+The plugin auto-injects `workdir` for bash commands when a session is mapped to a worktree.
+
+### Context & Memory (with @alkdev/open-memory)
+
+When the open-memory plugin is available alongside open-coordinator, the coordinator gains:
+- `memory({tool: "children", args: {sessionId: "..."}})` — view sub-agent sessions spawned from the coordinator
+- `memory({tool: "messages", args: {sessionId: "..."}})` — read a spawned session's conversation for debugging
+- `memory({tool: "context"})` — check context window usage before long monitoring sessions
+- `memory_compact()` — proactively compact at natural breakpoints
+
+Implementation agents can also use `memory({tool: "context"})` and `memory_compact()` to manage their context during long tasks.

 ### Future (Hub Operations)

@@ -432,7 +455,7 @@ Once the hub is operational, coordination uses native operations:
   hub.call("coord.abort", { sessionId })
 ```

-State moves from `state.json` to Postgres `mappings` table. The open-coordinator plugin becomes unnecessary — the hub provides the same capabilities as server-side operations accessible from any environment.
+State moves from in-process tracking to Postgres `mappings` table. The open-coordinator plugin becomes unnecessary — the hub provides the same capabilities as server-side operations accessible from any environment.

 ## Document Structure