Vibe Spec Sync

vibe-spec-sync

Code changes. Specs don't update themselves. This skill closes the loop.

When to Use This Skill

• Before committing — detect spec drift from staged changes
• After approving decisions (from vibe-decision-journal) — sync them back to spec
• When vibe-spec-vs-code-audit found gaps — fix them
• Periodically — ensure spec still reflects reality

When NOT to Use This Skill

• No spec exists (write one first, or use vibe-doc-quality-gate to bootstrap)
• Prototype/spike code with no spec commitment
• Spec is explicitly labeled as aspirational/future-state

Prerequisites

The project must have:

• A specification document (markdown) — configured in step 1
• Implementation code that the spec describes
• Optionally: a test suite with requirement traceability markers (# req:[ID])

Steps

Step 1: Locate Spec and Code

1. Find the spec — Look for:

• spec.md, SPEC.md, *_spec.md in project root or docs/
• Design docs in docs/design/, docs/architecture/
• Ask user if ambiguous: "Which document is the authoritative spec?"

1. Find the implementation — The code files the spec describes

1. Find the decision log — docs/decisions/decisions.jsonl (from vibe-decision-journal)

Step 2: Extract Drift from Staged Changes

Run git diff --cached and analyze what changed relative to the spec:

1. Categorize each change:

• Spec-aligned: Change matches what the spec says → no action
• Spec-extending: Change adds behavior the spec doesn't mention → spec needs new section
• Spec-modifying: Change alters behavior the spec describes differently → spec needs update
• Spec-contradicting: Change violates what the spec explicitly forbids → flag for review

1. For each drift item, produce:

`` DRIFT-[NNN]: Type: extending | modifying | contradicting Spec section: "## [Header]" Current spec says: "[quoted text]" Code now does: "[description of new behavior]" Suggested spec update: "[proposed new text]" ``

1. Present drift items to the user via AskUserQuestion:

• Approve update — update the spec to match the code
• Approve with edits — user refines the proposed spec text
• Reject — the code is wrong; flag for fix (do NOT update spec)
• Defer — not ready to decide; skip for now

Step 3: Apply Spec Updates

For each approved drift item:

1. Find the target section in the spec:

• Match by exact header first
• Fall back to normalized match (case-insensitive, whitespace-collapsed)
• If no matching section, determine correct placement by reading surrounding sections

1. Apply the update:

• For modifying: Replace the relevant paragraph/sentence within the section. Use search-and-replace with the old text and new text. Preserve surrounding content.
• For extending: Add new content to the appropriate existing section, or create a new section if the content doesn't fit anywhere.
• For contradicting (approved): Same as modifying — replace the contradicted text.

1. Preserve spec structure:

• Don't rewrite sections that weren't affected
• Maintain existing formatting, header hierarchy, and ordering
• Add a brief inline note if a section was significantly changed: ``

1. Stage the spec changes: git add [spec file]

Step 4: Verify Consistency

After applying updates:

1. Re-read the updated spec — verify it reads coherently (no dangling references, no contradictions between sections)

1. Cross-check with decision log — ensure approved decisions from vibe-decision-journal are reflected in the spec

1. Check test coverage — identify any updated spec sections that now lack test coverage:

• Scan tests for # req:[ID] markers matching affected requirements
• Report uncovered requirements: "Spec updated but no test covers [requirement]. Consider running vibe-adversarial-test-generation in spec-driven mode."

Step 5: Report

Output Format

Spec Sync Report

Spec: [path/to/spec.md] Staged Changes Analyzed: [N files, M insertions, K deletions]

| # | Type | Spec Section | Action | Status | |---|------|-------------|--------|--------| | 1 | modifying | ## Authentication | Updated: "JWT tokens" → "JWT tokens with 1h expiry" | Approved | | 2 | extending | (new) ## Rate Limiting | Added new section | Approved | | 3 | contradicting | ## Data Retention | Flagged: spec says "never delete", code adds TTL | Rejected — code needs fix | | 4 | extending | ## Error Handling | Deferred | — |

Spec Changes Applied

• docs/spec.md: 2 sections updated, 1 section added
• Linked decisions: DEC-0045, DEC-0046

Test Coverage After Sync

• Requirements with tests: X/N
• Newly uncovered: ## Rate Limiting (no tests yet)

Next Steps

• [ ] Fix rejected drift item #3 (code contradicts spec on data retention)
• [ ] Add tests for ## Rate Limiting section
• [ ] Run vibe-spec-vs-code-audit to verify full alignment

Integration with Other Skills

• vibe-decision-journal: Decisions feed into spec sync. When decisions are approved, this skill updates the spec to reflect them.
• vibe-spec-vs-code-audit: Run after sync to verify no remaining gaps.
• vibe-adversarial-test-generation (spec-driven mode): Generate tests for requirements that were updated or added during sync.
• vibe-coverage-enforcer: Verify that test coverage still meets tier targets after spec-driven test additions.
• vibe-pre-commit-audit: Complementary — that skill checks for secrets/debug code; this skill checks for spec alignment. Both belong in a pre-commit workflow.

Rules

• NEVER update the spec without user approval. Every drift item must be presented and explicitly approved.
• NEVER silently drop drift items. If a change affects the spec, report it — even if you think it's minor.
• Preserve spec authority. The spec is the source of truth for intended behavior. If code contradicts spec and the user rejects the update, the code is wrong — not the spec.
• Don't rewrite what you didn't change. Only modify spec sections affected by the current drift. Leave everything else untouched.
• Link to decisions. When a spec update corresponds to a recorded decision, add the decision ID as an HTML comment: ``

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ash1794
• Source: ash1794/vibe-engineering
• License: MIT

Install and usage instructions live in the source repository linked above.