Engineering Orchestrator
Decides what happens, in what order, and when to stop. Every other dev skill
is a specialist; this one is the lead engineer who assigns them.
Two failure modes are equally bad: activating everything for a typo, and
skipping a security gate to save tokens. The orchestrator optimises for the
smallest plan that still contains every mandatory gate.
1. Protocol
- Read the request literally. Extract the requested outcome, not the
supposed intent behind it. Record what was explicitly asked and what was
not.
- Classify the task into one or more categories from section 2.
- Locate the surface: which application, which layer, which files. When
this cannot be answered, exploration is the first step by definition.
- Establish the stack through
project-exploration, at the depth from
its section 2.
- Compose the plan from section 3, then apply the mandatory gates in
section 4 and the exclusion rules in section 5.
- Announce the plan in one block, at most one line per step.
- Execute step by step. Before each step, classify its complexity with
task-complexity and route it with model-routing; the two run per step,
not once for the whole request, because a plan's steps rarely carry the
same risk. On every dispatch to a subagent, resolve a model per
model-routing section 7 and pass it through the dispatch override,
without exception; an agent's own frontmatter default is never relied on
to happen to match. Record the dispatch in model-routing's routing log.
After each step, check its exit condition before moving on.
- Re-plan when a step invalidates an assumption. A discovery that changes
the category restarts planning from step 2, and the change is stated. The
same discovery is a reclassification for
task-complexity and an
escalation or de-escalation for model-routing: one event, read by all
three, never three separate judgment calls reaching different answers.
Escalate without re-planning when a step's returned output fails a
quality check instead: shallow against the brief's acceptance items, a
factual error found on verification, an uncited claim where one was
required, a missed required section, a failed test or review gate, or a
contradiction with a source. This is model-routing's
output-quality-failure trigger, section 6: the category and the plan do
not change, the step is redispatched one model tier stronger with the
failed output kept for comparison, and the escalation is recorded in the
routing log. A second failure of the same step at the strongest tier is
not redispatched a third time; it is anti-loop rule 5, a blocker reported
to whoever owns the task, not absorbed by another dispatch.
- Close with the completion verdict of section 7.
2. Classification
A request receives one primary category and any number of secondary ones. The
first twenty are the general categories; the remainder name a surface with its
own failure modes and its own plan.
| Category |
Recognised by |
| EXPLORATION |
unfamiliar codebase, how does X work, where is Y |
| ARCHITECTURE |
new subsystem, boundary change, data ownership, scaling shape |
| FRONTEND |
component, page, client state, form, rendering |
| BACKEND |
endpoint, handler, service, job, queue, business rule |
| FULLSTACK |
a feature crossing client and server |
| DATABASE |
schema, migration, query, index, transaction |
| API |
contract, versioning, payload shape, status codes |
| AUTHENTICATION |
login, session, token, provider, password, MFA |
| SECURITY |
vulnerability, audit, hardening, incident, dependency alert |
| VALIDATION |
untrusted input, schema, sanitisation, boundary |
| DEBUGGING |
reported defect, unexpected behaviour, failing test, crash |
| PERFORMANCE |
slow, timeout, memory, bundle size, query cost |
| UI_UX |
layout, visual design, interaction, accessibility, responsive |
| TESTING |
coverage, missing tests, flaky test, test strategy |
| BROWSER_AUTOMATION |
end to end flow, screenshot, visual check, journey |
| DOCUMENTATION |
readme, api docs, setup, decision record |
| GIT |
branch, commit, pull request, history, conflict |
| RELEASE |
ship, deploy readiness, changelog, version |
| REFACTORING |
restructure without behaviour change |
| DEPENDENCY |
add, remove, replace or upgrade a library |
| QUALITY_CAMPAIGN |
validate a whole product, QA campaign, release validation |
| ACCESSIBILITY |
keyboard, screen reader, contrast, WCAG, audit |
| REGRESSION |
after a fix or a merge, what still works |
| MIGRATION |
framework, provider, database or architecture change |
| LEGACY |
inherited codebase, no tests, nobody knows how it works |
| INCIDENT |
production degraded, outage, data at risk, postmortem |
| INFRASTRUCTURE |
provisioning, terraform, cloud resources, environments |
| PAYMENTS |
checkout, subscription, invoice, refund, webhook from a provider |
| JOBS |
queue, worker, cron, scheduled task, webhook consumer |
| REALTIME |
websocket, live updates, presence, collaboration |
| FILES |
upload, download, attachment, media, export, import |
| I18N |
translation, locale, timezone, currency format, right to left |
| SEO |
metadata, sitemap, canonical, indexing, structured data |
| DESIGN_SYSTEM |
tokens, component library, theme, visual consistency |
| PRIVACY |
personal data, retention, erasure, consent, export |
| CACHING |
cache, invalidation, CDN, stale data |
| ANALYTICS |
events, funnels, conversion, product measurement |
| FEATURE_FLAGS |
toggle, gradual rollout, kill switch, experiment |
| SITE_TEMPLATE |
a client site from a content file, portfolio or showcase, no-code handover |
Misclassification is cheap to fix and expensive to ignore. When two categories
compete, take the one with the stricter gates.
3. Plan composition
Canonical plans live in resources/execution-plans.md, one per category, in a
machine checkable format. The orchestrator starts from the canonical plan and
adapts it to the project.
Adaptation rules:
- A step whose skill has no purchase on this project is dropped, with the
reason stated. Example:
playwright-automation on a repository with no
browser surface.
- A step is added when the surface demands it. Example: adding
input-validation to a FRONTEND task because the page introduces a server
action.
- Steps are never reordered across a gate boundary from section 4.
Composition for multi category requests: merge the plans, deduplicate, and
keep the earliest position of each step.
4. Mandatory gates
These are never dropped to save time. Dropping one is a defect in the plan,
not an optimisation.
| Gate |
Applies when |
Enforced by |
| Exploration before decision |
any unread code is touched |
project-exploration |
| Validation before persistence |
any new external input reaches storage or a side effect |
input-validation |
| Authorization before exposure |
any new route, action or query returning user scoped data |
security-audit |
| Security review before merge |
auth, payments, uploads, user content, permissions, secrets, dependencies |
security-audit |
| Test before done |
any behaviour change |
testing-quality |
| Review before delivery |
any code written by the agent |
code-review-protocol |
| Continuity before handoff |
any session that changed the repository |
project-continuity |
| Author check before commit |
every commit |
git-workflow |
A gate can be satisfied by evidence rather than by a full skill run. Example:
the test gate is satisfied when the change is covered by an existing test that
was executed and observed to fail before and pass after.
5. Exclusion rules
The orchestrator does not activate:
architecture-design for a change confined to one existing module;
ui-ux-engineering for a change with no visual output;
playwright-automation when no browser tooling exists and the task does not
justify introducing it;
performance-engineering without a measurement or a concrete symptom;
dependency-selection unless a library is actually being added, replaced or
removed;
release-readiness outside an explicit ship or release request;
- itself, recursively. One orchestration per request, re-planned in place.
6. Anti-loop rules
- A skill runs at most twice per task. The second run must state what changed
since the first.
- A finding rejected once is not re-raised in the same form.
- When two skills disagree, the stricter one wins for security and
correctness, the project convention wins for style.
- Verification is not repeated when its inputs are unchanged.
- When a plan produces no progress twice in a row, the orchestrator stops and
reports the exact blocker rather than cycling.
These five rules are enforced here, at the orchestrator. token-optimization
is the discipline that keeps each individual step proportional; it does not
duplicate this section and this section does not duplicate it.
7. Completion verdict
The task is complete when all of the following are true, each with evidence:
- Every step of the plan ran or was dropped with a stated reason.
- Every mandatory gate that applies was satisfied.
- The definition of done from
engineering-core section 8 passes.
- The user visible outcome matches the literal request.
- What remains is named, or nothing remains.
The verdict is one of Complete, Partial with the named remainder, or
Blocked with the exact external blocker. There is no fourth value, and
Complete is never used to mean almost complete.
8. Plan announcement format
Category: BACKEND, secondary SECURITY
Surface: apps/api, payments module
Plan:
1 project-exploration L2, payments slice
2 architecture-design, transaction boundary only
3 backend-engineering, the endpoint
4 input-validation, request body and idempotency key
5 security-audit, authorization and amount handling
6 testing-quality, unit plus integration
7 code-review-protocol
8 technical-documentation, api reference
9 project-continuity
10 git-workflow
Dropped: ui-ux-engineering, no visual surface.
Nine lines of plan for a day of work is correct. Nine paragraphs is not.
9. Auto-critique
Score from 0 to 5: classification accuracy, minimality of the plan, presence
of every applicable gate, correctness of the ordering, quality of the dropped
step reasons, honesty of the completion verdict.
Threshold: no axis below 3, average at least 4. A plan missing an applicable
gate scores 0 on that axis regardless of the rest, and is recomposed.
10. Auto-critique of the orchestrator itself
Every fifth task, verify that plans are not drifting toward a fixed maximal
sequence. Symptom: the same twelve steps for tasks of very different size.
Cause: classification collapsed into one category. Correction: re-read
section 2 and re-derive the surface.
11. Interfaces
- Upstream:
engineering-core.
- Downstream: every skill in
dev-skills.
- Reference data:
resources/execution-plans.md,
resources/routing-table.md.
- Validated by:
tests/validate-orchestration.sh.
1---2name: engineering-orchestrator3description: "Central routing layer for engineering work: classifies the request, detects the affected surface and the real stack, selects the smallest complete set of dev skills, orders them, defines the verification gates and decides when the task is done. Load first on any coding, review, debugging or release request."4license: MIT5metadata:6 source: https://skillmd.com/skills/handsomeboy990/engineering-orchestrator7 category: dev-skills8 version: 1.1.09 depends_on: [engineering-core, project-exploration]10 outputs: [task-classification, execution-plan, verification-gates, completion-verdict]11---1213# Engineering Orchestrator1415Decides what happens, in what order, and when to stop. Every other dev skill16is a specialist; this one is the lead engineer who assigns them.1718Two failure modes are equally bad: activating everything for a typo, and19skipping a security gate to save tokens. The orchestrator optimises for the20smallest plan that still contains every mandatory gate.2122## 1. Protocol23241. **Read the request literally.** Extract the requested outcome, not the25 supposed intent behind it. Record what was explicitly asked and what was26 not.272. **Classify** the task into one or more categories from section 2.283. **Locate the surface**: which application, which layer, which files. When29 this cannot be answered, exploration is the first step by definition.304. **Establish the stack** through `project-exploration`, at the depth from31 its section 2.325. **Compose the plan** from section 3, then apply the mandatory gates in33 section 4 and the exclusion rules in section 5.346. **Announce the plan in one block**, at most one line per step.357. **Execute step by step.** Before each step, classify its complexity with36 `task-complexity` and route it with `model-routing`; the two run per step,37 not once for the whole request, because a plan's steps rarely carry the38 same risk. On every dispatch to a subagent, resolve a model per39 `model-routing` section 7 and pass it through the dispatch override,40 without exception; an agent's own frontmatter default is never relied on41 to happen to match. Record the dispatch in `model-routing`'s routing log.42 After each step, check its exit condition before moving on.438. **Re-plan when a step invalidates an assumption.** A discovery that changes44 the category restarts planning from step 2, and the change is stated. The45 same discovery is a reclassification for `task-complexity` and an46 escalation or de-escalation for `model-routing`: one event, read by all47 three, never three separate judgment calls reaching different answers.48 **Escalate without re-planning when a step's returned output fails a49 quality check** instead: shallow against the brief's acceptance items, a50 factual error found on verification, an uncited claim where one was51 required, a missed required section, a failed test or review gate, or a52 contradiction with a source. This is `model-routing`'s53 `output-quality-failure` trigger, section 6: the category and the plan do54 not change, the step is redispatched one model tier stronger with the55 failed output kept for comparison, and the escalation is recorded in the56 routing log. A second failure of the same step at the strongest tier is57 not redispatched a third time; it is anti-loop rule 5, a blocker reported58 to whoever owns the task, not absorbed by another dispatch.599. **Close** with the completion verdict of section 7.6061## 2. Classification6263A request receives one primary category and any number of secondary ones. The64first twenty are the general categories; the remainder name a surface with its65own failure modes and its own plan.6667| Category | Recognised by |68|---|---|69| EXPLORATION | unfamiliar codebase, how does X work, where is Y |70| ARCHITECTURE | new subsystem, boundary change, data ownership, scaling shape |71| FRONTEND | component, page, client state, form, rendering |72| BACKEND | endpoint, handler, service, job, queue, business rule |73| FULLSTACK | a feature crossing client and server |74| DATABASE | schema, migration, query, index, transaction |75| API | contract, versioning, payload shape, status codes |76| AUTHENTICATION | login, session, token, provider, password, MFA |77| SECURITY | vulnerability, audit, hardening, incident, dependency alert |78| VALIDATION | untrusted input, schema, sanitisation, boundary |79| DEBUGGING | reported defect, unexpected behaviour, failing test, crash |80| PERFORMANCE | slow, timeout, memory, bundle size, query cost |81| UI_UX | layout, visual design, interaction, accessibility, responsive |82| TESTING | coverage, missing tests, flaky test, test strategy |83| BROWSER_AUTOMATION | end to end flow, screenshot, visual check, journey |84| DOCUMENTATION | readme, api docs, setup, decision record |85| GIT | branch, commit, pull request, history, conflict |86| RELEASE | ship, deploy readiness, changelog, version |87| REFACTORING | restructure without behaviour change |88| DEPENDENCY | add, remove, replace or upgrade a library |89| QUALITY_CAMPAIGN | validate a whole product, QA campaign, release validation |90| ACCESSIBILITY | keyboard, screen reader, contrast, WCAG, audit |91| REGRESSION | after a fix or a merge, what still works |92| MIGRATION | framework, provider, database or architecture change |93| LEGACY | inherited codebase, no tests, nobody knows how it works |94| INCIDENT | production degraded, outage, data at risk, postmortem |95| INFRASTRUCTURE | provisioning, terraform, cloud resources, environments |96| PAYMENTS | checkout, subscription, invoice, refund, webhook from a provider |97| JOBS | queue, worker, cron, scheduled task, webhook consumer |98| REALTIME | websocket, live updates, presence, collaboration |99| FILES | upload, download, attachment, media, export, import |100| I18N | translation, locale, timezone, currency format, right to left |101| SEO | metadata, sitemap, canonical, indexing, structured data |102| DESIGN_SYSTEM | tokens, component library, theme, visual consistency |103| PRIVACY | personal data, retention, erasure, consent, export |104| CACHING | cache, invalidation, CDN, stale data |105| ANALYTICS | events, funnels, conversion, product measurement |106| FEATURE_FLAGS | toggle, gradual rollout, kill switch, experiment |107| SITE_TEMPLATE | a client site from a content file, portfolio or showcase, no-code handover |108109Misclassification is cheap to fix and expensive to ignore. When two categories110compete, take the one with the stricter gates.111112## 3. Plan composition113114Canonical plans live in `resources/execution-plans.md`, one per category, in a115machine checkable format. The orchestrator starts from the canonical plan and116adapts it to the project.117118Adaptation rules:119120- A step whose skill has no purchase on this project is dropped, with the121 reason stated. Example: `playwright-automation` on a repository with no122 browser surface.123- A step is added when the surface demands it. Example: adding124 `input-validation` to a FRONTEND task because the page introduces a server125 action.126- Steps are never reordered across a gate boundary from section 4.127128Composition for multi category requests: merge the plans, deduplicate, and129keep the earliest position of each step.130131## 4. Mandatory gates132133These are never dropped to save time. Dropping one is a defect in the plan,134not an optimisation.135136| Gate | Applies when | Enforced by |137|---|---|---|138| Exploration before decision | any unread code is touched | `project-exploration` |139| Validation before persistence | any new external input reaches storage or a side effect | `input-validation` |140| Authorization before exposure | any new route, action or query returning user scoped data | `security-audit` |141| Security review before merge | auth, payments, uploads, user content, permissions, secrets, dependencies | `security-audit` |142| Test before done | any behaviour change | `testing-quality` |143| Review before delivery | any code written by the agent | `code-review-protocol` |144| Continuity before handoff | any session that changed the repository | `project-continuity` |145| Author check before commit | every commit | `git-workflow` |146147A gate can be satisfied by evidence rather than by a full skill run. Example:148the test gate is satisfied when the change is covered by an existing test that149was executed and observed to fail before and pass after.150151## 5. Exclusion rules152153The orchestrator does not activate:154155- `architecture-design` for a change confined to one existing module;156- `ui-ux-engineering` for a change with no visual output;157- `playwright-automation` when no browser tooling exists and the task does not158 justify introducing it;159- `performance-engineering` without a measurement or a concrete symptom;160- `dependency-selection` unless a library is actually being added, replaced or161 removed;162- `release-readiness` outside an explicit ship or release request;163- itself, recursively. One orchestration per request, re-planned in place.164165## 6. Anti-loop rules1661671. A skill runs at most twice per task. The second run must state what changed168 since the first.1692. A finding rejected once is not re-raised in the same form.1703. When two skills disagree, the stricter one wins for security and171 correctness, the project convention wins for style.1724. Verification is not repeated when its inputs are unchanged.1735. When a plan produces no progress twice in a row, the orchestrator stops and174 reports the exact blocker rather than cycling.175176These five rules are enforced here, at the orchestrator. `token-optimization`177is the discipline that keeps each individual step proportional; it does not178duplicate this section and this section does not duplicate it.179180## 7. Completion verdict181182The task is complete when all of the following are true, each with evidence:1831841. Every step of the plan ran or was dropped with a stated reason.1852. Every mandatory gate that applies was satisfied.1863. The definition of done from `engineering-core` section 8 passes.1874. The user visible outcome matches the literal request.1885. What remains is named, or nothing remains.189190The verdict is one of `Complete`, `Partial` with the named remainder, or191`Blocked` with the exact external blocker. There is no fourth value, and192`Complete` is never used to mean almost complete.193194## 8. Plan announcement format195196```197Category: BACKEND, secondary SECURITY198Surface: apps/api, payments module199Plan:200 1 project-exploration L2, payments slice201 2 architecture-design, transaction boundary only202 3 backend-engineering, the endpoint203 4 input-validation, request body and idempotency key204 5 security-audit, authorization and amount handling205 6 testing-quality, unit plus integration206 7 code-review-protocol207 8 technical-documentation, api reference208 9 project-continuity209 10 git-workflow210Dropped: ui-ux-engineering, no visual surface.211```212213Nine lines of plan for a day of work is correct. Nine paragraphs is not.214215## 9. Auto-critique216217Score from 0 to 5: classification accuracy, minimality of the plan, presence218of every applicable gate, correctness of the ordering, quality of the dropped219step reasons, honesty of the completion verdict.220221Threshold: no axis below 3, average at least 4. A plan missing an applicable222gate scores 0 on that axis regardless of the rest, and is recomposed.223224## 10. Auto-critique of the orchestrator itself225226Every fifth task, verify that plans are not drifting toward a fixed maximal227sequence. Symptom: the same twelve steps for tasks of very different size.228Cause: classification collapsed into one category. Correction: re-read229section 2 and re-derive the surface.230231## 11. Interfaces232233- Upstream: `engineering-core`.234- Downstream: every skill in `dev-skills`.235- Reference data: `resources/execution-plans.md`,236 `resources/routing-table.md`.237- Validated by: `tests/validate-orchestration.sh`.