This release refines the knowledge layer with a new document type and cleaner type boundaries.
Improvements
- New
specdocument type — captures the canonical normative contract for a concrete system, component, interface, schema, or protocol. Defines externally observable behavior, constraints, invariants, and conformance requirements - More balanced
docdescription — now explicitly focused on non-behavioral reference material: registries, glossaries, lookup tables, component lists - Removed unused
projecttype — usedocinstead for project-level reference material
Meet spec — contracts your agents can enforce
Use spec when you need a single source of truth for how a system boundary works. If implementation differs from the spec, the spec wins until it’s amended.
When to use it:
- Defining an API contract — endpoints, schemas, error codes, rate limits
- Formalizing a protocol — message formats, state machines, delivery guarantees
- Locking down a schema — required fields, valid values, validation rules
Quick test: “Does this document define a normative contract for a specific technical boundary?” If yes — it’s a spec.
Example — creating a webhook delivery spec:
archcore mcp# Then ask your agent:# "Create a spec for our webhook delivery contract"Your agent creates .archcore/webhook-delivery.spec.md with a structured template covering purpose, scope, contract surface, normative behavior, constraints, and conformance criteria. From that point on, any agent working on webhook code sees exactly what correct behavior looks like.
spec vs other types:
| If the content… | Use |
|---|---|
| Defines how a component must behave | spec |
| Lists what exists (registries, glossaries) | doc |
| Sets a team practice (“always do X”) | rule |
| Records why a choice was made | adr |