feat(opencode): Planning with KV + Planner → Lead merge #858
Conversation
…ructure
This commit introduces two major enhancements to the Agentuity Coder agent team:
## 1. Planning with KV Infrastructure
Added Manus-style persistent planning using KV storage:
- **Session Planning**: Active work tracking in session records with loose
planning section (objective, phases with rich notes, findings, errors,
blockers, prdKey linking to PRD)
- **PRD Coordination**: Product agent owns PRDs at project:{label}:prd which
define 'what' and 'why'. Session planning tracks 'how' and 'where we are'
- **Cadence Mode Flow**: Lead MUST involve Product first to establish PRD,
and involves Product at session end to update PRD
- **5-Question Reboot**: Memory uses this format for Cadence context recall
(Where am I? Where going? What's the goal? What learned? What done?)
- **Lead-of-Leads**: Parent Lead can spawn child Leads via background tasks
for parallel work, with PRD workstreams for coordination
## 2. Planner → Lead Merge
Merged the Planner agent into Lead, simplifying from 11 to 10 agents:
- Lead already had 'Technical Planning Is YOUR Job' and extended thinking
- Planner was a delegation convenience; Lead has all the context needed
- Eliminates a hop: Lead → Planner → Lead → Builder becomes Lead thinks → Builder
- Added Strategic Decision Framework guidance to Lead
- Extended thinking section now references Product's PRD for grounding
## Files Changed
### Agent Prompts
- lead.ts: Absorbed Planner capabilities, added planning infrastructure,
terminology clarifications (Technical Planning vs Product Planning)
- product.ts: Added PRD check/create workflow for Cadence, session end
updates, workstreams for parallel work
- memory.ts: Added loose planning schema, 5-Question Reboot format,
Session Planning vs PRD clarity
- scout.ts, builder.ts, architect.ts: Updated Planner references
### Infrastructure
- types.ts: Removed 'planner' from AgentRoleSchema
- agents/index.ts: Removed plannerAgent export
- plugin.ts: Removed from AGENT_MENTIONS
- delegate.ts: Removed from delegation tool
- keyword.ts: Removed from activation message
- cadence.ts, session-memory.ts: Enhanced compaction hooks with planning state
### Removed
- planner.ts: Deleted (capabilities merged into Lead)
## Agent Team (Now 10 Agents)
| Agent | Role |
|-----------|---------------------------------------------------|
| Lead | Orchestrates + technical planning (absorbed Planner) |
| Product | Defines what/why (requirements, PRDs, user value) |
| Scout | Explores codebase (read-only) |
| Builder | Implements (interactive) |
| Architect | Implements (autonomous, Cadence) |
| Reviewer | Reviews code quality |
| Memory | Stores/recalls context |
| Reasoner | Extracts conclusions |
| Expert | Agentuity CLI/cloud specialist |
| Runner | Runs commands |
📝 WalkthroughWalkthroughThis PR removes the Planner agent, adds a Monitor agent, elevates Lead to own planning responsibilities, introduces a Product role and a Lead-of-Leads orchestration pattern, and adds background-task inspection, recovery, and status refresh capabilities across hooks, tools, and docs. Changes
🚥 Pre-merge checks | ✅ 1✅ Passed checks (1 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. 🧹 Recent nitpick comments
📜 Recent review detailsConfiguration used: Organization UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🧰 Additional context used📓 Path-based instructions (1)**/*.{ts,tsx}📄 CodeRabbit inference engine (AGENTS.md)
Files:
🧠 Learnings (1)📚 Learning: 2025-12-21T00:31:41.858ZApplied to files:
🧬 Code graph analysis (1)packages/opencode/src/background/manager.ts (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (10)
🔇 Additional comments (4)
✏️ Tip: You can disable this entire section by setting Comment |
📦 Canary Packages Publishedversion: PackagesInstallAdd to your {
"dependencies": {
"@agentuity/drizzle": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-drizzle-1.0.1-4a1ed95.tgz",
"@agentuity/frontend": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-frontend-1.0.1-4a1ed95.tgz",
"@agentuity/core": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-core-1.0.1-4a1ed95.tgz",
"@agentuity/evals": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-evals-1.0.1-4a1ed95.tgz",
"@agentuity/workbench": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-workbench-1.0.1-4a1ed95.tgz",
"@agentuity/cli": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-cli-1.0.1-4a1ed95.tgz",
"@agentuity/react": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-react-1.0.1-4a1ed95.tgz",
"@agentuity/postgres": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-postgres-1.0.1-4a1ed95.tgz",
"@agentuity/runtime": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-runtime-1.0.1-4a1ed95.tgz",
"@agentuity/auth": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-auth-1.0.1-4a1ed95.tgz",
"@agentuity/opencode": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-opencode-1.0.1-4a1ed95.tgz",
"@agentuity/schema": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-schema-1.0.1-4a1ed95.tgz",
"@agentuity/server": "https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-server-1.0.1-4a1ed95.tgz"
}
}Or install directly: bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-drizzle-1.0.1-4a1ed95.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-frontend-1.0.1-4a1ed95.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-core-1.0.1-4a1ed95.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-evals-1.0.1-4a1ed95.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-workbench-1.0.1-4a1ed95.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-cli-1.0.1-4a1ed95.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-react-1.0.1-4a1ed95.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-postgres-1.0.1-4a1ed95.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-runtime-1.0.1-4a1ed95.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-auth-1.0.1-4a1ed95.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-opencode-1.0.1-4a1ed95.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-schema-1.0.1-4a1ed95.tgz
bun add https://agentuity-sdk-objects.t3.storageapi.dev/npm/1.0.1-4a1ed95/agentuity-server-1.0.1-4a1ed95.tgz |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
packages/opencode/src/plugin/hooks/session-memory.ts (1)
132-149:⚠️ Potential issue | 🟡 MinorAlign planning field list with cadence.ts and memory.ts schema: add
planning.currentandplanning.blockers; clarifyplanning.progress.The session-memory.ts list omits
planning.current(which is present in cadence.ts line 292) andplanning.blockers(referenced in memory.ts line 937). Additionally, step 2 referencesplanning.progressbut it's not listed in the fields section. Update the planning fields list to match the schema used elsewhere:🔧 Suggested update
**Planning State (if active):** If this session has planning active (user requested "track progress" or similar), the session record contains: - `planning.prdKey` - Link to PRD if one exists - `planning.objective` - What we're trying to accomplish - `planning.phases` - Current phases with status and notes +- `planning.current` - Current phase - `planning.findings` - Discoveries made during work - `planning.errors` - Failures to avoid repeating +- `planning.blockers` - Active blockers +- `planning.progress` - Compaction summary
🤖 Fix all issues with AI agents
In `@packages/opencode/README.md`:
- Around line 48-60: Add a short breaking-change callout above or directly below
the "Agent Team" heading stating that the Planner agent has been removed and
replaced by the Product/Lead split; mention potential migration steps (search
for "Planner" in configs, update references to "Lead" or "Product") and link to
any migration notes or changelog. Ensure the note is clearly labeled (e.g.,
"Breaking change: Planner removed") so readers searching the Agent Team table
will see it immediately.
In `@packages/opencode/src/agents/memory.ts`:
- Around line 913-935: The 5-Question Reboot markdown template references
planning.nextActions but the planning schema provides planning.next; update the
template in the Cadence Context Recall block to use planning.next (or map
planning.next to planning.nextActions before rendering) so the Next Actions
section pulls from the actual field; ensure the template placeholder for Next
Actions replaces "{from planning.nextActions}" with the correct
"{planning.next}" and adjust any rendering code that flattens/joins that array
into list items.
- Around line 359-394: The planning JSON example is missing the required PRD
linkage field; add a planning.prdKey property to the planning schema/example so
session plans can reference the PRD. Update the "planning" object (the one with
keys active, objective, current, next, phases, findings, errors, blockers) to
include a prdKey string (or nullable) with a brief comment/example value and
ensure any code that serializes/deserializes planning (e.g., memory read/write
handling for planning) expects and preserves planning.prdKey so PRD linkage is
consistently stored and recalled.
In `@packages/opencode/src/agents/product.ts`:
- Around line 146-206: The PRD example JSON blocks in
packages/opencode/src/agents/product.ts (the "Lightweight PRD" and "Full PRD"
examples) contain inline `//` comments which make them invalid JSON; remove
those `//` comments from inside the JSON objects (e.g., remove the "//
High-level phases - Lead tracks detailed progress in session planning" and "//
Only if Lead-of-Leads parallel work" notes) and instead place those notes as
plain text before or after the code blocks or as separate fields (e.g., add a
"notes" string/array outside the JSON) so the examples shown for
functions/processes that call kv set are valid JSON for direct copy/paste into
kv set.
🧹 Nitpick comments (1)
packages/opencode/src/plugin/hooks/cadence.ts (1)
287-300: Includeplanning.nextandplanning.blockersin the cadence compaction list.
This keeps the compaction prompt aligned with the 5‑Question Reboot (“Where going?”) and the overall planning schema used elsewhere.♻️ Suggested tweak
**Planning State:** If this session has planning active, the session record contains: - `planning.prdKey` - Link to the PRD being executed - `planning.objective` - What we're trying to accomplish - `planning.phases` - Current phases with status and notes - `planning.current` - Current phase +- `planning.next` - Next planned step - `planning.findings` - Discoveries made during work - `planning.errors` - Failures to avoid repeating +- `planning.blockers` - Active blockers
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (16)
packages/opencode/README.mdpackages/opencode/src/agents/architect.tspackages/opencode/src/agents/builder.tspackages/opencode/src/agents/index.tspackages/opencode/src/agents/lead.tspackages/opencode/src/agents/memory.tspackages/opencode/src/agents/planner.tspackages/opencode/src/agents/product.tspackages/opencode/src/agents/scout.tspackages/opencode/src/plugin/hooks/cadence.tspackages/opencode/src/plugin/hooks/keyword.tspackages/opencode/src/plugin/hooks/session-memory.tspackages/opencode/src/plugin/plugin.tspackages/opencode/src/tools/delegate.tspackages/opencode/src/types.tspackages/opencode/test/agents.test.ts
💤 Files with no reviewable changes (4)
- packages/opencode/src/types.ts
- packages/opencode/src/agents/index.ts
- packages/opencode/src/agents/planner.ts
- packages/opencode/src/tools/delegate.ts
🧰 Additional context used
📓 Path-based instructions (4)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx}: Use Prettier formatter with tabs (width 3), single quotes, and semicolons for TypeScript files
Use TypeScript strict mode with ESNext target and bundler moduleResolution
UseStructuredErrorfrom@agentuity/corefor error handling
Files:
packages/opencode/src/plugin/hooks/session-memory.tspackages/opencode/src/agents/architect.tspackages/opencode/test/agents.test.tspackages/opencode/src/plugin/plugin.tspackages/opencode/src/agents/product.tspackages/opencode/src/agents/scout.tspackages/opencode/src/plugin/hooks/cadence.tspackages/opencode/src/agents/builder.tspackages/opencode/src/agents/lead.tspackages/opencode/src/plugin/hooks/keyword.tspackages/opencode/src/agents/memory.ts
packages/opencode/src/plugin/**/*
📄 CodeRabbit inference engine (packages/opencode/AGENTS.md)
Open Code plugin integration code should be in the
src/plugin/directory
Files:
packages/opencode/src/plugin/hooks/session-memory.tspackages/opencode/src/plugin/plugin.tspackages/opencode/src/plugin/hooks/cadence.tspackages/opencode/src/plugin/hooks/keyword.ts
packages/opencode/src/agents/**/*
📄 CodeRabbit inference engine (packages/opencode/AGENTS.md)
Agent definitions should be located in the
src/agents/directory
Files:
packages/opencode/src/agents/architect.tspackages/opencode/src/agents/product.tspackages/opencode/src/agents/scout.tspackages/opencode/src/agents/builder.tspackages/opencode/src/agents/lead.tspackages/opencode/src/agents/memory.ts
packages/*/test/**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
packages/*/test/**/*.{ts,tsx}: Place test files intest/folder (never insrc/or__tests__/)
Import from../src/in test files to reference source code
Use@agentuity/test-utilsfor mocks and test helpers
Files:
packages/opencode/test/agents.test.ts
🧠 Learnings (1)
📚 Learning: 2025-12-21T00:31:41.858Z
Learnt from: jhaynie
Repo: agentuity/sdk PR: 274
File: packages/cli/src/cmd/build/vite/server-bundler.ts:12-41
Timestamp: 2025-12-21T00:31:41.858Z
Learning: In Bun runtime, BuildMessage and ResolveMessage are global types and are not exported from the bun module. Do not import { BuildMessage } from 'bun' or similar; these types are available globally and should be used without import. This applies to all TypeScript files that target the Bun runtime within the repository.
Applied to files:
packages/opencode/src/plugin/hooks/session-memory.tspackages/opencode/src/agents/architect.tspackages/opencode/test/agents.test.tspackages/opencode/src/plugin/plugin.tspackages/opencode/src/agents/product.tspackages/opencode/src/agents/scout.tspackages/opencode/src/plugin/hooks/cadence.tspackages/opencode/src/agents/builder.tspackages/opencode/src/agents/lead.tspackages/opencode/src/plugin/hooks/keyword.tspackages/opencode/src/agents/memory.ts
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: Cloud Deployment Tests
- GitHub Check: Playwright E2E Smoke Test
- GitHub Check: Sandbox CLI Tests
- GitHub Check: SDK Integration Test Suite
🔇 Additional comments (18)
packages/opencode/src/agents/builder.ts (1)
13-13: LGTM!The terminology update from "Planner" to "Strategic planner" correctly aligns with the PR's Planner → Lead merge. This clarifies that the column describes a capability the Builder should avoid, rather than referencing the now-removed Planner agent.
packages/opencode/src/plugin/hooks/keyword.ts (3)
14-23: LGTM! Team roster correctly reflects the Planner → Lead merge.The roster now lists 10 agents (down from 11), with Planner removed and Product added. The new roles (Reasoner at line 20, Product at line 23) are appropriately described and align with the PR objectives.
35-41: LGTM! Guidelines updated to reflect the new Product-first workflow.The updated guidance correctly incorporates the Product agent for new features and unclear requirements (line 38), aligning with the PR's Cadence mode flow where Lead involves Product first. The logical progression (Scout → Product → Reviewer → cloud services) is sensible.
44-92: LGTM! Runtime logic unchanged and functional.The keyword detection and context injection logic remains intact. The in-memory
activatedSessionsSet appropriately prevents duplicate activations within a session.packages/opencode/src/agents/architect.ts (1)
178-182: Lead handoff wording is aligned with the new planning model.packages/opencode/src/agents/scout.ts (1)
9-12: Scout identity update reads clean and consistent.packages/opencode/src/agents/product.ts (2)
11-26: Role boundary clarification looks good.
406-412: Principle update is clear and consistent.packages/opencode/src/plugin/plugin.ts (1)
472-493: Cadence guidance wording is consistent with the new planning flow.packages/opencode/test/agents.test.ts (2)
6-8: Agent count assertion aligns with planner removal.
141-142: PRD Generation assertion matches new product prompt.packages/opencode/src/agents/memory.ts (2)
686-688: Good callout to involve Product for PRD updates at session end.
942-975: Clear separation of PRD vs session planning and activation rules.packages/opencode/src/agents/lead.ts (5)
45-52: Product gate + requirements‑contract guidance is clear and actionable.Also applies to: 59-59, 122-125, 151-151, 154-161, 163-175, 176-183, 204-206
91-116: Planning/ultrathink and strategic‑decision guidance reads well.Also applies to: 333-349, 370-370, 391-405, 409-428, 539-547
488-488: Background‑task example looks good.
557-557: Deep‑debug step in the bug workflow is a nice addition.
973-979: Cadence planning/PRD linkage and progress‑capture guidance is solid.Also applies to: 1001-1011, 1013-1029, 1031-1040, 1041-1067, 1068-1082
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
Added comprehensive Lead-of-Leads documentation for parallel work: Lead Agent: - When to use Lead-of-Leads (independent workstreams, explicit parallelism) - When NOT to use (small tasks, sequential work, tight coordination) - Complete workflow: PRD with workstreams → spawn child Leads → monitor → integrate - Child Lead behavior with [CHILD LEAD] tag - Coordination rules (PRD is source of truth) Product Agent: - Workstream status values (available, in_progress, done, blocked) - How to handle workstream requests (create, claim, complete, status) - Example: claiming a workstream step-by-step README: - New 'Lead-of-Leads: Parallel Work Orchestration' section - ASCII diagram showing the orchestration flow - Workstream structure and status table - Coordination rules
The /agentuity-cadence command template was missing Product agent integration. Now the Cadence workflow properly includes: 1. FIRST: Establish PRD with Product (REQUIRED) 2. Initialize loop state with prdKey link 3. Each iteration (unchanged) 4. When complete 5. Finalize: Update PRD via Product, then memorialize via Memory Also added 'Product first' to guidelines.
Added Lead-of-Leads section to the /agentuity-cadence command template so Lead knows when and how to parallelize work: - When to use: independent workstreams that can run in parallel - Workflow: Product creates PRD with workstreams, spawn child Leads, monitor via PRD, integrate when done - When NOT to use: small tasks, sequential work, tight coordination
This comment has been minimized.
This comment has been minimized.
…-Leads - Add inspectTask() to fetch session details and messages from OpenCode Server - Add refreshStatuses() to batch refresh task statuses via session.children() - Add agentuity_background_inspect tool for agents to debug stuck tasks - Add TaskInspection type for structured inspection results This is Phase 1-3 of Option C (Hybrid) approach for better background task management.
…undManager - Store task metadata in session title for persistence (Phase 4) - Add recoverTasks() to reconstruct task state from sessions on startup (Phase 5) - Call recoverTasks() during plugin initialization - Properly set concurrencyGroup on recovered tasks Tasks now survive plugin restarts by storing metadata in OpenCode sessions.
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@packages/opencode/README.md`:
- Around line 257-286: Update the fenced ASCII diagram in README.md to declare a
language (use "text") so markdownlint MD040 is satisfied; locate the block
containing the Lead-of-Leads diagram (the triple-backtick fence that starts with
User: "Build auth, cart, and payments in parallel") and change the opening fence
to ```text while keeping the diagram contents and closing fence unchanged.
In `@packages/opencode/src/background/manager.ts`:
- Around line 258-270: The code reconstructing BackgroundTask (properties
queuedAt and startedAt) uses new Date(metadata.createdAt) which can produce
Invalid Date; update the logic in the BackgroundTask construction (in the
manager that builds task from sess/metadata) to parse metadata.createdAt into a
Date, check validity with isNaN(parsed.getTime()) and fall back to new Date()
when invalid or missing, then assign those validated Date objects to queuedAt
and startedAt; keep references to BackgroundTask, metadata.createdAt, queuedAt,
startedAt, mapSessionStatusToTaskStatus and getConcurrencyGroup to locate the
change.
- Around line 160-197: refreshStatuses currently mutates task.status directly
which bypasses the side effects in completeTask/failTask (concurrency slots,
notifications, result handling); change the logic where newStatus !==
task.status to invoke the existing handlers instead of setting task.status
directly: call this.completeTask(matchedTaskId, ...) when
mapSessionStatusToTaskStatus(childSession) yields BackgroundTaskStatus.Completed
and call this.failTask(matchedTaskId, ...) when it yields
BackgroundTaskStatus.Failed (or the equivalent failure enum), leaving other
status transitions to be applied normally; ensure you use the same
matchedTaskId/task lookups used now, avoid duplicate completion/failure if task
already marked finished, and preserve async behavior (await or schedule as
appropriate) so side effects run.
- Around line 120-149: The inspectTask method returns session messages that may
be non-array when throwOnError is false; update inspectTask (inside the
unwrapResponse handling for messages) to coerce the unpacked messages into an
array (e.g., use Array.isArray check or similar) before returning so that
messages is always an array (mirror the defensive pattern used in
fetchLatestResult); locate inspectTask, the unwrapResponse<Array<{ info:
unknown; parts: unknown[] }>>(messagesResponse) binding, and replace the direct
messages ?? [] usage with a normalized array value.
🧹 Nitpick comments (5)
packages/opencode/src/agents/monitor.ts (1)
16-18: Consider adding a maximum poll count or timeout guidance."No timeout - watch indefinitely" (line 18) could lead to extended polling if a monitored task hangs. While the parent Lead can cancel the Monitor, consider documenting a recommended upper bound (e.g., "after 100 polls without progress, report potential stall") to provide a safety net.
packages/opencode/test/agents.test.ts (2)
45-57: Consider adding test coverage for the monitor agent in lookup functions.The
getAgentByRoletests verify all agents exceptmonitor. While the monitor agent is hidden and operates as a subagent, the lookup functions should still return it correctly. Addingexpect(getAgentByRole('monitor')?.id).toBe('ag-monitor');would ensure consistency.💡 Suggested addition
expect(getAgentByRole('product')?.id).toBe('ag-product'); expect(getAgentByRole('reasoner')?.id).toBe('ag-reasoner'); + expect(getAgentByRole('monitor')?.id).toBe('ag-monitor'); });
60-72: Consider adding test coverage for monitor ingetAgentById.Similar to
getAgentByRole, thegetAgentByIdtests don't cover the monitor agent. Adding coverage ensures the bidirectional lookup works correctly.💡 Suggested addition
expect(getAgentById('ag-product')?.role).toBe('product'); expect(getAgentById('ag-reasoner')?.role).toBe('reasoner'); + expect(getAgentById('ag-monitor')?.role).toBe('monitor'); });packages/opencode/src/plugin/hooks/cadence.ts (1)
277-308: Consider extracting shared background task context formatting.The background task context building logic (lines 277-308) is nearly identical to the implementation in
session-memory.ts(lines 134-156). Extracting this to a shared helper function would reduce duplication and ensure consistent formatting.♻️ Suggested helper extraction
Create a shared helper in a common location (e.g.,
packages/opencode/src/plugin/hooks/utils.ts):import type { BackgroundTask } from '../../background'; export function formatBackgroundTaskContext(tasks: BackgroundTask[]): string { if (tasks.length === 0) return ''; const taskList = tasks .map( (t) => `- **${t.id}**: ${t.description || 'No description'} (session: ${t.sessionId ?? 'pending'}, status: ${t.status})` ) .join('\n'); return ` ## Active Background Tasks This session has ${tasks.length} background task(s) running in separate sessions: ${taskList} **CRITICAL:** Task IDs and session IDs persist across compaction - these tasks are still running. Use \`agentuity_background_output({ task_id: "..." })\` to check their status. `; }packages/opencode/src/background/manager.ts (1)
201-205: Prefer StructuredError + app logging over console.error.Using
console.errordrops structure and bypasses the shared error handling approach; consider creating aStructuredErrorand logging viathis.ctx.client.app.logfor consistency. As per coding guidelines "Use StructuredError from@agentuity/corefor error handling".Also applies to: 293-295
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (20)
packages/opencode/README.mdpackages/opencode/src/agents/architect.tspackages/opencode/src/agents/builder.tspackages/opencode/src/agents/index.tspackages/opencode/src/agents/lead.tspackages/opencode/src/agents/memory.tspackages/opencode/src/agents/monitor.tspackages/opencode/src/agents/planner.tspackages/opencode/src/agents/product.tspackages/opencode/src/agents/scout.tspackages/opencode/src/agents/types.tspackages/opencode/src/background/manager.tspackages/opencode/src/background/types.tspackages/opencode/src/plugin/hooks/cadence.tspackages/opencode/src/plugin/hooks/keyword.tspackages/opencode/src/plugin/hooks/session-memory.tspackages/opencode/src/plugin/plugin.tspackages/opencode/src/tools/delegate.tspackages/opencode/src/types.tspackages/opencode/test/agents.test.ts
💤 Files with no reviewable changes (1)
- packages/opencode/src/agents/planner.ts
🧰 Additional context used
📓 Path-based instructions (5)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx}: Use Prettier formatter with tabs (width 3), single quotes, and semicolons for TypeScript files
Use TypeScript strict mode with ESNext target and bundler moduleResolution
UseStructuredErrorfrom@agentuity/corefor error handling
Files:
packages/opencode/src/background/types.tspackages/opencode/src/agents/types.tspackages/opencode/src/types.tspackages/opencode/src/agents/monitor.tspackages/opencode/src/agents/memory.tspackages/opencode/src/plugin/hooks/session-memory.tspackages/opencode/src/plugin/hooks/cadence.tspackages/opencode/src/agents/index.tspackages/opencode/src/agents/architect.tspackages/opencode/test/agents.test.tspackages/opencode/src/plugin/hooks/keyword.tspackages/opencode/src/agents/lead.tspackages/opencode/src/agents/builder.tspackages/opencode/src/agents/product.tspackages/opencode/src/agents/scout.tspackages/opencode/src/background/manager.tspackages/opencode/src/plugin/plugin.tspackages/opencode/src/tools/delegate.ts
packages/opencode/src/agents/**/*
📄 CodeRabbit inference engine (packages/opencode/AGENTS.md)
Agent definitions should be located in the
src/agents/directory
Files:
packages/opencode/src/agents/types.tspackages/opencode/src/agents/monitor.tspackages/opencode/src/agents/memory.tspackages/opencode/src/agents/index.tspackages/opencode/src/agents/architect.tspackages/opencode/src/agents/lead.tspackages/opencode/src/agents/builder.tspackages/opencode/src/agents/product.tspackages/opencode/src/agents/scout.ts
packages/opencode/src/plugin/**/*
📄 CodeRabbit inference engine (packages/opencode/AGENTS.md)
Open Code plugin integration code should be in the
src/plugin/directory
Files:
packages/opencode/src/plugin/hooks/session-memory.tspackages/opencode/src/plugin/hooks/cadence.tspackages/opencode/src/plugin/hooks/keyword.tspackages/opencode/src/plugin/plugin.ts
packages/*/test/**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
packages/*/test/**/*.{ts,tsx}: Place test files intest/folder (never insrc/or__tests__/)
Import from../src/in test files to reference source code
Use@agentuity/test-utilsfor mocks and test helpers
Files:
packages/opencode/test/agents.test.ts
packages/opencode/src/tools/**/*
📄 CodeRabbit inference engine (packages/opencode/AGENTS.md)
Custom tools should be located in the
src/tools/directory
Files:
packages/opencode/src/tools/delegate.ts
🧠 Learnings (1)
📚 Learning: 2025-12-21T00:31:41.858Z
Learnt from: jhaynie
Repo: agentuity/sdk PR: 274
File: packages/cli/src/cmd/build/vite/server-bundler.ts:12-41
Timestamp: 2025-12-21T00:31:41.858Z
Learning: In Bun runtime, BuildMessage and ResolveMessage are global types and are not exported from the bun module. Do not import { BuildMessage } from 'bun' or similar; these types are available globally and should be used without import. This applies to all TypeScript files that target the Bun runtime within the repository.
Applied to files:
packages/opencode/src/background/types.tspackages/opencode/src/agents/types.tspackages/opencode/src/types.tspackages/opencode/src/agents/monitor.tspackages/opencode/src/agents/memory.tspackages/opencode/src/plugin/hooks/session-memory.tspackages/opencode/src/plugin/hooks/cadence.tspackages/opencode/src/agents/index.tspackages/opencode/src/agents/architect.tspackages/opencode/test/agents.test.tspackages/opencode/src/plugin/hooks/keyword.tspackages/opencode/src/agents/lead.tspackages/opencode/src/agents/builder.tspackages/opencode/src/agents/product.tspackages/opencode/src/agents/scout.tspackages/opencode/src/background/manager.tspackages/opencode/src/plugin/plugin.tspackages/opencode/src/tools/delegate.ts
🧬 Code graph analysis (5)
packages/opencode/src/agents/index.ts (1)
packages/opencode/src/agents/monitor.ts (1)
monitorAgent(82-109)
packages/opencode/test/agents.test.ts (1)
packages/opencode/src/agents/index.ts (1)
agents(17-29)
packages/opencode/src/background/manager.ts (1)
packages/opencode/src/background/types.ts (3)
TaskInspection(58-68)BackgroundTaskStatus(2-2)BackgroundTask(12-29)
packages/opencode/src/plugin/plugin.ts (2)
packages/opencode/src/plugin/hooks/cadence.ts (1)
createCadenceHooks(52-350)packages/opencode/src/plugin/hooks/session-memory.ts (1)
createSessionMemoryHooks(22-179)
packages/opencode/src/tools/delegate.ts (4)
packages/opencode/src/types.ts (1)
AgentRole(31-31)packages/opencode/src/index.ts (1)
AgentRole(11-11)packages/opencode/src/tools/index.ts (2)
DelegateArgsSchema(1-1)DelegateArgs(1-1)apps/create-agentuity/bin.js (1)
args(4-4)
🪛 LanguageTool
packages/opencode/README.md
[style] ~239-~239: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ...Leads: Parallel Work Orchestration For very large tasks with independent workstreams, Lea...
(EN_WEAK_ADJECTIVE)
🪛 markdownlint-cli2 (0.20.0)
packages/opencode/README.md
[warning] 257-257: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (10)
- GitHub Check: Playwright E2E Smoke Test
- GitHub Check: Framework Integration Tests (TanStack & Next.js)
- GitHub Check: Cloud Deployment Tests
- GitHub Check: SDK Integration Test Suite
- GitHub Check: Storage CLI Tests
- GitHub Check: Template Integration Tests
- GitHub Check: Package Installation & Usage Test
- GitHub Check: Queue CLI Tests
- GitHub Check: Sandbox CLI Tests
- GitHub Check: Build
🔇 Additional comments (44)
packages/opencode/src/agents/builder.ts (1)
11-14: LGTM — prompt label aligns with renamed role.packages/opencode/src/plugin/hooks/keyword.ts (2)
10-24: Activation message updates look good.Role list changes are consistent and read clearly.
35-40: Guideline updates look good.The revised ordering and wording are clear and aligned with the new flow.
packages/opencode/src/agents/types.ts (1)
14-19: Well-documented new property.The
hiddenproperty is clearly documented with its intended behavior. The constraint that it "only applies to subagents" is documented but not enforced at the type level. Consider whether runtime validation should warn ifhidden: trueis used withoutmode: 'subagent'.packages/opencode/src/agents/memory.ts (2)
686-688: Good addition for PRD update flow.The guidance to involve Product at session end to update the PRD ensures completed work is properly reflected. This aligns well with the Cadence mode requirements.
942-975: Clear documentation of Session Planning vs PRD distinction.The table and guidance clearly delineate the purpose and lifecycle of each concept. This will help agents correctly use session planning for execution tracking while keeping PRDs as the source of truth for requirements.
packages/opencode/src/agents/scout.ts (4)
11-15: Role clarification aligns with Planner → Lead merge.The updated trait table correctly positions Scout as a non-strategic agent. Replacing "Planner who creates strategies" with "Strategic planner (that's Lead's job)" and adding the cartographer/builder distinction reinforces Scout's read-only, fact-finding role.
45-45: Tightened Phase 5 instruction.The explicit instruction to not include "planning, suggestions, or opinions" prevents Scout from overstepping into Lead's strategic domain.
157-162: "Recommendations" → "Observations" is a good semantic shift.Changing from recommendations (which imply action suggestions) to observations (factual notes) aligns with Scout's revised role. The examples are appropriately factual.
310-310: New verification criterion strengthens boundaries.Adding "Did NOT give opinions on the task instructions or suggest what Lead should do" as a self-check reinforces Scout's non-strategic role.
packages/opencode/src/agents/monitor.ts (2)
1-80: Well-structured Monitor agent prompt.The prompt clearly defines the Monitor's narrow responsibility: poll, track status, report completion. The "What You Do NOT Do" section (lines 52-59) effectively constrains the agent's scope.
The "conversation history as timer" workaround (lines 75-79) is pragmatic given LLM constraints. Note that actual delays will depend on LLM response latency rather than being precisely 10 seconds.
82-109: Monitor agent definition correctly configured.
mode: 'subagent'+hidden: truealigns with the new hidden flag semantics- Extensive tool exclusion list ensures Monitor can only use
agentuity_background_outputtemperature: 0.0is appropriate for deterministic polling behavior- Lightweight model (
claude-haiku-4-5) is a good choice for this simple taskpackages/opencode/src/agents/lead.ts (9)
45-59: Product Gate strengthens requirements clarity.The Product Gate ensures success criteria are clear before implementation begins. The criteria for when to involve Product (unclear "done" definition, new features, ambiguous requests, user-facing changes) are well-defined and actionable.
91-117: Extended thinking guidance effectively absorbs Planner capabilities.This section successfully merges Planner's deep reasoning into Lead with clear guidelines on when to use extended thinking vs. direct planning. The emphasis on grounding technical planning in Product's PRD requirements (lines 101-104) prevents technical elegance from overriding product goals.
154-182: Requirements Contract and Functional Review Loop formalize Product collaboration.The lightweight contract format (lines 165-172) provides just enough structure without being heavyweight. The Functional Review Loop (lines 176-182) closes the loop to prevent "technically correct but wrong thing" outcomes.
333-350: Planning Mode Detection covers both Cadence and opt-in scenarios.Clear trigger phrases for opt-in planning ("track my progress", "make a plan", etc.) and the workflow for activating planning in regular sessions are well-defined.
391-428: Strategic Decision Framework promotes pragmatic minimalism.The framework's emphasis on simplicity, leveraging existing code, and developer experience over theoretical optimization is sound engineering guidance. The Plan Format for Builder (lines 409-428) provides a clear template for actionable plans.
539-547: Phase-Based Workflow correctly references Lead for planning.The update from Planner to "Lead (extended thinking)" in Phase 2 aligns with the Planner → Lead merge. The guidance on when to use extended thinking vs. direct planning is clear.
1001-1067: Session Planning vs PRD and Cadence Product Gate are comprehensive.The distinction between PRD (what/why) and session planning (how/where) is clearly documented. The mandatory Product gate at Cadence start (lines 1013-1029) ensures PRD exists before execution begins. The session-end requirement to update PRD (lines 1031-1040) maintains PRD accuracy.
1149-1294: Lead-of-Leads orchestration pattern is well-designed.The pattern addresses parallel work orchestration with clear guidance on:
- When to use (independent workstreams, explicit parallelism)
- When NOT to use (sequential dependencies, tight coordination)
- Workflow steps with PRD workstreams
- BackgroundMonitor delegation for clean context management
- Coordination rules through PRD as source of truth
The example (lines 1264-1285) provides a concrete illustration of the workflow.
1191-1204: The background task infrastructure accepts "lead" as a valid agent identifier.The
agentuity_background_tasktool usesAgentRoleSchemafor agent validation, which explicitly includes'lead'as a valid option. This confirms the Lead-of-Leads pattern is supported—child Leads can be spawned via background tasks to work autonomously on parallel workstreams.packages/opencode/src/agents/architect.ts (1)
181-181: Terminology update aligns with Planner → Lead merge.Changing "Consult Planner agent" to "Ask Lead (Lead handles strategic planning)" is consistent with the PR's objective of consolidating strategic planning into Lead.
packages/opencode/src/background/types.ts (1)
53-68: TaskInspection interface provides useful debugging capability.The interface correctly uses
unknownfor the loosely-typed session and message fields, which is appropriate for a debugging interface where the exact structure may vary.Consider documenting the expected format of
lastActivity(e.g., "ISO 8601 timestamp string") in the JSDoc for clarity.packages/opencode/src/agents/index.ts (1)
13-28: LGTM!The agent registry correctly replaces
plannerwithmonitor. The import and registry entry are properly aligned with the newmonitorAgentdefinition frommonitor.ts, and theRecord<AgentRole, AgentDefinition>type ensures compile-time validation against the updatedAgentRoletype.packages/opencode/src/types.ts (1)
18-31: LGTM!The
AgentRoleSchemacorrectly replaces'planner'with'monitor'. SinceAgentRoleis inferred viaz.infer, this change automatically propagates type safety throughout the codebase.packages/opencode/src/plugin/hooks/session-memory.ts (2)
22-26: LGTM!The optional
backgroundManagerparameter maintains backward compatibility while enabling background task context injection. The null coalescing pattern (backgroundManager?.getTasksByParent(sessionId) ?? []) handles the undefined case safely.
134-156: LGTM!The background task context injection is well-structured:
- Only builds context when tasks exist (efficient)
- Includes task ID, description, session ID, and status for traceability
- Provides clear guidance on how to check task status post-compaction
packages/opencode/src/plugin/hooks/cadence.ts (1)
52-56: LGTM!The optional
backgroundManagerparameter follows the same pattern assession-memory.ts, maintaining consistency across hooks.packages/opencode/src/agents/product.ts (1)
3-27: LGTM!The prompt correctly updates role attributions: Lead now handles technical architecture/design, while Product maintains ownership of requirements, user value, and product intent. The "Product vs Scout vs Lead" table clearly delineates responsibilities.
packages/opencode/src/tools/delegate.ts (3)
5-26: LGTM!The
DelegateArgsSchemacorrectly replaces'planner'with'monitor'. The schema intentionally uses a hardcoded enum rather than deriving fromAgentRolesince Lead delegates but cannot be delegated to.
31-42: LGTM!The
AGENT_MENTIONStype correctly usesExclude<AgentRole, 'lead'>to ensure type safety while excluding the Lead agent from delegation targets. The monitor entry is properly added.
64-65: LGTM!The type cast
args.agent as Exclude<AgentRole, 'lead'>is necessary here becauseargs.agentis inferred from the narrower schema enum, and TypeScript needs the explicit cast to index intoAGENT_MENTIONS.packages/opencode/src/background/manager.ts (3)
4-11: Type import additions look consistent.The added type imports align with the new background task APIs.
300-316: LGTM: clear status mapping.
432-445: Session title overflow risk is speculative without documented API limits.The OpenCode SDK
session.create()API does not document a maximum length constraint for thetitlefield. While truncating user input is a reasonable defensive practice, the claim that the description "can exceed title limits" cannot be confirmed. Consider:
- If a legitimate backend limit exists, it should be documented or discovered through error reports rather than speculative fixes.
- If truncation is needed for safety, prefer a limit derived from actual API documentation or observed failures.
Remove the urgency tag unless you have evidence of failures or confirmed backend constraints.
packages/opencode/README.md (1)
80-90: LGTM: Product model entry is clear.packages/opencode/src/plugin/plugin.ts (8)
67-81: LGTM: Monitor mention wiring is clear.
129-159: Nice addition: task recovery + background-aware hooks on startup.
300-313: LGTM: hidden agent flag is propagated to config.
499-544: Cadence workflow updates read clearly.
600-615: Delegate tool enum updates are consistent.
638-652: Background task enum updates are consistent.
723-764: Background inspect tool implementation looks good.
903-909: Tools map now exposes background inspection.
✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.
… BackgroundManager - inspectTask: Add Array.isArray check for messages (mirrors fetchLatestResult pattern) - refreshStatuses: Use completeTask/failTask for completed/error states to trigger proper side effects (concurrency release, notifications, result fetching)
Summary
Three improvements to the Agentuity Coder agent team:
1. Merged Planner into Lead
Lead now handles all planning directly using extended thinking. One less agent hop.
2. Planning with KV Storage
session:{id}in KV)project:{label}:prd3. Lead-of-Leads for Parallel Work
Lead can now spawn child Leads for independent workstreams:
agentuity_background_inspecttool for debugging stuck tasksBreaking Changes
@Agentuity Coder Plannerno longer exists — use Lead instead.Summary by CodeRabbit
New Features
Changes