spec-lock

Files (1)

• SKILL.md

SKILL.md (first lines)

# Spec-Lock: Documentation Synchronization

## Overview

Spec-Lock prevents documentation rot by maintaining bi-directional sync between code and specifications. It treats documentation as executable code that must stay synchronized with implementation.

## The Problem It Solves

**Documentation Rot**: In agentic workflows, code evolves faster than docs. Users hate writing documentation, and agents frequently ignore old instructions.

**Spec-Lock Solution**: Automatic synchronization that detects drift and keeps context perfectly synced with reality.

## How It Works

### 1. Post-Edit Analysis (PostToolUse Hook)
Every time a file is edited:
- Analyzes semantic intent of the change
- Compares against CLAUDE.md and SPEC.md
- Detects drift between code and docs

### 2. Conflict Detection
Two scenarios trigger sync:

**Scenario A: Code Drift**
- Code violates the spec (e.g., wrong auth method)
- Plugin asks: "Revert code or update spec?"

**Scenario B: Spec Evolution**
- Code introduces new logic not in spec
- Plugin asks: "Update SPEC.md to match code?"

### 3. Auto-Update
Uses headless Claude to:
- Generate documentation patches
- Update dependent docs automatically
- Maintain knowledge graph of dependencies

## When to Use

Activate Spec-Lock when:
- Changing API endpoints or parameters
- Modifying authentication flows
- Updating database schemas
- Changing configuration values
- Implementing new features
- Refactoring existing code

## Usage

### Automatic Mode
With PostToolUse hooks:
```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit(*)|Write(*)",
        "command": "python3 /a0/usr/plugins/spec-lock/spec-lock.py --check"
      }
    ]
  }
}
```

### Manual Commands
```bash
# Check a file for drift
python3 /a0/usr/plugins/spec-lock/spec-lock.py --check <file>

# Register a new dependency
python3 /a0/usr/plugins/spec-lock/spec-lock.py --register <code> <spec> [priority]

# Show sync status
python3 /a0/usr/plugins/spec-lock/spec-lock.py --status

# Force full sync
python3 /a0/usr/plugins/spec-lock/spec-lock.py --sync
```

## Configuration

### Priority Rules
Create `/a0/usr/plugins/spec-lock/spec-priorities.yaml`:

```yaml
files:
  "src/auth/**":
    spec_source: "AUTH_SPEC.md"
    priority: code  # Code wins (security)
  
  "docs/api/**":
    spec_source: "API_SPEC.md"
    priority: spec  # Spec wins (contracts)
  
  "src/models/**":
    spec_source: "DATA_MODEL.md"
    priority: ask   # Always ask user
```

**Priority Options:**
- `code`: Implementation is source of truth
- `spec`: Documentation is source of truth
- `ask`: Prompt user for decision

## Drift Detection

Spec-Lock detects these drift types:

### Function Signature Mismatch
```javascript
// Code has:
function createUser(name, email, role)

// Spec says:
function createUser(name, email)
// DRIFT: 'role' parameter not documented
```

### API Endpoint Changes

From aegntic/cldcde, MIT.

More from aegntic/cldcde