requirements.md
New in OpalSpec
Introducing features:opal:intent
Every feature starts as a sentence. "We should add payment".
You can't build that — not only because it's big, but because it's undefined: decisions nobody has made, assumptions nobody has checked, no sense of what comes first.
/opal:intent is where that sentence becomes work. You and the agent narrow it in conversation, one question at a time, until what you're building is clear from a product and tech perspective and what's still undecided is named out loud.
Then every spec that follows inherits and is guided by it.
The problem
Ideas arriveundefined.
Before features, you had two costly options: write one enormous spec and discover the gaps during the build, or hold it all in your head and re-explain the same background to the agent every session.
With opal:intent you talk it through with the agent until what you're building is clear, and anything you can't settle becomes an open question. Out of that comes a product intent (intent.md) — what you're building and what's true when it's done. The agent then reads your codebase to answer what it can, and your decisions become a technical approach (approach.md) — the direction and the constraints every spec is built under. Then it proposes a sequenced list of specs, each saying what gets built, why it matters, and how you'll know it works. You build them one at a time, each starting with everything you already decided.
The feature layer
Each step adds definition. Every one is optional, and every one can be re-entered. `/opal:intent` is the first rung — product intent and outcomes, not acceptance criteria.
01
Intent
/opal:intent — What and why
A conversation, one question at a time, at product level. It ends when the shape is clear, not when everything is answered — whatever is left is tagged with what would settle it.
Outputintent.md — outcomes, scope, the vocabulary the feature uses, and the open questions, each tagged needs: research, needs: decision or needs: spike.
02
Research
/opal:research — How
The agent reads your codebase before it asks you anything, then recommends with the evidence underneath: the file, the existing pattern, the constraint it found. You decide.
Outputapproach.md — the direction, the constraints every spec is built under, and what was ruled out, so it does not come back around in three months.
03
Breakdown
In what order
No command — offered at the end of 01 or 02
The agent proposes the whole slicing at once and you cut it up: merge, split, reorder. Every slice has to compile, ship and prove itself without the next one existing.
Outputplanned specs in intent.md — each with what gets built, how you'll know it works, and what it's waiting on.
Into the spec workflow
04
Spec
/opal:new — The work itself
Now precision is affordable. You write acceptance criteria and edge cases for one slice, and only get asked what is genuinely local to it.
Outputrequirements.md — with its Why, vocabulary and constraints already inherited from above.
One feature, many specs — built in order
design.md
feature.md
stripe-foundation
Built
requirements.md
design.md
tasks.md
invoice-api
In progress
requirements.md
design.md
tasks.md
invoice-ui
Planning
requirements.md
billing-admin
Planning
Open questions
Honest aboutwhat ismissing.
An intent is allowed to be incomplete. That is what makes it resumable — and what tells the rest of the workflow how ready you are.
intent.md — Open Questions
- [ ] Does the ledger support idempotency keys? — needs: research
- [ ] How do partial refunds work? — needs: decision
- [ ] Will the job runner handle nightly volume? — needs: spike
- [x] Currency rounding rule — resolved: banker's rounding (2026-09-04)needs: research
An agent can investigate and answer it
/opal:research
needs: decision
A call only you can make
You, in /opal:intent
needs: spike
Only code will tell you
A throwaway or POC spec
Why it changes agent work
One truth,inherited.
Without a feature, every spec re-derives the same background. Why are we doing this? What did we decide three specs ago? Which words mean what?
With `/opal:intent`, that context lives in `intent.md`. Requirements get their Why from the feature. Askme mode stops re-asking what you already settled. Scope boundaries are written down, not remembered.
Spec #6, written three weeks later in a different session, starts with the same vocabulary as spec #1 — without anyone remembering to say so.
What you gain
01
Definition before precision
Capture the why, outcomes, and vocabulary before acceptance criteria. The distance between a rough idea and a buildable spec is real work — intent is where that work happens.
02
Incomplete is allowed
Open questions tagged needs: research, needs: decision, or needs: spike let an intent converge honestly. You know exactly what would unblock it.
03
Context every spec inherits
Intent, scope, and decisions live in one place. Every spec beneath the feature reads them — so spec #6 in a later session starts with the same vocabulary as spec #1.
04
Resumable by design
Stop halfway, switch tasks, come back next week. The open questions block is the state machine — no re-explaining the same background to a fresh agent session.
05
Gaps surface early
Research gets a precise queue. Decisions waiting on you are visible. External blockers like vendor agreements get named before they quietly stall the sequence.
06
Entirely optional
Never run /opal:intent and nothing changes. Single-spec work stays on /opal:new. The feature layer is invisible until you use it.
The reassurance
Never run it andnothing changes.
Most changes fit in one spec. Use `/opal:new` directly and OpalSpec behaves exactly as before. Your specs stay in `.opal/specs/`. No migration. No new ceremony.
The feature layer is invisible until you use it. When the work needs several specs that share intent and architecture, `/opal:intent` is where you start — one conversation at a time, resumable whenever you need it.