Context Sync

Keeps .context/ files in sync with the actual codebase. Prevents context drift — the #1 failure mode of spec-driven development.

When to Use This Skill

• After installing or removing a dependency

• After creating new files or directories

• After completing a feature spec

• When starting a new session (validation mode)

Sync Rules

Dependency Changes → stack.md

When a dependency is added, removed, or upgraded:

• Read .context/stack.md

• Check if the change is already reflected

• If not, propose an update with: package name, purpose, version, and constraints

Trigger signals:

• npm install , pip install , dotnet add , go get commands

• Changes to package.json , requirements.txt , *.csproj , go.mod

New Files/Directories → architecture.md

When new files or directories are created outside the existing structure:

• Read .context/architecture.md

• Check if the new path fits an existing module

• If not, propose adding it to the directory structure section

Trigger signals:

• mkdir commands

• Creating files in previously empty directories

• Adding new top-level directories

Feature Completion → project.md

When a spec status changes to [x] Completed :

• Read .context/project.md

• Update the "Current Status" section to reflect the new capability

• Suggest moving the spec to .context/specs/.archive/

Conventions Changes → conventions.md

When the team agrees on a new pattern during development:

• Read .context/conventions.md

• Propose adding the new convention with rationale

• Ensure it doesn't conflict with existing conventions

Validation Mode

When activated at session start, perform a quick audit:

SYNC CHECK: ✅ stack.md — matches package.json (last verified: {timestamp}) ✅ architecture — all src/ modules documented ⚠️ project.md — 2 completed specs not yet reflected ❌ conventions — new pattern "useQuery hooks" found but not documented

Output Format

Always present sync suggestions as a clear diff:

Suggested Update: stack.md

Trigger: npm install @tanstack/react-query

Apply this update? [Y/N]

Integration

This skill is designed to fire automatically after other skills complete. Skills that should trigger a sync check:

• spec-lifecycle (on status change)

• architecture-guard (on new file creation)

• commit-conventions (on commit — optional)