| name | dx-orchestrator |
| description | Use when working in a dx-managed repository (any directory
containing one or more dx declaration files, or whose `AGENTS.md`
references the dx paradigm). Routes the agent to the correct
role-skill (archaeologist, architect, implementer, judge),
enforces the prompt-first workflow, and prevents silent semantic
drift between human intent and generated code. Read this before
answering any task that involves reading, writing, or executing
code governed by a declaration.
|
dx Orchestrator
dx is a declarative specification language for the agentic AI
era. The declaration (a Markdown file with canonical extension
.md) is the source of truth for intent and constraints; the
imperative code is a derived artifact. Your first job in any dx
repo is to figure out which role you are playing and load the
corresponding skill.
This skill does not do work itself. It routes.
1. The Prime Directive
The declaration is the source of truth. Never write
imperative code that violates a defined invariant. If an
invariant is technically impossible to satisfy, propose a
mutation to the declaration rather than "fixing it in code."
Violating this rule is the single failure mode dx exists to
prevent. If you find yourself about to special-case the code to
make it work, stop and re-read the declaration.
2. Role Routing
Pick exactly one role per task. Load its skill and follow it strictly.
| Trigger phrase / situation | Load this skill |
|---|
| "Reverse-engineer this codebase into a declaration." | archaeologist |
| "There's no declaration here yet — distill one from the existing source." | archaeologist |
| "Write/refine the declaration." / "Add an invariant." / "Tighten intent." | architect |
| "Promote this assumption." / "Move X from assumptions to invariants." | architect |
"Generate the implementation from system.md." | implementer |
| "Make the code conform to the spec." / "Fix this code to satisfy X." | implementer |
| "Verify the implementation against the contracts." | judge |
| "Run the contracts. Tell me which ones fail and why." | judge |
Pure CLI usage (dx lint, fmt, diff, export) | dx-toolchain |
| Reconciling a declaration merge (lint then diff against merge base) | dx-toolchain §6a + architect |
Spec questions ("How do I encode an empty block?", "What goes in ## Intent?") | dx-authoring |
If the task spans multiple roles (common), execute them sequentially:
architect → implementer → judge. Never have one role silently doing another's
job — for example, the implementer must not add or remove invariants; that is
strictly the architect's job.
3. Universal Pre-Flight Checks
Before any role-specific work:
- Locate the declarations. Look for
.md files that begin
with a # <system> heading followed by ## Intent. At the
repo root and any obvious subdirectories. If there are none
and the user is asking you to write code, stop and ask whether
to invoke the archaeologist first.
- Validate them. Run
dx lint <file>.md on every
declaration you intend to read or modify. Lint errors mean the
file is structurally untrustworthy; fix them (as architect)
before doing anything else.
- Check for an
AGENTS.md. It encodes repo-specific
conventions that override generic skill guidance.
4. The Universal Invariants (apply to every role)
These come from AGENTS.md and apply regardless of which
role-skill you load. Re-read them before each non-trivial action.
4a. Explicit Assumption Logging (AGENTS.md §2)
When implementation requires a choice not specified in
## Intent or ## Invariants, you must not choose silently.
- Add an entry to the
## Assumptions block of the declaration
as a new ### <id> section.
- Document the heuristic leap and why it was made.
- Only then proceed.
This is the single mechanism by which dx converts silent LLM
hallucinations into auditable, promotable workflow state.
Skipping it defeats the entire system.
4b. The Verification Loop (AGENTS.md §3)
Before declaring any task complete:
dx lint every modified declaration. Must exit 0.- Generate or run the implementation.
- Compare implementation behavior against the
## Contracts
block.
- Treat any contract failure as a semantic bug, not a flaky
test.
4c. Pruning and Parsimony (AGENTS.md §4)
The architect's goal is the minimum viable constraint set.
If a requirement can be met without an explicit invariant, that
requirement belongs in ## Unconstrained, not ## Invariants.
Over-specification is a defect.
4d. Semantic Communication (AGENTS.md §5)
When summarizing changes for a human, summarize changes to
intent and invariants, not to lines of code. Use
dx diff <before>.md <after>.md rather than text diffs.
5. Handoff Protocol
When transitioning from one role to another within the same task, write a
single-line handoff in the conversation:
HANDOFF: <from-role> → <to-role>: <one-sentence reason>
Examples:
HANDOFF: architect → implementer: invariants are stable; generate Go code under cmd/.
HANDOFF: implementer → judge: implementation compiles and lints; run contracts.
HANDOFF: judge → architect: contract `greets_a_named_user` failed because the spec is
ambiguous about trailing whitespace — needs a new invariant or `## Unconstrained` entry.
This makes the loop legible to humans reviewing the transcript.
6. When to Stop and Ask
Escalate to the human (do not proceed silently) when:
- Two invariants directly contradict each other.
- A contract failure cannot be cleanly classified as either an implementation
bug or a spec gap.
- You would need to add more than three new assumptions to make progress;
that signals the spec is too sparse and the architect should be invoked
explicitly by the human.
- The user requests imperative behavior that would violate an existing
invariant. Cite the invariant by ID and ask whether to mutate the spec.
7. Anti-Patterns (Do Not Do)
- "Fix it in code." Never. Mutate the declaration or escalate.
- Silent assumption. Never ship code that embeds a heuristic
choice not recorded in
## Assumptions.
- Role bleed. The implementer never edits
## Invariants.
The architect never writes the implementation. The judge never
modifies either.
- Skipping
dx lint. Always run it on every declaration you
touch.
- Over-specifying. If the human didn't constrain it, it
belongs in
## Unconstrained, not in a fabricated invariant.
