ultragoal

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: ultragoal
category: planning
status: active
core: true
description: Create and execute durable repo-native multi-goal plans. Break a brief into tracked goals, drive them to verified completion, and steer as findings change.
agent_created: true
triggers: ["ultragoal", "create-goals", "complete-goals", "durable plan", "multi-goal", "sequential goals"]
---

> Ported from oh-my-codex `ultragoal`. OMX runtime conventions (`$macro` invocation, `omx` CLI, `.omx/` state directory) are replaced with WorkBuddy idioms (Skill tool, Agent tool, task list, `.workbuddy/memory`).

# Ultragoal Workflow

Use when the user asks for durable multi-goal planning or sequential execution over a set of stories/objectives. Ultragoal turns a brief into repo-native artifacts and drives them to verified completion. There is no Codex `/goal` mode or `omx ultragoal` CLI — tracking is the **task list** (the live goal board), **memory** (durable brief/ledger), and optional files under `.omw/ultragoal/`.

## Durable artifacts

- `.omw/ultragoal/brief.md` — the original brief and constraints.
- `.omw/ultragoal/ledger.jsonl` — checkpoint and structured steering audit events (append-only).
- The **task list** is the live source of truth for goal/story state.

Write the brief once at creation via the Write tool. Append every checkpoint/steering decision to `ledger.jsonl`.

## Create goals

1. Capture the brief (from argument, a pasted file, or a `brief.md` path) into `.omw/ultragoal/brief.md`.
2. Decompose into goals/stories. For each, create a task with `TaskCreate`:
   - `subject`: short goal title
   - `description`: objective, acceptance criteria, constraints
   - `owner`: `leader` (Ultragoal stays leader-owned)
   - `addBlockedBy`/`addBlocks` for dependencies
3. Set the first story `in_progress`; keep the rest `pending`.
4. Inspect the board and refine if needed (reorder, split, reword).

## Complete goals

Loop until the task list reports all goals complete:

1. Run `ultragoal complete-goals` (i.e. pick the next `in_progress` story).
2. Read the printed handoff (the story description).
3. If the story benefits from parallel execution, invoke the `team` skill (`skill: team`) and pass Team the evidence; the leader stays Ultragoal owner.
4. Complete ONLY the current story. Use a lighter model for planning if available; use the appropriate execution skills (`plan`, `skill: tdd` discipline, etc.).
5. Run a completion audit against the story objective and real artifacts/tests.
6. In aggregate mode, do **not** mark sibling stories done from one story; checkpoint only the finished story. On the final story only, first run the **mandatory final cleanup/review gate** below, then mark complete.
7. Checkpoint the durable ledger with evidence: append to `.omw/ultragoal/ledger.jsonl`:
   `{"goal_id":"<id>","status":"complete","evidence":"<tests/files/review evidence>","at":"<now>"}`
8. If blocked/failed, checkpoint failure:
   `{"goal_id":"<id>","status":"failed","evidence":"<blocker/evidence>","at":"<now>"}`
9. Resume failed goals by re-opening the task (`TaskUpdate` → `in_progress`) and re-running.

## Dynamic steering

Use steering when real findings/blockers prove the decomposition should change while the brief's aggregate objective and constraints stay fixed. Steering is explicit-only and evidence-backed; broad natural-language requests are rejected instead of guessed.

Allowed mutation kinds (apply via `TaskCreate`/`TaskUpdate`/`Edit` on the board + brief):
- `add_subgoal` — add a new task.
- `split_subgoal` — split a pending task.
- `reorder_pending` — reorder `addBlockedBy`/order.
- `revise_pending_wording` — edit a pending task description.
- `annotate_ledger` — append a note to `ledger.jsonl`.
- `mark_blocked_superseded` — mark a task `deleted` with steering metadata retained in the brief.

Steering invariants:
- Do not edit the original brief constraints, quality gates, or completion status carelessly. The brief is the stable pointer; `.omw/ultragoal/