Start here
- Quickstart gives the shortest install path.
- Install guide covers update, uninstall, and troubleshooting.
- Architecture explains the state machine, hooks, adapters, and completion gate.
- Runtime E2E review is the live verification checklist.
Install
install.sh downloads the repository archive to a temporary directory and runs the real installer from there.
For CLI, MCP, and VS Code Chat support:
What it adds
| Area | What it does |
|---|---|
| Goal tools | goal_system_open, goal_system_status, goal_system_checkpoint, and goal_system_finish create, reload, checkpoint, and finish persisted goals. Compatibility update and close tools remain available for older or advanced flows. Completion is refused without proof. |
| MCP stdio server | Adds goalSystem to Copilot CLI MCP config and exposes status, open, checkpoint, finish, update, close, block, and cancel tools over stdio. |
| Lifecycle hooks | Restore goal context, write compact snapshots, block premature stop, warn on stale non-goal tool drift, and keep subagents outside goal ownership. |
| VS Code Chat adapter | Adds the Goal System custom agent, VS Code hook config, direct VS Code goal tools, and local goalctl fallback. |
| Goal contract | Installs the goal skill and instruction snippet so Copilot knows the work is execution, not a loose reminder. |
Default behavior
- Goal mode is manual. Normal prompts do not become goals.
/goalactivation creates a persisted draft goal before work begins. Explicit execution-contract phrases (for example “new goal” or “keep working until this is done”) activate the same way without requiring the literal/goalcommand.- Goal state is main-session only. Subagents cannot open, update, read, or close goals.
- Drift warnings are recoverable. Stale tool use escalates from warning to critical reminder, but default installs do not deny every tool call when the checkpoint tool is missing or ignored.
- Same-directory sessions are isolated.
- Completion requires inspection evidence, validation proof, verification results, requirement coverage, no remaining work, no blockers, resolved or evidence-covered discovered issues, and a completion audit.