--- name: huytieu/ultragoal source: https://app.decimal.ai/s/huytieu-ultragoal@2/SKILL.md source_sha256: f53ac90ef8bd --- # Ultragoal — the closed loop for goals too big to ship in one run An **ultragoal** is the term for a north-star that spans many sessions: fork the repos, combine the strong parts, ship one product. A normal `/execute` run is one task through the loop. An ultragoal is a *chain of phases*, each of which is its own full closed-loop run, tracked so any cold session can resume. **Core rule (from dwarves-kit, adopted fully): the worker never grades its own homework, and wrongness compounds across sessions — so verify every phase, not just the end.** ## When to use - `/ultragoal ` — resume or advance an existing ultragoal - `/ultragoal new ""` — charter a new one - `/ultragoal status` — report all ultragoals from the registry - Trigger phrases: "make this an ultragoal", "this is a long-running goal", "combine these into one product over time" Do **not** use for single-run work — that is `/execute`. Rule of thumb: if it needs a phase decomposition and won't finish today, it is an ultragoal. ## Files (one goal = one folder) | File | Role | |---|---| | `04-projects/harness/ultragoals.md` | Registry: every ultragoal, status, current phase | | `04-projects//spec.md` | Contract: north-star + `AC-n` acceptance criteria + phases `P0…Pn` + traceability matrix | | `04-projects//STATUS.md` | Living ledger: phase state, current phase, open `AC-n`, next action (resume from here) | | `04-projects//evidence/P/` | Per-phase evidence bundle (ledger.md + CP-* files) | Code, if any, lives outside the vault (e.g. `~/code//`) — the spec/status/evidence stay in the vault. ## Phase 0 — Charter (`/ultragoal new`) 1. Interview the user for the **north-star** in one sentence (what "done" looks like). 2. Write `04-projects//spec.md` from `04-projects/harness/templates/SPEC-template.md`: - North-star statement - Falsifiable `AC-n` acceptance criteria (these define done for the *whole* goal) - Phase decomposition `P0…Pn` — each phase is a shippable increment mapped to a subset of `AC-n` - Traceability matrix (`AC-n` ↔ phase ↔ status) 3. Create `STATUS.md` (see template below) and add a row to the registry. Record: `bash .claude/lib/checkpoint.sh record 04-projects//evidence/P0 CP-1 PASS "N criteria, M phases"` ## The phase loop (every phase, no lane downgrade) Each phase runs the **full** closed loop. Do not shortcut with `tiny`. Ultragoals are `full` lane by construction. ``` select next phase from STATUS.md │ ▼ CP-2 PLAN tasks for this phase ↔ AC-n → evidence/P/CP-2-plan.md │ ▼ CP-3 BUILD worker implements (traced to AC-n); returns paths only │ ▼ CP-3v VERIFY task-verifier (fresh context, read-only) → evidence rows per AC-n │ ├── FAIL:fixable → fix-agent (max 2) → re-verify │ └── FAIL:escalate → stop, escalate to the user ▼ CP-4 INTEGRATE integration-verifier → does this phase wire correctly with prior phases? │ (always run for ultragoals — cross-phase regression is the main risk) ▼ CP-5 ACCEPT observe the artifact (curl / screenshot / re-fetch), not the tool return │ EVIDENCE AC-n | CP-5 | PASS | | ▼ CP-6 SHIP external mutation? → Review Gate: you approve. Internal? → auto. │ ▼ update STATUS.md (phase → done, advance current phase, log open AC-n) │ ▼ CP-7 RETRO /retro 04-projects//evidence/P → harvest + STATUS ``` Merge every verifier's `EVIDENCE` rows into `evidence/P/ledger.md`. ## The two acceptance gates 1. **Per-phase (CP-5):** every `AC-n` this phase claims has a PASS row before the phase is marked done. 2. **North-star (final):** before the ultragoal is declared complete, spawn a fresh-context verifier whose only job is to check the spec matrix — **every** `AC-n` across all phases has ≥1 PASS evidence row. Any `AC-n` without one is a gap, not a ship. This is the ultragoal-level analogue of CP-5. ``` North-star acceptance: read spec.md matrix (all AC-n) read every evidence/P*/ledger.md for each AC-n: assert ≥1 PASS row exists, artifact re-observed any miss → list open AC-n, STATUS stays "in progress", do NOT declare done ``` ## The HTML report (regenerate at every phase gate + final) Every ultragoal carries a single self-contained HTML report that **covers everything**: north-star, live status, all phases, the full `AC-n` traceability table with pass/open/fail, evidence rows per phase (with screenshots embedded as `data:` URIs), and the open-items / next-action block. It is the human-readable face of the evidence ledger. - **Template:** `04-projects/harness/templates/report.html` (house style, theme-aware, rows-not-cards). Copy it, then fill every `{{token}}` and `` / `` block from `spec.md` + `STATUS.md` + `evidence/P*/`. You fill it by editing — do not build a parser. - **Deliverable path:** `04-projects//report.html`. One file, overwritten each phase (it always reflects current truth). - **When:** regenerate at each phase gate (CP-6) and again at final north-star acceptance. The final report must show every `AC-n` with a PASS row — if any pill is `open`, the goal is not done. - **Self-contained only:** inline everything, embed screenshots as `data:` URIs, so it also works when published as an Artifact (external hosts are blocked). Before publishing as an Artifact, load the `artifact-design` skill. - **Surface it:** `SendUserFile 04-projects//report.html` (display: render) so the user can open it, or publish via `Artifact` for a shareable link. ## STATUS.md template ```markdown # — status ledger North-star: Spec: 04-projects//spec.md · Registry: 04-projects/harness/ultragoals.md Current phase: P · Overall: ## Phases | Phase | AC covered | State | Evidence | Notes | |---|---|---|---|---| | P0 | AC-1,AC-2 | done | evidence/P0/ | | | P1 | AC-3 | in-progress | evidence/P1/ | | ## Open AC-n (no PASS row yet) - AC-3 — ## Next action (resume cold from here) ``` ## Resuming cold (most common entry) `/ultragoal ` with no other context: 1. Read `04-projects//STATUS.md` → "Next action" and "Open AC-n". 2. Read the spec's phase for the current phase only (progressive disclosure). 3. Run the phase loop for the current phase. 4. Never re-do a phase already marked `done` unless integration verify caught a regression. ## Rules - **Never downgrade the lane.** Even a one-line phase inside an ultragoal runs CP-3v + CP-4. The point is compounding correctness. - **UI/UX phases verify visually.** If a phase touches a UI/UX flow, capture rendered evidence with browser-harness (`evidence_shot` / `FlowRecorder.save_gif` / `pixel_diff`), read the image, fix any visual defect, and re-capture — do not accept a DOM check. Media lands in `evidence/P/` and feeds `report.html`. See CLAUDE.md → Visual Verification. - **Fresh-context verifiers.** `task-verifier`, `integration-verifier`, north-star verifier get paths only — never paste worker output in (CLAUDE.md fresh-context isolation). - **Read-only verifiers.** They cannot edit files or mutate external state. - **Gate all external.** Any publish / deploy / push waits at CP-6 for the user (Review Gate = your approval). - **One STATUS.md is the source of truth** for where the goal stands. Update it at the end of every phase or it drifts. - Model routing per CLAUDE.md: Sonnet workers build/collect/verify; Opus lead reasons, decomposes, synthesizes. ## Escalation template ``` ULTRAGOAL ESCALATED — / P Last CP: | Open AC: Evidence: 04-projects//evidence/P/ Decision needed: ``` ## Registered ultragoals Live list: `04-projects/harness/ultragoals.md`. Each ultragoal gets its own `04-projects//` folder holding `spec.md`, `STATUS.md`, `evidence/`, and `report.html`.