{"id":51077043,"url":"https://github.com/robzilla1738/goalkeeper","last_synced_at":"2026-06-23T15:02:28.297Z","repository":{"id":363361292,"uuid":"1262460936","full_name":"robzilla1738/goalkeeper","owner":"robzilla1738","description":"Evidence-first control plane for agentic work: turn a vague goal into a bounded contract, then refuse to call it done without proof. Hooks and MCP for Claude Code and Codex.","archived":false,"fork":false,"pushed_at":"2026-06-09T01:53:14.000Z","size":201,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-21T14:57:14.323Z","etag":null,"topics":["agentic","ai-agents","claude-code","codex","developer-tools","guardrails","llm","mcp","verification"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/robzilla1738.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-08T02:29:53.000Z","updated_at":"2026-06-13T17:46:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/robzilla1738/goalkeeper","commit_stats":null,"previous_names":["robzilla1738/goalkeeper"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/robzilla1738/goalkeeper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robzilla1738%2Fgoalkeeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robzilla1738%2Fgoalkeeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robzilla1738%2Fgoalkeeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robzilla1738%2Fgoalkeeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/robzilla1738","download_url":"https://codeload.github.com/robzilla1738/goalkeeper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/robzilla1738%2Fgoalkeeper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34694786,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","ai-agents","claude-code","codex","developer-tools","guardrails","llm","mcp","verification"],"created_at":"2026-06-23T15:02:25.423Z","updated_at":"2026-06-23T15:02:28.292Z","avatar_url":"https://github.com/robzilla1738.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Goalkeeper\n\n[![CI](https://github.com/robzilla1738/goalkeeper/actions/workflows/ci.yml/badge.svg)](https://github.com/robzilla1738/goalkeeper/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n\n**An evidence-first control plane for agentic work.**\n\n\u003e **Don't let agents claim done. Make them prove it.**\n\nGoalkeeper turns a vague goal into a bounded contract, lets an agent work inside\nit, and refuses to call the work done until there's proof. Proof is whatever the\nbest available verifier can give you: a passing test, a clean diff, an external\ncheck, a human signing off. It runs on top of the host's own `/goal`, hooks,\nskills, and subagents rather than replacing them.\n\nCoding came first because software is easy to check: tests pass or fail, a diff\nis in scope or it isn't, CI is green or red. The contract engine itself is\ndomain-neutral, though, with adapters for research, writing, and ops.\n\n\u003e **Contract, don't vibe.** Don't build a raw infinite-loop wrapper. Codex and\n\u003e Claude Code already have first-party continuation. The piece that's actually\n\u003e missing is a contract system that makes long-running work measurable, bounded,\n\u003e and auditable, then gates completion on proof.\n\n---\n\n## The promise, honestly\n\nGoalkeeper does not claim it can automatically prove any goal is done. What it\ndoes: define what proof means for that goal, record the evidence as the work\nhappens, and gate completion on the best verifier available. It always shows the\ncompletion tier (0–6), so nobody gets to fake confidence.\n\n```\nContract → Work → Evidence → Verification → Audit → Accept / Review\n```\n\n## What's inside\n\n- **Goalkeeper Core** (`goalkeeper_core/`) is domain-neutral and dependency-free\n  (Python 3 stdlib only): the Universal Goal Contract v2, a validator registry\n  (command, git_diff, file, http, github, ticket, sql, rubric, human_approval),\n  verifier tiers 0–6, the completion gate, proof bundles, bounded run-output\n  artifacts, risk/approval gates, loop modes, and subagent packets.\n- **Adapters** (`goalkeeper_core/adapters/`): `code`, `research`, `writing`,\n  `ops`, picked by `goal.domain`.\n- **Hosts** (`hosts/`): `claude` and `codex` plugins (skills, agents, hooks), an\n  MCP server, a GitHub Actions gate + PR-comment workflow, and a bare `shell`\n  entrypoint.\n- **Schema** (`schema/goalkeeper.contract.schema.json`) plus a stdlib\n  `validate-contract`.\n\n## How it works (one diagram)\n\n```\n/goalkeeper \"Refactor auth…\"            ← a skill (instructions)\n        │  the model runs the goalkeeper CLI to write the v2 contract\n  .goalkeeper/  →  state.json (canonical) · goal.md (generated) · runs.jsonl · proof.md\n        │  goalkeeper doctor (gate) → render --format prompt\n  /goal \u003cobjective + scope + proof + constraints\u003e   ← primary host workflow\n        │  the host works the goal; hooks inject the contract and block\n        │  obvious destructive / out-of-scope shell commands\n        ▼\n  goalkeeper run → goalkeeper gate → complete → proof   (PASS only with evidence)\n```\n\nGoalkeeper renders a native `/goal` prompt the host runs, then verifies\ncompletion on its own. It does not need a separate `/loop` command. The hooks are\nwhat make \"done\" non-bypassable: for an enforced contract (templates and\n`init --auto` switch this on) the **Stop** hook holds the turn open, bounded by\nthe contract's turn budget, until the gate passes. Then it records completion and\nthe proof bundle automatically, or pauses for a named human if the contract calls\nfor one. Writes outside scope get denied at the boundary (`Edit`/`Write`, and\nCodex `apply_patch`), and commands run during the turn are auto-recorded as\nevidence. Turn it all off with `goalkeeper autocontinue off` or\n`GOALKEEPER_NO_STOP=1`. See [`/goal` and continuation](./docs/concepts/GOAL_AND_LOOP.md).\n\n## Quick start\n\n```bash\n# in a target git repo\npython3 /path/to/goalkeeper/bin/goalkeeper init --auto -o \"Refactor auth to the new token API while preserving behavior\"\npython3 /path/to/goalkeeper/bin/goalkeeper status\npython3 /path/to/goalkeeper/bin/goalkeeper render --format prompt   # paste into /goal\npython3 /path/to/goalkeeper/bin/goalkeeper run \"\u003crequired validator command\u003e\"\npython3 /path/to/goalkeeper/bin/goalkeeper checkpoint --id cp1 --evidence \"validators passed and diff reviewed\" --met\npython3 /path/to/goalkeeper/bin/goalkeeper gate                     # exit 0 only when complete\npython3 /path/to/goalkeeper/bin/goalkeeper complete --accepted-by you\npython3 /path/to/goalkeeper/bin/goalkeeper proof\n```\n\nAlready started a change before initializing Goalkeeper? Run\n`goalkeeper adopt -o \"Finish the current change\"` to scope the contract around\nyour current git diff. For local setup, `goalkeeper install all --dry-run` shows\nthe shell/Claude/Codex symlinks it would create, and `goalkeeper smoke core`\nruns the whole gate flow in a throwaway repo.\n\n**As a Claude Code plugin:** `claude --plugin-dir ./hosts/claude`, then\n`/goalkeeper Refactor the auth module…`. **As a Codex plugin:** see\n[`hosts/codex`](./hosts/codex). **As MCP tools (either host):** see\n[`hosts/mcp`](./hosts/mcp). **In CI:** see\n[`hosts/github-actions`](./hosts/github-actions).\n\n## Documentation\n\n- [Architecture](./docs/concepts/ARCHITECTURE.md) · [`/goal` and continuation](./docs/concepts/GOAL_AND_LOOP.md) · [Goal Contract v2](./docs/concepts/GOAL_CONTRACT.md)\n- [Verifier tiers](./docs/concepts/VERIFIER_TIERS.md) · [Loop modes](./docs/concepts/LOOP_MODES.md)\n- [Contract schema reference](./docs/schemas/CONTRACT_V2.md) · [Writing an adapter](./docs/adapters/WRITING_AN_ADAPTER.md)\n- [Risk \u0026 approvals](./docs/security/RISK_AND_APPROVALS.md) · [CLI](./docs/CLI.md) · [Hooks](./docs/HOOKS.md)\n- Playbooks: [code refactor](./docs/real-world-playbooks/code-refactor.md), [recurring maintenance](./docs/real-world-playbooks/recurring-maintenance.md)\n- Examples: [`examples/`](./examples) (runnable v2 contracts)\n\n## Status\n\nGoalkeeper Core, the hook, host wiring, the MCP server, the installer, and the\nsmoke path are covered by a 76-test `pytest` suite that runs in CI on Python\n3.9–3.12 with zero runtime dependencies. The in-process hook loop (enforce →\ncontinue → auto-complete) is tested end to end. What's still unproven is a long\nlive Claude or Codex session driving the plugin skills turn after turn; on Codex\nyou also do the one-time `/hooks` trust first. Check local wiring with\n`goalkeeper host doctor` and `goalkeeper smoke`.\n\n## License\n\nMIT © Robert Courson — see [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobzilla1738%2Fgoalkeeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frobzilla1738%2Fgoalkeeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frobzilla1738%2Fgoalkeeper/lists"}