Skip to content

feat: prescribe sub-agent delegation and model tiering across the workflow lifecycle#259

Merged
aagnone3 merged 4 commits into
mainfrom
claude/eng-workflow-sub-agents-9dcc9a
Jul 22, 2026
Merged

feat: prescribe sub-agent delegation and model tiering across the workflow lifecycle#259
aagnone3 merged 4 commits into
mainfrom
claude/eng-workflow-sub-agents-9dcc9a

Conversation

@aagnone3

Copy link
Copy Markdown
Collaborator

Summary

Augments the eng workflow so the session's default agent is the orchestrator and validator across all six lifecycle stages — never the worker — delegating stage work to focused sub-agents and choosing each sub-agent's model by that unit's complexity.

  • New canonical reference wf-development/references/subagent-delegation.md: orchestrator/sub-agent roles, when to delegate, a lifecycle delegation map (grooming → development → testing → review → delivery → documentation), a three-tier model-selection matrix (economy / standard / strongest, judged on exit-check ambiguity, reasoning depth, and blast radius), dispatch-brief contract, and verification rules (bounded retries, tier escalation on dry attempts, never validate with a weaker model than produced the work).
  • Six lifecycle routers (wf-grooming, wf-development, wf-testing, wf-review, wf-delivery, wf-documentation) each gain a self-contained, stage-tailored "Sub-agent delegation" section, keeping routers valid for skills-only installs. wf-setup deliberately excluded (not a task-lifecycle stage).
  • workflows-work.md: Orchestrated execution is now the default execution model (Inline demoted to fallback for trivial edits or hosts without a sub-agent mechanism); the fixed "always Opus for implementation subagents" tiering is replaced with complexity-based per-dispatch selection.
  • workflows-orchestrate.md: Execute section opens with the coordinator-not-worker posture and adds an explicit dispatch step.
  • WORKFLOW_SKILLS.md: documents the delegation model as a cross-cutting architectural layer.

Sub-agents never mutate shared tracker/board/PR state; the orchestrator owns every write, all verification, and keeps the session's own model for triage.

Testing

  • bun test: 426 pass, 0 fail (architecture guardrails, link checks, vendored-script sync, counts all green)
  • No agent/skill counts changed; no version or changelog hand-edits

Post-Deploy Monitoring & Validation

  • No additional operational monitoring required: markdown-only workflow-policy change to plugin skills; behavior is exercised by consuming agents at session time and guarded by the architecture test suite.

Compound Engineered 🤖 Generated with Claude Code

aagnone3 and others added 3 commits July 21, 2026 20:27
…kflow lifecycle

The session's default agent is now the orchestrator and validator across
all six lifecycle stages, delegating stage work to focused sub-agents and
selecting each sub-agent's model by unit complexity.

- Add canonical subagent-delegation reference under wf-development with
  roles, lifecycle delegation map, model-selection matrix, dispatch
  contract, and verification rules
- Add stage-tailored delegation sections to the six lifecycle routers
- Make Orchestrated execution the default in workflows-work (Inline is
  now the fallback); replace fixed Opus tiering with complexity-based
  selection
- Open workflows-orchestrate Execute with the coordinator-not-worker
  posture and an explicit dispatch step
- Document the delegation model as a cross-cutting layer in
  WORKFLOW_SKILLS.md

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…n policy

An agent operating under a dispatch brief is a sub-agent for that unit;
it must not re-enter the policy as orchestrator or delegate further.
Prevents recursive delegation when a loosely written brief lets a
sub-agent load a workflow router.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…nisms

Review findings on PR #259: the self-disambiguation rule lived only in
the Roles prose, so it never traveled with an actual dispatch. Add it to
the dispatch-contract exclusions and the copy-paste subagent brief
template. Also tighten "shared state" to "shared tracker, board, or PR
state" in WORKFLOW_SKILLS.md, drop a second-person sentence from the
execution-model table, and clarify that in-loop reviewer agents are
distinct from the mandated wf-review stage.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… dispatch

Hosts inherit the session's model when a dispatch omits one, so the
prior "choose per complexity" guidance silently ran every sub-agent on
the most expensive tier by default. Make tier selection mandatory and
explicit at every dispatch, default to the lowest tier that can pass
the unit's exit checks, and flip "when uncertain take the stronger" to
start-lower-and-escalate-on-retry (with a carve-out for wrong answers
the exit checks cannot catch). Propagated to the canonical reference,
all six lifecycle routers, both orchestration references, and
WORKFLOW_SKILLS.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@aagnone3

Copy link
Copy Markdown
Collaborator Author

Pre-merge knowledge-disposition check (wf-documentation gate, against head 4e2e4f18)

Disposition: no separate compounding artifact required.

Rationale: the durable knowledge this work produced is the deliverable itself — the sub-agent delegation policy (skills/wf-development/references/subagent-delegation.md) and the delegation-model section of WORKFLOW_SKILLS.md. The two session learnings that emerged during review were folded back into the shipped policy rather than a docs/solutions/ entry:

  1. Safeguards must travel with the dispatch (the no-recursive-delegation rule was threaded into the dispatch contract and brief template after review found it stranded in prose).
  2. Host model inheritance makes omission the most expensive choice (explicit downshifted selection is now mandatory at every dispatch).

Out-of-scope residue was tracked as #260. No generated docs regions were touched; component counts unchanged.

@aagnone3
aagnone3 merged commit e956f65 into main Jul 22, 2026
6 checks passed
@aagnone3
aagnone3 deleted the claude/eng-workflow-sub-agents-9dcc9a branch July 22, 2026 02:37
@github-actions github-actions Bot mentioned this pull request Jul 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant