# Supergoal
[切换至中文版](README.zh-CN.md)
<p align="center">
<img src="docs/assets/supergoal-logo.png" alt="Supergoal logo" width="760">
</p>
**A Codex skill for ambitious, long-running engineering work.**
Supergoal turns a rough, oversized idea into a verifiable goal-running system: Codex clarifies the task, defines root-level success, decomposes the work into a dependency-aware sub-goal DAG, then executes each selected checkpoint as its own `/goal` until the whole task is proven done.
It is designed for work that normally spills out of one chat: multi-day refactors, research reproductions, migrations, bug hunts, experiment campaigns, test-first implementation plans, and other tasks where Codex needs durable memory, explicit verification, and a way to keep going after context compaction.
With enough token and time budget, Supergoal is intentionally open-ended: it can keep turning blockers and failed verification into focused repair sub-goals instead of losing the thread. It is an operational loop that enables Codex to work over long horizons, while allowing users to intervene at any point, thereby supporting human-in-the-loop interaction throughout.
## Highlights
- 🧭 **Rough idea to root spec**: Codex inspects the repo, asks targeted clarifying questions, and writes down the success criteria before planning.
- 🧩 **Intelligent DAG decomposition**: large tasks become verifiable sub-goals with explicit dependencies instead of a fragile linear checklist.
- 🎯 **One `/goal` per sub-goal**: each checkpoint runs through Codex goal mode as a durable contract, giving long work a stable inner loop.
- ✅ **Evidence and review gates**: progress only advances after evidence is recorded and the sub-goal result is reviewed.
- 🧪 **Root verification first and last**: the whole task must have a measurable verification surface before decomposition, and final completion waits for that proof.
- 🔁 **Repair sub-goals**: failed checks become scoped follow-up goals rather than hidden failures or vague "almost done" claims.
- 💸 **Budget-aware execution**: reported tokens, elapsed time, and optional Codex account quota can be tracked across the run.
- 📊 **Live progress dashboard**: Supergoal renders a read-only dashboard showing sub-goal status, evidence, budget, and overall progress.
- 🧑✈️ **Human control surface**: users can pause, change scope, protect paths, set approval gates, and steer priorities mid-run.
## How It Works
```text
rough idea
-> intake and clarification
-> root spec
-> root verification
-> dependency-aware sub-goal DAG
-> sequential /goal execution
-> evidence and budget review
-> repair loops when needed
-> final root verification and report
```
Codex is the planner. The scripts are guardrails for scaffolding, validation, selection, evidence checks, budget checks, dashboard rendering, and state maintenance.
## Install
Clone this repository, then symlink `skill/supergoal` into your Codex skills directory:
```bash
git clone https://github.com/Lancelot-Xie/Supergoal.git
cd Supergoal
mkdir -p "$HOME/.codex/skills"
ln -s "$PWD/skill/supergoal" "$HOME/.codex/skills/supergoal"
```
A symlink is convenient because `git pull` updates the installed skill. If you prefer a fixed copy, copy `skill/supergoal` into `$HOME/.codex/skills/supergoal` instead.
Open a new Codex session or restart Codex so it can discover the installed skill.
Then invoke it from Codex by name:
```text
Use supergoal for this large engineering task.
```
## Recommended Prompt
```text
Use supergoal to work on this project in the current directory.
I want to reproduce and improve this paper:
"SWIFT: Mapping Sub-series with Wavelet Decomposition Improves Time Series Forecasting".
Please follow the skill workflow: create and maintain GOAL_RUN, ask me for key clarifications when needed, then decompose the work into subgoals that are suitable for sequential /goal execution.
For each subgoal, follow the Supergoal process: execute it through /goal, record evidence/usage/progress, and refresh the dashboard.
I want to complete baseline training and testing on ETTh1, ETTh2, ETTm1, and ETTm2. After reproducing the baseline, try a reasonable improvement. Ideally, the final main metric should improve by about 5% over the baseline on each dataset.
```
## What You Get
An orchestrated run is stored in a `GOAL_RUN/` directory:
```text
GOAL_RUN/
ROOT_SPEC.md
ROOT_GOAL.md
ROOT_VERIFICATION.md
ROOT_VERIFICATION.json
GOAL_GRAPH.json
SUBGOALS/
SG-001.md
SG-002.md
STATE/
PROGRESS.json
CONTROL.md
CONTROL.json
BUDGET.json
EVIDENCE.md
USAGE_LEDGER.md
DECISIONS.md
BLOCKERS.md
scripts/
REPORTS/
dashboard.html
FINAL_REPORT.md
```
## Typical Flow
1. Ask Codex to use `supergoal`.
2. Codex inspects the repo and asks targeted questions only when needed.
3. Codex writes the root spec, root goal, and root verification.
4. Codex decomposes the task into a sub-goal DAG.
5. Codex validates the package and refreshes the dashboard.
6. Codex selects the next ready sub-goal and runs it as a `/goal`.
7. Codex records evidence, usage, review results, budget state, and progress.
8. Codex refreshes the dashboard after each accepted sub-goal.
9. Codex runs root verification and creates repair sub-goals if needed.
10. Codex writes the final report only after required verification evidence exists.
## Manual Commands
These commands are usually executed by Codex itself. They are exposed so the run is transparent and reproducible.
Create an empty scaffold:
```bash
python skill/supergoal/scripts/init_goal_run.py \
--project-path . \
--run-dir GOAL_RUN \
--title "Add refresh-token rotation" \
--rough-idea "Refactor auth to support refresh-token rotation while preserving existing sessions." \
--budget-enabled \
--soft-tokens 50000 \
--hard-tokens 75000
```
If the target project is a subdirectory, point `--project-path` there. For example, a task scoped to `examples/SWIFT/` should create `examples/SWIFT/GOAL_RUN/`, not a root `GOAL_RUN/` beside this README.
Check readiness before launching sub-goals:
```bash
python skill/supergoal/scripts/preflight_codex_goal.py --project-path .
python GOAL_RUN/scripts/preflight_goal_run.py GOAL_RUN
```
Select the next ready sub-goal:
```bash
python GOAL_RUN/scripts/select_next_subgoal.py GOAL_RUN
```
Render the dashboard:
```bash
python GOAL_RUN/scripts/render_dashboard.py GOAL_RUN
```
Run root verification:
```bash
python GOAL_RUN/scripts/run_root_verification.py GOAL_RUN
```
## Dashboard
The dashboard is a read-only static HTML report generated from `GOAL_RUN/`:
```text
GOAL_RUN/REPORTS/dashboard.html
```
Rendered from the real SWIFT example at `examples/SWIFT/GOAL_RUN/REPORTS/dashboard.html`.
Codex should refresh it 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.
For live viewing during a Codex session, start the optional read-only local viewer after the first render:
```bash
python GOAL_RUN/scripts/serve_dashboard.py GOAL_RUN --host 127.0.0.1 --port 8765 --refresh 5
```
The dashboard does not execute goals, modify progress, or replace Codex judgment. It only makes the current run state easier to inspect.
## Layout
This repository contains the skill, docs, and tests:
```text
.
├── skill/supergoal/
│ ├── SKILL.md Codex-facing skill instructions
│ ├── scripts/ Scaffold, validation, execution helpers, dashboard renderer
│ ├── references/ Detailed policies loaded only when needed
│ └── assets/templates/ GOAL_RUN scaffold templates
├── docs/ User-facing design and usage docs
└── tests/ Script regression tests
```
`Layout` just means this project map. It helps open-source users understand where the actual skill lives and which files are docs or tests.
## When Not To Use
Do not use this for tiny one-shot edits, unrelated backlogs, tasks without verifiable completion criteria, or production-critical operations that require human approval.
## Validate
Run the regression tests:
```bash
python3 tests/run_tests.py
```
If you have the `skill-creator` validation helper available, also run:
```bash
python3 /path/to/skill-creator/scripts/quick_validate.py skill/supergoal
```
## Documentation
- [Installation](docs/installation.md)
- [Usage](docs/usage.md)
- [Sequential Subgoal Goal Mode](docs/sequential_subgoal_goal_mode.md)
- [Budget and Usage](docs/budget_and_usage.md)
- [Graph Review Limitations](docs/graph_review_limitations.md)
- [Contributing](docs/contributing.md)
- [Release Checklist](docs/release.md)
- [FAQ](docs/faq.md)
## Relationship To goal-forge
Supergoal was inspired by [michaelpersonal/goal-forge](https://github.com/michaelpersonal/goal-forge), an excellent skill for turning a rough coding idea into a single strong `/goal` contract.
`supergoal` builds on that style for larger runs: it keeps the upfront specification discipline, then adds root-level verification, dependency-aware sub-goal decomposition, sequential `/goal` execution, evidence ledgers, budget/time tracking, repair sub-goals, and a dashboard.
## License
MIT. See [LICENSE](LICENSE).
قراءة الملف الأصلي