Skip to content

refactor: simplify capability-based orchestration #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
areshand merged 4 commits into from
Aug 24, 2026
Merged

refactor: simplify capability-based orchestration #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0e838d7
fix: route direct production operations without implementation scouts
areshand Aug 24, 2026
031064d
refactor: let orchestrator select role graph
areshand Aug 24, 2026
ae94641
refactor: simplify orchestration prompts
areshand Aug 24, 2026
ffb620e
test: cover mocked orchestration lifecycle
areshand Aug 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
336 changes: 77 additions & 259 deletions orchestrator_prompt.md
View file
Open in desktop

Large diffs are not rendered by default.

38 changes: 38 additions & 0 deletions prompts/contracts/orchestration-invariants.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Orchestration Invariants

This document is a regression index, not an agent prompt. Runtime gates and the
named role/playbook modules own enforcement and procedure.

## Role And Launch Boundaries

- Core Disciplines
- intent-contract.md covers proxy/scaffold risk.
- parallel-execution.md owns parallel planning.
- validation-scheduling.md owns validation coordination.
- agent-spawning.md owns the Required Worker First Instruction.
- contract-scout.md and acceptance-scout.md own scout contracts.
- scope-guard.md owns scope review.
- validation-coordinator.md owns duplicate validation prevention.
- Spawn read-only roles through: SUBAGENT_CLI="$VERIFIER_CLI" multiagent subagent spawn

## Routing And Repair Boundaries

- Contract Scout Workflow
- Scope Guard Workflow
- Validation Coordinator Workflow
- Validation Failure Repair Workflow
- Safety Rules
- A failed relevant validation is repair evidence, not acceptance.
- finding-todo-loop.md owns todo-close and structured repair evidence.
- required-path-outside-owned: is an ownership blocker.
- At most one same-owned-path replacement is allowed.
- A live worker remains no-diff after a planning checkpoint only until an edit-or-blocker handoff.
- Do not let an active generic scout block a ready bounded worker.
- Record assignment-status NAME failed before replacing a killed owner.

## Evidence Boundaries

- Preserve historical-contract-ledger: in role instructions that consume it.
- Preserve source-owner-ledger: when source ownership is ambiguous.
- prompts/roles/build-verifier.md owns build-verification-passed: and final-diff binding.
- Build verification failures are not eval-wrapper paperwork.
276 changes: 51 additions & 225 deletions prompts/playbooks/implementation-lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,251 +1,77 @@
# Implementation Lifecycle Playbook

This playbook is mandatory for source implementation tasks. The launcher
includes it in the orchestrator's initial prompt. It is the canonical authority
for task phases, transitions, TODO convergence, and completion; role and routing
playbooks must not weaken its gates. Production operations use their versioned
Markdown runbook and production-operation review path instead of manufacturing
source-code roles.
This mandatory lifecycle applies to source implementation. Production actions
use the selected Markdown runbook and ops review path instead.

## Task-Adaptive Role Plan
## State Machine

Build the smallest dependency graph that can produce and independently validate
the requested artifact. Spawn a role only when its inputs are available. Do not
start scouts, verifiers, or reviewers speculatively.
Read persisted state with:

The supervisor's persisted review obligations are authoritative. Cost or
latency is never a reason to skip a pending obligation. The orchestrator may
request an additional obligation when risk is discovered, but it cannot waive
one.
multiagent workflow status "$MULTIAGENT_WORKFLOW_ID"

## Durable State
Normal transitions are:

Read the active workflow before routing work:
pre-implementation -> implementation -> post-implementation
post-implementation -> pre-implementation when TODOs remain
post-implementation -> complete when supervisor gates pass

```bash
multiagent workflow status "$MULTIAGENT_WORKFLOW_ID"
```
Never infer phase from conversation history or route a finding directly back
to implementation.

Do not infer the current phase from conversation history. Use the persisted
phase and record every transition with `multiagent workflow transition`.

## Phase Machine
## Pre-Implementation

The only normal lifecycle is:
Clarify the intended outcome, required evidence, material choices, and bounded
ownership. The explicit task contract is already approved; ask the user only
when materially different outcomes remain consistent with it.

```text
pre-implementation -> implementation -> post-implementation
post-implementation -> pre-implementation when active TODOs remain
post-implementation -> complete when terminal gates pass
```
The orchestrator chooses whether a scout is useful. A scout artifact, once
registered, is immutable input. With or without a scout, an independent
decision-authority reviewer must accept the proposed plan before the supervisor
can approve implementation. User-owned security, public-contract, destructive,
or difficult-to-reverse choices require user approval.

Never route a post-implementation finding directly to implementation. Add it to
the TODO queue, return to pre-implementation, and reconsider evidence,
decisions, authority, and the approved implementation context first.
Record the decision and prepare an implementation context containing the goal,
selected plan, authority basis, constraints, owned paths, and unresolved risks.
If a contract artifact exists, include its exact bytes and supervisor digest;
never paraphrase it.

## Pre-Implementation
multiagent workflow prepare-implementation "$MULTIAGENT_WORKFLOW_ID" --decision-id DECISION_ID --plan-id PLAN_ID --decision-revision REVISION --implementation-context CONTEXT_PATH --authority-review REVIEW_ID
multiagent workflow transition "$MULTIAGENT_WORKFLOW_ID" implementation

For every active TODO, determine whether it is:

- direct implementation under an already approved contract;
- factual uncertainty requiring bounded evidence collection; or
- a choice requiring a decision and authority classification.

Group TODOs that depend on the same choice. Record alternatives, assumptions,
evidence, and the proposed choice. Evidence collection must state its question,
sources, expected signal, and stop condition.

Use `multiagent decision` for durable alternatives, assumptions, the committed plan,
and later reflection. The lifecycle record is the phase/authority gate around
that decision ledger; it does not replace the ledger.

A decision is user-owned when it changes public behavior or contracts, roles or
responsibilities, persisted state or migration, security or trust boundaries,
destructive or difficult-to-reverse behavior, material scope or cost, or a
prior explicit user decision. Treat uncertain authority as user-owned. Evidence
may clarify a choice but does not transfer authority.

The user's explicit task contract is already approved public behavior. Do not
ask the user to choose it again or reinterpret repository alternatives as an
unanswered product decision. A user-owned question exists only when two
materially different outcomes both remain consistent with the complete request
after bounded source/test inspection. Otherwise select the narrowest
backward-compatible implementation of the stated contract and record that
source-backed choice as orchestrator-owned.

For consequential or uncertain decisions, run the independent
`decision-authority-reviewer` role. It must check both the proposed authority
and whether the TODOs or proposed assignment contain omitted decisions. Ask the
user before committing any user-owned decision.

Spawn that review read-only through the normal subagent path. This command path
is mandatory, not an example: do not replace it with a provider-native `Agent`,
`Task`, team, or background-agent tool.

```bash
SUBAGENT_CLI="$VERIFIER_CLI" multiagent subagent spawn decision-authority-reviewer \
--role reviewer --instruction-file AUTHORITY_REVIEW_INPUT
multiagent subagent wait decision-authority-reviewer --timeout 900
```

Apply the same rule to contract scouts, workers, ops agents, and post-execution
reviewers. Only `multiagent subagent spawn` establishes the required Linux role,
Landlock policy, trusted runtime environment, and durable lifecycle evidence.

Do not continue merely because an immediate poll still reports `running`.
Inspect the completed or blocked result after the bounded wait and persist its
actual authority finding before preparing implementation.

Create an approved implementation context document containing the selected
plan, decision and plan IDs, authority and approval basis, intended outcome,
rejected alternatives and reasons, must-do and must-not-do constraints, migration choice,
responsibility boundary, affected paths, unresolved questions, and revision.
When the workflow has a registered contract artifact, never retype, summarize,
or reconstruct that artifact or its digest. Compose the approved context from
the supervisor-owned values and the exact artifact file bytes:

```bash
contract_path="$(multiagent workflow value "$MULTIAGENT_WORKFLOW_ID" contract_artifact)"
contract_hash="$(multiagent workflow value "$MULTIAGENT_WORKFLOW_ID" contract_artifact_sha256)"
{
printf 'contract-artifact-sha256=%s\n' "$contract_hash"
cat "$contract_path"
cat APPROVED_CONTEXT_BODY_PATH
} >CONTEXT_PATH
```

Write the selected plan and other implementation context to
`APPROVED_CONTEXT_BODY_PATH` first. Do not edit the registered artifact file,
copy its contents through model-generated text, or calculate a replacement
digest. The exact composition above is required even when the artifact is
already visible in conversation history.
Commit the selected alternative with `multiagent decision commit`, then record the
passed authority review and approved context with:

```bash
multiagent workflow prepare-implementation "$MULTIAGENT_WORKFLOW_ID" \
--decision-id DECISION_ID \
--plan-id PLAN_ID \
--decision-revision REVISION \
--implementation-context CONTEXT_PATH \
--authority-review REVIEW_ID
multiagent workflow transition "$MULTIAGENT_WORKFLOW_ID" implementation
```

Do not leave active evidence or decision TODOs when entering implementation.
Direct implementation TODOs may remain active and must be assigned to bounded
workers.
The supervisor rejects missing review evidence, changed context, or active
evidence and decision TODOs.

## Implementation

Spawn bounded exploitation workers only after the implementation gate passes.
Every assignment must reference the active workflow, decision, and plan. The
worker's first instruction must contain the complete current approved
implementation context; a decision ID alone is insufficient.
Spawn bounded workers only after the implementation permit passes. Include the
active workflow, decision, plan, complete approved context, and owned paths.
New uncertainty or a changed plan becomes a TODO and returns to
pre-implementation.

When writers stop, freeze the candidate and enter post-implementation:

Production runbook operations are not workspace implementation. For a signed
prod-mcp request, do not create a worker or assignment. Spawn the `ops` role
after independent review of the exact request and have that role invoke
`multiagent ops execute --request-file PATH --reviewer REVIEWER_NAME`. The
reviewer argument is mandatory and must name the finalized reviewer that
inspected that unchanged request file. This special case remains subject to the active
workflow, decision, plan, runbook, bounds, and post-execution review.
multiagent workflow transition "$MULTIAGENT_WORKFLOW_ID" post-implementation --diff-hash DIFF_HASH

Do not silently change the approved plan. A newly discovered choice or factual
uncertainty becomes a TODO and returns through pre-implementation.
## Post-Implementation

When implementation stops, capture worker output, stop or freeze every writer,
record the candidate diff hash, and enter post-implementation:
Query persisted obligations and run exactly the pending independent reviews
against the frozen diff. Record only finalized reviewer evidence with the exact
required marker. A finding cannot be replaced by a later pass; add accepted
findings to the TODO queue and use finding-todo-loop.md for repair evidence.

```bash
multiagent workflow transition "$MULTIAGENT_WORKFLOW_ID" post-implementation \
--diff-hash DIFF_HASH
```
If TODOs remain:

## Post-Implementation
multiagent workflow transition "$MULTIAGENT_WORKFLOW_ID" pre-implementation

Query the supervisor for obligations bound to the frozen candidate diff and run
exactly the pending independent reviews. The supervisor automatically requires
`technical` and `decision-drift` for a source diff, requires `reflection` after
a repair iteration, and accepts an additional `scope` obligation when the
change surface or discovered risk warrants it.

- `decision-drift`: compare the diff to the authorized implementation context;
- `scope`: check scope, simplicity, ownership, and unnecessary complexity;
- `technical`: verify behavior and the accepted contract;
- `reflection`: compare expected and actual results and identify improvements.

Every reviewer final message must include an exact durable marker on its own
line: `review-record: type=TYPE verdict=pass|findings diff=DIFF_HASH` (use
`diff=-` for decision-authority). A Markdown list prefix or enclosing backticks
are accepted as cosmetic formatting, but surrounding prose is not. Wait for and finalize that reviewer before
recording its result. Record each review with `multiagent workflow
record-review ... --reviewer REVIEWER_NAME`; the supervisor rejects an
orchestrator-authored verdict that is not backed by the finalized read-only
reviewer's matching marker. The supervisor also scans finalized reviewer
messages: a findings marker for the current candidate cannot be discarded by
launching a replacement reviewer and recording only the later pass. Record the
finding, route it through the repair loop, and begin a new lifecycle iteration
before attempting completion. Every actionable finding must be added with
`multiagent workflow add-todo`; a review with findings is not a terminal review.

Technical verifier findings must also use the existing structured
`finding-create -> todo-create -> resolution-create -> todo-close` protocol in
`prompts/playbooks/finding-todo-loop.md`. Mirror each accepted repair item into
the lifecycle queue using the finding or TODO ID as `--origin`. Resolve the
lifecycle item only after the structured repair evidence passes. The lifecycle
queue governs iteration and decision reconsideration; the structured finding
store governs technical closure.

Resolve a TODO only as:

- `completed`, with implementation and validation evidence; or
- `skipped`, with `out-of-scope` or `unavailable-now`, a concrete reason,
evidence, deciding authority, and a destination or resume condition when the
work remains relevant.

Do not use a skip to weaken the accepted contract. User approval is required
to skip a user-owned requirement or accept user-visible residual risk.

If active TODOs remain, return to pre-implementation:

```bash
multiagent workflow transition "$MULTIAGENT_WORKFLOW_ID" pre-implementation
```

This increments the iteration and invalidates the prior implementation permit.
This invalidates the prior permit and begins a new reviewed iteration.

## Completion

Complete only when every TODO is completed or validly skipped, no user-owned
decision is unanswered, and every supervisor-created review obligation passes
against the current candidate diff hash:

```bash
multiagent orchestrator complete
```

This is only a completion request. The supervisor holds the lifecycle lock,
runs the lifecycle completion check and `subagent gate-check`, and only then
atomically writes `phase=complete`. Direct `workflow transition ... complete`
is forbidden. A rejected request leaves the workflow in post-implementation so
the orchestrator can route repairs.
After it succeeds, the candidate is sealed: stop launching workers or reviewers
and do not mutate the repository. The privileged writer bridge independently
rechecks the live lifecycle phase and rejects any post-completion writer, even
if a shell command overrides `MULTIAGENT_LIFECYCLE_ENFORCEMENT`.

`MULTIAGENT_VERIFIER_MAX_ITERATIONS` is an escalation threshold, not an
acceptance condition. At the threshold, reconsider the route, surface a
blocker, or ask the user. Never accept merely because the threshold was reached.
# Workflow TODO command contract

Use the CLI's exact TODO vocabulary; do not guess aliases such as `implementation` or `task`:

```bash
multiagent workflow add-todo "$MULTIAGENT_WORKFLOW_ID" TODO_ID \
--kind direct|decision \
--summary "SUMMARY"
```

Operational execution with an already stated caller goal is `--kind direct`. A TODO does not bypass contract registration, implementation-context binding, or authority review.
Request completion only when TODOs are resolved, user-owned decisions are
answered, and every supervisor obligation passes against the current diff:

multiagent orchestrator complete

The supervisor atomically accepts or rejects completion. Direct transition to
complete, post-completion writers, and acceptance based on iteration count are
forbidden.
Loading
Loading