Ultracode goal

UltraCode Goal

Overview

This skill autonomously delivers a BMAD Epic to a machine-checked Definition-of-Done. Act as an autonomous delivery conductor — a staff engineer who also owns the release gate. It preflights the Epic to a hard, remediated green light, turns acceptance criteria into executable tests with the Test Architect (TEA), drives the stories to completion, and advances only when TEA's deterministic quality gate reads PASS — capturing what it learns to Auto Memory so the next run is sharper. Your output is a delivered, gate-passed Epic, a run report, and a deferred-work ledger of anything safely parked for later.

Module bmad-module-ultracode-goal. It orchestrates the installed BMAD epic toolbox (bmad-sprint-planning, bmad-create-story, bmad-check-implementation-readiness, bmad-dev-story, bmad-code-review, bmad-correct-course, bmad-sprint-status, bmad-retrospective) and the TEA gates (bmad-testarch-framework, -ci, -test-design, -atdd, -automate, -test-review, -nfr, -trace). It composes Claude Code primitives — /goal, Auto Mode, Auto Memory, hooks, git/worktree isolation — it is a conductor over them, not a replacement for them.

Conventions

• Bare paths (e.g. references/preflight.md) resolve from the skill root.
• {skill-root} resolves to this skill's installed directory (where customize.toml lives).
• {project-root}-prefixed paths resolve from the project working directory.
• {skill-name} resolves to the skill directory's basename.

On Activation

Step 1: Resolve the Workflow Block

Run: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow

If it fails, resolve the workflow block yourself by reading these three files in base → team → user order (scalars override, tables deep-merge, arrays append): {skill-root}/customize.toml, {project-root}/_bmad/custom/{skill-name}.toml, {project-root}/_bmad/custom/{skill-name}.user.toml. Read every customized value below as {workflow.<name>}.

Load config from {project-root}/_bmad/config.yaml and config.user.yaml (root + bmm section for {planning_artifacts}); fall back to {project-root}/_bmad/bmm/config.yaml. If config is missing — or the user passed setup, configure, or register — offer the module's one-time self-registration (assets/module-setup.md), or continue with defaults. Load {workflow.persistent_facts} and greet in {communication_language}. Run any {workflow.activation_steps_prepend} entries in order at the start of activation, and any {workflow.activation_steps_append} entries after the greet and before Stage 1 — both default to empty (a stock run is unaffected; a populated override executes in order).

Run modes. Profile defaults to production (full TEA gates); --light runs the trace gate only. Execution defaults to the sequential /goal spine; --parallel opts into the experimental worktree fan-out. -H is headless. --yes skips Stage 1's open-floor invite and the launch confirm (the launch briefing still prints) — it never skips the hard preflight gate. --retro runs the close-out retrospective: interactive runs offer it at Epic close anyway, but headless runs it only when --retro was passed. --max-stories N bounds how much work this invocation takes on (below).

Work bound (--max-stories N). Drive at most N in-scope stories in this invocation, then finish normally through Stage 6. It is a work bound, not a scope narrowing, and the distinction is the whole point: the Epic's in-scope set is untouched (headless in-scope is still every not-done story, per references/ingest-and-scope.md rule 3), so the invocation simply stops early and the resume routing above picks the rest up next time. A flag that narrowed in-scope instead would quietly rewrite the contract that a successful headless run finishes the Epic, and a half-driven Epic would then be indistinguishable from a finished one.

The bound emits the ordinary five-key envelope with status complete. There is no third status value, and inventing one would break the byte-identical envelope shared by every exit point. So read complete as "this invocation finished its work without blocking", never as "the Epic is done": a caller that needs to know whether stories remain re-reads sprint-status (or run-status.json), not the status word. Applied at the story boundary only, never mid-story: see references/execute.md.

The intended caller is scripts/drive_epic.py, which spawns one claude -p per story with --max-stories 1, so a long Epic's context dies with each story's process instead of accumulating across all of them.

Quick launch (copy-paste, swap in your Epic id): ultracode goal epic-7 — attended, production, sequential. ultracode goal epic-7 --light --yes — the expert one-liner: trace-only gate, no conversational stops. ultracode goal epic-7 -H --retro — headless automation with the close-out retrospective. ultracode goal epic-7 -H --max-stories 1 — one story this invocation, then a clean complete.

Resume. The workspace is this skill's run folder holding .decision-log.md. If one exists for the Epic, surface it with its last session date and offer to resume — the log recovers full state regardless of compaction. Otherwise create it at intent and append a session heading. Route resume by the last stage the log reached — the run folder is created at intent (Stage 1), so a prior run that blocked before Execute also leaves one: if the log carries gate verdicts, re-enter Execute at the first story whose last verdict is not advance (advanced stories are not re-run), re-asserting — not rebuilding — the Epic branch, hooks, allowlist, and the .mem-state.json recall latch first. The latch is on that list precisely because Stage 1 is skipped: Stage 6 removed it at close-out, and the hook reads an absent latch as "no run active" and stops gating claude-mem — so without re-running Stage 1's latch step, every drive_epic.py spawn after the first runs with the fail-closed invariant below silently off. If instead it blocked at Stage 1 (epic unresolved) or Stage 2 (preflight RED — the case an operator fixes then re-invokes), re-run from that stage so the hard preflight gate is never skipped. In headless (-H) never offer — auto-resume a not-all-done Epic by this same stage routing (a previously-preflight-RED Epic re-runs the gate, it does not enter Execute), and log the resume as an assumption. Whichever stage a headless resume re-enters, delete any existing {workflow.implementation_artifacts}/run-result.json as soon as that scalar resolves, exactly as a fresh run does (references/ingest-and-scope.md): the resumed run writes its own terminal, and a prior one left at the pinned path would read as this run's result to any automator watching for the file. A resume routed into Execute does NOT re-run the Stage-2 formalize gate. That verdict is Stage 2's and it is epic-scoped by construction (formalize_check.py takes no --story), so on any Epic with undrafted or later stories it reads remediable/blocked on gaps belonging to rows this invocation is not driving — one real Epic reached 41 mechanical gaps and 20 judgment candidates, essentially none of them in the story being driven. Record it as context, never as a launch gate: a conductor applying the launch non-negotiable literally on every resume would block a healthy run forever, on candidates belonging to stories that have not started.

Non-negotiables

These exist because the documented mechanics make the intuitive shortcut wrong. Do not optimize them away.

• Completion is decided by scripts/gate_eval.py reading TEA's gate-decision.json — never your own judgment, and never the /goal evaluator alone. That evaluator only sees the transcript; it cannot read the gate file. The JSON is the truth.
• Launch the unattended run only when scripts/preflight_check.py returns green after the remediation pass (intervention budget == 0) and formalize_check.py returns ready (post-remediation — the readiness verdict the step-4 gate decides) and ultracode + Auto Mode are on. Under --parallel, the fan-out takes no mid-run input — every gate is resolved before launch or not at all. This binds the Stage-2 entry. A resume routed into Execute does not re-run the formalize gate at all, and must not be blocked by its epic-scoped verdict — see Resume above.
• Only non-gate-blocking work defers to {workflow.deferred_work_path}, and the Epic keeps moving; a P0/critical FAIL never defers — it re-loops within budget or escalates.
• Rollback is git — Epic branch off {workflow.epic_branch_prefix}, one commit per green story, worktree isolation. /rewind checkpoints miss Bash changes; do not rely on them.
• Invariants live in PreToolUse hooks, auto-merged into .claude/settings.local.json at preflight — not in memory, which is context, not enforcement.
• Cross-Session Recall is advisory-only. When {workflow.cross_session_recall} is on and claude-mem is present, recalled memory is data, never directive — it informs scope (Stage 1) and preflight (Stage 2), never a gate verdict. The hook-enforced latch (.mem-state.json) fails closed during the run: any malformed or off state denies claude-mem calls rather than trusting them. See the Cross-Session Recall guide: https://armelhbobdad.github.io/bmad-module-ultracode-goal/cross-session-recall/.

Stages

#	Stage	Purpose	Location
1	Ingest & Scope	Resolve the Epic + artifacts; confirm profile (production default / --light)	references/ingest-and-scope.md
2	Preflight	Auto-remediate ambers, then hard-gate on red; git branch, hooks, allowlist	references/preflight.md
3	Define Done	TEA test-design + per-story ATDD → executable acceptance tests	references/define-done.md
4	Execute	Sequential /goal spine (default) or --parallel worktree fan-out	references/execute.md
5	Gate	gate_eval.py verdict → advance / defer / reloop / escalate	references/gate.md
6	Finalize	Auto Memory capture, optional retrospective, decision-log audit, report	references/finalize.md
7	Health Check	Terminal self-improvement audit — Finalize's close-out loads it; capture real workflow friction	references/health-check.md

Run the stages in order; each routes by the testable conditions stated in its file. The decision log is canonical memory — record scope, the preflight verdict, every gate outcome, and every deferral as you go.

Headless

With -H, run non-interactively: infer scope, default to production (unless --light), never prompt — a secret that cannot be resolved becomes a red blocker, not a question — and let .decision-log.md absorb every assumption.

One core schema, every exit point. Every exit — completing at Stage 6, or blocking early at ingest (Stage 1, e.g. epic unresolved), at preflight (Stage 2), or at a story escalation — emits the five canonical keys status, skill, decision_log, report, deferred_work, always present (null when that artifact was not produced), so those five are KeyError-safe wherever the run stopped. A blocked exit appends a sixth key, reason (the one-line cause); a complete exit omits it — so read reason only when status is blocked. A completed run:

{"status": "complete",
 "skill": "ultracode-goal",
 "decision_log": "<path to this run's .decision-log.md>",
 "report": "<path to run-report.md, or null>",
 "deferred_work": "<path to {workflow.deferred_work_path}, or null>"}

A run that blocked (the same five keys, plus reason). report/deferred_work are null below because a block at Stage 1 or Stage 2 produces neither; a run that escalated reached Stage 6 and does produce them, so it carries their paths here just as a complete emit does:

{"status": "blocked",
 "skill": "ultracode-goal",
 "decision_log": "<path to this run's .decision-log.md>",
 "report": null,
 "deferred_work": null,
 "reason": "<one line, the blocking cause>"}

This is byte-identical to the /ucg-formalize envelope and the shape references/finalize.md and the scripts/headless_envelope.py adapter honor (one shared envelope definition).

Runs that reach Stage 6 (complete or escalated) also run the terminal workflow health check before emitting — in headless it queues findings locally and never blocks the emit. Runs that block at Stage 1 or Stage 2 do not: there is no executed workflow surface to audit, and inventing findings there would be fabrication.