# Opi Workflow

> Route opi work among inward pi realignment, outward capability research, human-led shaping, delivery, assurance, documentation, and release without creating a second state machine.

- Skill: `odradekai/opi-workflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add odradekai/opi-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/odradekai/opi-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: OdradekAI (https://skillmd.com/u/odradekai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/odradekai/opi-workflow

---


# Opi Workflow Router

Route work to the skill that owns the next decision or artifact. This skill is
an index, not an orchestrator: open the selected skill before making any
load-bearing claim, and stop at human decision and irreversible boundaries.

## Design direction

- **Inward:** pi is opi's design reference. Use `opi-realign` to measure the
  latest pi direction against the Rust implementation and selected opi scope.
- **Outward:** optional capabilities beyond or poorly served by pi are researched
  for plugin/package placement before expanding core. Use `opi-research`.
- **Implementation:** `.opi-impl-state.json` and `opi-implement` are the only
  delivery state machine. Do not introduce another ticket, plan, worktree, or
  commit protocol inside it.

## Routes

| Situation | Open and use |
|---|---|
| Compare current opi with the latest pi design or implementation | `opi-realign` |
| Investigate an external or non-pi capability | `opi-research` |
| Resolve a large, multi-session decision space with fog | Recommend explicit Matt `wayfinder`, after the tracker adapter check below |
| Sharpen bounded ambiguity in the current session | Recommend explicit Matt `grill-with-docs`, with the opi glossary adapter below |
| Synthesize settled decisions when no reviewed spec exists | Recommend explicit Matt `to-spec`, producing a non-normative tracker candidate |
| Admit a reviewed, registered source and construct its task graph | `opi-implement plan` |
| Execute an admitted ledger task | `opi-implement` |
| Diagnose a hard bug or performance regression | Matt `diagnosing-bugs`, then return to the owning delivery route |
| Audit a completed phase | `opi-audit` |
| Validate and optionally fix normalized findings | `opi-remediate` |
| Gather release-candidate runtime evidence | `opi-eval` |
| Synchronize product documentation | `opi-document` |
| Publish a verified release | `opi-release` |
| Reduce integration-test binary count | `opi-slim-tests` |

Direct invocation of any routed skill is valid. Do not call a skill merely to
make the route look complete: skip `to-spec` when wayfinding already produced a
reviewed spec, and skip assurance or release work whose entry gate is not met.

## Matt adapter contract

- `wayfinder`, `grill-with-docs`, `to-spec`, and
  `setup-matt-pocock-skills` are user-invoked Matt skills. Return the exact
  recommended invocation and stop; do not claim to invoke or compose them from
  this router.
- Before recommending `wayfinder` or `to-spec`, require
  `docs/agents/issue-tracker.md`. If it is absent, recommend explicit Matt
  `setup-matt-pocock-skills` and stop until the tracker is configured. Do not
  invent tracker conventions inside an opi skill.
- When `wayfinder` or `grill-with-docs` invokes Matt `domain-modeling`, bind its
  glossary target to opi's existing `docs/CONTEXT.md` and its ADR target to
  `docs/adr/`. Do not create a competing root `CONTEXT.md`.
- A wayfinder map, decision ticket, or `to-spec` tracker issue is shaping
  evidence, not an `opi-implement` source. Human review must materialize the
  settled result into `docs/opi-spec.md` or a supplemental spec registered by
  `opi-implement`; only then may `opi-implement plan` admit it.

## Phase boundaries

- Research and realignment produce evidence, not product decisions.
- Human-led shaping may return to either evidence path repeatedly.
- `opi-implement plan` is an adversarial admission check, not a shaping tool.
- `opi-implement` cannot silently amend a normative source when meaning is
  missing or wrong; it returns to the owning shaping artifact.
- Audit does not fix, eval does not fix, documentation does not release, and
  release does not cross an irreversible boundary without explicit approval.

When a required routed skill is unavailable, stop with a setup error. Do not
silently substitute a similarly named workflow from another skill package.