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** | Versioned (schema_version table, sequential) |
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;
128 -| Decision | Choice |
129 -| ------------------- | -------------------------------------------------------------- |
130 -| **Style** | Fluent chaining (`.step().gate().when().loop()`) |
131 -| **Step definition** | Object config (`{ agent, input, output, expect }`) |
132 -| **Gate syntax** | Expect-based (`expect: z.object({ approved: true })`) |
133 -| **Validation** | Zod for pipeline definition, SDK structured output for runtime |
134 -| **Reusable steps** | Via composable pipeline fragments |
136 -###
DSL Syntax (Draft) 139 -import { gate, parallel, pipeline, step, when }
from "@opencode/chef";
140 -import { z }
from "zod";
142 -export default pipeline(
"feature")
143 - .
step(
"research", {
144 - agent:
"researcher",
145 - prompt:
"Research the codebase",
146 - output: z.
object({ findings: z.
string() }),
150 - prompt: (ctx)
=> `Create a plan based on: ${ctx.research.findings}`,
151 - output: z.
object({ tasks: z.
array(z.
string()) }),
153 - .
gate(
"approval", {
155 - expect: z.
object({ approved: z.
boolean() }),
157 - .
when((ctx)
=> !ctx.approval.approved)
159 - .
step(
"implement", {
160 - agent:
"programmer",
161 - prompt:
"Implement the approved plan",
164 - step(
"review_security", { agent:
"security" }),
165 - step(
"review_perf", { agent:
"profiler" }),
166 - step(
"review_code", { agent:
"reviewer" }),
168 - .
gate(
"all_passed", {
170 - ctx.review_security.passed
&& 171 - ctx.review_perf.passed
&& 172 - ctx.review_code.passed,
174 - .
step(
"ship", { agent:
"shipper" });
177 -###
Agent Execution Strategy 179 -| Aspect | Implementation |
180 -| --------------------- | ------------------------------------------------------------ |
181 -| **Session Creation** | `client.session.create({ body: { agent, title } })` |
182 -| **Context Injection** | `client.session.prompt({ body: { noReply: true, parts } })` |
183 -| **Agent Prompting** | `client.session.prompt({ body: { parts, format } })` |
184 -| **Output Validation** | SDK structured output with `format: { type: "json_schema" }` |
185 -| **Schema Conversion** | Zod → JSON Schema via `zodToJsonSchema()` |
186 -| **Error Handling** | SDK automatic retries (retryCount: 2) |
190 -| Failure Type | Recoverable? | Handling |
191 -| ------------------------- | ------------ | ------------------------------------ |
192 -| Agent timeout | Yes | Retry or fail phase |
193 -| Agent error | Maybe | Retry with feedback |
194 -| Gate failure | Yes | Loop back to appropriate phase |
195 -| Max iterations reached | No | Fail pipeline, escalate |
196 -| SDK error | No | Fail immediately (plugin bug) |
197 -| User cancellation | No | Abort, preserve state |
198 -| Pipeline definition error | No | Fail immediately (caught at startup) |
199 -| Agent not found | No | Fail immediately (caught at startup) |
201 -###
Pipeline Tools API 207 - input:
"Add dark mode toggle",
212 -pipeline.
status({ id:
"abc-123" });
217 - input: { answer:
"PostgreSQL" },
221 -pipeline.
abort({ id:
"abc-123" });
229 -##
Implementation Plan 231 -###
Phase 1: Core Infrastructure (Current) 233 -- [x] Update PLUGIN_SDK.md with correct capabilities
234 -- [x] Update PLAN.md with revised architecture
235 -- [x] Create `package.json` with dependencies
236 -- [x] Create `store.ts` - SQLite setup and state management
237 -- [x] Create `chef.ts` - Plugin entry point with tools
238 -- [x] Create `pipeline/builder.ts` - Basic pipeline builder
240 -###
Phase 2: Execution Engine 242 -- [x] Create `executor.ts` - Step execution logic
243 -- [x] Implement context injection via `noReply: true`
244 -- [x] Implement structured output with schema conversion
245 -- [x] Add error taxonomy (ChefError, AgentTimeoutError, AgentError,
246 - GateFailureError, MaxIterationsError, SchemaValidationError)
247 -- [x] Add configurable retry policies with exponential backoff
248 -- [x] Add session cleanup with try/finally blocks
249 -- [x] Add max loop iteration guard (default: 10)
250 -- [x] Add per-step timeout with Promise.race
252 -###
Phase 3: Advanced Features 254 -- [x] Add pipeline validation on startup (agents, schemas, loop targets)
255 -- [x] Add builder validate() method for structural validation
256 -- [x] Add reusable fragments (fragment() function + use() method)
257 -- [x] Add gate onFail loop-back handling
258 -- [x] Add abort checking in executor loop
263 -- [x] DSL ergonomics improvements (typed context)
264 -- [ ] Documentation improvements
272 -- [x] Storage: SQLite with bun:sqlite
273 -- [x] DSL style: Fluent chaining
274 -- [x] Step definition: Object config
275 -- [x] Gate syntax: Expect-based with Zod
276 -- [x] Reusable steps: Via pipeline fragments
277 -- [x] State location: `.opencode/chef/`
278 -- [x] Concurrent pipelines: Supported from day one
279 -- [x] Schema validation: Zod for definition, SDK structured output for runtime
280 -- [x] Message injection: Works via `noReply: true`
281 -- [x] Agent spawning: Works via SDK `session.create()` and `session.prompt()`
285 -- [ ] Parallel result access syntax (by step name? by array?)
286 -- [ ] Exact Zod schema for pipeline definition
287 -- [ ] How chef agent integrates (if at all)
291 -- [x] Reusable step/fragment syntax: fragment() function + use() method
292 -- [x] Loop target syntax: by step name
293 -- [x] Pipeline validation on startup: validate() + startup check
294 -- [x] Parallel result access syntax (by step name? by array?) — resolved: nested
295 - context by step name
296 -- [x] Exact Zod schema for pipeline definition — resolved: Zod schemas in step
301 -##
Directory Structure (Planned) 305 -├── package.json # Dependencies (zod, zod-to-json-schema)
306 -├── chef.ts # Main plugin entry point
307 -├── store.ts # SQLite state management
308 -├── executor.ts # Step execution engine
310 -│ ├── mod.ts # Pipeline DSL exports
311 -│ ├── builder.ts # Pipeline builder
312 -│ ├── step.ts # Step definition
313 -│ ├── gate.ts # Gate definition
314 -│ └── context.ts # Context/interpolation
316 -│ ├── start.ts # Start tool
317 -│ ├── status.ts # Status tool
318 -│ ├── continue.ts # Continue tool
319 -│ ├── abort.ts # Abort tool
320 -│ └── list.ts # List tool
322 -│ ├── pipeline.test.ts # Pipeline DSL tests
323 -│ ├── executor.test.ts # Executor tests
324 -│ └── store.test.ts # State tests
325 -└── pipelines/ # User pipeline definitions
332 -##
Key Implementation Details 334 -###
1. Context Injection Pattern 338 -async function injectContext(
343 - await client.session.
prompt({
344 - path: { id: sessionId },
350 - text:
`Previous context:\n${JSON.stringify(context, null, 2)}`,
358 -###
2. Structured Output Pattern 362 -import { zodToJsonSchema }
from "zod-to-json-schema";
364 -async function executeStep(step
: Step, context
: any, client
: SDKClient) {
365 - const jsonSchema
= zodToJsonSchema(step.output);
367 - const result
= await client.session.
prompt({
368 - path: { id: sessionId },
370 - parts: [{ type:
"text", text: step.
prompt }],
372 - type:
"json_schema",
373 - schema: jsonSchema,
380 - return result.
data.info.structured_output;
384 -###
3. Session Management Pattern 388 -const session
= await client.session.
create({
390 - title:
`Chef: ${step.name}`,
396 - await injectContext(session.
id, context, client);
397 - const output
= await executeStep(step, context, client);
401 - await client.session.
delete({ path: { id: session.
id } });
409 -- **@devil** - Challenged assumptions about LLM self-control, gate enforcement,
411 -- **@architect** - Identified missing specs (error taxonomy, state schema,
412 - concurrency, cancellation, observability)
413 -- **@simplify** - Challenged complexity (mostly rejected as our use cases
414 - require the complexity)
415 -- **@researcher** - Confirmed testability (Bun test patterns exist), storage
416 - options (bun:sqlite is standard)
417 -- **OpenCode SDK Docs** - Validated message injection and structured output
424 -- OpenCode SDK Documentation - Structured output and message injection
425 -- Temporal.io workflow SDK - Orchestration patterns
426 -- Inngest step functions - Step execution model
427 -- Mastra workflow DSL - Fluent API design
428 -- Zod schema validation - Type-safe pipeline definitions
429 -- bun:sqlite documentation - State persistence
430 -- zod-to-json-schema - Schema conversion
434 -_Last updated: 2026-04-01_