| name | spec-guard |
| description | Pre-implementation spec check. Auto-invoke before building any feature on an existing system. Scans the project's specs directory, flags unimplemented specs in the same domain, blocks work until specs are acknowledged. Prevents reimplementing what's already been designed. |
| type | agent |
Spec Guard -- Pre-Implementation Spec Check
Before building anything on an existing system, verify no spec already governs the work. This skill fires BEFORE implementation, BEFORE writing code, BEFORE seeding data, BEFORE writing migrations.
When to invoke
Auto-invoke when ANY of these are true:
- You are about to write code for a feature on a system that has a project directory under
02_Projects/
- You are about to seed data into an existing database schema
- You are about to write a migration for an existing service
- You are about to create an import/export pipeline for an existing system
- A research subagent returned spec filenames matching your current work domain and you haven't read them
Do NOT invoke for:
- New projects with no existing specs
- Bug fixes where the fix is self-evident (typo, crash, missing null check)
- Documentation-only changes
Step 1: Identify the target project
Determine which project directory the work targets. Map from the code path or database schema to the vault project. The mapping is project-specific, so consult your vault's CLAUDE.md or project index for the canonical signals. A general heuristic:
| Signal | Likely project directory |
|---|
apps/<app>/ or <app>.* schema | 02_Projects/.../<app>/ |
services/<svc>/ | 02_Projects/.../<svc>/ |
Domain-specific subfolder (e.g. payments/, auth/) | Closest matching project dir |
If no project directory exists, skip to Step 4 (no specs possible).
Step 2: Scan for governing documents (SD first, then specs)
2a. System Definitions (constitutional authority).
Glob: {project_dir}/**/SD - *.md
Glob: {vault_root}/02_Projects/**/SD - *.md (broader search if project-level finds nothing)
SDs define principles, not implementations. If an SD exists for the domain, read it first. Its principles constrain every spec and implementation beneath it. A spec that contradicts its governing SD is wrong; the SD wins.
2b. Product Definitions.
Glob: {project_dir}/**/PD - *.md
PDs define what a product does at the concept level. If a PD exists, it provides context the spec may have been written against.
2c. Specs.
Glob: {project_dir}/specs/**/*.md
Read the frontmatter of every spec found. Extract:
status: draft, reviewed, conditional, implemented, superseded- Title (from
# SPC - ... heading)
- Date created
Filter to specs that are NOT status: implemented or status: superseded. These are live design documents.
Reading order: SD first (for principles and constraints), then PD (for product context), then SPC (for implementation details). If the SD and SPC disagree, flag the disagreement to the user. The SD is authoritative for design principles; the SPC is authoritative for implementation specifics that don't contradict the SD.
Step 3: Domain match
For each live spec, check whether its title or purpose touches the same domain as your planned work. Use keyword overlap. Generic categories:
| Your work | Spec keywords that often match |
|---|
| Data ingest / import / seeding | import, ingest, audit, seed, pipeline |
| Content generation | content, generation, brief, corpus |
| Auth / login changes | auth, login, SSO, password, session |
| API endpoint changes | API, endpoint, route |
| UI component changes | component, page, view, dashboard |
| Data migration | migration, schema, table |
If ANY spec matches:
- Read the full spec (not just frontmatter)
- Identify which functional requirements (FRs) govern your planned work
- Check the data model section for tables, columns, or schemas the spec defines
Step 4: Gate decision
No matching specs found:
Proceed with implementation. Log: "Spec guard: no governing specs found for [domain] in [project]."
Matching spec found, status = reviewed or conditional:
HARD GATE. Present the spec's design to the user:
- Spec name and date
- The FRs that apply to your planned work
- The data model the spec defines
- Ask: "This spec governs this work. Implement per spec, or deviate with reason?"
Do not proceed until the user responds. Do not silently deviate.
Matching spec found, status = draft:
SOFT GATE. Present the spec but note it's a draft:
- "Draft spec exists: [name]. It defines [summary]. Follow the draft design, or implement independently?"
Matching spec found, your work contradicts the spec:
HARD BLOCK. You cannot implement something that conflicts with a reviewed spec without user approval. Present the conflict clearly:
- "The spec says [X]. Your plan does [Y]. These are incompatible because [reason]."
Step 5: Log the check
After the gate passes (either no specs found or user approved), log the result in your working context:
Spec guard: [PASS - no specs | PASS - spec acknowledged | PASS - user approved deviation]
Specs checked: [list of spec filenames scanned]
Governing spec: [name, or "none"]
This log survives in the conversation and can be referenced at closeout.
What this prevents
- Reimplementing from scratch when a data model already exists (e.g. an agent designs a feature from DB schema alone, ignoring a spec that already defines the canonical tables and routing logic)
- Conflicting implementations where two sessions build the same feature differently
- Wasted work that gets thrown away when the spec's design is eventually implemented
- Silent spec violations where the agent doesn't know a spec exists
