Dave Ng
Projects / Workflow case study

Inside my OpenCode setup.

How I use a team of specialized agents in OpenCode: four workflow routes, skills loaded as needed, and clear handoffs from plan to code to verification.

01 / Routing

Four routes, not one pipeline.

The Chief of Staff (CoS) is the default entry point. It classifies the request by the deliverable and what the user authorized, then hands the work to the specialist who owns it.

A request comes in

Chief of Staff

Choose the route. Name the owner, scope, and completion criterion.

  1. 01 / Build

    Software change

    software-change

    Change product behavior, a contract, or a build. Choose planning, implementation, or combined.

    workflow-routingopenspec-workflow
    See the engineering flow ↓
  2. 02 / Write

    Writing

    writing

    Ask the content owner or General for an RFC, ADR, system design explanation, or other prose. Drafting does not authorize implementation.

    doc-writingdoc-artifacts
  3. 03 / Find out

    Investigation & advice

    investigation/advice

    Explore the repo or scout external sources, then hand off to the relevant specialist. Deliver findings, not changes.

    workflow-routingorchestration-handoff
  4. 04 / Operate

    Operational action

    operational-action

    General handles routine config and housekeeping; DevOps handles deployment and runtime. Use existing checks as needed.

    command-hygienegit-workflow

CoS specifies a route in each handoff. The other three routes do not automatically inherit software delivery gates. Skills shown are examples, loaded when relevant.

02 / A closer look

How a software change moves.

The cards follow the usual OpenSpec path. CoS routes each handoff directly; a specialist reports back rather than launching the next specialist. Conditional reviews only run when their trigger applies.

Workflow map · one changeFrom request to verified candidate

The Chief of Staff coordinates each handoff. The roles shown do the work; they do not dispatch one another.

01Spec Planningplanning
Product · Architect · UX as neededAgree on the outcome and contract

Proposal, design, and spec changes. No implementation tasks or executable tests.

openspec-workflow
Agreed spec commit + explicit authorization to implement

Merging a planning PR is optional. It does not authorize delivery.

02–04Deliveryimplementation
  1. 02 · SDETPrepare

    Set up the worktree, tasks, and tests.

    executable-specification
  2. 03 · Software EngineerBuild and self-test

    Implement, run the checks, fix failures, and rerun.

    dispatch-format↺ Build–check loop
  3. 04 · SDETVerify independently

    Check the candidate and record evidence. Passing checks let the change move toward PR delivery.

    e2e-verification

Conditional branch before build: the Architect reviews the task breakdown or interface boundary only when it needs a separate check.

↶ Verification–correction loop

If verification finds a gap, CoS routes it to the owner of the code, test, or contract. The owner fixes it; SDET rechecks what changed. If the fix changes agreed scope or behavior, return to Spec Planning for a decision.

Review map · a closer look

Who checks the translation?

CoS routes each step and receives each report. The arrows show dependencies, not agents dispatching one another.

  1. 01
    Architect · as needed

    Establish the contract.

    Define public behavior, component boundaries, data invariants, and compatibility. Use the agreed contract as the reference, rather than prescribing private implementation details.

  2. 02
    SDET · implementation preparation

    Translate it into executable proof.

    Break down the work, map criteria to tests, and prepare the worktree. Draft Boundary Verification for applicable interfaces, preserving the contract’s names, payloads, and compatibility rules.

  3. ?
    CoS routes · Architect reviews only triggered scopes

    One focused pass, distinct questions.

    Decomposition fidelity

    Does a new or changed dependency, split proof chain, or clean-state risk make execution order unsafe or uncertain? Check that setup, events, and evidence are available when each test needs them.

    Interface fidelity

    Does SDET’s boundary block match the real external interface or normative public/cross-component contract? Check wire endpoints and authentication only when an actual wire exists.

    Test-only artifacts

    Could a compilable test interface, schema, or prototype invent behavior? Check it against the agreed contract and keep it explicitly non-production.

    Combine overlapping scopes for the same unit. An unchanged routine sequence and a purely private implementation seam do not need these extra reviews. A private wrapper still needs real dependency proof when it touches an affected database or provider.

    decomposition-fidelity-reviewinterface-fidelity-review
  4. 03
    Software Engineer → independent SDET verification

    Build, self-test, then verify the candidate.

    The engineer implements and runs the checks. SDET independently verifies the integrated candidate. Passing the preparation review does not prove the implementation, and a passed unit does not prove the whole feature.

  5. 04
    Spec owner → CoS → Software Engineer

    Review the delta. Finalize within authority.

    The declared spec owner reviews the change against the current baseline. CoS authorizes archive only after the required review and completion checks. In a CLI-managed project, SE runs the archive inside the implementation PR. PR and merge actions retain their separate authorization requirements.

External platform discovery comes earlier. Before integration design or test planning, ground the boundary in version-pinned source, SDK, or official documentation, reusing trustworthy research when the version and boundary are unchanged. This establishes what the platform does; fidelity review later checks that the test plan represents it correctly.

A report is not automatic approval. Work can finish asynchronously. CoS reads the result and routes the next authorized step; a pending task, green check, or archive approval never grants merge permission. A scoped acceptance is not a passed check.

03 / Ownership

Who does what.

Each specialist has a reason to be called and a clear boundary. The model badges distinguish fixed assignments from my usual default.

Fast means the role has an explicit fast-model assignment. Defaults to Reasoning describes my usual setup for these roles. Not pinned means the model can still change with the session.

Defaults to ReasoningNot pinned

Chief of Staff

Routes new requests, resolves stalled handoffs, and keeps the status record. Coordinates rather than implements.

Defaults to ReasoningNot pinned

Product Manager

Defines user outcomes, product behavior, and what is in or out of scope. Owns the OpenSpec proposal.

Defaults to ReasoningNot pinned

UX/UI Designer

Designs user flows, accessibility, mockups, and visual systems. The declared spec author owns the normative behavior.

Defaults to ReasoningNot pinned

Software Architect

Owns the design and cross-component contracts. Reviews interface boundaries and risky task decomposition.

Defaults to ReasoningNot pinned

SDET Engineer

Owns test design, task breakdown, worktree setup and cleanup, and independent verification. Does not write feature code.

Fast

Software Engineer

Implements in the assigned worktree, runs the specified tests, and handles the implementation PR within the authorization given.

Defaults to ReasoningNot pinned

DevOps Engineer

Handles deployments, runtime operations, observability, and post-deploy checks. Does not own feature merges.

Fast

Planner

Manages dates, commitments, and daily planning through CoS. This is distinct from authoring an OpenSpec change plan.

Defaults to ReasoningNot pinned

Business Strategist

Handles commercial viability, business plans, and the investor narrative.

Defaults to ReasoningNot pinned

Growth Marketer

Handles positioning, messaging, sales material, and go-to-market planning.

Fast

Explore & Scout

Explore reads the local repo; Scout researches external docs and dependencies. Both are intended for read-only discovery.

Fast

General

Handles work that has no specialist owner, such as routine config, housekeeping, and standalone prose.

04 / A worked example

Parallel planning and delivery.

The engineering map above follows one change. Here, two changes are at different points in that same lifecycle: one is in Delivery while the next is in Spec Planning. They share repo history, not a live checkout or a mutable spec.

Session A · Delivery worktree

Notification preferences

Build and test against an agreed spec commit. Keep task and verification evidence with Change A.

Session B · Spec Planning worktree

Optional weekly digests

Discuss requirements, design, and spec deltas for Change B. Keep implementation tasks and tests out of this planning session.

A change moves from Spec Planning to Delivery with its ID, agreed spec commit, and explicit authorization to implement. If B needs to change a contract A relies on, raise it explicitly rather than rewriting A’s brief. Keep one writer for the shared status summary and separate any runtime resources both sessions need.

For one change taken from planning to delivery in sequence, a single combined session is enough.

05 / Configuration anatomy

Roles define ownership. Skills define procedures.

Global instructions set the rules of engagement. Agent definitions say who owns what. Skills carry the detailed procedures. The runtime config separately controls model choices, permissions, and tool integrations.

Skills in practice

Small enough to review. Complete enough to prove.

01 / Choose the outcome

Size the change, not just the diff.

Start with the smallest safe, independently landable outcome. Around 600 changed lines or 20 changed files prompts a focused review plan, not a hard ceiling or automatic approval request. Unrelated behavior belongs in another change.

Explicit project caps are different: they still bind. Any exception applies only to its named unit. Measure each change against its own base and show the cumulative dependency chain separately.

worktree-slicing
02 / Keep the units aligned

One change, ordered internal slices.

OpenSpec holds the agreed behavior and lifecycle. Worktree slicing organizes execution and review. The default is one implementation worktree, branch, and PR per change; internal slices are commits or checkpoints, not a PR per slice.

A separate planning session may have its own worktree and planning PR. Dependencies must be present on the implementation branch or available through an explicitly declared prerequisite chain.

openspec-workflowworktree-slicing
03 / Observe the outcome

Direct proof beats reassuring proxies.

For notification preferences, proof means using the public controls and observing that delivery follows the saved choice. A settings row, screenshot, dashboard, or passing storage test can support that proof, but cannot replace it.

Use the cheapest representative layer: a contract test can prove an in-process rule; a user workflow needs rendered/public-interface evidence. Mocks alone cannot prove an affected real database or provider boundary.

slice-governancee2e-verification
04 / Correct with new evidence

Repeat only what can teach us more.

Reuse unchanged review and test evidence. After a fix, rerun the failed or affected checks. Repeated identical failures without new evidence, an ambiguous contract, a suspect test, or an environment blocker mean stop and report, not another blind attempt.

CoS routes the gap to its owner. Only affected downstream artifacts are rechecked; independent final candidate verification remains in place.

iterative-feedback-loop
OpenSpec · How the units fit

One change can contain several slices.

Change A · One implementation PRNotification preferencesOne implementation branch and worktree
  1. Slice A1Save the preference
  2. Slice A2Expose the setting
  3. Slice A3Apply it to delivery
Verify the integrated behavior before merging Change A.
Change B · Separate implementation PR when builtOptional weekly digestsA distinct outcome, not another slice of Change A.

A slice is a unit of work, not a Git object. It can be tracked as a checkpoint or span one or more commits in the same implementation PR. It does not have its own PR. An optional planning PR is separate from this diagram and carries the plan, not the slices.

Review cadence

Review in slices. Land as one change.

  1. Agents check slices as they go.Keep commits or checkpoints on one branch. Link the slice ranges and what they prove in the draft implementation PR.
  2. SDET verifies the combined change.Independently check the integrated candidate. Passing individual slices does not show they work together.
  3. One routine human review request.CoS asks for review of the verified revision in the same PR, not a separate PR or approval for each slice.

CoS raises stalled work or decisions that need a human sooner. If the diff is hard to review, improve the PR guide; if it contains distinct outcomes that should land separately, define separate OpenSpec changes.

Three different stop conditions, not one retry budget
  • Interface-review rejections: stop after the third total rejection. The Architect clarifies the contract; CoS asks the user only if a decision remains.
  • External-interface implementation failures: after 1–2 failures caused by incorrect interface assumptions, pause and return to source-grounded research.
  • Upstream correction cycles: after three complete owner-correction/recheck cycles on the same unresolved gap, CoS asks for a user tie-break. Local fixes are not full correction cycles.
Routing and handoffs

workflow-routing picks the route. direction-validation checks the goal and scope. orchestration-handoff tells the next agent which artifacts to use and when to stop.

Specifications and writing

openspec-workflow governs behavior changes. doc-artifacts defines structured artifact conventions. doc-writing selects the right treatment for an RFC, ADR, system design, or other prose.

Contracts and test design

architecture-contract-template records the boundary. executable-specification turns behavior into checks. decomposition-fidelity-review and interface-fidelity-review are conditional reviews, not universal gates.

Implementation and delivery

dispatch-format frames the engineering handoff, worktree-slicing guides workspace setup, e2e-verification defines independent evidence, and git-workflow governs PRs, merge, and cleanup.

Specialist work outside implementation

planner-orchestration supports dated planning; design-theme-foundation guides visual systems; pitch-deck-template, sales-deck-template, and social-media-strategy support commercial and marketing work.

Workflow policy is not a permission boundary. CoS is the default coordinator, not an exclusive entry point. Runtime permissions govern what agents can actually do; the workflow tells them when and why to act.