Process discipline: orchestrator bypasses dispatch, agents lack behavioral contracts, no scope checks

[nullhack]

Problem

Post-mortem PM_20260528_process_discipline identified that the orchestrator agent (the main session) repeatedly:

1. Does the work itself instead of dispatching to subagents — reads skill files and writes code directly instead of using task tool to dispatch to SE/SA/PO/R agents
2. Invents procedures from flow state names instead of following skill steps — wings it from descriptions instead of executing numbered skill procedures verbatim
3. Treats the anchor as a formality — transitions without running flowr next to check conditions

Additionally, post-mortem PM_20260528_feature_scope_creep identified that hyperliquid_api_adapter.feature bundled 6 rules spanning 2 sub-adapter interfaces (MarketDataAdapter + ExecutionAdapter), and no gate caught this. Order placement code was written when only data ingestion was requested.

Root Causes

1. Agent definitions are too thin (10-11 lines each)

The .opencode/agents/*.md files say what the agent IS but not what it MUST DO. A subagent dispatched via task gets the agent definition + dispatch prompt. With only 3 lines of behavioral instruction, the subagent has no enforcement anchor to self-correct.

2. AGENTS.md buries procedural instructions in reference material

The Session Protocol (lines 141-229) mixes critical dispatch mechanics with file naming conventions, flowr command tables, and artifact templates. When context gets compressed, the procedural detail is summarized away. The specific mechanical steps — use task with subagent_type mapped from attrs.owner — are lost.

3. No scope alignment check in review-spec skill

The review-spec skill checks BDD quality, cross-document consistency, and pre-mortem coverage. It does NOT check whether the feature scope matches stakeholder intent or spans multiple sub-adapter interfaces.

4. select-feature skill does not validate feature cohesion

The skill picks the highest-priority incomplete feature without checking if its rules span multiple bounded-context interfaces that should be split.

5. simulate-spec skill does not tag rules by sub-adapter interface

Walkthroughs 3-4 discovered order placement rules for hyperliquid_adapter context, but without interface tags there was no signal to split during refine-features.

6. No enforcement mechanism for dispatch

Nothing verifies that the orchestrator actually called task with the correct subagent_type. The todowrite can say "dispatched" while the orchestrator did the work directly.

Proposed Changes

Agent definitions — add behavioral contract

Each .opencode/agents/*.md needs a "You MUST" section:

• Follow every numbered step in the skill file received
• Never skip steps or improvise alternatives
• Report output notes for gaps/inconsistencies
• Never modify files outside the out contract

Files: software-engineer.md, system-architect.md, product-owner.md, reviewer.md, domain-expert.md, design-agent.md, setup-agent.md, data-engineer.md

AGENTS.md — add anti-pattern warning + extract protocol

Add prominently after Golden Rules:

THE ORCHESTRATOR NEVER WRITES CODE. The orchestrator dispatches to owner agents via the task tool. If you find yourself editing source files, writing test code, or running implementation commands — STOP. You have bypassed dispatch.

Extract the Session Protocol section (lines 141-229) into a new knowledge file .opencode/knowledge/workflow/orchestrator-protocol.md with progressive disclosure. AGENTS.md references it.

Todo anchor protocol — add orchestrator constraint

Add to .opencode/knowledge/workflow/todo-anchor-protocol.md key takeaways:

The orchestrator must never write code, edit files, or run implementation commands. If the orchestrator needs to make a file change, it has bypassed dispatch. The only files the orchestrator touches are session state (via flowr) and the todo list (via todowrite).

review-spec skill — add scope alignment check

Add step between existing steps 2 and 3:

2a. Verify scope alignment: does this feature serve a single bounded-context interface? If the feature spans multiple sub-adapter interfaces (e.g., MarketDataAdapter + ExecutionAdapter), flag for splitting. Compare against the stakeholder's stated priority from interview notes — if the feature includes rules not needed for the current priority, flag those rules as out-of-scope.

File: .opencode/skills/review-spec/SKILL.md

select-feature skill — add scope validation

Add step after step 5:

5a. Before finalizing selection, verify the feature's rules are cohesive. IF the feature's rules span multiple sub-adapter interfaces or bounded-context subsystems, propose a split to the stakeholder with rationale. Do not select an oversized feature.

File: .opencode/skills/select-feature/SKILL.md

simulate-spec skill — add interface tagging

Update step 7 to include interface tagging:

Tag each rule with the sub-adapter interface it serves (if applicable): # Interface: MarketDataAdapter, # Interface: ExecutionAdapter, etc. This enables scope-based filtering during refine-features.

File: .opencode/skills/simulate-spec/SKILL.md

refine-features skill — add interface-based splitting

Update step 3 to check for interface-spanning features:

When redistributing rules from a context-level file, IF rules span multiple sub-adapter interfaces (as tagged during simulation), split into separate features per interface. A feature that serves both MarketDataAdapter and ExecutionAdapter is too broad for one development cycle.

File: .opencode/skills/refine-features/SKILL.md

Files Changed

File	Change
.opencode/agents/software-engineer.md	Add behavioral contract
.opencode/agents/system-architect.md	Add behavioral contract
.opencode/agents/product-owner.md	Add behavioral contract
.opencode/agents/reviewer.md	Add behavioral contract + adversarial enforcement
.opencode/agents/domain-expert.md	Add behavioral contract
.opencode/agents/design-agent.md	Add behavioral contract
.opencode/agents/setup-agent.md	Add behavioral contract
.opencode/agents/data-engineer.md	Add behavioral contract
AGENTS.md	Add anti-pattern warning, extract protocol to knowledge
.opencode/knowledge/workflow/orchestrator-protocol.md	NEW — extracted session protocol
.opencode/knowledge/workflow/todo-anchor-protocol.md	Add orchestrator constraint
.opencode/skills/review-spec/SKILL.md	Add scope alignment check
.opencode/skills/select-feature/SKILL.md	Add scope validation
.opencode/skills/simulate-spec/SKILL.md	Add interface tagging
.opencode/skills/refine-features/SKILL.md	Add interface-based splitting

Post-Mortems

• docs/post-mortem/PM_20260528_process_discipline.md
• docs/post-mortem/PM_20260528_feature_scope_creep.md