What is a spec?
A Design Spec is a 24-section implementation specification comprehensive enough that a coding agent can implement a feature without ambiguity. A Change Spec is a delta-oriented specification layered on top of a promoted Design Spec — it captures what is being added, modified, replaced, or removed against a stable baseline.
Both shapes are defined by JSON Schema contracts. The same files back the platform UI, the get_spec_schema MCP tool, and any external tooling that wants to validate or generate specs.
Using the spec formats
Authored in PMCollab (recommended)
The platform's authoring tools — chat-driven exploration, multi-agent review, change-spec drafting, readiness evaluation — create and manage these specs end to end. Specs link to the use cases, capabilities, and code scans they describe, and stay in sync as the product evolves.
Authored manually
The schemas are open contracts. Anyone can hand-author a spec markdown file (or generate one with their own tooling) and validate it against the JSON Schema using any compliant validator. Useful for templating, external pipelines, or migrating an existing backlog into the format.
Have a question?
The FAQ covers when to pick Design vs. Change, how the 24 sections map across both, the status lifecycle, and how to validate a spec against the schema with Ajv.