# IntentSpec v1.2, condensed for agents

> A portable, evidence-backed format for AI agent intent. Carries both the contract (what the agent must do) and the judgment (the evidence behind it).

An IntentSpec can be JSON or Markdown, conventionally `intent.md` at the repo root. Markdown has two accepted serializations: fields in YAML frontmatter, or identity and scalars in frontmatter with list fields in recognized `##` sections. Validate the normalized object against https://intentspec.org/schema.json, not just the frontmatter. The normative, human-readable spec lives at https://intentspec.org/spec.

## Markdown normalization

- Parse YAML frontmatter first. Malformed frontmatter is a parse failure.
- Remove fenced code blocks and HTML comments before reading body sections.
- Frontmatter `objective` wins; `## Objective` is used only when frontmatter has none.
- `## Outcomes`, `## Constraints`, `## Edge Cases`, and `## Health Metrics` take precedence over the corresponding frontmatter array when they contain at least one list item.
- `## Verification` takes precedence when it yields at least one check. Flatten checks to an array of strings in document order, dropping grouping labels.
- Unrecognized sections are free-form context and do not contribute to the model. `id` and `status` still require frontmatter.

Full normalization rules: https://github.com/pathmodeio/intentspec/blob/main/SPEC.md#2-normalization

Evidence items may carry an `anchors` array. From the schema: Spec sections this evidence backs. Use 'objective', 'userGoal', 'outcome:N', 'edgeCase:N', 'constraint:N', or 'healthMetric:N'. Allowed values match `^(objective|userGoal|outcome:[0-9]+|edgeCase:[0-9]+|constraint:[0-9]+|healthMetric:[0-9]+)$`. An anchor must point at a section that exists in the spec (an `outcome:2` in a two-outcome spec is a broken reference); the browser validator and the GitHub Action both enforce this.

## Field reference

- `id` (string, required): Unique identifier for the intent specification.
- `status` ("draft" | "validated" | "approved" | "shipped" | "verified", required):
- `version` (integer, optional):
- `objective` (string, required): The core problem to solve and why it matters.
- `problemSeverity` ("low" | "medium" | "high" | "critical", optional): Priority or severity of the problem.
- `userGoal` (string, optional): The specific goal the user is trying to achieve.
- `outcomes` (array of string, required): Observable state changes indicating success.
- `healthMetrics` (array of string, optional): metrics that must not degrade.
- `verification` (array of string, optional): How the outcomes are confirmed — the fastest automated check, a manual fallback, and the observable signal once shipped. Added in v1.2.
- `scope` (object, optional): What the implementation may touch, and what it must leave alone. Added in v1.2.
  - `inScope` (array of string, optional):
  - `outOfScope` (array of string, optional):
- `constraints` (array of string, optional): Hard boundaries the agent must respect.
- `edgeCases` (array of object, optional):
  - `id` (string, optional):
  - `scenario` (string, required):
  - `expectedBehavior` (string, required):
- `evidence` (array of object, optional): Source observations that informed this spec — quotes, friction, observations, metrics, or requests. Optional. When present, each item can anchor to specific spec sections via the 'anchors' field.
  - `id` (string, optional): Stable identifier for cross-referencing (e.g., from a Pathmode workspace).
  - `type` ("friction" | "quote" | "observation" | "metric" | "request", required):
  - `source` (string, optional): Where this came from — ticket ID, replay ID, interview transcript, dashboard URL.
  - `excerpt` (string, required): The actual observation, quote, or measurement.
  - `anchors` (array of string, optional): Spec sections this evidence backs. Use 'objective', 'userGoal', 'outcome:N', 'edgeCase:N', 'constraint:N', or 'healthMetric:N'.
- `strategicAlignment` ("high" | "medium" | "low" | "deviation", optional):
- `alignmentNotes` (string, optional):
- `createdAt` (integer, optional):
- `updatedAt` (integer, optional):

## Example

```markdown
---
id: json-export
status: approved
userGoal: Export the rows I am looking at as JSON
objective: >-
  Analysts take filtered results into their own
  tools without filing a support ticket.
outcomes:
  - Export never contains rows outside the active filter.
  - The file never includes PII fields.
constraints:
  - Runs client-side. No new export endpoint.
edgeCases:
  - scenario: Empty dataset
    expectedBehavior: Show a toast, create no file.
verification:
  - Unit test asserts PII columns are stripped.
evidence:
  - type: friction
    source: support-ticket-4421
    excerpt: Analysts re-filter full exports by hand.
    anchors: ["outcome:0", "edgeCase:0"]
---
```

## Validation

- Browser: https://intentspec.org/#validate
- Standard: https://github.com/pathmodeio/intentspec
- CI: https://github.com/pathmodeio/validate-intentspec-action
- Local, including a six-check readiness verdict: `npx -y @pathmode/cli preflight`

More: https://intentspec.org/llms.txt