Orchestrion Universal Agent Router

Orchestrion: Universal Agent Skill Router

A host-neutral skill for agents that must coordinate many other skills without pretending every agent is the same machine.

0. Activation

Use Orchestrion whenever the human asks for any of the following:

• Build, modify, debug, refactor, review, test, document, ship, or deploy software.
• Turn vague human intent into a plan or implementation.
• Use or combine skills from Superpowers, gstack, Matt Pocock skills, or llm-council-plus.
• Work in an unfamiliar repository.
• Make a decision with architecture, security, product, data, deployment, or long-term maintenance risk.
• Continue work after another agent/session.
• Create TODOs for agent execution.

If the task is trivial, still perform a lightweight host/capability check, but do not run the full orchestration ceremony.

1. Prime directive

The human may provide vague, messy, contradictory, incomplete, emotional, or misspelled tasks.

Do not jump straight into implementation.

Route the task through the strongest available workflow:

INTAKE
→ HOST DISCOVERY
→ SKILL DISCOVERY
→ AMBIGUITY REDUCTION
→ PLAN
→ COUNCIL CHECK WHEN HIGH-RISK
→ TODO CREATION
→ ISOLATED EXECUTION
→ TDD / DEBUG / IMPLEMENT
→ REVIEW
→ QA / SECURITY / PERFORMANCE
→ VERIFICATION
→ DOCS
→ SHIP / HANDOFF / RETRO

Non-negotiable contract

1. Do not pretend a skill, MCP tool, plugin, browser, or CLI exists.
2. Do not claim a skill was loaded unless it was actually invoked, read, imported, or applied through a declared fallback.
3. Do not implement through ambiguity when clarification/planning skills are available.
4. Do not patch bugs without reproduction and root-cause evidence.
5. Do not claim completion without verification evidence.
6. Do not ship without review and QA when those skills/tools exist.
7. Do not deploy without post-deploy observation when deployment/canary tools exist.
8. TODOs are the execution spine, not decoration.

2. Host-neutral vocabulary

Different agents expose skills differently. Use these abstract operations and map them to the current host.

Never expose these names as fake tool calls. They are implementation-independent mental handles.

3. Host discovery

Before choosing paths, identify where you are running.

3.1 Detect host identity

Inspect what is available, in this order:

1. System/developer/runtime metadata.
2. Built-in tool names.
3. Agent-specific command palette/slash command list.
4. Environment variables.
5. Project instruction files.
6. Local skill/plugin directories.
7. Process names or CLI help output, if terminal access exists.

3.2 Known host hints

Use these as hints, not truth. Verify locally.

If the host is unknown, proceed with the portable fallback protocol. Do not block unless the task requires unavailable tools.

4. Capability discovery

Create a capability matrix before running a serious workflow.

## Capability Matrix

- Host:
- Skill mechanism available: yes/no/unknown
- Slash commands available: yes/no/unknown
- MCP available: yes/no/unknown
- Terminal available: yes/no/unknown
- File editing available: yes/no/unknown
- Browser available: yes/no/unknown
- Git available: yes/no/unknown
- Issue tracker available: yes/no/unknown
- LLM Council Plus available: yes/no/unknown
- Existing project instructions: [AGENTS.md / CLAUDE.md / GEMINI.md / .cursor rules / other]
- Missing critical capabilities:

4.1 Generic local search commands

Use only if terminal/filesystem access exists.

# Common skill and instruction locations
for d in \
  "$HOME/.claude/skills" \
  "$HOME/.codex/skills" \
  "$HOME/.config/opencode/skills" \
  "$HOME/.cursor/skills" \
  "$HOME/.hermes/skills" \
  "$HOME/.gbrain/skills" \
  "$HOME/.kiro/skills" \
  "$HOME/.slate/skills" \
  "$HOME/.factory/skills" \
  "$HOME/.pi/agent/skills" \
  "$HOME/.agents/skills" \
  ".claude" ".cursor" ".codex" ".opencode" ".hermes" ".roo" ".clinerules" ".kilocode"
do
  [ -e "$d" ] && echo "FOUND $d"
done

# Find skill files without assuming host
find "$HOME" "$(pwd)" \
  -maxdepth 5 \( -iname "SKILL.md" -o -iname "AGENTS.md" -o -iname "CLAUDE.md" -o -iname "GEMINI.md" -o -iname "*rules*" \) \
  2>/dev/null | sort | head -200

5. Skill loading precedence

When multiple mechanisms exist, prefer the one with the strongest native semantics.

1. Native executable skill/slash command/plugin.
2. MCP tool that performs the intended action.
3. Local SKILL.md read/import.
4. Project instruction file, such as AGENTS.md, CLAUDE.md, GEMINI.md, rules files.
5. Official repo docs.
6. Manual fallback method, clearly labeled.

5.1 Missing skill rule

If a required skill is missing:

## Missing Skill Handling

- [ ] Name the missing skill.
- [ ] State which host/capability was checked.
- [ ] Search likely locations.
- [ ] If install is safe and permitted, install or print exact install steps.
- [ ] If install is not possible, use `FALLBACK_METHOD(skill-name)` and label it.
- [ ] Continue with best-effort only if correctness and safety are not compromised.

Never say "loaded X" if the agent only copied the idea of X.

6. Always-start skill gate

For non-trivial software work, first try to load:

using-superpowers

using-superpowers is the dispatcher/constitution layer. If present, obey it first.

If unavailable, apply this fallback:

## Fallback: using-superpowers

- [ ] Search for applicable skills before acting.
- [ ] Prefer process skills before implementation skills.
- [ ] If any skill has even a small chance of applying, inspect/load it before proceeding.
- [ ] Treat debugging/TDD/verification skills as rigid workflows.
- [ ] Treat product/design/planning skills as adaptable workflows.

7. Core skill families

7.1 Superpowers: discipline and workflow gates

Use as the constitutional workflow.

7.2 Matt Pocock skills: engineering clarity

Use to turn unclear work into crisp engineering artifacts.

7.3 gstack: specialist product/engineering team

Use for role-based scrutiny and shipping.

7.4 llm-council-plus: deliberation gate

Use for high-stakes decisions, not routine edits.

Council should be used for:

architecture decisions
security-sensitive work
irreversible migrations
large refactors
unclear product strategy
major UI direction choices
multiple plausible root causes
performance tradeoffs
API/data model design
deployment risk
when skills disagree
before high-impact shipping

Council should usually be skipped for:

typos
formatting
simple copy changes
obvious one-line fixes
routine tests
low-risk dependency bumps

Council access precedence

1. MCP tool/server if available.
2. Native skill/API wrapper if installed.
3. REST API or local web app if available.
4. CLI/script wrapper if present.
5. Human-readable council prompt prepared for manual use.

Council prompt

# Council Request

## Task
[One paragraph]

## Context
- Repo:
- Branch:
- Host agent:
- User goal:
- Constraints:
- Files:
- Existing behavior:
- Known failures:

## Options
1. Option A:
2. Option B:
3. Option C:

## Judge by
- Correctness
- Simplicity
- Maintainability
- Security
- Testability
- User impact
- Reversibility
- Implementation risk

## Required output
- Recommended option
- Why
- Rejected alternatives
- Hidden risks
- Required tests
- Stop/go decision

8. Task router

8.1 Vague or ambiguous task

using-superpowers
→ brainstorming
→ grill-me OR grill-with-docs
→ /office-hours if product-ish
→ llm-council-plus if high-impact or options conflict

TODO:

## Ambiguity TODO

- [ ] Restate the task concretely.
- [ ] Identify missing requirements.
- [ ] Identify hidden assumptions.
- [ ] Define success criteria.
- [ ] Define non-goals.
- [ ] Ask only blocking questions.
- [ ] Infer safely when blocked, and mark assumptions.
- [ ] Update CONTEXT.md/ADRs if appropriate.

8.2 New feature

using-superpowers
→ brainstorming
→ grill-with-docs
→ /office-hours
→ /autoplan
→ /plan-ceo-review
→ /plan-eng-review
→ /plan-design-review if UI/UX
→ /plan-devex-review if developer-facing
→ llm-council-plus if high-impact
→ to-prd
→ to-issues
→ using-git-worktrees
→ writing-plans
→ subagent-driven-development OR executing-plans
→ test-driven-development OR tdd
→ /review
→ requesting-code-review
→ receiving-code-review if needed
→ /qa
→ verification-before-completion
→ /document-release
→ /ship

TODO:

## Feature TODO

### Intake
- [ ] Host/capability matrix complete.
- [ ] Relevant skills loaded or fallback declared.
- [ ] User, pain, success metric, constraints defined.

### Product
- [ ] Product wedge reviewed.
- [ ] Scope mode chosen: expand / selective expand / hold / reduce.
- [ ] Non-goals documented.

### Architecture
- [ ] Current system understood.
- [ ] Data flow / state machine / failure paths documented.
- [ ] Test matrix defined.

### Council
- [ ] Council run or explicitly skipped as low-risk.
- [ ] Plan revised if council found material flaws.

### Execution
- [ ] Worktree/branch prepared.
- [ ] PRD/issues/tasks written.
- [ ] TDD loop used.
- [ ] Review and QA completed.
- [ ] Verification evidence captured.

8.3 Bug, regression, or flaky behavior

using-superpowers
→ systematic-debugging
→ diagnose
→ /investigate
→ zoom-out if architecture unclear
→ llm-council-plus if root cause disputed
→ test-driven-development OR tdd
→ /review
→ /qa OR /qa-only
→ verification-before-completion

TODO:

## Bug TODO

- [ ] Reproduce bug.
- [ ] Minimize reproduction.
- [ ] Define expected vs actual behavior.
- [ ] Trace data flow.
- [ ] Instrument if needed.
- [ ] Form hypotheses.
- [ ] Test hypotheses.
- [ ] Write failing regression test.
- [ ] Fix minimally.
- [ ] Verify test fails before fix and passes after fix.
- [ ] Re-run relevant suite.
- [ ] Capture evidence.

Hard rule:

No root cause, no fix.
No regression test, no completion.

8.4 Architecture cleanup/refactor

using-superpowers
→ zoom-out
→ improve-codebase-architecture
→ /plan-eng-review
→ llm-council-plus
→ to-prd
→ to-issues
→ using-git-worktrees
→ writing-plans
→ test-driven-development OR tdd
→ /review
→ verification-before-completion

TODO:

## Architecture TODO

- [ ] Current architecture mapped.
- [ ] Coupling/duplication/boundary issues identified.
- [ ] Refactor goal stated in behavior-preserving terms.
- [ ] Council critique obtained unless low-risk.
- [ ] Characterization tests added.
- [ ] Smallest reversible change chosen.
- [ ] No unrelated edits.

8.5 UI/UX/frontend polish

using-superpowers
→ brainstorming
→ grill-with-docs
→ /plan-design-review
→ /design-consultation if direction unclear
→ /design-shotgun if alternatives useful
→ /design-html if converting approved mockup
→ /design-review
→ /qa
→ /benchmark if performance-sensitive

TODO:

## Design TODO

- [ ] Target user and desired feeling identified.
- [ ] Existing design system inspected.
- [ ] Visual direction chosen.
- [ ] Accessibility considered.
- [ ] Before/after screenshots captured if browser available.
- [ ] UX reviewed.
- [ ] Browser QA completed.

8.6 Developer experience, APIs, SDKs, CLI, docs

using-superpowers
→ grill-with-docs
→ /plan-devex-review
→ /devex-review
→ to-prd
→ to-issues
→ tdd
→ /document-generate OR /document-release
→ /qa if browser flow exists

TODO:

## DX TODO

- [ ] Developer persona identified.
- [ ] First successful action defined.
- [ ] Setup flow tested or reason documented.
- [ ] API/CLI/docs friction listed.
- [ ] Examples verified.
- [ ] Docs updated.

8.7 Security-sensitive work

using-superpowers
→ careful / guard / freeze if available
→ git-guardrails-claude-code or equivalent
→ /cso
→ llm-council-plus
→ /review
→ verification-before-completion

Security-sensitive triggers:

auth
permissions
payments
PII
secrets
tokens
database access
file upload
admin flows
network calls
browser automation
deployment config
sandboxing
prompt injection surfaces

TODO:

## Security TODO

- [ ] Assets, actors, trust boundaries listed.
- [ ] Authn/authz checked.
- [ ] Input validation checked.
- [ ] Secrets checked.
- [ ] Injection paths checked.
- [ ] Unsafe file/network/browser paths checked.
- [ ] Council critique obtained for high-severity items.
- [ ] Exploit/regression test added where possible.

8.8 Testing/QA/browser verification

using-superpowers
→ test-driven-development OR tdd
→ /qa-only if report only
→ /qa if fixes allowed
→ /benchmark if performance-sensitive
→ verification-before-completion

TODO:

## QA TODO

- [ ] Critical flows listed.
- [ ] Expected results defined.
- [ ] Browser/devtools/logs/screenshots used if available.
- [ ] Bugs recorded by severity.
- [ ] Fixes limited to verified bugs.
- [ ] Regression tests added.
- [ ] Exact failing flow re-run.

8.9 Docs-only or docs-after-code

using-superpowers
→ grill-with-docs
→ /document-generate if missing docs
→ /document-release if code changed
→ /devex-review if onboarding docs

TODO:

## Docs TODO

- [ ] Doc type chosen: tutorial / how-to / reference / explanation.
- [ ] Code inspected before writing.
- [ ] Examples tested where possible.
- [ ] README/ARCHITECTURE/CONTRIBUTING/AGENTS-style files updated if affected.

8.10 Release/deploy/PR finalization

using-superpowers
→ finishing-a-development-branch
→ /ship
→ /land-and-deploy if approved
→ /canary
→ /retro

TODO:

## Release TODO

- [ ] Branch clean.
- [ ] Tests pass.
- [ ] Review complete.
- [ ] QA complete.
- [ ] Security/perf/doc gates complete as applicable.
- [ ] Verification evidence captured.
- [ ] PR/release notes prepared.
- [ ] Deploy only if approved.
- [ ] Canary/post-deploy checks complete.
- [ ] Retro captured if non-trivial.

9. Master TODO ledger

Maintain a living ledger. Use the host's TODO tool if available; otherwise maintain this Markdown.

# Orchestrion TODO Ledger

## Task
- Human request:
- Interpreted goal:
- Host:
- Repo:
- Branch/worktree:
- Risk level: low / medium / high / critical

## Capabilities
- Skills:
- MCP:
- Terminal:
- Browser:
- Git:
- Council:

## Assumptions
- [ ] ...

## Skill gates
- [ ] using-superpowers: loaded / fallback / unavailable
- [ ] ambiguity reducer:
- [ ] product gate:
- [ ] engineering gate:
- [ ] council gate:
- [ ] TDD/debug gate:
- [ ] review gate:
- [ ] QA gate:
- [ ] security gate:
- [ ] verification gate:
- [ ] docs gate:
- [ ] ship/handoff gate:

## Work items
| ID | State | Task | Skill/source | Evidence | Blocker |
|---|---|---|---|---|---|
| T1 | todo |  |  |  |  |

## Evidence
- Tests:
- Logs:
- Screenshots:
- URLs:
- Commits:
- PR:
- Council result:
- Review result:

State values:

todo
doing
blocked
needs-human
needs-council
needs-review
needs-qa
done
discarded

10. Bootstrap and installation appendix

Use this only when the human explicitly wants installation or when missing skills block safe work.

10.1 gstack

Generic install/detect:

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/gstack
cd ~/gstack
./setup

Target known host:

./setup --host codex
./setup --host opencode
./setup --host cursor
./setup --host factory
./setup --host slate
./setup --host kiro
./setup --host hermes
./setup --host gbrain

If OpenClaw delegates to another coding agent, install gstack in the spawned coding agent and add routing instructions to the parent agent's project instructions.

10.2 Superpowers

If native plugin marketplace exists, search for superpowers.

Known Claude-style commands:

/plugin install superpowers@claude-plugins-official
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

For other agents, prefer their plugin/extension marketplace or read/import the relevant skills/*/SKILL.md files.

10.3 Matt Pocock skills

npx skills@latest add mattpocock/skills

Then run the setup skill if available:

/setup-matt-pocock-skills

If slash commands are unavailable, read/import the installed skill Markdown files and apply them as documented methodologies.

10.4 llm-council-plus

Local app:

git clone https://github.com/jacob-bd/llm-council-plus.git
cd llm-council-plus
uv sync
cd frontend && npm install
cd ..
./start.sh

MCP mode where supported (use uv pip install -e . if pip is wrapped, or activate the project venv first):

uv pip install -e .
# host-specific MCP registration goes here

Claude-style MCP registration example:

claude mcp add llm-council python -m llm_council_mcp

Direct REST/API skill mode where supported:

mkdir -p ~/.claude/skills/llm-council-api
curl -o ~/.claude/skills/llm-council-api/SKILL.md \
  https://raw.githubusercontent.com/jacob-bd/llm-council-plus/main/skills/llm-council-api/SKILL.md

For non-Claude hosts, adapt this as:

1. make the Council API reachable,
2. expose it through MCP if the host supports MCP,
3. otherwise document the REST endpoints/tool wrapper in the host's project instructions.

11. Output rules

When reporting back to the human:

1. Say what was done.
2. Say which skills were actually loaded or which fallbacks were used.
3. Show the TODO ledger state.
4. Show verification evidence.
5. State remaining risks honestly.
6. Do not dump unnecessary ceremony unless useful.

Minimal completion format:

## Done

### Skills used
- ...

### Changes
- ...

### Verification
- ...

### Remaining risks
- ...

### Next action
- ...

12. Final mnemonic

Discover the room.
Load the right instruments.
Question the brief.
Plan the route.
Ask the council when the bridge is expensive.
Cut one slice.
Test the slice.
Invite review.
Walk the product in a browser.
Verify before victory.
Document the map.
Ship only with smoke cleared.