🧠 miaco - The Recursive DevOps Architect & Ceremonial Forger CLI

miaco (pronounced mee-AH-koh) embodies Mia, the Recursive DevOps Architect, serving as the Engineering World CLI Agent within the mia-code ecosystem. While miatel handles story world and miawa handles ceremony, miaco is the terminal interface designed for generative structures via structural tension and creative orientation. It focuses on relational accountability and treats knowledge work as a ceremony, specifically managing:

• Schema Design & Validation: Ensuring integrity and precision.
• System Architecture & Tracing: Observing and forging emergent patterns.
• Structural Tension Charting: Guiding creative advancement.

🗺️ Kinship Map

/src/mia-code/                              ← Parent Package
├── miaco/                                  ← Engineering World CLI (this one)
├── miatel/                                 ← Story World CLI
└── miawa/                                  ← Ceremony World CLI

CONNECTS TO:
├── /workspace/langchain/.../narrative-tracing/    ← Tracing adapters
├── /workspace/langgraph/.../narrative-intelligence/ ← Analysis toolkit
└── /src/coaia-planning/                           ← Structural tension

What miaco Does

Schema Operations

miaco schema design --name 'HeroJourney' --type story
miaco schema list --type character
miaco schema export --name hero_journey --output ./schema.json
miaco schema migrate --from v1 --to v2

Validation Operations

miaco validate ncp --file ./story.ncp.json --strict
miaco validate beat --file ./beat.json
miaco validate coherence --session session_123
miaco validate types --project ./tsconfig.json

Tracing Operations

miaco trace start --session my-session --story hero-journey --langfuse
miaco trace log --event BEAT_GENERATED --data '{"beat_id": "beat_001"}'
miaco trace end --export ./trace.json
miaco trace list --limit 10
miaco trace view trace_abc123 --format timeline
miaco trace correlation --session my-session --story hero-journey

Structural Tension Chart Operations

miaco chart create --outcome 'Working CLI' --reality 'Scaffolding exists'
miaco chart list
miaco chart add-step --chart chart_123 --title 'Build commands' --reality 'Started'
miaco chart complete --step 'Build commands'
miaco chart review --chart chart_123

### PDE (Prompt Decomposition Engine) Operations

`miaco` extends its generative capabilities by providing advanced PDE operations, allowing for the structured decomposition of complex prompts and the orchestration of inquiry chains.

```bash
miaco decompose run -p "<prompt>"                              # Root decomposition
miaco decompose run --prompt-file ./prompt.md                  # Read root prompt from a UTF-8 file
miaco decompose run -p @./prompt.md                            # Compact prompt-file form
miaco decompose run -p "<prompt>" --parent <uuid> \            # Child decomposition with kind framing
                                  --child-kind issue
miaco decompose run -p "<prompt>" --engine pva                 # Use pva engine (@avadisabelle/ava-pi-coding-agent)
miaco decompose run -p "<prompt>" --engine hermes              # Use Hermes Agent (provider defaults to Hermes auto/config)
miaco decompose run -p "<prompt>" --engine hermes --hermes-provider openai-codex # Force Hermes provider
miaco decompose run -p "<prompt>" --fallback-provider codex,claude # Root-only Copilot rate-limit fallback chain
miaco steer --pde <pde-id> -p "<prompt>" --pva-provider gh     # Switch active pva provider to github-copilot for this PDE tree
miaco decompose run -p "<prompt>" --engine pva -pp gh -pm haiku # gh model alias → claude-haiku-4.5
miaco decompose run -p "<prompt>" --add-dir ../shared ../docs  # Persist extra workspace dirs in meta.json for future steers/continues
miaco continue --pde <pde-id> --yolo                           # Resume an interactive PDE session with approval bypass
miaco steer --pde <pde-id> -p "<prompt>" --yolo               # Inject a non-interactive prompt into the same PDE session
miaco pde-to-st <pde-id>                                       # Transform a PDE decomposition into an ST Chart

Engine selection

All PDE commands accept -e, --engine <engine> to select the LLM backend. Supported engines:

| Engine | Binary | Default model | Resume | Notes | |-----------|---------|------------------|--------|------------------------------------------| | copilot | copilot | gpt-5-mini | ✅ | Default engine | | claude | claude | sonnet | ✅ | | | gemini | gemini | gemini-3-flash-preview| ✅ | | | codex | codex | gpt-5.4-mini | ✅ | | | pva | pva | gpt-5.4 | ✅ | @avadisabelle/ava-pi-coding-agent | | hermes | hermes | gpt-5.5 | ✅ | Hermes Agent CLI; provider is optional |

Set MIACO_DEFAULT_ENGINE to make an engine the persistent default:

MIACO_DEFAULT_ENGINE=pva miaco decompose run -p "my prompt"
MIACO_DEFAULT_ENGINE=claude miaco steer --pde <uuid> -p "steer prompt"

QMD provider mode

miaco qmd and miaco qmd-inquiry-decompose use the container provider by default in generic installs:

miaco qmd search "structural tension"

In constrained workspaces, prefer mcp-remote and avoid host-local QMD execution. Set MIACO_QMD_CONTAINER_DISABLED to 1 or true only on hosts where local QMD is explicitly permitted:

MIACO_QMD_CONTAINER_DISABLED=1 miaco qmd search "structural tension"
MIACO_QMD_CONTAINER_DISABLED=true miaco qmd query "PDE inquiry routing"

Host mode resolves qmd from PATH. Use MIACO_QMD_BIN=/path/to/qmd if an explicit binary path is needed.

Provider mode can also be selected explicitly:

MIACO_QMD_PROVIDER=host miaco qmd search "structural tension"
MIACO_QMD_PROVIDER=mcp-local miaco qmd query "PDE inquiry routing"
MIACO_QMD_PROVIDER=mcp-remote miaco qmd-inquiry-decompose run --pde <uuid>

Supported providers are container, host, mcp-local, and mcp-remote. When MIACO_QMD_MCP_CONFIG or MIACO_QMD_MCP_COMMAND is set and no provider is specified, miaco selects mcp-remote. MCP providers use MIACO_QMD_MCP_COMMAND when set; otherwise they can load a stdio server from MIACO_QMD_MCP_CONFIG / MIACO_QMD_MCP_SERVER, then fall back to qmd mcp or qmd mcp-remote. Use MIACO_QMD_COLLECTIONS to override default collection filters. Only use host, container, or mcp-local where local QMD execution is safe for that machine.

For the EURY remote QMD index, point miaco at the existing stdio config. This starts the remote MCP wrapper described by the config; it does not require local QMD indexing:

export MIACO_QMD_PROVIDER=mcp-remote
export MIACO_QMD_MCP_CONFIG=/workspace/repos/miadisabelle/mia-qmd/etc/mcp-config-qmd-remote-eury.json
export MIACO_QMD_MCP_SERVER=qmd-remote
miaco qmd search "structural tension"

--child-kind taxonomy

When decomposing a child PDE, --child-kind tells the LLM how the child relates to the parent. The parent's primary + secondary intents are injected into the prompt as background, and the LLM is instructed to decompose the child in context of the parent — not to re-decompose the parent.

| Kind | Parent semantics | Typical use | |---------------|---------------------------------------------------|--------------------------------------| | milestone | (no parent — root) | top-level umbrella | | issue | parent = milestone | GitHub issue under a milestone | | sub-task | parent = issue | sub-issue / checklist item | | follow-up | parent = any | spin-off discovered during work | | refinement | parent = prior version of same artifact | re-decompose with new info (new UUID, never overlay) | | sibling | parent = peer | peer decomposition, no hierarchy |

Validation: --child-kind milestone is mutually exclusive with --parent/--parent-path; all other kinds require a parent reference.

--meta provenance

--meta '<json>' accepts a JSON object that is persisted into the child's meta.json under the provenance key. Useful for caller-side context (repo, issue numbers, webhook IDs, etc.):

miaco decompose run -p "Issue #42: ..." --parent <milestone-uuid> --child-kind issue \
  --meta '{"repository":"jgwill/dummass","milestoneNumber":5,"issueNumber":42}'

Persistent --add-dir

--add-dir <dir1> <dir2> can be used on decompose run, continue, and steer; repeated --add-dir flags are also accepted. The normalized values are persisted in meta.json as add_dirs, inherited by child PDEs, and reused by later engine calls for that PDE tree. Claude Code receives one variadic --add-dir <dir1> <dir2> group; Codex, Copilot, and Gemini receive their required repeated directory flags; PVA does not need directory arguments. For Codex, miaco also adds --sandbox workspace-write whenever persisted add-dirs are replayed without --yolo, because Codex rejects additional writable roots under the default effective permissions.

--format json scrape contract

--format json emits a stable single-line JSON contract on stdout for downstream consumers:

{"uuid":"<child-uuid>","parent":"<parent-uuid>","kind":"issue","pdeDir":"/abs/path","sessionId":"<engine-session-id>"}

(--json remains an alias that prints the full stored decomposition record.)

Storage layout

Root decompositions are stored at .pde/<timestamp>--<uuid>/. New child decompositions are stored nested under their parent at .pde/<root>/<child>/ (and grandchildren continue nesting the same way), so the filesystem path mirrors the PDE tree. Children inherit the parent tree session id, carry parent_pde_id in meta.json, and the parent's meta.json carries a children[] reverse edge with {uuid, kind, created_at}. Legacy flat PDEs remain readable through recursive lookup.

Children inherit the parent's engine, model, PVA settings, add-dirs, and session id from meta.json unless overridden. Root fallbacks (see below) record a fallback object on the root meta.json.

For explicit placement, --parent-path <path> can be used instead of --parent <uuid>:

miaco decompose run -p "Issue intent..." --parent-path .pde/2605021130--<root-uuid>/ --child-kind issue

Body-size advisory

Prompt input is advisory-capped at 16 KB; oversized inputs print a warning but still attempt the call (the engine may reject or truncate). Use -P, --prompt-file <path> or -p @<path> to load larger or reusable prompts from a UTF-8 text file without shell quoting. Use -p @@text when an inline prompt must start with a literal @.

These operations support:

• Chaining PDE Steps: Seamlessly transition between decomposition stages.
• Resuming Interactive Sessions: Pick up where you left off in complex inquiry processes.
• Folder-based PDE Format: Organize and manage PDE outputs effectively.
• Parent PDE UUIDs: Maintain hierarchical relationships between decompositions, with kind-aware framing per child.
• Inquiry-Chain Orchestration: Manage the flow of information and tasks across related inquiries.

AI Model Integrations

miaco leverages a dynamic ecosystem of generative AI models to power its decomposition and generation capabilities:

• Copilot-First Decomposition: Prioritizes Copilot for prompt decomposition (default engine), with intelligent fallback mechanisms and resource optimization.
• Claude Integration: Full session capture and resume support via the claude CLI.
• Gemini Integration: Google Gemini via the gemini CLI with model override.
• Codex Integration: Improved for efficiency and cost-effectiveness, featuring a cheaper default model and enhanced JSON parsing for robust output handling.
• PVA Integration: @avadisabelle/ava-pi-coding-agent — a first-class engine with resumable session capture plus configurable thinking depth (MIACO_PVA_THINKING), provider (MIACO_PVA_PROVIDER), and model (MIACO_PVA_MODEL) passthrough. CLI overrides can switch provider mid-tree (--pva-provider, alias -pp; gh → github-copilot, oc → openai-codex) and can use provider-aware model aliases (--pva-model, alias -pm; for gh: haiku → claude-haiku-4.5, g5mini → gpt-5-mini). The resolved PVA adapter state is persisted in PDE metadata.
• Hermes Agent Integration: --engine hermes invokes hermes chat -q for non-interactive PDE work and resumes with hermes --resume <session> --pass-session-id chat for interactive continuation. The model defaults to gpt-5.5; --hermes-provider or MIACO_HERMES_PROVIDER maps directly to hermes chat --provider, and omitting it leaves provider selection to Hermes' configured auto/default provider. The resolved provider is persisted in PDE metadata as hermes_provider.
• Ollama Integration: Seamlessly integrates with Ollama for RAG workflows, enabling powerful context-aware generation from local models.
• HuggingFace Research Integration: Incorporates insights and capabilities from HuggingFace for advanced research and experimental features.

Environment Variables

miaco --help displays all environment variables with their current values. Key variables:

| Variable | Description | Default | |----------|-------------|---------| | MIACO_DEFAULT_ENGINE | Default engine: copilot \| claude \| gemini \| codex \| pva \| hermes | copilot | | MIACO_MODEL | Cross-engine model override | engine default | | MIACO_PVA_PROVIDER | pva-only --provider passthrough (codex-openai alias normalizes to openai-codex) | openai-codex | | MIACO_PVA_MODEL | pva --model override (takes priority over MIACO_MODEL) | gpt-5.4 | | MIACO_PVA_THINKING | pva --thinking level: off \| minimal \| low \| medium \| high \| xhigh | high | | MIACO_HERMES_PROVIDER | hermes-only --provider passthrough; unset leaves Hermes auto/default provider | unset | | MIA_CODE_PVA_BIN | pva binary path | pva | | MIA_CODE_HERMES_BIN | Hermes Agent binary path | hermes | | MIA_CODE_CLAUDE_BIN | claude binary path | claude | | MIA_CODE_COPILOT_BIN | copilot binary path | copilot | | MIA_CODE_GEMINI_BIN | gemini binary path | gemini | | MIA_CODE_CODEX_BIN | codex binary path | codex |

Deprecated: MIACO_PROVIDER → use MIACO_DEFAULT_ENGINE instead (warning printed on use).

Root fallback

On a Copilot weekly rate-limit failure, root decomposes fall back through --fallback-provider (default codex,claude; use none to disable). Children never fall back — they reuse the parent engine/session from meta.json.

miaco decompose run -p "new root PDE" --fallback-provider codex,claude
miaco decompose run -p "new root PDE" --fallback-provider codex --fallback-model gpt-5.4-mini

Expanded Capabilities and Frameworks

miaco continually evolves, integrating cutting-edge tools and frameworks to support a broader spectrum of engineering and creative endeavors:

• MMOT (Managerial Moments of Truth) Specifications: New spec types guide critical review and decision-making processes.
• RISE RISpecs for @mino/store: Incorporates Reverse Engineering, Intent, Specifications, and Exportation principles for robust store design.
• Comprehensive RAG (Retrieval Augmented Generation) System: Leverages advanced RAG for context-aware content generation, enhancing accuracy and relevance.
• Narrative Remixing Project: Supports the dynamic restructuring and creative reinterpretation of narratives.
• X11 Applications & Simplex OS Roadmap: Facilitates development for a minimalist operating system and X11-based applications, including event-window and simple-window utilities.
• Agentic Extensions & Software 3.0 Vision: Enables the creation of custom sub-agents and advances the vision for narrative-driven Software 3.0.
• LangGraph for Story Generation: Integrates LangGraph to orchestrate complex story generation workflows and intelligent agents.
• Flowise Automation Tools: Provides command-line tools for managing Flowise automation, streamlining workflow deployments and interactions.
• RISE Methodology Integration: Deeply embeds the RISE framework, guiding all development from reverse engineering to exportation.

Installation

cd /src/mia-code/miaco
npm install
npm run build
npm link  # optional, for global install

The Three Universes Lens

miaco primarily represents Engineering World (Mia):

| Universe | Lens | Key Question | |----------|------|--------------| | 🔧 ENGINEER | Mia (this one) | Is the schema valid? Are types correct? | | 🙏 CEREMONY | Ava8 | Is K'é honored? Is there sacred pause? | | 📖 STORY_ENGINE | Miette | Is the arc coherent? Do themes thread? |

Structural Tension Charts

Inspired by Robert Fritz's creative process and guided by the Four Directions of Inquiry (Medicine Wheel Framework), miaco treats the space between Desired Outcome and Current Reality as generative mana. This structural tension is a vital force for creative advancement, not a problem to be solved.

┌─────────────────────────────────────────┐
│ DESIRED OUTCOME                         │
│ What you want to CREATE (not fix)       │
│ (East: Vision & Inquiry)                │
│                                         │
│         ↑  STRUCTURAL TENSION  ↑        │
│          (Generative Mana)              │
│                                         │
│ CURRENT REALITY                         │
│ Honest factual assessment               │
│ (West: Experience & Action)             │
└─────────────────────────────────────────┘

The dynamic interplay between outcome and reality actively drives purposeful creation.

Cross-System Tracing

miaco provides correlation headers for unified traces across:

• LangChain narrative-tracing
• LangGraph narrative-intelligence
• Miadi webhooks
• Storytelling package

miaco trace correlation --session my-session --story hero-journey
# Outputs:
#   X-Narrative-Trace-Id: trace_abc123
#   X-Session-Id: my-session
#   X-Story-Id: hero-journey

Development

# Run in development mode
npm run dev

# Build TypeScript
npm run build

# Run built version
npm start

# Utility to patch version, commit, and publish
./version-patch-commit-and-publish.sh

miaco: Where architecture emerges from ceremony, and becomes observable.