abi-spec

Specification compiler with content-addressed SpecPacks, requirements traceability, and spec-driven development with drift detection. Part of the Planning Pack (Layer 2).

Depends on abi-control-core for schema validation.

Install (after PyPI publication)

pip install abi-spec

Status: Not yet published to PyPI. Install from source: pip install -e . from the repo root. Requires abi-control-core.

Quick start

Compile a SpecPack from PRD JSON

from abi_spec.compiler import compile_prd_json_to_specpack

# Compile a PRD JSON file into a content-addressed SpecPack
result = compile_prd_json_to_specpack(
    prd_json_path="runs/latest/prd.json",
    out_dir="specs/feature_x/",
)
print(result["manifest_hash"])  # SHA-256 of the spec manifest
print(result["prd_hash"])       # SHA-256 of the input PRD

Spec-driven development with drift detection

from pathlib import Path
from abi_spec.sdd.spec_tracker import SpecTracker

# Initialize tracker (stores metadata in .abi/ by default)
tracker = SpecTracker(tracking_dir=Path(".abi"))

# Track a spec and link it to implementing code paths
tracker.track(spec_path="specs/auth.md", code_paths=["src/auth/"])

# Detect drift between spec and code (time-based + hash-based)
drift = tracker.detect_drift(spec_path="specs/auth.md", code_paths=["src/auth/"])
if drift.has_drift:
    print(drift.details)  # e.g., "Code updated without spec update — drift detected"

Requirements traceability

from abi_spec.traceability import generate_requirements_index

# Generate a traceability index from structured requirements
requirements = [
    {
        "id": "REQ-001",
        "title": "User Authentication",
        "text": "System shall authenticate users",
        "acceptance": ["Given valid token, When request, Then access granted"],
        "source_prd_section": "Security.Authentication",
    },
]
index = generate_requirements_index(requirements)
# Returns list of dicts with req_id, title, acceptance_criteria, source_prd_section

What's included

• SpecPack compiler -- compile PRD JSON into content-addressed, schema-validated specification packages
• Requirements traceability -- REQ-ID tracking with structured index generation
• Acceptance criteria parsing -- Given/When/Then extraction from structured requirements
• Spec-driven development -- SpecTracker with SHA-256 content hashing for drift detection
• Drift detection -- identify when specs and code are out of sync (time-based and hash-based)

ABI ecosystem

abi-spec is part of the Planning Pack (Layer 2), built on top of abi-control-core (Layer 1).

Related packages:

• abi-control-core -- contracts and audit trail SDK (Layer 1, required)
• abi-prd -- structured PRD generation (Layer 2)
• abi-evals -- eval runner for validating spec compliance

Versioning

Follows Semantic Versioning. Current version: 0.2.0. See CHANGELOG.md for release notes.

License

MIT License (see LICENSE file).