IntentSpec v1.0
The open standard for spec-driven development with AI coding agents.
Status of this document
This is the current published version of IntentSpec. Published 2026-05-13. This document is normative — the JSON Schema at /intentspec.schema.json is the machine-readable counterpart.
Where the two disagree, the JSON Schema is authoritative for syntactic validation; this prose document is authoritative for semantics and intent.
1. Abstract
IntentSpec defines a file format for capturing the intent of a software feature in a machine-validatable contract. An IntentSpec file describes what “done” looks like for a single feature: its objective, observable outcomes, hard constraints, edge cases, and health metrics that must not regress. AI coding agents and humans both read it.
The format is Markdown with a YAML frontmatter block. The frontmatter is the normative part and is validated against a published JSON Schema. The Markdown body below the frontmatter is free-form narrative context.
2. Conventions
The keywords MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.
“The schema” refers to the JSON Schema document at /intentspec.schema.json. “A consumer” is any tool that reads an IntentSpec file — for example an AI coding agent, a validator, or a visual editor.
3. File format
An IntentSpec file MUST be a UTF-8 encoded text file containing a YAML frontmatter block delimited by lines containing exactly ---. The frontmatter MUST appear at the very start of the file. Content after the closing --- is the Markdown body and is non-normative (see §5).
The conventional filename is intent.md. Consumers SHOULD recognize this filename without configuration. Consumers MAY accept other filenames such as *.intent.md or files configured by the host project.
A repository MAY contain multiple IntentSpec files. Each file MUST describe exactly one feature or unit of intent. A single file MUST NOT declare more than one IntentSpec.
--- id: "export-json" status: "draft" objective: "Allow users to export filtered data to JSON" outcomes: - "User clicks Export → JSON file downloads" ---
4. Field reference
Each subsection below documents one field of the frontmatter. Field names in YAML MUST match exactly (case-sensitive). Unknown fields MAY be ignored by consumers but SHOULD raise a warning during validation to catch typos.
id
stringREQUIREDUnique identifier for this IntentSpec within its repository.
The id MUST be a non-empty string. It MUST be unique within the repository. It SHOULD be a kebab-case slug (lowercase letters, digits, and hyphens) so it is safe to use in URLs, file paths, and command-line tooling.
Implementations MAY use a namespaced prefix (e.g. INT-EXPORT-JSON-001) for cataloging at scale. The schema does not currently constrain the format.
Once assigned, the id SHOULD NOT change. Renames break references from tickets, commit messages, and external systems.
status
enumREQUIREDLifecycle state of the IntentSpec.
The status MUST be one of:
draft— author is still shaping the spec; consumers MAY show a warningvalidated— passes schema validation and human reviewapproved— accepted for implementationshipped— feature has been implemented and deployedverified— outcomes confirmed in production
Transitions are not enforced by this specification. Tooling MAY impose its own state machine. The default value SHOULD be draft.
version
integerOPTIONALMonotonically increasing revision number for this IntentSpec.
The version SHOULD increment whenever a normative change is made to the outcomes, constraints, or edge cases. Default is 1. This is the version of the spec instance, not the version of the IntentSpec standard.
objective
stringOPTIONALThe core problem this feature solves and why it matters.
The objective SHOULD be a single sentence. It SHOULDexplain the user-facing outcome being enabled and the reason it's worth building. Implementation details belong in constraints, not objectives.
userGoal
stringOPTIONALThe specific goal the user is trying to achieve.
The userGoal is the job the user is trying to get done. Where objectiveis the team's framing of the work, userGoal is the user's framing. Both are OPTIONAL; teams MAY use one, the other, or both.
problemSeverity
enumOPTIONALHow urgent or impactful the underlying problem is.
One of: low, medium, high, critical. Used for prioritization.
outcomes
array of stringsREQUIREDObservable state changes that indicate the feature is done.
Each outcome MUST describe a state that is externally observable — by the user, by another system, or by an automated test. Outcomes MUST NOT describe implementation steps.
An IntentSpec MUSThave at least one outcome. The implementation is “done” when all outcomes are observably true.
outcomes: - "User clicks Export → JSON file downloads" - "Export contains only the currently filtered dataset" - "No PII fields are included in the output"
outcomes: - "Add a downloadJson() function in utils/" - "Wire up the button to onClick handler"
constraints
array of stringsOPTIONALHard boundaries the implementation must respect.
Constraints are non-negotiable rules. Examples: stack choices, performance budgets, security requirements, dependency restrictions. A consumer MUST treat each constraint as a hard limit, not a preference.
If a constraint cannot be met, the consumer SHOULD fail loudly rather than silently work around it.
edgeCases
array of objectsOPTIONALNon-happy-path scenarios and their expected behavior.
Each item in edgeCases MUST be an object with:
scenario(string, required) — the edge conditionexpectedBehavior(string, required) — what the system MUST do in that scenarioid(string, optional) — stable identifier for this edge case
edgeCases:
- scenario: "Empty dataset"
expectedBehavior: "Show toast 'Nothing to export' — no file created"
- scenario: "10k+ rows"
expectedBehavior: "Stream to file, show progress indicator"healthMetrics
array of stringsOPTIONALMetrics that must not degrade as a result of this change.
Health metrics name properties of the existing system that MUST be preserved. Examples: page load times, existing feature parity, accessibility benchmarks. They are guardrails, not goals.
strategicAlignment
enumOPTIONALHow well this work aligns with current strategic priorities.
One of high, medium, low, or deviation. Used by portfolio-level tooling to flag work that may be running counter to current direction. Optional and advisory.
alignmentNotes
stringOPTIONALFree-form note on why this work is aligned (or not).
Used to capture the “why” behind a non-trivial strategicAlignment value, especially when the value is deviation.
createdAt / updatedAt
integer (Unix milliseconds)OPTIONALCreation and last-modified timestamps.
Both fields are OPTIONAL. When present, they MUST be Unix epoch timestamps in milliseconds. Tooling SHOULD manage these automatically rather than requiring authors to set them by hand.
5. Markdown body
Content after the closing --- of the frontmatter is free-form Markdown. It is not validated by the schema. Authors MAY use it for narrative context, background research, evidence links, or verification notes.
A common pattern is to include sections named ## Evidence, ## Verification, or ## Background in the body. These are conventions, not part of v1.0. Future versions of this specification MAY promote some of these conventions to typed frontmatter fields.
6. Validation
A consumer that performs validation MUST validate the frontmatter against the published JSON Schema at /intentspec.schema.json. The reference implementation is the validate-intentspec-action GitHub Action.
Validation failure MUST identify the offending field and the rule that was violated. Validators SHOULD report all errors rather than stopping at the first.
7. Conformance
An IntentSpec file is conformant to v1.0 if and only if:
- It validates against the published JSON Schema, and
- It contains at least one outcome, and
- The
edgeCasesentries (if present) each include bothscenarioandexpectedBehavior.
A consumer is conformant to v1.0 if it:
- Reads the frontmatter without modifying it, and
- Treats unknown fields as non-fatal (forward compatibility), and
- Reports validation errors against the published schema when in validation mode.
8. Versioning policy
This specification follows semantic versioning. The current version is v1.0.
- Patch (v1.0.x): editorial corrections, clarifications. Conforming files and consumers remain conformant.
- Minor (v1.x): additive changes — new optional fields, new enum values. Existing conforming files remain conformant.
- Major (v2): breaking changes — renamed fields, removed fields, changed required-set. Consumers MUST declare which major versions they support.
The schema's $id URL is stable for a given major version. Breaking changes ship at a new URL.
9. Changelog
- v1.0 — 2026-05-13
- Initial published version.