supergoal

name

supergoal

description

Decompose rough coding goals into a verifiable sub-goal DAG, then run them as sequential Codex /goal contracts with review, evidence, budget control, root verification, and repair loops. Use for long-running repo work, migrations, refactors, bug hunts, prototypes, experiments, dependency mapping, and autonomous Codex goal execution. Do not use for small one-shot edits or tasks without verifiable completion criteria.

Supergoal

Supergoal turns rough engineering intent into a durable GOAL_RUN/ package: root spec, root verification, a reviewed dependency graph, sub-goal contracts, evidence, usage, budget controls, and final reporting.

Core Rule

Codex is the planner. Scripts are guardrails. Use files under GOAL_RUN/ as the project-level source of truth, and use one active Codex /goal at a time, normally a selected sub-goal. Do not rely on simultaneous nested goals.

Do not treat init_goal_run.py or any script as the intelligent decomposition engine. Use scripts only to create an empty scaffold, validate files, select ready work, record usage/evidence, check budget, and maintain state.

Hard Execution Gate

Root files are planning and verification artifacts, not execution goals. Never call /goal, create_goal, or any goal-starting tool for the whole root objective.

Before selecting a sub-goal, confirm pre-launch prerequisites:

• GOAL_RUN/ exists and is filled from repo context and user intent;
• GOAL_RUN/scripts/preflight_goal_run.py GOAL_RUN has no blockers;
• STATE/CONTROL.json and STATE/CONTROL.md allow execution;
• budget hard limits and approval gates do not require stopping.

After pre-launch prerequisites pass, run GOAL_RUN/scripts/select_next_subgoal.py GOAL_RUN. Goal-starting tools may be used only after it returns a specific ready SG-XXX, and the goal command must execute exactly GOAL_RUN/SUBGOALS/SG-XXX.md.

If the environment cannot actually launch a selected sub-goal /goal, stop after printing the exact command and wait. Continue manually only if the user explicitly approves a manual fallback.

Do not implement project code beyond inspection, scaffolding, and planning until the package validates and a concrete sub-goal is selected.

Interruption Recovery Gate

When the user interrupts, changes direction, adds or removes scope, or gives new steering while an orchestrated run may be in progress, do not continue normal execution immediately.

First perform an interruption recovery check:

1. Identify whether a selected or active sub-goal /goal exists from conversation context, STATE/PROGRESS.json, GOAL_COMMANDS.md, and the user's UI state when needed.
2. Compare the new instruction against the active sub-goal contract in SUBGOALS/SG-XXX.md.
3. Classify the impact as no_active_goal, non_affecting, affecting_active_goal, or uncertain.
4. Record the user instruction, classification, and decision in STATE/CONTROL.md and STATE/DECISIONS.md.
5. If no_active_goal, apply the change to the plan/control surface, rerun validation or graph review when needed, then continue through normal selection.
6. If non_affecting, record whether the change applies after the current goal, to future sub-goals, or to root verification. Tell the user they may continue the current active /goal, and do not rewrite its contract.
7. If affecting_active_goal, tell the user the active /goal contract is stale and ask them to stop/delete it in the UI. Do not proceed until the user confirms it has stopped. Then mark the old sub-goal blocked, superseded, or needs replanning; update contracts, graph, control files, and validation before launching a replacement selected sub-goal.
8. If uncertain, ask the user to pause/stop the active /goal or answer a targeted clarification before continuing. Do not launch another sub-goal while uncertain.

Codex cannot reliably suspend a running /goal from outside. It can stop launching the next sub-goal, record the interruption, and ask the user to stop/delete an active goal when the current contract may be invalid.

Intake And Clarification Gate

Do not silently convert a vague rough idea into a fixed plan. Before writing the final ROOT_SPEC.md, Codex must perform an intake pass:

1. Inspect the repo and infer all answerable details from files, tests, package metadata, docs, and existing project instructions.
2. Ask enough targeted questions to avoid solving the wrong problem. Do not ask for facts that the repo clearly proves, but do not over-optimize for asking fewer questions.
3. Classify open items as confirmed_by_repo, confirmed_by_user, pending_user_confirmation, safe_default, or blocker.
4. Ask the user to confirm every pending_user_confirmation and answer every blocker whose answer materially affects outcome, scope, verification, risk, budget, data, dependencies, approval gates, or user-facing behavior.
5. Do not treat assumptions as permission to execute. A material assumption may be recorded, but Codex must not decompose or execute based on it until it is confirmed by the user, confirmed by repo evidence, or explicitly accepted as a safe default.
6. If material questions exist, ask the user before finalizing ROOT_SPEC.md, ROOT_VERIFICATION, GOAL_GRAPH, or sub-goals.
7. If no material questions exist, record No blocking clarification needed. in GOAL_RUN/INTERVIEW_NOTES.md.
8. Record every user answer, inferred answer, unresolved question, explicit assumption, and assumption classification in GOAL_RUN/INTERVIEW_NOTES.md.
9. For Level 2+ orchestrated runs, explicitly ask for budget limits or present defaults during intake before decomposition. Ask budget as two separate decisions: usage budget and time budget. Usage budget may be specified either as reported tokens (none, soft limit, hard limit, or unknown) or as Codex account quota (weekly quota percent to spend, weekly minimum percent left, and optionally 5h minimum percent left) when the quota reader is available.
10. Only if the user confirms, declines to set limits, says they do not know, or asks Codex to proceed with defaults may Codex record the default policy: no hard token limit, no hard time limit, max repair sub-goals = 10, and unknown usage is recorded as unknown, never estimated or treated as zero.
11. Do not decompose into sub-goals until INTERVIEW_NOTES.md contains confirmed answers or approved safe defaults for material assumptions, and the budget policy for Level 2+ runs.

No intake record, no final ROOT_SPEC.md. No ROOT_SPEC.md, no ROOT_VERIFICATION. No ROOT_VERIFICATION, no DAG.

Mandatory Budget Intake Gate For Level 2+

For every Level 2+ run, budget intake is a separate hard gate before final ROOT_SPEC.md and decomposition. Ask or present defaults as separate user-visible items:

1. Usage budget: ask whether the user prefers reported-token budget, account-quota budget when available, or no hard usage budget.
2. Time budget: ask separately whether the user wants no time limit, a soft time limit, a hard time limit, or unknown.
3. Repair budget: state max_repair_subgoals = 10 as the default unless the user changes it.

Do not merge usage budget, time budget, and repair budget into one question such as Approve default budget policy? or Any budget limits?. Even when proposing defaults, list usage budget and time budget separately and require confirmation.

Adapt the budget questions to the user's language and task context; do not copy this template verbatim. Required decisions to cover:

Usage budget:
- If account quota was read successfully, say the current quota is readable and offer account-quota budgeting.
- If account quota was unavailable or declined, do not present it as an active option; offer reported-token budgeting or no hard usage budget.
- If account quota has not been checked yet, try the direct quota check when possible before asking, or tell the user it is unchecked and ask whether to try it or use reported tokens/no hard usage budget.

Time budget:
- Ask whether the run should have no time limit, a soft time limit, a hard time limit, or unknown.

Repair budget:
- State that the default max repair sub-goals is 10, and ask whether to keep or change it.

Mandatory Dashboard Viewer Intake Gate For Level 2+

For every Level 2+ run, dashboard viewer intake is a separate hard gate before final ROOT_SPEC.md and decomposition. Ask or present the default as a separate user-visible item:

1. Before asking for a preference, explain in one standalone plain-language sentence what the user will see: a read-only progress panel showing sub-goal status, evidence, budget, and overall progress.
2. Ask whether the user wants only the static GOAL_RUN/REPORTS/dashboard.html file, or also a local auto-refresh browser viewer after the first successful render.
3. If yes, ask which port to use, with 8765 as the default.
4. If yes, ask whether Codex may request permission for non-sandbox/elevated execution when the environment blocks local port binding.
5. If no, record that the run will use only the static GOAL_RUN/REPORTS/dashboard.html file.

Do not ask this preference using only terms like dashboard, static HTML, or viewer before the plain-language explanation. It is fine to name the dashboard, but the same sentence must immediately explain what it is and what information the user will see.

Do not merge dashboard viewer intake into a generic budget/defaults question. Record the answer in GOAL_RUN/INTERVIEW_NOTES.md.

Adapt the wording to the user's language and context. A good shape is:

Supergoal can show you a dashboard, which is a read-only progress panel with each sub-goal's status, evidence, budget, and overall progress. Do you want me to only update the HTML file, or also start a local auto-refresh browser view? If I start the local view, is the default port 8765 OK?

Workflow

When the user gives a rough engineering idea:

1. Identify the target project root for the user's task, then inspect that target repo enough to understand likely scope, existing tests, package manager, and relevant project instructions.
2. Before intake for long or risky runs, read account quota with the direct codex_status.py --json command when possible, then run scripts/preflight_codex_goal.py with --account-quota-status-json to assess Codex/repo readiness and quota-budget availability. Because quota capture starts Codex CLI/TUI and may need write access to Codex local state under ~/.codex, request user approval for non-sandbox/elevated execution at the start when the environment requires it. If the user declines, fall back to reported-token/time budget and record quota capture as unavailable by policy.
3. Read or initialize STATE/CONTROL.json and STATE/CONTROL.md.
4. Run the Intake And Clarification Gate; ask targeted clarification questions when answers materially affect outcome, verification, risk, scope, budget, protected paths, approval gates, dependencies, data, or user-facing behavior. For Level 2+ runs, explicitly ask for usage budget (reported tokens or account quota), time budget, and dashboard viewer preference/port, or present defaults for user approval before decomposition.
5. Record answers, inferred answers, unresolved questions, and assumptions in GOAL_RUN/INTERVIEW_NOTES.md.
6. Write GOAL_RUN/ROOT_SPEC.md with objective, success definition, non-goals, constraints, assumptions, and verification surface.
7. Write GOAL_RUN/ROOT_GOAL.md and GOAL_RUN/ROOT_VERIFICATION.md/json.
8. Classify complexity using references/workflow.md.
9. Decompose the root objective into verifiable checkpoints, not tiny edits.
10. Write GOAL_RUN/GOAL_GRAPH.json and GOAL_RUN/SUBGOALS/*.md.
11. Review the graph conservatively; edit only high-confidence duplicate or dependency problems.
12. Run validation/lint scripts and repair the generated package until it passes.
13. Refresh the read-only dashboard after the package first validates.
14. Execute sequential sub-goal /goal runs only through the Hard Execution Gate, rereading the control surface before each launch and recording evidence, usage, review, budget, progress, and a refreshed dashboard after each one.
15. Run root verification, refresh the dashboard, and create repair sub-goals if required checks fail.
16. Write GOAL_RUN/REPORTS/FINAL_REPORT.md and refresh the dashboard one final time.

Choose the smallest mode that satisfies the request:

• Level 0: one-shot task; do not create GOAL_RUN/.
• Level 1: single durable contract. In orchestrated mode, even Level 1 uses SUBGOALS/SG-001.md as the executable contract; root files remain planning and verification artifacts.
• Level 2: linear milestones; create 3-8 ordered sub-goals.
• Level 3: DAG orchestrated goal; create dependency graph with explicit gates.
• Level 4: program-level campaign; create a human-in-loop plan and do not imply full autonomy.

Create The Package

For a new orchestrated run, create GOAL_RUN/ in the target project root, not necessarily the current shell directory. If the user names a subdirectory such as examples/SWIFT, the run package belongs at examples/SWIFT/GOAL_RUN/. Do not create a root-level GOAL_RUN/ in the skill repository unless the skill repository itself is the target project.

You may use the scaffold script only to copy the standard directory layout, templates, and scripts:

python path/to/skill/supergoal/scripts/init_goal_run.py \
  --project-path path/to/target/project \
  --run-dir GOAL_RUN \
  --title "Short root goal title"

After scaffolding, Codex must fill the package from repo context and user intent. Do not leave generic scaffold text as the final plan.

Expected package:

GOAL_RUN/
  README.md
  INTERVIEW_NOTES.md
  ROOT_SPEC.md
  ROOT_GOAL.md
  ROOT_VERIFICATION.md
  ROOT_VERIFICATION.json
  ORCHESTRATION.md
  GOAL_GRAPH.json
  GOAL_COMMANDS.md
  SUBGOAL_GRAPH_REVIEW.md
  SUBGOALS/
  STATE/
    PROGRESS.json
    CONTROL.json
    CONTROL.md
    BUDGET.json
    USAGE_LEDGER.md
    EVIDENCE.md
    DECISIONS.md
    BLOCKERS.md
    ATTEMPTS.md
    RISK_REGISTER.md
  scripts/
  REPORTS/
    FINAL_REPORT.md

Decompose

Split by verifiable checkpoint, not tiny edits. Prefer discovery and tests before risky implementation. Every sub-goal must include objective, dependencies, allowed scope, out-of-scope items, done_when, verification, failure policy, budget policy, anti-gaming rules, evidence requirements, and review gate.

Use references/mode_runbooks.md, references/output_contracts.md, references/interview_policy.md, references/goal_fitness.md, references/decomposition_heuristics.md, references/subgoal_contract_schema.md, and references/anti_gaming_rules.md. Use references/human_control_surface.md whenever the user may need to steer, pause, constrain, or reprioritize a long-running run.

Review The Graph

Review the graph before execution. Detect duplicate or redundant sub-goals, dependency direction errors, missing prerequisite edges, over-broad sub-goals, over-small sub-goals, and sub-goals that merely duplicate root verification.

Only edit the graph for high-confidence fixes. Record ambiguous concerns as watch items in SUBGOAL_GRAPH_REVIEW.md and decisions in STATE/DECISIONS.md.

Use references/graph_review_policy.md.

Validate

Run validation after drafting or editing the package:

python path/to/skill/supergoal/scripts/codex_status.py --json --timeout 45 -C . > /tmp/supergoal_codex_status.json
python path/to/skill/supergoal/scripts/preflight_codex_goal.py --project-path . --account-quota-status-json /tmp/supergoal_codex_status.json
python GOAL_RUN/scripts/preflight_goal_run.py GOAL_RUN
python GOAL_RUN/scripts/validate_goal_graph.py GOAL_RUN
python GOAL_RUN/scripts/review_goal_graph.py GOAL_RUN --check-only
python GOAL_RUN/scripts/lint_subgoals.py GOAL_RUN
python GOAL_RUN/scripts/check_evidence.py GOAL_RUN
python GOAL_RUN/scripts/check_budget.py GOAL_RUN

Use codex_status.py --json as the preferred account-quota readiness check. Run it as a direct shell command before intake, requesting user approval or elevated execution if required by the environment. Then reuse its JSON with preflight_codex_goal.py --account-quota-status-json. This avoids less stable nested Codex TUI calls inside preflight. Only use preflight_codex_goal.py --account-quota-quick-check when direct JSON capture is not practical.

Use preflight_codex_goal.py as the Codex/repo readiness check. It can inspect repo state, package hints, and the captured 5h/weekly account quota status. /goal availability is reported separately under manual_confirmations. Only fall back to reported-token/time budget if direct quota capture fails or the user declines quota-budget setup.

Use preflight_goal_run.py as the GOAL_RUN package readiness gate before launching a sub-goal. It aggregates structure, graph, contract, evidence, budget, root verification, and human-control checks. It does not decide whether the plan is semantically good; Codex must still review the root spec, graph, and sub-goals.

If validation fails, fix the package. Do not weaken verification to make scripts pass.

Quota Path Semantics

Do not ask the user to record the skill install path. Before GOAL_RUN/ exists, resolve scripts from the loaded Supergoal skill directory, meaning the directory that contains this SKILL.md. After GOAL_RUN/ exists, prefer the copied self-contained tools under <target-project-root>/GOAL_RUN/scripts/.

Keep these paths distinct:

• <skill-dir>: loaded Supergoal skill directory; use only before the run package exists or when package scripts are missing.
• <target-project-root>: project root for the user's task; GOAL_RUN/ normally lives here.
• <trusted-codex-cwd>: a stable directory for codex_status.py -C; prefer the current workspace root, the target project root if already trusted by Codex, or a trusted parent workspace root. Account quota is account-level, so this directory does not have to be the exact target project, but it must not trigger a Do you trust the contents of this directory? prompt.
• <run-dir>: the generated run package, normally <target-project-root>/GOAL_RUN; use this for writing ledgers and state.

For quota capture, the codex_status.py script path may be <skill-dir>/scripts/codex_status.py or <run-dir>/scripts/codex_status.py, but -C must be <trusted-codex-cwd>, never the skill directory and never GOAL_RUN/. If codex_status.py --raw shows a trust prompt, do not record account quota as unavailable; use an already trusted workspace root for -C or ask the user to trust the target directory first.

If Codex CLI reports readonly local state such as attempt to write a readonly database under ~/.codex/sqlite or asks to repair Codex local data during quota capture, treat it as sandbox/permission blockage, not as damaged account quota state. Do not run the repair prompt from the skill flow. Request permission to rerun the same direct capture command outside the sandbox/elevated; if the user declines, record quota capture as unavailable and continue with reported-token/time budget options.

Preferred quota capture and ledger write after GOAL_RUN/ exists:

python3 <target-project-root>/GOAL_RUN/scripts/codex_status.py \
  --json \
  --timeout 45 \
  -C <trusted-codex-cwd> \
  > /tmp/supergoal_quota_SG-XXX_before.json

python3 <target-project-root>/GOAL_RUN/scripts/record_account_quota.py \
  <target-project-root>/GOAL_RUN \
  --goal SG-XXX \
  --phase before \
  --status-json /tmp/supergoal_quota_SG-XXX_before.json \
  --allow-unavailable

Dashboard

Refresh a read-only HTML dashboard at the main checkpoints of every orchestrated run:

python GOAL_RUN/scripts/render_dashboard.py GOAL_RUN

By default, Codex should run this after the package first validates, after each accepted sub-goal, after blocker or repair-subgoal creation, before and after root verification, and after the final report. The dashboard reads GOAL_RUN/ and writes GOAL_RUN/REPORTS/dashboard.html. It is only a status renderer. It must not replace graph review, sub-goal review, evidence recording, budget checks, or Codex semantic judgment.

After the first successful render, Codex may start a visible local viewer for the current session:

python GOAL_RUN/scripts/serve_dashboard.py GOAL_RUN --host 127.0.0.1 --port 8765 --refresh 5

Start the viewer only if the user approved it during intake or later explicitly asks for it. This viewer serves GOAL_RUN/REPORTS/dashboard.html on http://127.0.0.1:8765/ with browser auto-refresh. It is optional, read-only, and non-daemonized: keep it running only as a visible terminal/session process, stop it with Ctrl-C when no longer needed, and never treat it as part of orchestration state. If the viewer is not running, continue refreshing the static HTML file normally.

Execute Sequential Goals

Use Sequential Subgoal Goal Mode by default:

0. Confirm pre-launch prerequisites: GOAL_RUN/ exists, the package is filled, preflight_goal_run.py has no blockers, and control/budget allow execution.
1. Run python GOAL_RUN/scripts/select_next_subgoal.py GOAL_RUN.
2. Confirm the Hard Execution Gate is now fully satisfied. No selected SG-XXX, no /goal.
3. Re-read STATE/CONTROL.json and STATE/CONTROL.md; stop if pause or approval gates apply.
4. If account-quota budget is enabled and no quota baseline exists, capture quota using the Quota Path Semantics above: direct <target-project-root>/GOAL_RUN/scripts/codex_status.py --json --timeout 45 -C <trusted-codex-cwd>, then record it with <target-project-root>/GOAL_RUN/scripts/record_account_quota.py <target-project-root>/GOAL_RUN --status-json <captured.json> before launching the first sub-goal. Use record_account_quota.py internal capture only as fallback.
5. Launch or display the selected sub-goal's exact /goal command. Never launch a root-level /goal.
6. Execute only that sub-goal's contract.
7. Run local verification.
8. Append evidence to STATE/EVIDENCE.md.
9. Complete the selected Codex /goal when the environment supports goal completion reporting, then immediately record the returned token/time usage in STATE/USAGE_LEDGER.md. In Codex Desktop, update_goal(status=complete) returns the authoritative structured usage; do not pre-record unknown before that return. Record unknown only if the completed goal environment truly provides no usage.
10. If account-quota budget is enabled, capture quota with the same direct path from the Quota Path Semantics and write it with record_account_quota.py --status-json <captured.json>. This must happen before check_budget.py; check_budget.py only reads STATE/QUOTA_LEDGER.md and never fetches Codex account quota itself. If fresh capture fails, retry with a known trusted workspace root for -C; if sandbox or readonly ~/.codex state blocks capture, request non-sandbox/elevated execution and retry. Only after those recovery attempts fail or are declined may Codex record unavailable quota.
11. Run post-sub-goal review, including python GOAL_RUN/scripts/review_subgoal_result.py GOAL_RUN --goal SG-XXX --evidence-ref EVIDENCE-XXXX.
12. Update STATE/PROGRESS.json only when the review passes, passing evidence and usage refs when available.
13. Run python GOAL_RUN/scripts/check_budget.py GOAL_RUN --goal SG-XXX.
14. Refresh GOAL_RUN/REPORTS/dashboard.html with python GOAL_RUN/scripts/render_dashboard.py GOAL_RUN.
15. Continue only if dependencies, control surface, and budget allow it.

Never mark a sub-goal complete without evidence and review. Never start a downstream sub-goal while a required dependency is failed, blocked, or unverified.

Hard gate: when account-quota budget is enabled, no fresh quota capture and STATE/QUOTA_LEDGER.md update after the selected sub-goal means no valid budget check, no progress to the next sub-goal, and no claim that quota budget is safe. A fresh unavailable quota entry is a failure record, not proof that quota thresholds are safe; if quota thresholds are configured and fresh quota remains unavailable, pause and ask the user whether to continue under unavailable-quota fallback unless the user already approved that fallback.

Verify Root And Repair

After all required sub-goals pass, run root verification. Use python GOAL_RUN/scripts/run_root_verification.py GOAL_RUN for command checks in ROOT_VERIFICATION.json. Manual checks must be recorded as evidence before claiming root completion.

If root verification fails, classify the failure and create the smallest repair sub-goal with prefix RSG. Preserve old evidence; append new evidence and graph/progress updates.

Refresh the dashboard after root verification and after creating any repair sub-goal so the human control surface reflects the latest run state.

Use references/root_verification_schema.md, references/failure_taxonomy.md, and references/runbook.md.

Guardrails

• Do not delete, weaken, or skip relevant verification to pass.
• Do not fabricate token usage or treat unknown usage as zero.
• Do not fabricate account-quota readings or treat unavailable quota as zero consumption.
• Do not fabricate duration usage or treat unknown duration as zero.
• Do not continue after hard budget stop.
• Do not create more repair sub-goals than STATE/CONTROL.json.max_repair_subgoals permits; default is 10.
• Do not silently expand scope.
• Do not commit, push, deploy, change secrets, run production migrations, or perform destructive operations without explicit user approval.
• Do not hide failures in evidence, usage, decisions, blockers, or final reports.