Copyright (c) 2026 Samuel Collins All rights reserved.
HCAC is a completion contract for agents and tools.
It defines when something is truly “done” — not just structurally, but behaviorally.
HCAC allows multiple runtimes, agents, or systems to agree on completion without reinterpretation.
HCAC exists to make completion:
- deterministic
- portable
- verifiable
- enforceable across tools and agents
It separates:
✔ structural validity
✔ semantic meaning
✔ execution behavior
HCAC is defined across three layers:
| Layer | File | Purpose |
|---|---|---|
| Schema | hcac.schema.json | JSON validity & minimum required structure |
| Structure | hcac.spec.json | Field inventory & intended meaning |
| Behavior | hcac.spec.md | Normative execution semantics |
The behavioral contract lives in:
hcac.spec.md
The JSON files define structure — not execution.
Runtimes MUST interpret hcac.spec.md to determine completion.
hcac.schema.json → validates shape
hcac.spec.json → explains fields
hcac.spec.md → defines behavior
README.md → orientation
Use HCAC when completion must be:
- machine-verifiable
- portable across systems
- enforced rather than inferred
- safe to hand off between agents
Typical use cases:
- agent task completion
- release readiness
- PR gating
- artifact validation
- multi-agent workflows
HCAC is not for:
- brainstorming
- exploratory work
- subjective evaluation
If "done" cannot be checked, HCAC should not be used.
Schema validation alone is insufficient.
A runtime MUST:
- evaluate hard constraints
- evaluate acceptance criteria
- execute or simulate checks
- produce a completion status
Completion is defined by behavior, not structure.
HCAC describes:
What must be true + What must be proven
Not:
What was intended
HCAC is a behavioral completion protocol.
The canonical definition of that behavior is:
hcac.spec.md
Other files support validation and machine readability.