[kalyvask]

The gap

Workflow decomposition says where agent boundaries go. Agent shapes says what each agent is. Nothing said how they compose — or whether a boundary is worth creating at all.

Concretely, the repo had no answer to two probes it will definitely get: "why not one agent?" and "which orchestration pattern is this?" It also had no vocabulary for the topology both reference prototypes already use.

What's added

frameworks/orchestration-topology.md

• Two failures, not one. The agentic monolith (one agent accumulating dozens of tools, permission levels, and domains until it can't be tested or evolved) and multi-agent theater (seven agents because seven looks sophisticated — the Unforgivable of chasing trendy solutions). The governing trade-off: multi-agent doesn't eliminate complexity, it moves it into the orchestration layer, where you now also own delegation, coordination, state, failure handling, governance, and observability.
• The boundary test. Add a reasoning boundary only when ≥2 of these differ: failure mode, permissions, eval criteria, model tier, lifecycle/owner, business domain. None? It's a tool, not an agent.
• Six patterns — router, supervisor, sequential, fan-out, generator–verifier, hierarchical — each with the cost it carries (supervisors become the new monolith if they also do the work; fan-out needs partial-failure semantics; hierarchical makes ownership and debugging materially harder).
• What the prototypes actually are. Sequential pipeline, deterministic gate in front (the MNPI Scrubber fires before any LLM call, so a watch-list hit halts at zero token spend), generator–verifier pairs at the irreversible steps. Includes the defense for having no router or fan-out in v1, and what would change it at 10x volume — saying what would change your mind reads as judgment rather than defensiveness.
• MCP vs. A2A. "I need access to this capability" vs. "I need another agent to own this task." Complementary, not competing — and different blast radii: a tool call is bounded by its signature, a delegated objective only by the contract you wrote.
• The delegation contract. Objective → Context → Permissions → Expected Output → Completion Criteria → Failure Behavior, each with the failure that follows from skipping it. Plus context-as-permission, single ownership per task, bounded recursion, and instruction/data separation.
• Governance and observability as layers. The model proposes what should happen; the policy layer determines what is allowed to happen. And the debugging shift from "what did the model say?" to "what happened across the execution graph?" — which is why the audit trace is per-agent rather than per-run.
• The decision ladder (tool → agent → A2A → orchestration → governance → observability), walked top-down, stopping at the first rung that answers the problem.

Wiring

• frameworks/README.md, README.md, CLAUDE.md, COVERAGE_MAP.md (new coverage row), USING_CLAUDE_CODE.md, both START_HERE.md — count 16 → 17.
• Cross-linked from workflow-decomposition.md (new "what this framework does not answer" section), agent-shapes-catalog.md, and system-design-round.md (MCP → A2A distinction).

Numbering note: trust surface design stays Framework 16 as published; this is 17.

Checks

All new relative links resolve. No prototype or scoring code touched.

---

Generated by Claude Code