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.
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.
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.
Choose the route. Name the owner, scope, and completion criterion.
software-changeChange product behavior, a contract, or a build. Choose planning, implementation, or combined.
workflow-routingopenspec-workflowwritingAsk the content owner or General for an RFC, ADR, system design explanation, or other prose. Drafting does not authorize implementation.
doc-writingdoc-artifactsinvestigation/adviceExplore the repo or scout external sources, then hand off to the relevant specialist. Deliver findings, not changes.
workflow-routingorchestration-handoffoperational-actionGeneral handles routine config and housekeeping; DevOps handles deployment and runtime. Use existing checks as needed.
command-hygienegit-workflowCoS specifies a route in each handoff. The other three routes do not automatically inherit software delivery gates. Skills shown are examples, loaded when relevant.
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.
The Chief of Staff coordinates each handoff. The roles shown do the work; they do not dispatch one another.
planningProposal, design, and spec changes. No implementation tasks or executable tests.
openspec-workflowMerging a planning PR is optional. It does not authorize delivery.
implementationSet up the worktree, tasks, and tests.
executable-specificationImplement, run the checks, fix failures, and rerun.
dispatch-format↺ Build–check loopCheck the candidate and record evidence. Passing checks let the change move toward PR delivery.
e2e-verificationConditional branch before build: the Architect reviews the task breakdown or interface boundary only when it needs a separate check.
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.
CoS routes each step and receives each report. The arrows show dependencies, not agents dispatching one another.
Define public behavior, component boundaries, data invariants, and compatibility. Use the agreed contract as the reference, rather than prescribing private implementation details.
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.
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.
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.
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-reviewThe 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.
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.
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.
Routes new requests, resolves stalled handoffs, and keeps the status record. Coordinates rather than implements.
Defines user outcomes, product behavior, and what is in or out of scope. Owns the OpenSpec proposal.
Designs user flows, accessibility, mockups, and visual systems. The declared spec author owns the normative behavior.
Owns the design and cross-component contracts. Reviews interface boundaries and risky task decomposition.
Owns test design, task breakdown, worktree setup and cleanup, and independent verification. Does not write feature code.
Implements in the assigned worktree, runs the specified tests, and handles the implementation PR within the authorization given.
Handles deployments, runtime operations, observability, and post-deploy checks. Does not own feature merges.
Manages dates, commitments, and daily planning through CoS. This is distinct from authoring an OpenSpec change plan.
Handles commercial viability, business plans, and the investor narrative.
Handles positioning, messaging, sales material, and go-to-market planning.
Explore reads the local repo; Scout researches external docs and dependencies. Both are intended for read-only discovery.
Handles work that has no specialist owner, such as routine config, housekeeping, and standalone prose.
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.
Build and test against an agreed spec commit. Keep task and verification evidence with Change A.
Discuss requirements, design, and spec deltas for Change B. Keep implementation tasks and tests out of this planning session.
For one change taken from planning to delivery in sequence, a single combined session is enough.
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.
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-slicingOpenSpec 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-slicingFor 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-verificationReuse 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-loopA 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.
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.
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.
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.
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.
dispatch-format frames the engineering handoff, worktree-slicing guides workspace setup, e2e-verification defines independent evidence, and git-workflow governs PRs, merge, and cleanup.
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.