1 +#
Chef Orchestrator Plugin - Design Plan 3 +> Persistent planning document for the chef orchestrator plugin.
9 +**Phase 3 Complete** - Advanced features implemented.
15 +Chef is an orchestrator plugin for opencode that provides a declarative pipeline
16 +system for coordinating multiple agents in structured workflows. It leverages
17 +the OpenCode SDK's structured output and message injection capabilities for
18 +robust agent orchestration.
25 +┌─────────────────────────────────────────────────────────────┐
29 +│ User works naturally, says "start pipeline" │
30 +│ Agent calls pipeline tool │
31 +└─────────────────────────────────────────────────────────────┘
34 +┌─────────────────────────────────────────────────────────────┐
38 +│ - pipeline.start(name, input) │
39 +│ - pipeline.status(id?) │
40 +│ - pipeline.continue(id, input) │
41 +│ - pipeline.abort(id) │
42 +│ - pipeline.list() │
44 +│ Responsibilities: │
45 +│ - Read pipeline definitions (TypeScript DSL) │
46 +│ - Execute phases deterministically │
47 +│ - Call agents via SDK (session.create + prompt) │
48 +│ - Inject context via noReply: true │
49 +│ - Use SDK structured output for validation │
50 +│ - Handle retries (max iterations, policy-based) │
51 +│ - Manage state (SQLite) │
52 +│ - Return "needs_input" status for human questions │
53 +└─────────────────────────────────────────────────────────────┘
56 +┌─────────────────────────────────────────────────────────────┐
60 +│ ├── chef.db # SQLite database (WAL mode) │
62 +│ └── pipelines/ # Pipeline definitions │
67 +│ - pipeline_instance (id, status, context, current_phase) │
68 +│ - phase_state (pipeline_id, name, status, output) │
69 +│ - step_state (phase_id, agent, status, output, attempts) │
70 +└─────────────────────────────────────────────────────────────┘
73 +┌─────────────────────────────────────────────────────────────┐
74 +│ PIPELINE DSL (TypeScript + Zod) │
76 +│ Fluent chaining style with object configs: │
77 +│ - Steps as declarative objects (no side effects) │
78 +│ - Zod schemas for pipeline definition (author-time) │
79 +│ - SDK structured output for runtime validation │
80 +│ - Gates defined with expect() │
81 +│ - Parallel execution via parallel([]) │
82 +│ - Loops via when().loop() │
83 +└─────────────────────────────────────────────────────────────┘
92 +| Decision | Choice |
93 +| --------------------- | -------------------------------------------- |
94 +| **Database** | SQLite with `bun:sqlite` (built into Bun) |
95 +| **Location** | `.opencode/chef/chef.db` |
96 +| **Concurrency** | WAL mode for concurrent reads, single writer |
97 +| **Schema migrations** | Manual (simple schema, can evolve later) |
99 +###
State Schema (Draft) 102 +interface PipelineInstance {
104 + definition
: string;
105 + status
: PipelineStatus;
108 + current_phase
: number;
109 + created_at
: number;
110 + updated_at
: number;
113 +interface PhaseState {
115 + pipeline_id
: string;
117 + status
: PhaseStatus;
119 + error
: string | null;
121 + started_at
: number | null;
122 + completed_at
: number | null;
125 +interface StepState {
130 + status
: StepStatus;
132 + error
: string | null;
139 +| Decision | Choice |
140 +| ------------------- | -------------------------------------------------------------- |
141 +| **Style** | Fluent chaining (`.step().gate().when().loop()`) |
142 +| **Step definition** | Object config (`{ agent, input, output, expect }`) |
143 +| **Gate syntax** | Expect-based (`expect: z.object({ approved: true })`) |
144 +| **Validation** | Zod for pipeline definition, SDK structured output for runtime |
145 +| **Reusable steps** | Via composable pipeline fragments |
147 +###
DSL Syntax (Draft) 150 +import { gate, parallel, pipeline, step, when }
from "@opencode/chef";
151 +import { z }
from "zod";
153 +export default pipeline(
"feature")
154 + .
step(
"research", {
155 + agent:
"researcher",
156 + prompt:
"Research the codebase",
157 + output: z.
object({ findings: z.
string() }),
161 + prompt: (ctx)
=> `Create a plan based on: ${ctx.research.findings}`,
162 + output: z.
object({ tasks: z.
array(z.
string()) }),
164 + .
gate(
"approval", {
166 + expect: z.
object({ approved: z.
boolean() }),
168 + .
when((ctx)
=> !ctx.approval.approved)
170 + .
step(
"implement", {
171 + agent:
"programmer",
172 + prompt:
"Implement the approved plan",
175 + step(
"review_security", { agent:
"security" }),
176 + step(
"review_perf", { agent:
"profiler" }),
177 + step(
"review_code", { agent:
"reviewer" }),
179 + .
gate(
"all_passed", {
181 + ctx.review_security.passed
&& 182 + ctx.review_perf.passed
&& 183 + ctx.review_code.passed,
185 + .
step(
"ship", { agent:
"shipper" });
188 +###
Agent Execution Strategy 190 +| Aspect | Implementation |
191 +| --------------------- | ------------------------------------------------------------ |
192 +| **Session Creation** | `client.session.create({ body: { agent, title } })` |
193 +| **Context Injection** | `client.session.prompt({ body: { noReply: true, parts } })` |
194 +| **Agent Prompting** | `client.session.prompt({ body: { parts, format } })` |
195 +| **Output Validation** | SDK structured output with `format: { type: "json_schema" }` |
196 +| **Schema Conversion** | Zod → JSON Schema via `zodToJsonSchema()` |
197 +| **Error Handling** | SDK automatic retries (retryCount: 2) |
201 +| Failure Type | Recoverable? | Handling |
202 +| ------------------------- | ------------ | ------------------------------------ |
203 +| Agent timeout | Yes | Retry or fail phase |
204 +| Agent error | Maybe | Retry with feedback |
205 +| Schema validation failure | Yes | SDK auto-retries (retryCount: 2) |
206 +| Gate failure | Yes | Loop back to appropriate phase |
207 +| Max iterations reached | No | Fail pipeline, escalate |
208 +| SDK error | No | Fail immediately (plugin bug) |
209 +| User cancellation | No | Abort, preserve state |
210 +| Pipeline definition error | No | Fail immediately (caught at startup) |
211 +| Agent not found | No | Fail immediately (caught at startup) |
213 +###
Pipeline Tools API 219 + input:
"Add dark mode toggle",
224 +pipeline.
status({ id:
"abc-123" });
229 + input: { answer:
"PostgreSQL" },
233 +pipeline.
abort({ id:
"abc-123" });
241 +##
Implementation Plan 243 +###
Phase 1: Core Infrastructure (Current) 245 +- [x] Update PLUGIN_SDK.md with correct capabilities
246 +- [x] Update PLAN.md with revised architecture
247 +- [x] Create `package.json` with dependencies
248 +- [x] Create `store.ts` - SQLite setup and state management
249 +- [x] Create `chef.ts` - Plugin entry point with tools
250 +- [x] Create `pipeline/builder.ts` - Basic pipeline builder
252 +###
Phase 2: Execution Engine 254 +- [x] Create `executor.ts` - Step execution logic
255 +- [x] Implement context injection via `noReply: true`
256 +- [x] Implement structured output with schema conversion
257 +- [x] Add error taxonomy (ChefError, AgentTimeoutError, AgentError,
258 + GateFailureError, MaxIterationsError, SchemaValidationError)
259 +- [x] Add configurable retry policies with exponential backoff
260 +- [x] Add session cleanup with try/finally blocks
261 +- [x] Add max loop iteration guard (default: 10)
262 +- [x] Add per-step timeout with Promise.race
264 +###
Phase 3: Advanced Features 266 +- [x] Add pipeline validation on startup (agents, schemas, loop targets)
267 +- [x] Add builder validate() method for structural validation
268 +- [x] Add reusable fragments (fragment() function + use() method)
269 +- [x] Add gate onFail loop-back handling
270 +- [x] Add abort checking in executor loop
275 +- [ ] DSL ergonomics improvements (typed context)
276 +- [ ] Documentation improvements
284 +- [x] Storage: SQLite with bun:sqlite
285 +- [x] DSL style: Fluent chaining
286 +- [x] Step definition: Object config
287 +- [x] Gate syntax: Expect-based with Zod
288 +- [x] Reusable steps: Via pipeline fragments
289 +- [x] State location: `.opencode/chef/`
290 +- [x] Concurrent pipelines: Supported from day one
291 +- [x] Schema validation: Zod for definition, SDK structured output for runtime
292 +- [x] Message injection: Works via `noReply: true`
293 +- [x] Agent spawning: Works via SDK `session.create()` and `session.prompt()`
297 +- [ ] Parallel result access syntax (by step name? by array?)
298 +- [ ] Exact Zod schema for pipeline definition
299 +- [ ] How chef agent integrates (if at all)
303 +- [x] Reusable step/fragment syntax: fragment() function + use() method
304 +- [x] Loop target syntax: by step name
305 +- [x] Pipeline validation on startup: validate() + startup check
309 +##
Directory Structure (Planned) 313 +├── package.json # Dependencies (zod, zod-to-json-schema)
314 +├── chef.ts # Main plugin entry point
315 +├── store.ts # SQLite state management
316 +├── executor.ts # Step execution engine
318 +│ ├── mod.ts # Pipeline DSL exports
319 +│ ├── builder.ts # Pipeline builder
320 +│ ├── step.ts # Step definition
321 +│ ├── gate.ts # Gate definition
322 +│ └── context.ts # Context/interpolation
324 +│ ├── start.ts # Start tool
325 +│ ├── status.ts # Status tool
326 +│ ├── continue.ts # Continue tool
327 +│ ├── abort.ts # Abort tool
328 +│ └── list.ts # List tool
330 +│ ├── pipeline.test.ts # Pipeline DSL tests
331 +│ ├── executor.test.ts # Executor tests
332 +│ └── store.test.ts # State tests
333 +└── pipelines/ # User pipeline definitions
340 +##
Key Implementation Details 342 +###
1. Context Injection Pattern 346 +async function injectContext(
351 + await client.session.
prompt({
352 + path: { id: sessionId },
358 + text:
`Previous context:\n${JSON.stringify(context, null, 2)}`,
366 +###
2. Structured Output Pattern 370 +import { zodToJsonSchema }
from "zod-to-json-schema";
372 +async function executeStep(step
: Step, context
: any, client
: SDKClient) {
373 + const jsonSchema
= zodToJsonSchema(step.output);
375 + const result
= await client.session.
prompt({
376 + path: { id: sessionId },
378 + parts: [{ type:
"text", text: step.
prompt }],
380 + type:
"json_schema",
381 + schema: jsonSchema,
388 + return result.
data.info.structured_output;
392 +###
3. Session Management Pattern 396 +const session
= await client.session.
create({
398 + title:
`Chef: ${step.name}`,
404 + await injectContext(session.
id, context, client);
405 + const output
= await executeStep(step, context, client);
409 + await client.session.
delete({ path: { id: session.
id } });
417 +- **@devil** - Challenged assumptions about LLM self-control, gate enforcement,
419 +- **@architect** - Identified missing specs (error taxonomy, state schema,
420 + concurrency, cancellation, observability)
421 +- **@simplify** - Challenged complexity (mostly rejected as our use cases
422 + require the complexity)
423 +- **@researcher** - Confirmed testability (Bun test patterns exist), storage
424 + options (bun:sqlite is standard)
425 +- **OpenCode SDK Docs** - Validated message injection and structured output
432 +- OpenCode SDK Documentation - Structured output and message injection
433 +- Temporal.io workflow SDK - Orchestration patterns
434 +- Inngest step functions - Step execution model
435 +- Mastra workflow DSL - Fluent API design
436 +- Zod schema validation - Type-safe pipeline definitions
437 +- bun:sqlite documentation - State persistence
438 +- zod-to-json-schema - Schema conversion
442 +_Last updated: 2026-03-31_