IntentSpec

Coverage and enforcement layer for AI agent infrastructure.

Status (June 26 2026): Phase 2 complete · PyPI 0.3.0 (pre-1.0) · Phase 3 (beta) next — see STATUS.md

IntentSpec transforms agent development from ad-hoc documentation to versioned, testable, and enforceable intent. Document agent behavior as code, measure intent coverage, score intent debt, and enforce intent through CI/CD.

Works with any agent spec format — AGENTS.md, SKILL.md, agentskills, or CrewAI. Convert existing specs to a standardized intent.yaml, then validate, score, diff, lint, and enforce it in CI/CD.

Quickstart

pip install intentspec

# Create a new spec interactively
intentspec init --quickstart

# Or convert an existing AGENTS.md
intentspec init --from AGENTS.md ./AGENTS.md

# Validate and score
intentspec validate
intentspec score

# Run all checks for CI/CD
intentspec ci --min-coverage 80

Features

New: Source Resolution

IntentSpec now resolves original agent source files (AGENTS.md, SKILL.md, framework configs) for any intent.yaml:

• # Source: header provenance (written by intentspec init)
• Sibling filename matching (AGENTS.md, SKILL.md, crewai.yaml, etc.)
• Orphaned spec detection (health and drift report specs with no source)

Installation

pip install intentspec   # 0.3.0

Requires Python 3.11+.

Why IntentSpec?

AI agents are defined by scattered markdown files, README comments, and tribal knowledge. IntentSpec makes that explicit and measurable:

1. Document — Define agent intent in a structured intent.yaml
2. Convert — Import existing AGENTS.md / SKILL.md / CrewAI specs
3. Validate — Schema + semantic checks catch misconfigurations
4. Score — Intent Debt Score (0-100) measures spec quality
5. Coverage — Compare intent against actual source text
6. Enforce — CI/CD integration fails builds when intent is missing or broken
7. Audit — Generate compliance reports for SOC 2 / EU AI Act

License

MIT