UltraCode Goal (UCG)

Run a BMAD Epic autonomously to a machine-checked Definition-of-Done.

Built for Claude Code, and only Claude Code. UCG composes Auto Mode, Auto Memory, runtime hooks, and git branches, and writes each story's Definition-of-Done as a /goal-style condition; the autonomous run itself requires Claude Code.

UCG is a standalone BMAD module that delivers a BMAD Epic end to end without a babysitter. It preflights to a remediated green light, turns acceptance criteria into executable tests with the Test Architect (TEA), and advances a story only when a deterministic script reads PASS from TEA's gate artifact, not when the model decides it feels done.

---

The Problem

You hand an agent an epic and tell it to "build until done." It runs, it commits, it declares victory. At review time you discover "done" meant "the model felt done." Four mechanics, not vibes, make that the default:

• The /goal evaluator only sees the transcript. It cannot open the gate artifact TEA wrote to disk. So the thing deciding completion is reading a story about the work, not the verdict on the work.
• A model grading its own output is the fox auditing the henhouse. Self-assessment is the weakest possible signal for a release gate, and it is exactly the signal you get by default.
• /rewind checkpoints miss Bash changes. Rollback you cannot trust is rollback you do not have.
• Memory is context, not enforcement. Telling the agent "never commit on main" in a prompt is a suggestion. An invariant has to be a hook the runtime executes, or it is not an invariant.

UCG exists because the documented mechanics make the intuitive shortcut wrong.

The Fix

UCG preflights the epic to a remediated green light before anything launches, turns each story's acceptance criteria into red-phase tests with TEA, and advances only when gate_eval.py reads PASS from TEA's deterministic gate-decision.json. Completion is a fact on disk, not a feeling in the transcript.

That verdict is a small, real JSON object; here is the actual output of gate_eval.py reading a passing gate file (--profile light):

{
  "verdict": "advance",
  "gate_status": "PASS",
  "p0_status": "100%",
  "p1_status": "95%",
  "overall_status": "88%",
  "nfr_status": null,
  "review_score": null,
  "epic_level": false,
  "reasons": [
    "gate read from gate-decision.json",
    "gate_status PASS -> advance"
  ]
}

The gate_status comes straight from TEA's artifact: gate_eval.py never re-derives the thresholds; it reads the status as given and maps it to a verdict (PASS/WAIVED → advance, CONCERNS → defer, FAIL → reloop, NOT_EVALUATED → escalate). Under --profile production the same run additionally ANDs two signals: nfr_status and review_score populate, and any failure downgrades an otherwise-advance verdict to reloop. The contract is fail-closed: a missing or unparseable signal counts as a failing one, so prose drift degrades to a conservative re-loop, never a silent false-advance.

Install

Requires Claude Code >= 2.1.295 (the runtime UCG conducts), Node.js >= 22, Python >= 3.11, uv, plus git and gh on PATH. The project needs BMAD Method 6 with TEA 1.27.x: TEA 2.0 and later, and BMAD 7, are not supported yet.

Tested with: on 2026-10-16 a two-story Epic reached its Definition-of-Done with the versions below, under the --light profile (TEA test-design and the trace gate; the production gate set was not exercised). They are the versions that run used, not minimums.

Component	Version	Note
Claude Code	2.1.301	Attended, Auto Mode; the run resumed a preflight first started on 2.1.291
BMAD Method	6.12.0	Installed with --shims: that run predates UCG's own story skills, which need no BMAD shim
TEA (Test Architect)	1.27.2	Epic test-design, then a per-story trace gate read by gate_eval.py

npx bmad-module-ultracode-goal install

You'll be prompted for a project name and whether to install the learning material; the skill installs for Claude Code. UCG is also available through the Claude plugin marketplace. See Getting Started for that path.

Hook security: UCG installs PreToolUse/Stop hooks into your machine-local, gitignored .claude/settings.local.json at preflight, never into a committed file. They run zero-dependency Python scripts shipped in the skill. Claude Code treats that file as protected, so take a new Epic through preflight in an attended session (see Getting Started). See SECURITY.md for exactly what they execute and how to remove them.

Quick Start

Invoke the skill in natural language: "run this epic autonomously," "execute this epic," or ultracode goal. The conductor ingests the epic, preflights, defines done with TEA, executes, gates, and finalizes. Flags shape the run:

• --light: run the trace gate only (the production default runs the full TEA gate set).
• --parallel: retired. Still accepted so an old invocation does not error: the run logs one note that the flag was accepted and ignored, then executes the sequential /goal spine.
• --yes: skip Stage 1's open-floor invite and the launch confirm. It never skips the hard preflight gate.
• -H: headless: run non-interactively and emit the five-key status JSON at every exit point.
• --retro: run the close-out retrospective (interactive runs offer it anyway; headless runs it only when this flag is passed).
• --max-stories N: drive at most N stories in this invocation, then finish normally through the report and the terminal JSON. It bounds the work, not the scope: the Epic's in-scope set is untouched, so the next invocation resumes where this one stopped. scripts/drive_epic.py uses it to run one story per process, so a long Epic's context dies with each story.

See How It Works for the full six-stage walkthrough, routing conditions, and the headless contract.

How UCG Compares

A skeptical reader is probably already running one of these. Here is the honest contrast:

	UltraCode Goal	Hand-driven /goal per story	Plain Auto Mode	CI-only gating
Completion authority	gate_eval.py reads TEA's gate-decision.json	you, story by story	the model's self-assessment	CI, but only after the agent stops
Preflight autonomy gate	hard-gate to remediated green (intervention budget 0)	ad hoc, per story	none	none: CI runs post-hoc
Invariants enforcement	PreToolUse hooks in settings.local.json	your attention	prompt text (context, not a gate)	CI checks, after the fact
Rollback	git: epic branch, code + gate commits per story	manual	/rewind (misses Bash changes)	revert after merge
Knowledge capture	Auto Memory + CLAUDE.md split at Finalize	none structured	none structured	none

The alternatives aren't bad; they solve different problems. UCG solves exactly one: advancing an epic only when a deterministic script confirms the gate passed, and giving you the verdict JSON to check it yourself.

UCG's closest peer is bmad-loop (formerly bmad-auto, published under the bmad-code-org org), which makes the opposite architectural bet (a deterministic Python loop driving any CLI from outside the agent). For a side-by-side look at where each one wins, see UCG vs bmad-loop.

Verifying

You don't have to take the gate's word for it. The deterministic pieces ship with a test suite, and you can run the evaluator on a real artifact yourself.

Run the Python suite (1,700+ tests across the preflight, gate, hook, readiness, memory, mutation-runner, and customization scripts):

uv run --with pytest==9.1.1 --with pytest-xdist==3.8.0 pytest skills/ultracode-goal/scripts/tests/ -n auto

Then inspect any gate-decision.json TEA wrote and evaluate it directly:

uv run skills/ultracode-goal/scripts/gate_eval.py \
  --trace-output path/to/traceability \
  --profile light

The JSON it prints is the same object UCG routes on: verdict, gate_status, and the reasons trail that explains how it got there. Nothing is hidden behind the model.

Learn More

The docs are organized into three buckets: Why (start here), Try (do stuff), and Reference (look things up):

Why: Why UltraCode Goal: the problem, the three enforcement layers, and when not to use it.

Try

• Getting Started: install, prerequisites, the flags, and your first autonomous run.
• How It Works: the six stages, their routing conditions, and the headless five-key emit.

Reference

• Architecture: the conductor model, enforcement layers in depth, and customize.toml resolution.
• Gate Model: how gate_eval.py maps gate_status to a verdict, and the production AND-signals.
• Health Check: the terminal self-improvement loop: what it sends, privacy, and how to disable it.
• Cross-Session Recall: the optional run history in a local store UCG owns: what a run reads and writes, the trust model, and how to enable it.
• Knowledge-Graph Refresh: the optional graphify integration: preconditions, what it sends where, and what it never touches.
• Operating Tips: field notes from real drives: the driver's stop reasons, sequencing by row order, and the verification traps.
• Troubleshooting: real failure modes and their remediations.
• UCG vs bmad-loop: a side-by-side comparison with bmad-code-org's bmad-loop orchestrator.

Every run that reaches Finalize ends with a self-improvement check that can file a deduplicated GitHub issue with your approval, so please let runs finish through Finalize, or open an issue directly. If UCG shipped an epic while you slept, a ⭐ helps others find it.

Acknowledgements

UCG is a conductor over primitives it does not replace. It builds on:

Tool	Role in UCG
BMAD Method	The epic toolbox UCG orchestrates (sprint planning, story creation, dev, review)
TEA Test Architect	Machine-checked quality gates: test-design, ATDD, NFR, trace; the gate artifact
Claude Code	Auto Mode, Auto Memory, hooks, and git branches, the primitives UCG composes; /goal if you start one yourself

Contributing

See CONTRIBUTING.md for guidelines. Past releases are documented in CHANGELOG.md, and CONTRIBUTORS.md lists contributors.

License

MIT License. See LICENSE for details.

---

UltraCode Goal (UCG): A standalone BMAD module for autonomous epic delivery.