From bac335274d05520fcbfcaf03d5711b3e63f93f6f Mon Sep 17 00:00:00 2001 From: "glm-5.1" Date: Sun, 26 Apr 2026 05:46:20 +0000 Subject: [PATCH] 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. --- .opencode/agents/code-reviewer.md | 12 ++ .opencode/agents/coordinator.md | 198 ++++++++++-------- .opencode/agents/implementation-specialist.md | 92 ++++++-- .opencode/agents/poc-specialist.md | 46 +++- AGENTS.md | 29 ++- docs/sdd_process.md | 79 ++++--- 6 files changed, 309 insertions(+), 147 deletions(-) diff --git a/.opencode/agents/code-reviewer.md b/.opencode/agents/code-reviewer.md index bd6cc5a..7b87a77 100644 --- 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: diff --git a/.opencode/agents/coordinator.md b/.opencode/agents/coordinator.md index 8c6044d..7b7aeb6 100644 --- 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/ - - 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 --agent implementation-specialist "Your task: " - -# 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 --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 --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 --agent ` | `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 diff --git a/.opencode/agents/implementation-specialist.md b/.opencode/agents/implementation-specialist.md index 23eaa9f..f7edc9c 100644 --- 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//` +**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/` - 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// -git branch --show-current # Should show: feat/ +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//" }) +# ✅ 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 . - Tests: , all passing ``` -### 6. Commit +### 6. Commit and Notify ```bash # Stage and commit from worktree @@ -116,6 +143,11 @@ git commit -m "feat(): " git push origin $(git branch --show-current) ``` +```text +# Notify coordinator of completion +worktree({action: "notify", args: {message: "Task completed: ", 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(): " git push origin $(git branch --show-current) ``` -5. **Exit** - coordinator handles escalation +5. **Notify coordinator**: + ```text + worktree({action: "notify", args: {message: "Blocked on : ", 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//" +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 \ No newline at end of file +5. **Worktree isolation** - never touch files outside your worktree +6. **Communicate** - use `worktree({action: "notify", ...})` to keep coordinator informed \ No newline at end of file diff --git a/.opencode/agents/poc-specialist.md b/.opencode/agents/poc-specialist.md index 1d4c1c4..91b3892 100644 --- 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//` +**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/` - Use relative paths for all file operations **Verify (optional):** ```bash -pwd # Should show: /workspace/@alkdev/alkhub_ts/.worktrees/research// +pwd # Should show your worktree path git branch --show-current # Should show: research/ ``` +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//" }) +# ✅ 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(): POC for " git push origin $(git branch --show-current) ``` +```text +# Notify coordinator of completion +worktree({action: "notify", args: {message: "POC completed: ", level: "info"}}) +``` + ## POC Guidelines ### Do @@ -149,7 +177,11 @@ git push origin $(git branch --show-current) 1. **Document current state** in `poc//README.md` 2. **Update task**: `status: blocked` 3. **Commit and push** -4. **Exit** +4. **Notify coordinator**: + ```text + worktree({action: "notify", args: {message: "Blocked on : ", level: "blocking"}}) + ``` +5. **Exit** ## Key Principles diff --git a/AGENTS.md b/AGENTS.md index 773f171..2529fdd 100644 --- 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. \ No newline at end of file diff --git a/docs/sdd_process.md b/docs/sdd_process.md index 72ad675..c101bf6 100644 --- 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//` → Implementation Specialist - Research POCs: `.worktrees/research//` → 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/ + 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 --agent implementation-specialist "Your task: " +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