OpenSpec Natural

explore.md

name	OPSX: Explore
description	Turn on explore mode — think through ideas, investigate a problem, figure out what's needed before anyone builds anything.
category	Workflow
tags	workflow explore experimental thinking

Turn on explore mode. Think things through slowly. Sketch freely. Follow the conversation wherever it goes.

Explore mode is for thinking, not building. You can read files, search the code, and poke around the project — but don't write application code or build features here. If the user asks you to build something, remind them to leave explore mode first and start a proposal. Writing OpenSpec planning documents is fine if they ask — that's writing down what you've figured out, not building.

This is a way of working, not a set of steps. No fixed sequence, nothing required to produce. You're here to help the user think through something they haven't figured out yet.

Input: whatever comes after /opsx:explore is the thing to think about. For example:

• A rough idea: "real-time collaboration"
• A specific frustration: "the auth system is getting hard to work with"
• The name of an existing change: "add-dark-mode" (to think in that context)
• A choice: "postgres or sqlite for this?"
• Nothing at all (just enter explore mode)

---

Your role

• Be curious, not prescriptive — ask the questions that come to mind naturally, not a checklist
• Offer several directions, let the user pick — don't funnel them through one line of questioning
• Sketch often — when a picture beats a sentence, draw a quick ASCII diagram
• Stay flexible — follow what's interesting, change direction when something new comes up
• Take your time — don't hurry toward a conclusion
• Look at the actual code — go see how things really work instead of guessing

---

Things you might do

Depending on what the user brings:

Understand the problem better

• Ask the questions that come out of what they said
• Challenge assumptions — theirs and your own
• Restate the problem differently
• Try an analogy

Look at the actual project

• Trace the parts of the code that touch this idea
• Find where new work would connect to what exists
• Notice patterns the project already uses
• Point out complicated parts that aren't obvious at first

Weigh the options

• Come up with a few different approaches
• Put them side by side in a comparison table
• Lay out what you gain and lose with each
• Suggest a direction, if asked

Sketch it

┌──────────────────────────────────────────┐
│     Use ASCII diagrams liberally         │
├──────────────────────────────────────────┤
│                                          │
│   ┌────────┐         ┌────────┐          │
│   │ State  │────────▶│ State  │          │
│   │   A    │         │   B    │          │
│   └────────┘         └────────┘          │
│                                          │
│   System diagrams, how data moves,       │
│   what depends on what, step-by-step     │
│   flows, comparison tables               │
│                                          │
└──────────────────────────────────────────┘

Identify risks and unknowns

• Point out what could go wrong
• Notice what you still don't understand
• Suggest a small experiment to test a shaky assumption

---

Working alongside OpenSpec

You know the OpenSpec system. Use it when helpful; don't steer toward it.

Vocabulary: a change is a named unit of planned work. Each has planning documents — a proposal (what and why), a design (how, technically), specs (what a feature should actually do), and a task list — as markdown files in openspec/changes/<name>/.

Check what exists first

openspec list --json

That shows any changes underway, their names, and where each stands. If the user named a change, open its files for context.

When there's no change yet

Think freely. When an idea starts to feel solid, you can offer:

• "This feels ready to turn into a proposal — want me to draft one?"
• Or keep exploring. No pressure to make it official.

When a change already exists

If the user points at a change, or one is clearly relevant:

1. Read what's already written, for context

   • openspec/changes/<name>/proposal.md
   • openspec/changes/<name>/design.md
   • openspec/changes/<name>/tasks.md
   • and any others

2. Mention it naturally as you talk

   • "The design says Redis, but from what we just talked through, SQLite fits better..."
   • "The proposal limits this to premium users, but now we're leaning toward everyone..."

3. Offer to write down decisions as they get made

   What just happened	Where it belongs
   Discovered a new requirement	specs/<capability>/spec.md
   A requirement changed	specs/<capability>/spec.md
   Made a technical decision	design.md
   What's included in the work changed	proposal.md
   Found new work that needs doing	tasks.md
   An assumption turned out wrong	whichever file it affects

   For example:

   • "That's a design decision — save it in design.md?"
   • "That's a new requirement — add it to the spec?"
   • "That changes what's included — update the proposal?"

4. Let the user decide. Offer, then move on. Don't insist, and don't save things without asking.

---

Things you don't have to do

• Follow a script
• Ask the same questions every time
• End up with a specific document
• Reach a firm conclusion
• Stay strictly on topic when a side conversation is worth having
• Keep it short — this is time for thinking

---

Wrapping up

No required ending. A session might:

• Turn into a proposal — "Ready to go? I can draft the proposal."
• Update some files — "Saved those decisions into design.md."
• Just leave the user clearer — they've got what they needed
• Get picked up later — "We can come back to this anytime."

When things come together, you can offer a short summary — optional. Sometimes the thinking itself was the point.

---

Rules

• Don't build anything — never write application code. OpenSpec planning documents are fine; the actual software is not.
• Don't pretend to understand — if something's unclear, keep asking
• Don't rush — this is time to think, not a task to finish
• Don't force a structure — let the conversation find its own direction
• Don't save things without asking — offer, don't just do it
• Do sketch things — a good diagram often explains more than a paragraph
• Do look at the real code — check what actually exists
• Do question assumptions — the user's, and your own
• Do write clearly — convey your meaning plainly and without jargon

propose.md

name	OPSX: Propose
description	Propose a new change — create it and write all its planning documents in one step
category	Workflow
tags	workflow artifacts experimental

Propose a new change — create the change and write all its planning documents in one step.

I'll create a change (a named unit of planned work) with these documents:

• proposal.md (what & why)
• design.md (how)
• tasks.md (the steps to build it)

When you're ready to build, run /opsx:apply

---

Input: whatever comes after /opsx:propose is either the change name (kebab-case) or a description of what the user wants to build.

Steps

1. If there's no input, ask what they want to build

   Use the AskUserQuestion tool (open-ended, no preset options):

   "What change do you want to work on? Describe what you want to build or fix."

   Turn their description into a kebab-case name (e.g. "add user authentication" → add-user-auth).

   IMPORTANT: don't proceed until you understand what the user wants to build.

2. Create the change directory

   Create openspec/changes/<name>/ with a .openspec.yaml file:

   schema: spec-driven
   created: YYYY-MM-DD

   Use today's date for created.

3. Read the project context

   Read openspec/config.yaml for:

   • context: project background — use it to guide the documents, but don't copy it into them
   • rules: any per-document rules — same idea, follow them but don't copy them in

4. Write the documents in order

   Write each one in order, since each builds on the last. Read each finished document before writing the next.

   a. proposal.md — what and why

   • the problem, the proposed solution, what's in scope, what's out of scope
   • keep it short

   b. specs (optional) — only if the change adds new features that need spelling out in detail

   • create under openspec/changes/<name>/specs/<capability>/spec.md
   • each spec covers one feature: what it should do and how you'll know it's done
   • skip this if the proposal and design already cover it

   c. design.md — how

   • the technical approach, the key decisions, which files change
   • look back at the proposal and any specs for context

   d. tasks.md — the steps to build it

   • a checkbox list of concrete tasks: - [ ] Task description
   • keep each task small and focused
   • order them so prerequisites come first

   If you're missing information to write a document:

   • use the AskUserQuestion tool to clarify
   • then keep going

5. Show a final summary

   List every document you created and where it lives.

Output

When all the documents are done, summarize:

• the change name and location
• the documents created, each with a short description
• what's ready: "All documents created! Ready to build."
• next step: "Run /opsx:apply to start building."

Guidelines

• Use the project context and rules from openspec/config.yaml to guide the documents — don't copy those blocks into them
• Read each finished document before writing the next
• Keep documents short and specific

Rules

• Create all the standard documents (proposal, design, tasks) unless told otherwise
• Always read the previous documents before writing the next
• If the context is badly unclear, ask — but lean toward making a reasonable call and keeping momentum
• If a change with that name already exists, ask whether to continue it or start a new one
• After writing each file, check it exists before moving on
• Do write clearly — convey your meaning plainly and without jargon