supergoal: Instructions file for Claude Code

AGENTS.md

Authoritative project doc. Any agent (Claude, Codex, or other) opening this repo should be able to read this file alone and understand the project, where to make changes, and what conventions to follow.

What this repo is

Supergoal is a Claude Code / Codex skill that turns a vague build request into a deeply-planned, autonomously-executed /goal run with built-in retry, fix-spec recovery, per-phase memory writeback, and a final audit pass that re-validates the work against the original plan.

• Slash command: /supergoal <task>
• Central mechanism: produces one ready-to-paste /goal command. The user pastes it once; the rest is autonomous.
• Works on: Claude Code (via plugin marketplace) and Codex CLI (via manual skill copy).
• Public install: see README.md.

Repo layout

supergoal/
├── .claude-plugin/
│   ├── marketplace.json        Catalog Claude Code reads when added as a marketplace
│   └── plugin.json             Plugin manifest (name, version, description, skills path)
├── .gitattributes              Forces `*.sh` to LF (CRLF shebangs fail on a fresh Windows checkout).
├── .gitignore                  Editor/OS junk + .supergoal/ artifact dirs
├── AGENTS.md                   This file. Authoritative project doc.
├── CLAUDE.md                   Claude Code-specific tips. Points at this file.
├── CHANGELOG.md                Per-version release notes. Keep-a-Changelog format, SemVer.
├── LICENSE                     MIT.
├── README.md                   Public-facing: what it is, install, use, Mermaid flow charts.
├── skills/supergoal/
│   ├── SKILL.md                The skill itself. ~565 lines (grew with v0.7's Stage 0 namespace-claim section; the phase-loop section duplicates PROTOCOL.md and is a candidate for slimming next release).
│   ├── references/             Progressive-disclosure docs the agent reads when needed.
│   │   ├── planning-depth.md          What makes a plan deserve "super".
│   │   ├── phase-design.md            How to slice phases (adaptive count, no cap).
│   │   ├── goal-format.md             /goal mechanics on both hosts; required transcript blocks.
│   │   └── repo-state-comparison.md   The one comparison strategy (complete working tree vs baseline).
│   ├── scripts/                Bash scripts the planner/executor run during stages.
│   │   ├── detect-env.sh       Greenfield env recon.
│   │   ├── detect-stack.sh     Brownfield stack/framework detection.
│   │   ├── summarize-repo.sh   Compressed repo map.
│   │   ├── claim-run.sh        Atomically claims a unique per-run dir under .supergoal/ (concurrent-run isolation). Tested by tests/claim-run.test.sh.
│   │   ├── repo-state.sh       Complete working-tree-vs-baseline comparison (audit + cleanliness). Copied into the run's .supergoal/<run-id>/ dir at Stage 7.
│   │   └── validate-phase.sh   Sanity-checks a phase spec has required markers.
│   └── templates/              Files the planner copies into a run's `.supergoal/<run-id>/` dir.
│       ├── ROADMAP.md          Phase plan with dependencies.
│       ├── STATE.md            Live progress file.
│       ├── phase-goal.txt      Phase spec skeleton (work, criteria, evidence, commands).
│       └── PROTOCOL.md         Execution loop + failure recovery + final audit protocol.
└── tests/                      Repo-only (not shipped in the plugin payload).
    ├── claim-run.test.sh       Fixture tests for claim-run.sh (incl. the concurrent-claim race).
    └── repo-state.test.sh      Fixture tests for repo-state.sh over throwaway git repos.