Summary

agent-spec provides an AI-native framework for Behavior-Driven Development (BDD) and specification verification, specifically targeting task execution by AI agents. It bridges the gap between human-defined contracts and machine-verified code satisfaction, enabling precise alignment between intent and implementation for developers and AI agents.

How It Works

The core is the "Task Contract" DSL, a structured specification comprising Intent (purpose), Decisions (fixed technical choices), Boundaries (change constraints), and Completion Criteria (BDD scenarios). This DSL, supporting English and Chinese, allows AI agents to implement tasks and verifiers to deterministically check code against these explicit contracts, ensuring adherence to defined requirements.

Quick Start & Requirements

• Install: ./install-skills.sh installs the CLI via cargo install and copies AI agent skills. Manual installation or symlinking of skills is also supported.
• Prerequisites: Rust/Cargo for CLI installation.
• Docs: Examples are available in the examples/ directory.

Highlighted Details

• AI Agent Skills: Ships three skills (agent-spec-tool-first, agent-spec-authoring, agent-spec-estimate) to guide AI agents in task execution, contract authoring, and effort estimation.
• Multi-language DSL: Supports both English and Chinese for task contract definitions.
• Explicit Test Binding: Allows scenarios to declare specific test selectors for precise verification targeting.
• Boundary Enforcement: Mechanically enforces path-based constraints against code change sets.
• AI Verifier Skeleton: Features a pluggable AI verification backend, currently in stub mode, providing structured AI evidence and preparing for future model integration.
• Contract Acceptance: Replaces traditional code reviews with a process focused on contract correctness and verification outcomes.

Maintenance & Community

The project emphasizes a self-bootstrapping development model where contributions adhere to the contract-driven workflow. Specific community channels (e.g., Discord, Slack) are not detailed in the README.

Licensing & Compatibility

The project's license is not explicitly stated in the provided README, which requires further investigation for adoption decisions.

Limitations & Caveats

The AI verifier is currently a stub, lacking integration with real AI models. The stamp command is limited to a --dry-run mode. Boundary enforcement relies on explicit path constraints or VCS-backed change discovery.