| name | mini-ork |
| description | Use whenever an agent needs to drive the mini-ork orchestrator from ANY repo — the repo that vendors mini-ork into its own `.mini-ork/`, not only the mini-ork source itself. mini-ork is a "task operating system for agents": a universal loop (classify→plan→execute→verify→reflect→improve→eval→promote), a `run <recipe> <kickoff>` recipe runner, a native multi-epic `epics`+`scheduler` delivery mode, heterogeneous model lanes (opus/sonnet/codex/kimi/minimax/glm), a GRPO learning loop, and the full `MO_*`/`MINI_ORK_*` env surface. Trigger on "run this kickoff", "dispatch a framework-edit / code-fix", "fix this via mini-ork", "ingest this roadmap / run the scheduler", "what recipe should I use", "how do I use mini-ork in this repo safely", or any question about mini-ork recipes, lanes, env knobs, the epics/scheduler queue, or the orchestrator lifecycle. Read the SAFE-USAGE CONTRACT first — getting cwd, MINI_ORK_ROOT, or kickoff sizing wrong causes the failures this skill exists to prevent (cross-repo corruption, hollow plans, silent lane stalls). |
mini-ork — driving the orchestrator from a consuming repo
mini-ork is a framework you vendor into your repo (a .mini-ork/ directory)
and drive to do multi-file work through a verifier-gated loop instead of editing
by hand. This skill is the precise reference so an agent uses it correctly and
does not improvise flags, paths, or recipes.
Read the SAFE-USAGE CONTRACT (next section) before running anything. Every
serious failure mode this skill prevents — corrupting another repo, a hollow
truncated plan, a 19-minute silent stall — comes from violating one of its
three rules.
SAFE-USAGE CONTRACT (non-negotiable)
1. cwd / target isolation — never let a lane run inside the framework tree
A provider lane (codex, claude) runs git operations in its working
directory. If that cwd drifts into a mini-ork framework tree instead of the
target repo, the lane's git ops corrupt the framework repo (observed:
refs/codex/curated-sync reset to a foreign commit, wiping the tree).
- Always export
MO_TARGET_CWD=<absolute path to YOUR repo's worktree> before
dispatching. It is the directory lanes run in.
- Use ABSOLUTE paths in kickoffs (
/abs/path/to/file), never bare relative
paths that resolve against an unknown cwd.
- The dispatcher refuses a lane whose cwd lands inside the mini-ork framework
tree (
cwd guard failed). For a genuine mini-ork self-edit only, set
MO_ALLOW_FRAMEWORK_CWD=1.
- The framework repo additionally self-protects: a
reference-transaction hook
rejects any ref write to a commit foreign to its history (override:
MO_ALLOW_FOREIGN_REF=1). Do not disable these.
2. Install / root isolation — point at YOUR vendored copy
MINI_ORK_ROOT = your vendored install dir (the dir containing bin/ lib/),
e.g. <your-repo>/.mini-ork. Never point it at a shared mini-ork source
clone.MINI_ORK_HOME = where state lives, normally <your-repo>/.mini-ork. It holds
the gitignored, non-git-recoverable state.db (GRPO learning) and
config/secrets.local.sh (API keys).- Run the binary from your install:
"$MINI_ORK_ROOT/bin/mini-ork" ….
3. Kickoff sizing — one deliverable per kickoff
An oversized kickoff truncates the planner JSON into a hollow plan and the
run wastes its budget. Keep each kickoff to one deliverable. For several
deliverables, write several kickoffs (disjoint code regions can run in
parallel) or ingest a roadmap as epics (below).
The three delivery modes — pick one first
| You want… | Mode | Entry point |
|---|
| Run one kickoff through the loop / a recipe | bin/mini-ork run | "$MINI_ORK_ROOT/bin/mini-ork" run [<recipe>] <kickoff.md> |
| Fan a roadmap into dependency-ordered epics, dispatched serially by readiness, auto-merged to main | native epics + scheduler | bin/mini-ork epics split <roadmap.md> → bin/mini-ork scheduler |
| Fan a plan into N parallel worktree-isolated tracks | agentflow .agentflow/mini-orch/deliver.sh | a SEPARATE pipeline (not bin/mini-ork) |
run for one deliverable. epics+scheduler for many dependency-ordered epics
(serial, same tree). agentflow for many independent parallel tracks.
bin/mini-ork run — the common path
export MINI_ORK_ROOT="$PWD/.mini-ork"
export MINI_ORK_HOME="$PWD/.mini-ork"
export MO_TARGET_CWD="$PWD"
"$MINI_ORK_ROOT/bin/mini-ork" run kickoffs/my-thing.md
"$MINI_ORK_ROOT/bin/mini-ork" run framework-edit kickoffs/change.md
"$MINI_ORK_ROOT/bin/mini-ork" run code-fix kickoffs/fix-bug.md
"$MINI_ORK_ROOT/bin/mini-ork" init
"$MINI_ORK_ROOT/bin/mini-ork" doctor
"$MINI_ORK_ROOT/bin/mini-ork" version
A kickoff is a markdown file stating ONE deliverable: goal, concrete acceptance
criteria, and absolute paths to the files in scope.
Recipes (force with run <recipe> <kickoff>)
framework-edit (propose-not-commit framework change, produces a diff),
code-fix (apply a bug fix), bug-audit, epic-runner, research-synthesis,
recursive-self-improve, chapter-review, and ~24 more under
$MINI_ORK_ROOT/recipes/. List them: ls "$MINI_ORK_ROOT/recipes/". Don't
invent recipe names — check the directory.
Model lanes (the routing policy)
Lanes map a loop role to a model wrapper (lib/providers/cl_<lane>.sh), set in
$MINI_ORK_HOME/config/agents.yaml.
- Implementer / code lanes:
codex, minimax, kimi. Not glm
(analysis-only) and not the claude/opus lanes for implementation.
- Reviewer / judgment lanes:
opus is allowed (strongest reasoner) for the
final reviewer / synthesizer / cross-epic prioritizer.
- Each gateway lane needs its key in
config/secrets.local.sh
(GLM_API_KEY, KIMI_API_KEY, MINIMAX_API_KEY, …). A missing key makes
the lane die silently — the dispatcher's pre-flight (lane_health) now fails
fast with lane preflight failed: $X_API_KEY is not set, but set the keys
before a run regardless.
Multi-epic delivery (epics + scheduler)
"$MINI_ORK_ROOT/bin/mini-ork" epics split <roadmap.md>
"$MINI_ORK_ROOT/bin/mini-ork" epics list
"$MINI_ORK_ROOT/bin/mini-ork" scheduler
- The scheduler has no epic filter — bare
scheduler drains EVERY
not-started ready epic in state.db. Check epics list first; for a specific
roadmap, dispatch your epic ids in a scoped loop.
- The scheduler is long-running. Do NOT launch it from inside an interactive
agent turn (it gets reaped at the turn boundary). Run it under a real
supervisor —
tmux/launchd/CI — or in your own terminal.
Common pitfalls → the rule that prevents them
| Symptom | Cause | Fix |
|---|
Another repo's files get wiped / refs/codex/* appears | a lane's cwd drifted into the framework tree | set MO_TARGET_CWD to your repo; use absolute paths |
| Hollow/generic plan, budget wasted | oversized kickoff truncated the planner JSON | one deliverable per kickoff; split or use epics |
| A lane silent for ~19 min then nothing | missing API key / dead provider | set keys in secrets.local.sh; the lane pre-flight fails fast now |
| Lane read the wrong repo | MINI_ORK_ROOT/cwd pointed at the framework, not your repo | pin MINI_ORK_ROOT to your .mini-ork, MO_TARGET_CWD to your repo |
| Scheduler dies, DAG stalls | launched from a harness turn (reaped) | run under tmux/launchd/CI, not in-turn |
Updating mini-ork safely
Re-vendor the latest framework code into your .mini-ork/ without touching the
source clone or your state: rsync the framework dirs (bin/ lib/ recipes/ db/)
and exclude the gitignored state — state.db, config/secrets.local.sh,
runs/. Never git pull the source clone into your repo, and never run the
source clone's binary against your repo (that is the cwd-confusion vector).
Env surface (most-used)
MINI_ORK_ROOT, MINI_ORK_HOME, MO_TARGET_CWD, MINI_ORK_PROFILE_GATE
(0 to skip the planner Q&A gate), MO_AUTO_ANSWER_PROFILE, MO_NODE_TIMEOUT_S,
MO_ROUTING_POLICY (learning_governed default), MO_ALLOW_FRAMEWORK_CWD,
MO_ALLOW_FOREIGN_REF. Full list: grep -rhoE 'MO_[A-Z_]+|MINI_ORK_[A-Z_]+' "$MINI_ORK_ROOT/lib" | sort -u.
When unsure of a flag, recipe, lane, or path: read it from the install
(ls, grep, bin/mini-ork doctor) rather than guessing. Improvised syntax is
the most common cause of wasted runs.
