ZhangHanDong/agent-spec

What it solves

agent-spec is an "intent compiler" designed to bridge the gap between human requirements and AI-generated code. It prevents the common issue of AI agents "hallucinating" or drifting from original intent by transforming unstructured human requests (PRDs, issues, conversations) into verifiable, machine-readable Task Contracts. This ensures that AI implementations are mechanically verified against a strict set of criteria before they are accepted.

How it works

The project implements a compilation pipeline that moves from high-level intent to verified code:

1. Intake: Human intent is captured as structured requirements (the Intermediate Representation or IR).
2. Lowering: These requirements are converted into Task Contracts, which define the intent, technical decisions, boundaries (what can and cannot be changed), and completion criteria (BDD scenarios).
3. Implementation: AI agents implement the code based on these contracts.
4. Verification: A deterministic, model-free backend verifies the implementation using tools like cargo test, linting, and structural checks to ensure the code satisfies the contract.
5. Liveness Tracing: The system tracks whether requirements remain honored or are violated over time.

Who it’s for

It is primarily for developers and teams using AI agents (like Claude Code, Cursor, or Codex) to automate coding tasks who require strict governance, traceability, and mechanical verification of AI-generated changes.

Highlights

• Deterministic Verification: AI is used for drafting and coding, but the verification gates are model-free and deterministic.
• Task Contracts: A specialized DSL supporting English and Chinese for defining boundaries and BDD scenarios.
• Explicit Test Binding: Directly links specific BDD scenarios to actual test functions in the codebase.
• Agent Skills: Includes pre-built skills for authoring, estimation, and intent compilation for popular AI tools.
• Plan Generation: Generates self-contained prompts for AI agents that include the contract, codebase context, and a topologically sorted task sketch.