agentleFS
YomudoglyYomudogly/oh-my-agy/skills/ultragoal/SKILL.md

ultragoal

Skill4 starsChanged todayMITView on GitHub

[oh-my-agy] Create and execute durable repo-native multi-goal plans with a goals.json + ledger.jsonl audit trail, sequential completion, review gates, and resume. Use for $ultragoal, 'create-goals', 'complete-goals', durable multi-goal execution, or the Autopilot execution stage.

8 other projects use a version of this, 1 of them edited.

Adopted by

Most recently taken up by

Used with

Projects with it also use execute, map and 2 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • sahinSkill

    execute

    Also in 4 projects that use this

  • AWSSkill

    map

    Map verified service capabilities against customer-provided control framework and threat model. Produces mapping-results.json, controls-catalog.md, and framework-mapping.md. Supports pluggable frameworks: CCMv4, NIST 800-53, CIS Benchmarks, ISO 27001, etc. Split into 4 focused sub-skills for better accuracy; this skill orchestrates them.

    Also in 3 projects that use this

  • NVIDIASkill

    research

    Before designing a feature, research how comparable libraries solve the problem, check best practices, known pitfalls, and upstream changes. Use when starting a new feature, investigating an unfamiliar area, or the user asks to research something.

    Also in 5 projects that use this

  • genomewalkerSkill

    learn

    Learn from web sources, generate SKILL.md, and store key patterns in soul memory. Trigger keywords: learn, skill-gen, web-learn, documentation, tutorial.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 1 is distinctive, and 10 are very specific to this project.

  • 0

    Common

    Most of the 7 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use for $ultragoal, create-goals, complete-goals, durable multi-goal planning, or sequential execution of an approved plan/spec.

    line 10
  2. Very specific:

    Read the brief: the deep-interview spec, ralplan PRD/test-spec, or the user's inline brief.

    line 60
  3. Very specific:

    Write goals.json, append created ledger entries, and show the user a compact goal table (plus oh-my-agy HUD once if the HUD sidecar is …

    line 62
  4. Very specific:

    Ralplan receipt verification: when entering from $ralplan (.omagy/plans/prd-<slug>.md + .omagy/plans/ralplan-review-<slug>.json), run

    line 68
  5. Very specific:

    Stash-free shadow checkpoints: before risky multi-file edits or migrations, snapshot working-tree, .git/index, and untracked state via sh …

    line 69
  6. Very specific:

    If verification fails with failure_class: "harness" (test runner setup, missing fixture, port/env glitch), run up to 1 bounded …

    line 97
  7. Very specific:

    Before final completion (phase reviewing):

    line 112
  8. Distinctive:

    Run targeted verification for every goal.

    line 114
  9. Very specific:

    Run $ai-slop-cleaner on the changed files, then rerun verification.

    line 115
  10. Very specific:

    Run $code-review through independent code-reviewer and architect subagent lanes.

    line 117
  11. Very specific:

    When clean: append a final-gate ledger entry with cleaner, verification, review, and invariant evidence.

    line 118

“Common” is measured: kept by at least 6 in 10 of the 7 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Ultragoal Workflow

When to use

Use for $ultragoal, create-goals, complete-goals, durable multi-goal planning, or sequential execution of an approved plan/spec. Also used as Autopilot's execution stage.

The repo ledger is the single source of truth. Antigravity's /goal slash command is user-triggered. You may suggest it for very long runs, but never depend on it.

Durable artifacts (leader-owned)

  • .omagy/ultragoal/brief.md: the source brief (spec or plan text, or a pointer to it).
  • .omagy/ultragoal/goals.json: the plan.
  • .omagy/ultragoal/ledger.jsonl: append-only audit trail, one JSON object per line.
  • .omagy/ultragoal/notepad.md: compaction-resilient working memory organized under ## Priority, ## Working, and ## Manual headings (omagy-hook.mjs auto-reinjects exported sections up to 2,000 chars after <CONTEXT_SUMMARY> compaction so critical invariants, rulings, and live context survive compaction).

goals.json schema:

{
  "version": 1,
  "criteria_revision": 1,
  "objective": "<one-line aggregate objective>",
  "source": ".omagy/specs/deep-interview-<slug>.md | .omagy/plans/prd-<slug>.md | inline",
  "created_at": "<ISO>",
  "updated_at": "<ISO>",
  "invariants": ["<architecture/domain invariant that must hold at the end>"],
  "goals": [
    {
      "id": "G1",
      "title": "<short title>",
      "objective": "<verifiable objective>",
      "rigor": "light|heavy",
      "acceptance": ["<testable criterion>"],
      "status": "pending|in_progress|complete|blocked|failed|superseded",
      "depends_on": [],
      "product_failures": 0,
      "evidence": null
    }
  ]
}

Goal rigor classification (rigor):

  • "light": narrow change inside an existing module/pattern with no schema, auth, security, or public API contract change. Verified by targeted tests + acceptance check.
  • "heavy": cross-cutting change, new boundary/schema/auth/security surface, or state machine change. Requires targeted tests + at least 1 adversarial probe + independent verifier (AdversarialVerify) check before checkpointing.

Ledger entry shape (append; never rewrite earlier lines):

{"at":"<ISO>","goal_id":"G1","event":"created|started|checkpoint|blocked|failed|steer|review-blockers|final-gate","status":"<status>","evidence":"<commands + exit codes / file refs>","note":"<optional>"}

Append a ledger line using the crash-resilient newline-isolated hook helper (sh <plugin>/hooks/run.sh append-jsonl .omagy/ultragoal/ledger.jsonl '<json>', which prepends \n if a prior crash left a torn tail and refuses symlinks), or by reading the file and writing it back with the new line added on its own newline. Read the ledger tolerantly (sh <plugin>/hooks/run.sh read-jsonl .omagy/ultragoal/ledger.jsonl or line-by-line JSON parsing that skips malformed torn lines).

Operational steps: create

  1. Read the brief: the deep-interview spec, ralplan PRD/test-spec, or the user's inline brief. Copy it or point to it from brief.md.
  2. Decompose it into right-sized, independently verifiable vertical feature slices (using a Contract-First foundational goal before parallel $team fan-out and a Risk-First spike goal for existential technical unknowns) with testable acceptance criteria and explicit dependencies. Split any candidate goal touching > 5–8 files, spanning >= 2 independent subsystems, or joining two independent behaviors with "and" in its title. Carry spec non-goals, Always / Ask First / Never decision boundaries, and invariants into goals.json.
  3. Write goals.json, append created ledger entries, and show the user a compact goal table (plus [oh-my-agy HUD](sidecar://oh-my-agy/hud/) once if the HUD sidecar is enabled).
  4. Standalone: write .omagy/state/ultragoal-state.json (mode:"ultragoal", active:true, current_phase:"planning"). Inside Autopilot: keep the Autopilot state and set its current_phase:"ultragoal".

Operational steps: execute

  1. Pre-Flight Receipt Check, Shadow Checkpoints & Scoped Per-Goal Staging:
    • Ralplan receipt verification: when entering from $ralplan (.omagy/plans/prd-<slug>.md + .omagy/plans/ralplan-review-<slug>.json), run sh <plugin>/hooks/run.sh plan-hash verify .omagy/plans/prd-<slug>.md .omagy/plans/ralplan-review-<slug>.json --json first (exitCode: 0 required; halt if the PRD/test-spec drifted after approval or contains fake-timeline violations unless re-approved or steered).
    • Stash-free shadow checkpoints: before risky multi-file edits or migrations, snapshot working-tree, .git/index, and untracked state via sh <plugin>/hooks/run.sh checkpoint create <goal-id> --json (refs/omagy/checkpoints/<id>, keeping git stash list empty and HEAD unchanged); roll back cleanly on failed experiments via sh <plugin>/hooks/run.sh checkpoint rollback <id> --json.
    • Dirty-worktree baseline & scoped staging: capture git status --porcelain before starting so pre-existing modified/untracked files stay untouched. Whenever creating per-goal commits, never run blind git add -A, git add ., or git commit -a: stage explicit goal-owned paths only (git add -- <owned-paths>) and verify staged files via git diff --staged --name-only so pre-existing dirty files, .omagy/ scratch state, and secrets never stage.

Repeat until every goal is complete (or superseded):

  1. Pick the first pending goal whose dependencies are complete. Set it in_progress, append started, and set the phase to executing.
  2. Implement the goal: solo, or via an executor subagent for a bounded slice, or via $team when parallel lanes are justified.
    • Zero-Context-Bleed Brief & Review Handoffs: extract per-goal briefs via sh <plugin>/hooks/run.sh goal-brief .omagy/ultragoal/goals.json <goal_id> and package commit ranges via sh <plugin>/hooks/run.sh review-package <workspace> <base_sha> <head_sha> so subagents read file paths instead of inline prompt dumps.
    • 4-State Worker Routing & Model Escalation: handle worker returns deterministically (and harvest any ### Noticed (Out of Scope) items into "Rulings made & Deferred minors" without scope-creeping the active goal):
      • COMPLETED: proceed to step 3 verification.
      • COMPLETED_WITH_CONCERNS: inspect the reported concern (e.g., file growth or fragile edge case); either log a Ruling: (event:"steer", kind:"ruling") with cost_if_wrong or run a targeted fix pass before checkpointing.
      • NEEDS_CONTEXT: if a signature/path is missing or the worker reports a spec-vs-codebase architecture contradiction (file:line falsification), supply the authoritative context via send_message to the same worker conversation ID (or record an explicit steer / escalate when the spec contract itself is contradicted) without incrementing product_failures.
      • BLOCKED: if a worker on Model: "flash" or "inherit" stalls after 2 attempts on a complex implementation slice, escalate the retry to a higher model tier (flash -> inherit -> pro).
  3. Audit the goal against real artifacts (current_phase:"verifying"):
    • Apply the No-Reassurance Test Rerun Rule: never re-run an unchanged passing test command when zero files have been edited since that pass.
    • For "rigor": "light", run targeted tests and acceptance checks directly.
    • For "rigor": "heavy", record the leader's internal DoneClaim (changed files, commands + exit codes, criterion mapping, and canonical verdict from VERIFICATION_VERDICTS: live-ui-verified | unit-test-verified | type-check-only | enforcement-verified | formally-verified | verifier-blocked | verifier-failed), then validate via the verifier subagent (AdversarialVerify) using a Blind-Claim Packet:
      • Blind-Claim AdversarialVerify Input Rule: pass only ARTIFACT (actual diff / review-package path / touched file paths) + CONTRACT (verbatim goal acceptance criteria, goals.json invariants, and Consumes / Produces signatures) + raw command exit codes and diagnostic outputs—stripping persuasive executor narrative summaries (CLAIM self-assessments or prose rationales explaining why code is "safe").
      • AdversarialVerify returns verdict: "confirmed" | "false-positive" | "needs-fix" | "needs-human-review" and failure_class: "none" | "product" | "harness".
    • 4-Tier RECONCILE Precedence: classify every verification discrepancy, adversarial probe hit, or review finding in strict top-down precedence order:
      1. (1) Contract gap — exposes an ambiguity, contradiction, or missing safety boundary in the spec/plan/criteria -> treat as "needs-human-review" (or record an authorized steer with kind:"amend_criterion", incrementing criteria_revision).
      2. (2) Actionable defect — proven bug, regression, unmet criterion, or missing verification proof against ARTIFACT + CONTRACT -> route to Step 5 failure triage as "needs-fix" (failure_class: "product", or "harness" when isolated to test/env setup).
      3. (3) Explicit Ruling — bounded non-defect tradeoff within the stated load/scope ceiling -> record Ruling: <decision> — <why> — <cost_if_wrong> via steer (kind:"ruling") and proceed to checkpoint rather than forcing speculative churn.
      4. (4) Context noise — false positive disproved by repository file:line or command exit-code evidence -> dismiss with concrete file:line citation (verdict: "false-positive" when auditing an external critique; satisfies verification once CONTRACT proof holds).
    • Doubt/Review Theater Circuit Breaker: if >= 2 consecutive verification (AdversarialVerify) or final-gate review cycles return prose critiques ("substantive findings") with 0 actionable defects passing Tier 1–2, halt automated re-spinning immediately—do not invent blocking nits or burn product_failures; either checkpoint via an explicit Tier 3 Ruling: (with cost_if_wrong) or escalate ("needs-human-review") to the user.
  4. Checkpoint: when verdict is "confirmed" (or "false-positive" on a dismissed critique with CONTRACT proof green, or "light" checks pass), run sh <plugin>/hooks/run.sh goal-done <goal-id> --json -- <verification-cmd> to atomically execute the real non-echo verification command, write and validate .omagy/evidence/goal-<id>.json (VERIFICATION_VERDICTS + verified_head), mark the goal status:"complete" in goals.json, and append the checkpoint line (criteria_revision bound) to ledger.jsonl (or update goals.json + ledger.jsonl manually when custom multi-verdict metadata is required). Update .omagy/ultragoal/notepad.md (## Priority / ## Working / ## Manual) when rulings or cross-goal context change. When rendering ledger cells into Markdown or CSV tables, sanitize leading formula characters (=, +, -, @, \t, \r) via renderLedgerCell. Refresh updated_at in state.
  5. Failure triage (product vs harness), unavailable verification & blocked-goal cascade:
    • Unavailable verification never fabricates completion: if the required test runner, verifier subagent, or external environment is unavailable or indeterminate, never mark the goal complete and never fabricate passing evidence. Record a truthful non-terminal blocked ledger entry (event:"blocked", status:"blocked", note:"verification-unavailable:<reason>") and keep the goal in_progress or blocked until verification can actually run.
    • If verification fails with failure_class: "harness" (test runner setup, missing fixture, port/env glitch), run up to 1 bounded harness-repair attempt without incrementing product_failures.
    • If verification fails with failure_class: "product", increment product_failures (max 3 attempts per goal). After 3 product failures or "needs-human-review", set the goal status:"blocked" ([~]), append blocked to the ledger, and cascade status:"blocked" (note:"blocked-by:<goal_id>") to every downstream pending goal whose depends_on transitively includes this goal. Continue with remaining independent pending goals; if none remain and user input is required, write state current_phase:"blocked", active:false, and ask.

Explicit steering & stale-goal reconciliation

  • Stale-Goal Reconciliation (on start/resume): Before executing a pending goal, run observable repo checks (fileExists, fileContains, gitGrep) against its target paths. If the repository already satisfies a goal's acceptance criteria from earlier work, verify with targeted tests and record a checkpoint with note:"reconciled-from-repo" instead of re-implementing.
  • Explicit Steering: Change the decomposition only with evidence. Append a steer ledger entry with kind, evidence, and rationale, then edit goals.json accordingly. Supported kinds: add_subgoal, split_subgoal, reorder_pending, revise_pending_wording, amend_criterion, annotate_ledger, mark_blocked_superseded. Never silently delete goals. Mark them superseded instead.
  • Criterion Amendment, criteria_revision Binding & Autonomous Ruling Audit Trail (Rulings, not stalls): Whenever a goal's acceptance criteria or invariants in goals.json are amended after creation, increment top-level criteria_revision (default 1) in goals.json and append a steer (kind:"amend_criterion" or kind:"ruling") ledger entry recording criteria_revision, decision (or previous_criterion / amended_criterion), rationale, evidence, and cost_if_wrong ("Ruling: <what was decided> — <why> — <cost_if_wrong>"). Any checkpoint or final-gate receipt recorded against an older criteria_revision is stale and must be re-verified against the current criteria_revision before closeout. Surface all autonomous rulings and any deferred minor review observations explicitly under "Rulings made & Deferred minors" in the final closeout report. Ordinary prose does not mutate the plan.

Team bridge

For parallel story execution, run $team against the active goals. Team workers return task evidence only. The Ultragoal leader alone updates goals.json and the ledger.

Final gate and exit evidence

Before final completion (phase reviewing):

  1. Run targeted verification for every goal.
  2. Run $ai-slop-cleaner on the changed files, then rerun verification.
  3. Audit every invariant from goals.json and the brief/spec/steering against implementation, tests, and review evidence.
  4. Run $code-review through independent code-reviewer and architect subagent lanes. If review or invariant proof is not clean, add a Resolve final code-review blockers goal with the findings, append review-blockers, and loop back to execution. Inside Autopilot, design-level findings return Autopilot to ralplan.
  5. When clean: append a final-gate ledger entry with cleaner, verification, review, and invariant evidence. Standalone: write the state terminal (active:false, current_phase:"complete", completed_at). Inside Autopilot: set handoff_artifacts.ultragoal and let Autopilot finish.

Report goal ids/statuses, ledger path, review verdicts, and any blocker. Never claim completion from state files alone. Completion requires the verification evidence in the ledger.

Resume

On continue/resume, read goals.json, the tail of ledger.jsonl, and the state file, then resume from the first non-complete goal. Do not re-decompose an existing plan unless steering is justified.

  • Resumed-run started-edge closeout bound: when resuming an interrupted or previously blocked goal, append a fresh started ledger entry (event:"started"). Only verification runs and checkpoint entries recorded strictly after that latest unmatched started entry count toward closing out the resumed goal — pre-resume notes or stale artifacts from an earlier attempt never satisfy closeout.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.