Put product intent
before the proposal.
OpenSpec structures the change. Pathmode carries the product judgment into it: who is affected, what observably changes, what evidence supports it, and how you will know it worked.
Pathmode is an independent integration designed to work with OpenSpec, enabled by OpenSpec's open format and documented customization mechanism.
$ npx -y @pathmode/cli preflight openspec/changes/<change-id>
Read OpenSpec change at openspec/changes/add-export-filters
✓ goal
? objective read: "Analysts re-filter the weekly export by hand every Monday…"
✓ outcomes
· constraints nothing found
· edge cases nothing found
✓ verification
Nothing was written. A "?" means your text was read but not confirmed,
which is often the check's vocabulary rather than your writing.
Two ways in
One works on the changes you already have and touches nothing. The other starts your next change from the product judgment.
Use an existing change, unchanged
The preflight reads a change folder exactly as it is and grades six product dimensions. Where it cannot confirm something, it quotes your own text back and asks, rather than declaring it absent.
npx -y @pathmode/cli preflight openspec/changes/<change-id>- Read-only: writes nothing anywhere, in openspec/ or outside it
- Local and free, no account, nothing sent anywhere
- Four verdict states: pass, unconfirmed, absent, not applicable
Start your next change from intent
The experimental pathmode-intent schema adds one artifact ahead of the proposal. Unlike the preflight, it does write a file: intent.md, inside the change directory, which is the point of it.
openspec new change my-change --schema pathmode-intent
openspec status --change my-change # proposal shows "blocked by: product-intent"- The proposal is blocked until the product intent exists
- Preserves OpenSpec’s built-in templates and guidance, adding only the product-intent dependency and a proposal pointer
- Everything from the proposal onward behaves as it does upstream
How the workflow connects
Private evidence and authenticated provenance live in Pathmode. The OpenSpec change carries repo-safe intent and references. They meet at intent.md.
OpenSpec owns the change. Proposals, spec deltas, design notes, and checkable tasks, kept current as work ships. Its verify command is real and useful: it validates that the implementation matches the change artifacts, and it is optional and advisory, surfacing issues without blocking the archive.
Pathmode owns the judgment record. Which evidence justified the change, who confirmed each product call, and whether that confirmation survived later edits. The preflight asks before the build whether the change itself was justified; verify checks after the build whether the code matches the agreement. Different moments, different questions.
What belongs in git
intent.md is committed to your repository. Everyone who clones it can read it, and git keeps it after you delete the line. So the split matters.
In the change folder
- The intent: objective, outcomes, constraints, edge cases, verification
- Evidence references: a ticket id, a dashboard name, a link
- Claims without evidence, labelled as assumptions
- Confirmations you choose to record in the file
In Pathmode, never in git
- Raw customer quotes, names, and support transcripts
- Internal metrics and confidential context
- The evidence items your references point at
- Authenticated attribution: who actually confirmed what, verifiably
This rule is written into the schema's own instruction text, not just this page: a requirement can be traceable without its source material being published to everyone who clones the repo.
Compatibility and independence
The schema is experimental, the same label OpenSpec gives its own schema tooling, and both pieces are pinned to and tested against OpenSpec 1.11.0. The compatibility test ships in the repository so the fidelity claims can be checked rather than trusted.
Pathmode is not affiliated with or endorsed by the OpenSpec maintainers. OpenSpec's community schema catalog already extends the workflow toward product-first planning in its own right; this schema is not listed there.
One more thing, because it shaped how the preflight speaks: we tested our own gate against public OpenSpec changes before writing anything about them, found a blind spot of ours, and rebuilt the verdict around four states so it asks instead of accusing. Findings about other people's repositories stay unpublished.
Set up the schema
1. Copy the bundle into your project
git clone --depth 1 https://github.com/pathmodeio/pathmode-intent /tmp/pathmode-intent
mkdir -p openspec/schemas/pathmode-intent
cp -R /tmp/pathmode-intent/schema.yaml /tmp/pathmode-intent/templates openspec/schemas/pathmode-intent/2. Create a change with it
openspec new change my-change --schema pathmode-intent
openspec status --change my-change # proposal shows "blocked by: product-intent"3. Grade the intent before anyone proposes how to build it
npx -y @pathmode/cli preflight openspec/changes/<change-id>Full install notes, the template, and the compatibility test live in the repository.
Questions teams ask
Does Pathmode replace OpenSpec?
No. They answer different questions. OpenSpec records the agreed change and its optional, advisory verify command checks that the implementation matches those artifacts. Pathmode asks whether the change was justified: what evidence, who confirmed it, and whether that confirmation is still live. Teams that use both keep OpenSpec as the change workflow and Pathmode as the judgment record.
How is the preflight different from OpenSpec verify?
They run at different moments and check different things. OpenSpec verify is real and useful: it validates that the implementation matches your change artifacts, and it is optional and advisory, so it surfaces issues without blocking the archive. The preflight runs before the build and asks whether the change itself was justified, quoting your own text back where it needs confirmation.
What is the pathmode-intent schema?
An experimental custom schema for OpenSpec, built on its documented customization mechanism, that adds one artifact ahead of the proposal: intent.md, the product judgment behind the change. It preserves OpenSpec's built-in templates and guidance, adding only the product-intent dependency and a pointer from the proposal to intent.md, so proposals, spec deltas, design, and tasks behave as they do upstream. It is pinned to the OpenSpec version it was tested against. It is optional: the preflight reads unchanged OpenSpec changes without it.
What does Pathmode record that the OpenSpec format does not?
The private evidence record and its provenance. A change-local intent.md can carry evidence references and quote-anchored confirmations that go stale when the text they vouch for changes, and that is real and useful. What a file in a repository cannot do is hold raw customer evidence safely, anchor a claim to the actual evidence item behind it, or vouch for who wrote a confirmation. Authenticated attribution and the evidence itself stay in Pathmode; the file carries summaries and references.
Using OpenSpec? Add product intent before the proposal.
The preflight reads a change you already have, unchanged. The experimental schema makes intent.md the first artifact of your next one.
Try the OpenSpec integration