Engineering Orchestrator

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

1. Read the request literally. Extract the requested outcome, not the supposed intent behind it. Record what was explicitly asked and what was not.
2. Classify the task into one or more categories from section 2.
3. Locate the surface: which application, which layer, which files. When this cannot be answered, exploration is the first step by definition.
4. Establish the stack through project-exploration, at the depth from its section 2.
5. Compose the plan from section 3, then apply the mandatory gates in section 4 and the exclusion rules in section 5.
6. Announce the plan in one block, at most one line per step.
7. Execute step by step. After each step, check its exit condition before moving on.
8. Re-plan when a step invalidates an assumption. A discovery that changes the category restarts planning from step 2, and the change is stated.
9. 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.

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.

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

1. A skill runs at most twice per task. The second run must state what changed since the first.
2. A finding rejected once is not re-raised in the same form.
3. When two skills disagree, the stricter one wins for security and correctness, the project convention wins for style.
4. Verification is not repeated when its inputs are unchanged.
5. When a plan produces no progress twice in a row, the orchestrator stops and reports the exact blocker rather than cycling.

7. Completion verdict

The task is complete when all of the following are true, each with evidence:

1. Every step of the plan ran or was dropped with a stated reason.
2. Every mandatory gate that applies was satisfied.
3. The definition of done from engineering-core section 8 passes.
4. The user visible outcome matches the literal request.
5. 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.