Metadata-Version: 2.4
Name: intentspec
Version: 0.3.0
Summary: Coverage and enforcement layer for AI agent infrastructure
Author-email: oni <oni@intentspec.dev>
License: MIT
Project-URL: Homepage, https://github.com/onicarps/intentspec
Project-URL: Documentation, https://intentspec.dev
Project-URL: Repository, https://github.com/onicarps/intentspec
Project-URL: Bug Tracker, https://github.com/onicarps/intentspec/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: click<9.0,>=8.0
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: jsonschema<5.0,>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mkdocs>=1.6; extra == "dev"
Requires-Dist: mkdocs-material>=9.0; extra == "dev"
Requires-Dist: pip-audit>=2.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: pip-tools>=7.0; extra == "dev"

# 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](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

```bash
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

| Feature | Command | Description |
|---------|---------|-------------|
| **Validate** | `validate` | Schema + semantic validation of intent.yaml |
| **Score** | `score` | Intent Debt Score (IDS 0-100) with 7 weighted components |
| **Coverage** | `coverage` | Structural coverage analysis against source text |
| **Diff** | `diff` | Git-integrated intent change tracking between commits |
| **Lint** | `lint` | Quality checks (goal length, tool rationale, duplicates, etc.) |
| **CI** | `ci` | Unified hook: validate + lint + score + coverage in one pass |
| **Audit** | `audit-report` | SOC 2 / EU AI Act compliance report with SHA-256 hash |
| **Convert** | `init --from` | Import from AGENTS.md, SKILL.md, agentskills, CrewAI, LangGraph, AutoGen, OpenAI Agents |
| **Templates** | `init --template` | 5 built-in agent templates |
| **Health** | `health` | Terminal dashboard — coverage, IDS, stale/orphaned specs |
| **Drift** | `drift` | Detect stale intents (source file age vs last commit) |
| **Dashboard** | `dashboard --serve` | Web dashboard for coverage trends and IDS scores |

### 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

```bash
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
