English | νκ΅μ΄
Note
This README documents the current master branch, which may include
unreleased workflow changes beyond the latest tagged release. For the exact
behavior of v2.3.1, see the corresponding tag and CHANGELOG.
Important
This is a personal template, not a general-purpose product. This repository is public only to make maintenance convenient (for syncing and referencing across the author's own projects). It is a personal variant of Spec-Kit, heavily reshaped around one person's workflow, tooling, and assumptions. It is not intended for others to adopt as-is β paths, agents (Codex/Antigravity), and gates are wired to the author's environment, and no support or stability is promised. Use it as a reference for ideas, not as a drop-in starter.
SPECTER is a requirements-governance and verification overlay for AI-assisted product development.
It preserves product intent as work moves from PRDs to Feature boundaries, GEARS specifications, implementation plans, tests, code, and runtime evidence. It uses GitHub Spec-Kit as its generation engine while retaining ownership of its gates, traceability rules, and independent verification protocol.
- GEARS Requirements β Translates ambiguous PRDs into verifiable requirement statements.
- Feature Map Gates β Enforces exactly one Feature owner for every PRD commitment.
- Constitution β Extracts project standards once, pins them in a single place, and re-injects them at every step.
- TAG Navigation β Provides a lightweight, grep-based index from requirement IDs to their primary test and implementation files through
@SPEC β @TEST β @CODE. TAG wiring is mechanically checked, but TAG presence does not prove that a test semantically covers a requirement. Executable tests and review evidence remain authoritative. - Independent Semantic Verification β Codex and Antigravity independently review artifacts at semantic verification stations. Deterministic scripts validate structure and mechanically aggregate their SHA-bound verdicts.
- Graphify Exploration Accelerator β Maintains a local tree-sitter graph that gives agents file-and-line pointers for structural questions. Graph results are navigation hints, not authoritative evidence; agents verify the referenced source files. Missing Graphify degrades to
rg/findwith a recorded warning and never blocks a Feature.
It targets three core issues:
AI forgets rules. A prompt saying "keep files small" is often followed by a massive file a few steps later. Constitution and AGENTS.md repeatedly inject rules, and deterministic gates (pre-commit, hooks, CI) mechanically catch what prompts miss.
Ambiguous requirements lead to unstable implementations. Requesting "build a login feature" lacks authentication details, failure handling, and session policies. GEARS addresses this:
When a user submits valid credentials, the auth service shall issue a session token.
[Error Handling] When credentials are invalid, the auth service shall return a generic authentication error.
It's hard to trace why code exists. The TAG anchor chain connects requirements to tests and code β one grep-able comment line per artifact:
specs/001-auth/tasks.md **TAG**: @SPEC:AUTH-001
tests/auth.test.ts // @TEST:AUTH-001
src/auth/service.ts // @CODE:AUTH-001
The current release is v2.3.1 β see CHANGELOG.md for changes.
A SPECTER Feature is the smallest dependency-aware slice that can be specified, implemented, verified, reviewed, and merged independently.
A Feature may be architectural rather than independently user-shippable. End-to-end user value is guaranteed at the Phase boundary, whose final Feature owns the Phase E2E scenario.
Prefer vertical slices where practical; use dependency-aware architectural slices when foundations or cross-layer boundaries require sequencing.
SPECTER does not treat every artifact as a competing source of truth. Each artifact owns a different kind of decision:
| Artifact | Authority |
|---|---|
| PRD | Product intent and durable commitments |
| Feature Map | Commitment ownership, Feature boundaries, and dependency order |
spec.md |
Executable behavioral contract for one Feature |
plan.md |
Verified implementation decisions and architecture |
tasks.md |
Execution breakdown and traceability assignments |
| Tests and runtime evidence | Observed implementation behavior |
implementation-notes.md |
In-scope deviations discovered during implementation |
A downstream artifact may add domain-appropriate detail without literal
upstream wording. Such refinement and repository-backed
reality-correction may be evidence-resolved. A new actor/journey, integration,
retained-data category, permission boundary, paid capability, or explicit
exclusion/cost/policy conflict is a boundary-change/conflict. At
/ms.clarify it is presented to the user with a proposed upstream patch;
outside that sole human boundary it fails rather than expanding scope
silently. Input hashes prove what was reviewed; they do not grant product authority
or lock an abstract document.
GEARS is used for executable behavioral requirements:
[Where <static>] [While <runtime>] [When <trigger>] the <subject> shall <behavior>.
Given-When-Then remains the acceptance-scenario format:
Where + Whilemaps toGivenWhenmaps toWhenshallmaps toThen
SPECTER does not force GEARS onto schemas, scope declarations, preservation constraints, or implementation notes. Those may use plain but verifiable statements.
GEARS compliance is currently enforced through templates, workflow rules, structural checks, and semantic reviewers. It is not presented as a complete formal-language parser.
Semantic stations use two fresh independent reviewers. Each writes a fixed-path
report bound to the current input SHA256; specter-gate.sh reduce validates
exactly one PASS/WARN/FAIL per report and returns worst-of. One unavailable
reviewer caps a non-FAIL result at WARN, both unavailable is FAIL, and a station
reruns once only after inputs change.
There are no risk profiles, signal tables, receipts, round state, or
acknowledgment gates. Final review always applies the relevant executable safety
checks for migrations, destructive operations, authorization, secrets, public
contracts, and gate/hook changes. See
refinement-first.md.
/ms.init
/ms.pre-specter @docs/prd/PRD.md
/ms.specter 001/ms.pre-specter prepares and verifies the product-wide Feature Map. /ms.specter 001 runs Feature 001 from readiness checks through code review. /ms.clarify is the cycle's sole mandatory human stop: it resolves evidence-determined items first, then hands control to the user for review and any remaining product-intent choices.
For debugging or manual control, each underlying /ms.* step can also be run individually.
Expanded command sequence
/ms.init
/ms.featuremap @docs/prd/PRD.md
/ms.featuremap-checklist @docs/prd/PRD.md
/ms.pre-verify
/ms.constitution
/ms.checklist
/ms.verify
/ms.specify
/ms.clarify
/ms.plan
/ms.tasks
/ms.analyze
/ms.implement
/ms.reviewββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
π Setup
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
0. /ms.init Install Spec-Kit + Constitution + code graph
1. /ms.prd Co-author PRD β Discovery interview for unknowns (Out-of-cycle)
docs/prd/PRD.md (or multiple PRDs)
β
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
πΊοΈ Pre-Feature Cycle Β· Once Β· Bulk run: /ms.pre-specter
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
2. /ms.featuremap Decompose PRD into Feature DAG
3. /ms.featuremap-checklist PRD-only baseline checklist (isolated subagent)
4. /ms.pre-verify Current-hash Codex & Antigravity audit β Global Gate
5. /ms.constitution Finalize project standards (Constitution Β§IX)
β
βΌ Repeat for each Feature in DAG order
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
π°οΈ Per-Feature Cycle Β· N times Β· Bulk run: /ms.specter
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
βββΆ 6. /ms.checklist Verify current Feature (PRD alignment)
β 7. /ms.verify Current-hash Codex + Antigravity verification
β 8. /ms.specify Write specification (Input Feature section)
β 9. /ms.clarify π΄ Mandatory human handoff (evidence-first Q&A)
β 10. /ms.plan Implementation plan + Reality check
β 11. /ms.tasks Generate TAG-based tasks
β 12. /ms.analyze Match spec β plan β tasks consistency
β 13. /ms.implement TDD implementation + TAG injection
β 14. /ms.review Automatic high-risk evidence + execution gates
βββββ Repeat from step 6 if features remain
β All Features completed
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
π Publish / Release
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
15. /ms.fin Automatic high-stakes evidence β commit Β· push Β· PR
16. /ms.merglease Merge PR β tag β GitHub Release
The normal per-Feature cycle has exactly one mandatory human stop:
/ms.clarify. It always hands control to the user, but evidence-backed answers
are resolved before questions are asked. Migration, destructive, irreversible,
reviewer-availability, round-limit, and gate-policy decisions remain executable
evidence gates and add no acknowledgment stop.
Using bare calls is recommended. PRDs and the Feature Map are automatically discovered in their conventional paths (docs/prd/*.md, docs/prd/feature-map.md). Avoid attaching the entire PRD with @ in conductor commands, as it re-injects the file into the context every time the conductor restarts (which can bloat token usage β e.g., 1.05M tokens in one project). Only use @ for files outside conventional paths.
Tracks determined by the nature of changes outside the main cycle.
| Scenario | Track | Key Points |
|---|---|---|
| No PRD or vague ideas | /ms.prd |
Blind-spot pass β Viability gate β Interview to bridge gaps. No gates; output is a PRD consumed directly by the pipeline. |
| No new requirements (bug/copy/style fixes) | /ms.fix |
Maintains TDD, TAG, and gates while skipping spec/clarify/plan/tasks ceremonies. |
| Incremental requirements on baseline or design changes discovered during build | /ms.expand |
Append ## PRD Amendment N to the PRD β decompose only the diff. Existing Features remain unchanged, no global re-audit, rejects freeform input. In-scope implementation deviations remain in specs/<id>/implementation-notes.md; a requirement change returns through /ms.expand. |
| All features green but product-level check needed | /ms.audit |
6 modules (exposure, cold-start, threat model, perf/a11y, gate value, blind spots). Advisory only β blocks nothing; findings route to /ms.fix, /ms.expand, or todo. |
Authoring stays with the host; semantic grading stays with two fresh independent reviewers. The mechanical gate checks current hashes, fixed report paths, exact verdict fields, and worst-of without persisting workflow state.
| Gate | When | Verification |
|---|---|---|
Global Feature Map (/ms.pre-verify) |
Pre-Feature | Full PRD coverage, ownership, DAG, exclusions, end-to-end journey |
Per-Feature (/ms.checklist + /ms.verify) |
Feature start | Scope, dependencies, Done criteria, unsupported boundary additions |
Documents (/ms.analyze) |
Before implementation | spec β plan β tasks against repository reality |
Code (/ms.review) |
After implementation | lint/type/test/build once, real-entrypoint Done Criteria, applicable E2E and safety checks |
Direct /speckit-specify bypass is denied by a PreToolUse hook. A bounded Stop
hook requires fresh executable evidence after code changes and accepts honest
FAIL evidence. Pre-commit and CI retain Feature Map hash and TAG-chain
backstops. /ms.clarify is the cycle's only mandatory human stop.
| Command | Role |
|---|---|
/ms.init |
Install Spec-Kit + inject SPECTER overlays, hooks, backstops, lean gate, and Graphify |
/ms.prd |
Co-author PRD via discovery interview (Out-of-cycle) |
/ms.pre-specter |
Bulk run the Pre-Feature cycle (featuremap β constitution) |
/ms.featuremap |
Decompose PRD into a Feature DAG and generate per-feature prompts |
/ms.featuremap-checklist |
Create a fresh PRD-only independent baseline checklist |
/ms.pre-verify |
Match PRD + checklists from both agents + Feature Map β Global Gate |
/ms.constitution |
Establish Constitution Section IX project baseline (Usually once) |
/ms.specter |
Bulk run the Per-Feature cycle (checklist β review) with one human stop at clarify and automatic evidence gates elsewhere |
/ms.checklist / /ms.verify |
Verify current Feature's PRD coverage (Host + Codex/Antigravity) |
/ms.specify / /ms.clarify / /ms.plan / /ms.tasks |
GEARS spec β Clarification β Plan β TAG tasks |
/ms.analyze |
Validate document consistency + agent checks before build |
/ms.implement |
TDD implementation + TAG injection (--to-end, --mode tdd|refactor, --task TNNN, --pbt property-based tests from GEARS) |
/ms.review |
Code review + adversarial agent review + execution gates |
/ms.fix / /ms.expand / /ms.audit |
Alternative tracks (See table above) |
/ms.fin |
Sync docs β require current review β commit Β· push Β· PR |
/ms.merglease |
Merge PR β Automate semver β tag β GitHub Release |
/ms.up-docs |
Sync living docs |
/ms.sync |
Broadcast workflow files to registered project repos (with 3-way conflict protection) |
The default Constitution (test-first, simplicity, GEARS, TRUST, TAG) created by /ms.init is active even before /ms.specify. /ms.constitution does not create a new one from scratch; it extracts and establishes the project-wide baseline (Section IX) from the verified Feature Map. Thus, it is run once immediately after /ms.pre-verify, not during the feature cycles.
/ms.init β Activate default Constitution
/ms.featuremap-checklist β Run PRD-only independent checklist
/ms.pre-verify β Run global gate
/ms.constitution β Establish Section IX baseline (Usually once)
npx degit beomeodev/specter my-new-project
cd my-new-project
# Inside Claude Code:
/ms.init/ms.init is pinned to a verified Spec-Kit release (v0.12.5). Because upstream is pre-1.0 and changes its integration surface frequently, pinning protects wrappers from unexpected breakage. To track the latest, run SPEC_KIT_REF=main /ms.init β though you may need to re-verify command delegation names as listed in the Spec-Kit Compatibility section below.
specter/
βββ .claude/
β βββ commands/ # Workflow entrypoints
β βββ agents/ # Specialist subagents
β βββ skills/ # Reusable checkers, rules, and rubrics
β βββ settings.json # Permission baseline
βββ .specify/ # Spec-Kit state (Constitution, scripts β created by /ms.init)
βββ scripts/specter/ # Deterministic gate and sync scripts (Agent-neutral)
βββ docs/
β βββ prd/ # PRDs, feature-map, checklists, and verification reports
β βββ review/ # Review output artifacts
β βββ templates/ # Constitution and spec templates, gate scripts
βββ specs/NNN-{feature}/ # spec.md Β· plan.md Β· tasks.md
βββ AGENTS.md # Agent-neutral contract (CLAUDE.md is a symlink)
βββ README.md
SPECTER is a compatibility layer that delegates work to upstream skills by name rather than re-implementing the engine. /ms.* acts as explicit workflow entrypoints and remains commands, while reusable verification logic is kept as skills. /ms.init injects the Feature Map gate into all candidate locations, whether they are in the command layout (.claude/commands/speckit.*.md) or the native-skill layout (.claude/skills/speckit-*/SKILL.md).
Upstream renaming will break only these delegations. Before bumping the pin (SPEC_KIT_REF), ensure these names remain correct.
| SPECTER Wrapper | Delegation Target (Pinned v0.12.5) |
|---|---|
/ms.specify |
/speckit-specify (+ /ms.init injects the gate) |
/ms.clarify |
/speckit-clarify |
/ms.plan |
/speckit-plan |
/ms.tasks |
/speckit-tasks |
/ms.analyze |
/speckit-analyze (foundation only) |
/ms.implement |
/speckit-implement |
/ms.checklistintentionally does NOT delegate to/speckit-checklist(runs independent verification against the PRD).*- v0.12.x also renders upstream skills outside this contract (
speckit-converge,speckit-taskstoissues,speckit-constitution,speckit-checklist) β SPECTER does not wrap them;/ms.constitutionand/ms.checklistare independent implementations, not wrappers of the same-named upstream skills.*- GEARS template injection uses the v0.12.x resolution stack:
/ms.initinstalls the GEARS spec-template at.specify/templates/overrides/(priority 1 β no preset or extension can shadow it) plus the core path as a pre-0.12 fallback.*
While conforming names, paths, versions, and flags to upstream, SPECTER will never compromise on: the Feature Map gate, direct-call bypass block (dual guard via prompt marker and PreToolUse hook), GEARS reaching new specs, TAG traceability, Constitution Section IX, independent dual-agent verification (Codex & Antigravity), gate ownership (retained by SPECTER, not delegated to Spec-Kit CLI flags), and maintaining gate integrity during agent unavailability.
We will fork the engine if any of the following cannot be resolved via thin compatibility shims (renaming, path adjustment, version/flag alignment):
| Tripwire | Impact |
|---|---|
| Spec-template resolution deviates from 'core' (=.specify/templates/spec-template.md) | GEARS fails to reach new specs |
| Patchable 'speckit-specify' file disappears (locked, signed, or generated dynamically) | Cannot inject gates β Bypass blocks collapse |
| Unable to block automatic '/speckit-specify' calls | Sequential gate enforcement breaks down |
| Upstream engine hard-conflicts with SPECTER injections (TAG/Constitution) | Composition/wrapping becomes impossible |
| Dependent scripts break repeatedly without a viable shim | Workflow steps become non-functional |
Principle: Conform on names, paths, versions, and flags. Never bend on gates, GEARS, TAG, Constitution, and Codex.
The current repository remains a personal, environment-specific template. The roadmap below describes a possible future distribution model, not the support or compatibility contract of the current release.
While SPECTER is currently Claude Code-specific, we plan to transition it to a workflow that runs identically on Codex CLI. The direction aligns with Spec-Kit's unified architecture: keep .claude/commands/ as the single source of truth, and let renderers generate agent-specific formats (e.g., .agents/skills/ for Codex). Adding other agents like Gemini CLI later will then just be a matter of adding one unified definition.
- Driver-Aware Cross-Verification: The external reviewer at the verification station switches dynamically based on the driver (Claude driver β Codex +
agyreview; Codex driver β Claude +agyreview). This avoids hardcoded drift by keeping a single dispatch table. - uv Package Distribution: Aims for a simple setup like
uvx specter init --integration claude|codex, similar to Spec-Kit. - Full English Translation + Language Selector: Consolidates templates in English, allowing users to choose their reporting and interaction language at installation.
- Pre-Distribution Cleanup: Prioritizes removing personal account configurations and hardcoded local paths before open-sourcing.
The step-by-step execution plan follows: Cleanup β Renderer β Driver-aware protocol β Packaging. The gate invariants remain intact, although hook-based enforcement under Codex might fallback to pre-commit/CI backstops (the only structural gap).
Suitable: Projects with continuous AI-assisted feature development Β· Products requiring tight PRD-spec-impl-review traceability Β· MVPs shipping sequential features Β· Long-term codebases needing quick answers for "why does this code exist?".
Unsuitable: One-off scripts Β· Quick experiments around 100 LOC Β· Micro-projects where the maintenance cost of traceability outweighs the benefits.
- Git
- ripgrep
- uv/uvx
- Claude Code
- Project-specific test/lint/type/build tooling
- Codex CLI (authenticated) + Codex plugin for Claude Code
- Google Antigravity CLI
agy(authenticated) + Antigravity plugin
With one unavailable reviewer, a remaining FAIL stays FAIL and any other result is capped at WARN. If no independent reviewer remains, the station fails rather than substituting a host-only verdict.
- Graphify (
graphifyy, version-pinned;/ms.initinstalls it viauv tool install --python 3.12)
Its absence at runtime is non-blocking and falls back to rg/find.
Optional: GitHub CLI (PR/release automation in /ms.fin and /ms.merglease)
The workflow has automated fixture and gate-contract tests for current input
hashing, exact verdict parsing, reviewer unavailability, worst-of reduction,
hooks, sync, and publish/release helpers. The lean contract is covered by
tests/specter/test_specter_gate.py; consuming-project end-to-end runs remain
the final integration check.
See docs/SYSTEM_MAP.md for current verified invariants and known gaps.
- AGENTS.md β AI coding rules (CLAUDE.md is a symlink)
- CHANGELOG.md β Release history
- docs/SYSTEM_MAP.md β Curated prose snapshot (invariants, risks, verification); structural exploration may use Graphify pointers in consuming projects, which must be verified against source files (
/ms.initStep 2.9) - .claude/commands/ Β· .claude/agents/ Β· .claude/skills/
Spec-Kit Β· Claude Code Β· ripgrep
MIT License