Why Spec-Scout?
Out of the box, GitHub Copilot starts every session with zero knowledge of your codebase architecture, module boundaries, or quality rules. Spec-Scout fixes that.
| ❌ Without Spec-Scout | ✅ With Spec-Scout |
|---|---|
| Copilot guesses at intent each session | Copilot reads verified, structured context first |
| Scope creep — AI changes things it shouldn't | Strict scope boundary enforced automatically |
| Test coverage is undefined | 90% coverage floor enforced by the Constitution |
| Context lost between sessions | Session temp files let you resume exactly where you left off |
| No record of module responsibilities | Ownership, flows, and boundaries committed to the repo |
Key Features
Structured Context Files
Module ownership, flows, and integration boundaries committed directly to your repo — Copilot reads them before every story.
Governed Phase Workflow
P0 → Analysis → Solution → Plan → Execution → Quality Gate. Copilot waits for your approval at every transition.
90% Coverage Mandate
The Constitution enforces a minimum 90% test coverage on all new or changed application logic — no exceptions.
Session Resilience
Temp files save exact phase state. Use @continue to resume any session, on any day, right where you stopped.
Drift Detection
@update-context diffs your commits against main and updates only the module context files that drifted.
Zero Dependencies
Pure Markdown files. No build tools, no packages, no runtime. Works in any repo, any language, any stack.
The Workflow at a Glance
Every story follows the same governed sequence. Copilot always waits for your explicit approval before advancing.
| Phase | What happens | Your response |
|---|---|---|
| P0 — Drift Check | Optional context drift check against main |
YES / NO |
| 1 — Analysis | Copilot reads module context + codebase, produces a tech analysis report | PROCEED |
| 2 — Solution | Copilot proposes approaches with trade-offs | SELECT 1 / SELECT 2 |
| 3 — Task Plan | Dependency-aware task breakdown with test gates | EXECUTE PLAN |
| 4 — Execution | One task at a time, tests run after each | CONFIRM per task |
| 5 — Quality Gate | Full test suite, code review, summary file, commit message | Review & commit |
Install in 30 Seconds
Option A — curl into any existing repo
curl -fsSL https://raw.githubusercontent.com/specscout27/spec-scout/main/install.sh | bashOption B — clone and inspect first (recommended)
# 1. Clone spec-scout outside your repo
git clone https://github.com/specscout27/spec-scout.git /tmp/spec-scout
# 2. cd into YOUR repo root
cd /path/to/your-repo
# 3. Run the installer
bash /tmp/spec-scout/install.shOption C — GitHub Template (new repos)
Click "Use this template" on the GitHub repo page to spin up a new repository with all framework files pre-installed.
The Constitution — Three Hard Rules
Every story Copilot works on is governed by three non-negotiable mandates. The AI enforces them automatically — you cannot skip them.
- [C1] Data Sanctity — Zero-tolerance for plaintext PII or secrets in any persistent storage, log, or telemetry.
- [C2] Resilience Threshold — Minimum 90% code coverage on all new or changed application logic. Excludes config, infrastructure-as-code, generated code, and test helpers.
- [C3] Scope Preservation — No drive-by refactoring. The AI is forbidden from modifying code outside the current story's scope.
Commands
| Command | What it does |
|---|---|
@update-context | Sync module context files with committed changes on main; interactive Before → After review |
@analysis | Run Phase 1 only — full analysis report, no code changes |
@solution | Run Phases 1–2 — analysis + solution options, then stop |
@continue | Resume a previous session from its .tmp.md file |
@noscout | Bypass SDD entirely for this one message — standard Copilot behaviour |
Stop guessing. Start governing.
Spec-Scout is free, open-source, and installs in under a minute into any repository.