miaco (mee-AH-koh) is the command-line embodiment of Mia, the Recursive DevOps Architect. You hand it a messy, half-formed prompt; it hands you back a structured decomposition you can reason about, search against your own memory, and advance into real work.
It treats every prompt as structural tension — the charged space between what you want to create and what is true right now — and gives you commands that move you across that space instead of just answering you.
The published package is
mia-co; the installed binary ismiaco.
🌸 Think of miaco as a workbench, not an oracle. You don't ask it for the answer; you watch your intention get laid out in the open, its blind spots flagged, its memory consulted, until the next move is obvious.
npm install -g mia-co
miaco --help # every command + live env-var valuesThen:
miaco examples # copy-paste starting points
miaco decompose run -p "your first prompt"miaco decompose run -p "Redesign auth to support OAuth2, SAML, and magic links \
without breaking the existing session-cookie flow"You get a PDE (Prompt Decomposition) — a folder that holds your prompt broken into:
| You receive | What it gives you |
|---|---|
| Primary intent | the one thing this prompt is really asking for, with a confidence score |
| Secondary intents | the implicit asks you'd otherwise miss |
| Four Directions | the work mapped to Vision / Planning / Action / Reflection |
| Action stack | ordered steps, with dependencies, ready to execute |
| Ambiguity flags | the vague or contradictory parts — named, not silently assumed |
That last row is the point. miaco doesn't pretend your prompt was clear. It tells you where it wasn't — and then gives you a way to resolve it.
decompose ──▶ qmd-inquiry ──▶ clarify ──▶ continue / steer ──▶ stc
(structure) (resolve from (settle (drive the engine (chart the
memory) the rest) to actually build) tension)
decomposeturns the prompt into structure — and flags what's ambiguous.qmdexplores your shared markdown memory to resolve those flagged ambiguities — fast keyword search for intents, deeper semantic search where meaning matters most. The blind spots the decomposition surfaced get answered from what you already know.clarifysettles the obvious placeholders that remain.continue/steerreopen the same session and drive a coding agent to do the work.stc/pde-to-stturn the resolved decomposition into a Structural Tension Chart you can track.
🌸 Decomposition asks the brave question — "what here is unclear?" — and QMD answers it from your own remembered knowledge. The ambiguity isn't a failure; it's the doorway to the memory that resolves it.
➡️ Full per-command walkthrough: COMMANDS.md
This is the command most sessions begin with. The basics:
miaco decompose run -p "<your prompt>" # decompose inline
miaco decompose run -p @./prompt.md # …or read it from a file
miaco decompose run -p "<prompt>" --engine ollama # …on a local modelWhat makes it powerful is how it decomposes. The same prompt can be broken down three different ways depending on what you need:
| Strategy | The experience you get | Reach for it when |
|---|---|---|
standard (default) |
One clean pass. Fast, cheap, predictable. | The prompt is focused and well-defined. |
iterative-refinement |
Four progressive passes — each one deepens the structure (intents → directions → actions → calibration). | The prompt is complex and interleaved; one pass comes out shallow. |
adversarial-consensus |
Two opposing readings — one optimistic, one skeptical — reconciled into one. | The prompt is ambiguous or high-stakes and you want its blind spots surfaced. |
miaco decompose run -p "<prompt>" --strategy iterative-refinement
miaco decompose run -p "<prompt>" --strategy adversarial-consensus➡️ How each strategy thinks, when to choose it, and what it costs: STRATEGIES.md
Every decomposition runs on the model you choose — cloud or local. Pick once with a flag, or set MIACO_DEFAULT_ENGINE to make it the default:
copilot · claude · gemini · codex · pva · hermes · ollama · opencode
- Cloud agents (
copilot,claude,gemini,codex,pva,hermes) capture and resume their sessions, socontinueandsteerpick up exactly where you left off. - Local agents (
ollama,opencode) keep the whole loop on your machine — no prompt ever leaves the host.
miaco --help lists every engine and its tuning knobs with their current values. You rarely need more than --engine.
Beyond the decomposition loop, miaco carries the engineering-world toolkit. Each is one command family — full usage lives in COMMANDS.md.
| Command | The experience |
|---|---|
qmd |
Search your shared markdown memory directly — keyword or semantic. |
qmd-inquiry-decompose |
Auto-resolve a PDE's flagged ambiguities against that memory. |
clarify |
Generate a clarification pass for the placeholders in a PDE tree. |
continue / steer |
Resume a PDE session and drive the engine — interactively or one-shot. |
stc / pde-to-st |
Turn a decomposition into a Structural Tension Chart / Four Questions. |
chart |
Build and review structural tension charts by hand. |
schema · validate |
Design and validate NCP schemas and story structures. |
trace |
Open correlation traces across the wider narrative-intelligence stack. |
skill |
Install miaco's packaged agent skill into your workspace. |
miaco is the Engineering eye of a three-part family. Each tool sees the same work through a different lens:
| Universe | Voice | The question it holds |
|---|---|---|
| 🔧 Engineering | Mia (miaco) | Is the structure sound? Is the intent clear? |
| 📖 Story | Miette (miatel) | Does the arc cohere? Do the themes thread? |
| 🙏 Ceremony | Ava8 (miawa) | Is the work honored? Is there a pause to reflect? |
miaco holds the structural tension between Desired Outcome and Current Reality and treats it as generative — a force to create with, never a problem to make disappear.
- COMMANDS.md — what you ask each command, and what it gives back
- STRATEGIES.md — the three decomposition strategies in depth
miaco: where a prompt stops being a wish and becomes a structure you can build from.