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.
This commit is contained in:
2026-04-26 05:46:20 +00:00
parent 6d391e3ad8
commit bac335274d
6 changed files with 309 additions and 147 deletions

View File

@@ -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