{"id":50483300,"url":"https://github.com/gabrimatic/copilot-goal-system","last_synced_at":"2026-06-01T19:30:53.014Z","repository":{"id":357098313,"uuid":"1231317104","full_name":"gabrimatic/copilot-goal-system","owner":"gabrimatic","description":"Manual goal mode with persisted state, drift blocking, and proof-based completion for GitHub Copilot CLI.","archived":false,"fork":false,"pushed_at":"2026-05-21T15:30:19.000Z","size":838,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-21T22:43:05.692Z","etag":null,"topics":["ai-agent","copilot-cli","github-copilot","goal-system","vscode-extension"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/gabrimatic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-06T21:04:54.000Z","updated_at":"2026-05-21T15:38:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gabrimatic/copilot-goal-system","commit_stats":null,"previous_names":["gabrimatic/copilot-goal-system"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/gabrimatic/copilot-goal-system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrimatic%2Fcopilot-goal-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrimatic%2Fcopilot-goal-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrimatic%2Fcopilot-goal-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrimatic%2Fcopilot-goal-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gabrimatic","download_url":"https://codeload.github.com/gabrimatic/copilot-goal-system/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gabrimatic%2Fcopilot-goal-system/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33790684,"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-01T02:00:06.963Z","response_time":115,"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":["ai-agent","copilot-cli","github-copilot","goal-system","vscode-extension"],"created_at":"2026-06-01T19:30:51.479Z","updated_at":"2026-06-01T19:30:53.006Z","avatar_url":"https://github.com/gabrimatic.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Copilot Goal System\n\n[![CI](https://github.com/gabrimatic/copilot-goal-system/actions/workflows/ci.yml/badge.svg)](https://github.com/gabrimatic/copilot-goal-system/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)\n[![Copilot CLI](https://img.shields.io/badge/GitHub_Copilot_CLI-supported-blue)](https://docs.github.com/copilot)\n[![VS Code Chat](https://img.shields.io/badge/VS_Code_Copilot_Chat-preview-orange)](https://gabrimatic.github.io/copilot-goal-system/product/vscode-chat/)\n\nCopilot Goal System keeps long-running Copilot work tied to one persisted Active Goal.\n\nIt gives GitHub Copilot CLI and VS Code Copilot Chat local goal state, lifecycle hooks, subagent boundaries, drift warnings, and completion gates that require proof before a goal can close. Use it when a task needs to survive compaction, parallel sessions, subagents, and the moment where inspection turns one issue into ten.\n\n[Quick start](#quick-start) · [What it adds](#what-it-adds) · [How it works](#how-it-works) · [Docs](https://gabrimatic.github.io/copilot-goal-system/) · [Security](./SECURITY.md)\n\n---\n\n## Quick start\n\nRuntime: **Node.js \u003e= 20** and either **GitHub Copilot CLI** or **VS Code Copilot Chat**. CLI hook mode also needs a bash-compatible shell and `jq`.\n\n### VS Code\n\nInstall from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=gabrimatic.copilot-goal-system).\n\nAfter VS Code installs the extension, run:\n\n```text\nCopilot Goal System: Install Recommended Setup\n```\n\nThe Marketplace **Install** button installs the VS Code wrapper. The command above installs the local goal system for your current OS account:\n\n- Copilot CLI stable adapter\n- VS Code Copilot Chat preview adapter\n- local goal tools\n- lifecycle hooks\n- the Goal System custom agent\n\nAfter extension updates, VS Code checks whether `~/.copilot/extensions/goal-system/` is older than the bundled runtime. If it is stale, the status bar switches to `Goal Update` and VS Code prompts you to update the local Copilot files. Updates replace the installed runtime snapshot so removed files do not linger in `~/.copilot/extensions/goal-system/`.\n\n### Terminal\n\nClone with SSH:\n\n```bash\ngit clone git@github.com:gabrimatic/copilot-goal-system.git\ncd copilot-goal-system\n./install.sh\n```\n\nClone with HTTPS:\n\n```bash\ngit clone https://github.com/gabrimatic/copilot-goal-system.git\ncd copilot-goal-system\n./install.sh\n```\n\nInstall from the published docs site:\n\n```bash\ncurl -fsSL https://gabrimatic.github.io/copilot-goal-system/install.sh | bash\n```\n\n`./install.sh` installs the Copilot CLI adapter by default. Use `./install.sh --target all` to install both CLI and VS Code Chat adapters.\n\nFor CLI mode, restart Copilot CLI, then run:\n\n```text\n/skills reload\n/env\n```\n\nFor VS Code Chat, reload VS Code, then select the `Goal System` custom agent in Copilot Chat.\n\nStart a goal in either surface:\n\n```text\n/goal\nMake this project pass its test suite. Inspect first, fix every in-scope issue, verify with real evidence, and finish only after the completion audit passes.\n```\n\n## What it adds\n\n| Area | What it does |\n|------|--------------|\n| 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. |\n| Lifecycle hooks | Restore goal context, write compact snapshots, block premature stop, warn on stale non-goal tool drift, and keep subagents outside goal ownership. |\n| VS Code Chat adapter | Adds the `Goal System` custom agent, VS Code hook config, direct VS Code goal tools, and local `goalctl` fallback. |\n| Goal contract | Installs the `goal` skill and instruction snippet so Copilot knows the work is execution, not a loose reminder. |\n\nDefault behavior:\n\n- Goal mode is **manual**. Normal prompts do not become goals.\n- `/goal` activation is recognized as a real slash command and creates a persisted draft goal before work begins.\n- Goal state is **main-session only**. Subagents cannot open, update, read, or close goals.\n- Same-directory sessions are **isolated**. Automatic continuation happens only when exactly one open same-directory goal exists, and repeated records for the same resumed goal are treated as one goal.\n- The remaining queue is **dynamic**. Newly discovered in-scope issues are added to the goal and must be resolved before completion.\n- Discovered issues can be **renamed, merged, deduplicated, superseded, or resolved under clearer wording** only with evidence-backed `issueResolutions`.\n- 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**.\n- Tool drift is controlled without deadlocking the session. After three non-goal tool calls without `goal_system_checkpoint` or a compatible goal update, Copilot gets a warning. At five, it gets a critical recovery reminder, but the tool call is still allowed so the agent can inspect, repair, or checkpoint manually when goal tools are unavailable.\n- Stop hooks are blocked while an open goal remains active, with a hard continuation directive that tells Copilot to reload status, continue work, checkpoint persisted state, and finish only with evidence.\n\n## Install details\n\n`./install.sh` supports three targets:\n\n```bash\n./install.sh --target cli\n./install.sh --target vscode-chat\n./install.sh --target all\n```\n\nThe default target is `cli`.\n\nFor Copilot CLI, the installer:\n\n1. Copies this package to `~/.copilot/extensions/goal-system/`.\n2. Installs production dependencies inside that extension directory.\n3. Installs the goal skill at `~/.copilot/skills/goal/SKILL.md`.\n4. Installs the hook helper at `~/.copilot/hooks/goal-context.sh` and merges hook entries into `~/.copilot/settings.json`.\n5. Installs `~/.copilot/extensions/goal-system/bin/goalctl.mjs` as the local fallback for goal status, open, checkpoint, finish, block, cancel, update, and close.\n\nFor VS Code Copilot Chat, the installer:\n\n1. Installs `~/.copilot/agents/goal-system.agent.md`.\n2. Installs `~/.copilot/hooks/goal-system-vscode.json`.\n3. Reuses the same package under `~/.copilot/extensions/goal-system/`, including `goalctl`.\n\nThe installer preserves existing settings and writes backups before changing JSON, JSONC, or Markdown files. Config backups keep the original file permissions, and newly created config files default to owner-only permissions.\nCopilot CLI `settings.json` may contain comments and trailing commas; the installer accepts it and keeps comments outside the exact config subtree it updates.\nIf `settings.json` is malformed or is not a JSON object, the installer preserves the original as an `*.invalid-backup-*` file, recreates a clean JSON object, and then applies the goal-system entries.\nCurrent installs do not create server config. The runtime path is local hooks, direct tools, and `goalctl`.\nDuring updates, it recognizes existing goal hooks written with `~`, `$HOME`, `$COPILOT_HOME`, absolute paths, or wrapper commands. If a composite hook already runs `goal-context.sh`, the installer keeps that hook and avoids adding a duplicate direct goal hook.\nDuring updates, the installer prepares a fresh runtime and production dependencies in a temporary directory before replacing the installed runtime, so failed dependency installs leave the previous runtime in place.\n\nRun a local host health check any time the system feels off:\n\n```bash\nnpm run doctor\n```\n\nUse `npm run doctor -- --target all` after installing both adapters.\n\nRepository-level hook config is optional. Copy `.github/hooks/goal-system.json` into a repository if you want the same lifecycle hooks committed with a project.\n\n## Source and releases\n\nThe root package is the single editable source for the goal-system runtime, hook, skill, tests, and documentation.\n\nThe VS Code extension generates `vscode-extension/resources/goal-system/` during packaging. That directory is a build artifact and is ignored by Git, so there is no second runtime source to keep in sync.\n\nMarketplace releases are packaged snapshots. A GitHub commit does not update installed Marketplace copies by itself; a new extension version must be published. This repository includes `.github/workflows/publish-vscode.yml` so tagged or manually dispatched releases can package and publish the VSIX from GitHub when the `VSCE_PAT` secret is configured.\n\nUpdating the VS Code extension is not enough by itself because Copilot reads files from `~/.copilot/`. The extension compares its bundled version with the installed local runtime and prompts you to run the installer when local files are stale.\n\n## How it works\n\n```text\nUser prompt\n  -\u003e goal skill explains the execution contract\n  -\u003e shared goal core owns persisted state, validation, and summaries\n  -\u003e CLI adapter exposes SDK tools and CLI hooks\n  -\u003e VS Code Chat adapter exposes direct VS Code tools, goalctl fallback, and VS Code hooks\n  -\u003e tests verify the state machine without a live Copilot session\n```\n\nState lives under:\n\n```text\n~/.copilot/session-state/goal-system/\n~/.copilot/session-state/\u003csession-id\u003e/goal-state.json\n```\n\nThe duplicated state is intentional. It gives the system same-session lookup, same-directory continuation, and compact snapshots after context loss.\n\n## Verify locally\n\n```bash\nnpm ci\nnpm run verify\n```\n\nThis runs:\n\n- Node syntax checks\n- shell syntax checks\n- JSON validation\n- goal-state unit tests\n- hook smoke tests\n\nRun the fixture check:\n\n```bash\ncd tests/fixtures/sample-goal-project\nnpm test\n```\n\nExpected result: fail before a goal session fixes it. The runtime E2E prompt uses the fixture to prove Copilot inspected, fixed, verified, updated the goal, and closed only with evidence.\n\n## Docs\n\n| Document | Purpose |\n|----------|---------|\n| [Install guide](https://gabrimatic.github.io/copilot-goal-system/reference/installation/) | Install, update, uninstall, and troubleshoot setup. |\n| [VS Code Chat](https://gabrimatic.github.io/copilot-goal-system/product/vscode-chat/) | Preview adapter details, installed files, and current limits. |\n| [Architecture](https://gabrimatic.github.io/copilot-goal-system/reference/architecture/) | State model, hooks, tools, and lifecycle rules. |\n| [Requirements](https://gabrimatic.github.io/copilot-goal-system/reference/requirements/) | Goal-system contract and completion gates. |\n| [Runtime E2E review](https://gabrimatic.github.io/copilot-goal-system/operations/runtime-e2e-review/) | Manual checklist for a live Copilot session. |\n| [Portability](https://gabrimatic.github.io/copilot-goal-system/product/portability/) | Why the stable release is Copilot-first and what other CLIs would need. |\n| [Support](SUPPORT.md) | Where to report issues and what diagnostics to include. |\n\n## Project layout\n\n```text\n.\n├── extension.mjs                         # Copilot SDK extension entrypoint\n├── lib/goal-core.mjs                     # Goal state, validation, formatting, storage\n├── adapters/vscode-chat                  # VS Code hooks and custom agent\n├── bin/goalctl.mjs                       # Local goal command fallback\n├── hooks/goal-context.sh                 # CLI lifecycle hook helper\n├── skills/goal/SKILL.md                  # Goal-mode instruction contract\n├── instructions/copilot-instructions.goal-snippet.md\n├── scripts/install.mjs                   # Installer implementation\n├── scripts/install.sh                    # Shell installer wrapper\n├── tests/*.test.mjs                      # Local state and hook tests\n└── tests/fixtures/sample-goal-project    # Runtime E2E fixture\n```\n\n## Development\n\n```bash\nnpm ci\nnpm run verify\n```\n\nRun one test file:\n\n```bash\nnode --test tests/goal-core.test.mjs\nnode --test tests/goal-hook.test.mjs\n```\n\nManual install into a temporary home:\n\n```bash\ntmp_home=\"$(mktemp -d)\"\nHOME=\"$tmp_home\" ./install.sh\nfind \"$tmp_home/.copilot\" -maxdepth 4 -type f | sort\nrm -rf \"$tmp_home\"\n```\n\n## Compatibility\n\nThis release supports:\n\n- GitHub Copilot CLI: stable strict mode\n- VS Code Copilot Chat: preview strict mode through VS Code agent hooks and direct VS Code goal tools\n\nVS Code agent hooks and language model tools are VS Code extension surfaces. VS Code shows a confirmation dialog for extension-contributed language model tools; choose Always Allow for the goal tools if you want the smoothest loop. If an organization disables hooks or extension tools, the VS Code Chat adapter falls back to hook context plus the local `goalctl` command, and cannot force tool use by itself.\n\nOther coding CLIs and model-runtime wrappers need a separate adapter before this can be called stable outside Copilot.\n\n## License\n\n[MIT License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabrimatic%2Fcopilot-goal-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgabrimatic%2Fcopilot-goal-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgabrimatic%2Fcopilot-goal-system/lists"}