ducnd58233/ultragentic

**The spec-to-PR agent harness for Claude Code, Codex, Cursor, and opencode.**
Agent skills, slash commands, hooks, and a Go runtime that take an AI coding agent from a one-line
goal to a reviewed pull request, moving to the next step only on recorded evidence (tests, lint, CI,
review) that the last one passed.
- **One toolkit, every coding agent.** The same /spec, /plan, /build, /test, /review, and
/ship commands, skills (SKILL.md), and hooks run in Claude Code, Codex CLI, Cursor, opencode,
Google Antigravity, Kimi Code, and Muse.
- **Spec-driven, evidence-gated delivery.** /goal and /auto run a delivery graph
(spec → plan → build → test → review → PR) where the runtime, not the model, decides what runs next.
- **Guardrails built in.** Permission policy, pre-tool gates, secret hygiene, and a shared
AGENTS.md baseline, so vibe coding stays reviewable.
Install it once per machine, or mount it into any repo as a git submodule under .ultragentic/.
Domain rules live in each repo's own AGENTS.md.
**Contents:** Quick start · The runtime · Ways to work ·
Research and experiments · Install options ·
Supported coding hosts · Add third-party skills ·
Watch a run · Upgrading from vibe-agent ·
Contributing
Quick start
You need git, curl, and openssl (the runtime installs itself on first use; see The runtime). Some hooks call
python3 (3.8+, stdlib); on Windows, disable the Microsoft Store python3 alias or those hooks fail
silently.
**1. Install globally** (every project on this machine gets the commands; the ultragentic runtime follows on first use):
Keep the clone: the installed skills and commands are links back to it, so git pull updates them.
On Git Bash they are copies instead; re-run the script after pulling.
**2. Open your coding agent in any repo and give it a goal:**
Codex CLI uses $ instead of / ($ua-goal). Next: pick how much you want to steer in
Ways to work.
Ways to work
Three paths over the same assets. What changes is who drives each gate.
| Path | You type | Who moves to the next step | Use it when |
|---|---|---|---|
| Step by step | /spec, /plan, /build, … | You | You want to stop and review between stages |
| One outcome | /goal | The runtime, pausing at your approvals | You know the outcome and want checkpoints |
| Unattended | /auto | The runtime, gates closed by evidence | The work is routine and the repo has opted in |
Command names in this section are the workspace form. A global install adds the ua- prefix
(/ua-goal); see How commands look in your host.
Step by step
Run each command yourself. Skip /research when the repo already has the facts; /code-simplify is
optional. /build through /ship need the runtime.
| Command | Role |
|---|---|
| /spec | Write the spec. |
| /research | Citation-first digest (see Research and experiments). |
| /plan | Tasks from an approved spec. |
| /build | One planned task on its own branch. Needs the runtime. Never merges to main. |
| /test, /review, /ship | Proof, review, merge gate. Need the runtime. |
/design, /analyze, and /investigate are optional when the work needs extra passes. Full list:
.ai-agents/commands/ROUTER.md.
One outcome (/goal)
The same pipeline, but the runtime graph walks the sequence and pauses at checkpoints. You approve
the spec and the plan.
The host agent runs ultragentic goal " ". Slug and graph are derived; do not pass
--goal, --graph, or --slug. Rules: .ai-agents/commands/goal.md.
Unattended (/auto)
Same graphs and checks as /goal, but approval gates close on evidence instead of waiting for you.
Requires the runtime and a workspace opt-in file.
| Gate | /goal | /auto |
|---|---|---|
| Spec and plan | You approve | Skipped when the docs pass structural checks |
| Merge to main | You approve | Only if auto.yaml says merge: true and CI, tests, lint, and /ship already pass |
| Danger list (migrations, prod writes, credentials, …) | You decide | Stops every time |
No opt-in file, or merge: false, means auto stops at a green PR and you merge manually. Rules:
.ai-agents/commands/auto.md.
Work that is not code (/task, /tutor)
For a report, an analysis, a document, a data job, an ops step, or a message to other people, there