Replace Plan Mode with OpenSpec in Cursor and Claude Code

TL;DR

• Built-in Plan Mode (Cursor’s Shift+Tab mode, Claude Code’s --permission-mode plan) is good at one thing: delaying code edits until you approve a markdown plan.
• OpenSpec replaces that default with a repo-native planning loop that survives chat resets, supports team review in git, and separates thinking from committing more explicitly than a single plan.md file.
• The replacement mapping is simple:

Plan Mode "research + plan"     ->  /opsx:explore
Plan Mode "approved plan file"  ->  /opsx:propose  (proposal + specs + design + tasks)
Plan Mode "Build"               ->  /opsx:apply
Plan archive / team memory      ->  /opsx:archive   (+ merged specs in openspec/specs/)

• OpenSpec feels lighter because the default core profile is five chat commands and one openspec init — not a heavyweight SDD ceremony.
• The reason explore stays agnostic is not magic. It is written into the skill and command files: no code, no change folder, no forced conclusion, offer capture instead of auto-capture.
• My recommendation: treat OpenSpec as your default planning layer in Cursor or Claude Code. Keep native Plan Mode for quick one-off tasks where you do not need durable specs — not as your primary product-planning system.

What You Will Learn Here

• What Plan Mode actually does in Cursor and Claude Code, and where durable plans break down
• Why OpenSpec is a credible full replacement, not just an add-on
• How /opsx:explore, /opsx:propose, and /opsx:apply map to familiar planning phases
• How OpenSpec skills and commands are written to prevent unwanted changes during exploration
• A practical setup path for engineers and non-engineers on the same team
• When I would still use native Plan Mode instead

On July 6, 2026, I reviewed Cursor’s Plan Mode docs, Anthropic’s Claude Code common-workflows guidance, the Fission-AI/OpenSpec repository (including the explore guide and OPSX workflow docs), and the OpenSpec skills/commands installed in this repo under .cursor/skills/ and .cursor/commands/. Product behavior and guardrail wording below are source-backed where cited. The “replace Plan Mode by default” recommendation is my editorial judgment for teams that already use git-backed collaboration.

For hands-on OpenSpec setup, see How to Get Started with OpenSpec. For the full delivery loop including PRs and archive timing, see OpenSpec Across the Full Development Workflow.

The Problem with Plan Mode as Your Only Planning Layer

Plan Mode solves a real problem: eager agents write code before humans agree on intent.

Cursor’s docs describe Plan Mode as a workflow where the agent researches the codebase, asks clarifying questions, creates a reviewable plan, and waits for you to click Build. You enter it with Shift+Tab in the agent input or the mode picker. Claude Code documents the same idea under Plan before editing with claude --permission-mode plan (and plan toggling within a session). Both tools share the core contract: read and propose first, edit only after approval.

That discipline is valuable. The limitation is what happens after the plan:

Plan Mode session
  -> plan.md (often outside git, or saved manually)
  -> Build in Agent mode
  -> chat context eventually resets
  -> "why did we choose Redis?" lives in scrollback, not the repo
  -> next agent session re-discovers the same codebase from scratch

Cursor’s docs note plans save to your home directory by default, with an optional Save to workspace step — commonly under .cursor/plans/. That is useful for personal continuity. It is weaker as a team contract unless everyone adopts the same save habit and review ritual.

OpenSpec’s positioning on openspec.dev targets exactly that gap: specs that extend across sessions, live beside code, and merge into a growing source of truth after delivery. The explore guide states the product intent plainly: explore is for when you have a problem but not yet a plan, and it hands off to propose when the picture is clear.

Why OpenSpec Can Replace Plan Mode Entirely

“Replace entirely” sounds strong. Here is the precise claim:

Replace Plan Mode as the default planning surface — not delete the feature from your IDE.

OpenSpec wins as the default because it gives you Plan Mode’s best property (think before code) plus properties Plan Mode does not standardize:

OpenSpec’s README (as of July 2026) describes the rebuilt OPSX workflow as intentionally lightweight, brownfield-first, and fluid — iterate on artifacts while coding rather than freezing a monolithic PRD. That is the durability argument: the plan is not one markdown file; it is a small set of linked artifacts with explicit roles.

For non-engineers, the practical difference is review surface:

• Plan Mode plan: “Edit these 12 files, add a cache layer, update tests.”
• OpenSpec proposal pack: “Why we are doing this, what behavior changes (spec scenarios), how we will implement it, and the ordered task checklist.”

PMs can comment on proposal.md and spec scenarios without reading diffs. Engineers still get file-level tasks in tasks.md. Same change folder, two readable layers.

What a PM actually reviews (mini walkthrough)

After /opsx:propose, a change folder might look like this:

openspec/changes/add-guest-checkout/
|-- proposal.md          <- start here: problem, scope, non-goals
|-- specs/
|   `-- checkout/spec.md <- behavior scenarios (WHEN/THEN)
|-- design.md            <- technical approach (optional skim)
`-- tasks.md             <- engineering checklist (usually not PM-owned)

A PM can approve or push back using only proposal.md and the spec scenarios. Questions like “Does guest checkout require an email?” belong in the spec file, not in a long chat thread. That is the durability win over Plan Mode’s single implementation-oriented plan.

The Replacement Workflow

Think of OpenSpec as Plan Mode split into explicit phases with hard guardrails:

                    OPEN SPEC AS PLAN-MODE REPLACEMENT
                    ==================================

  Vague idea                Clear idea                 Ready to ship
      |                         |                            |
      v                         v                            v
 /opsx:explore            /opsx:propose                 /opsx:apply
 (think, no artifacts)    (durable plan pack)           (task-by-task build)
      |                         |                            |
      |    "let's propose"      |                            |
      +------------------------>|                            |
                                |                            v
                                +----------------------> /opsx:archive
                                                         (merge specs, history)

Phase 1 — Explore instead of “Plan Mode research”

OpenSpec’s explore guide defines explore as a conversation, not a generator. It reads code, compares options, draws diagrams, and helps narrow scope — but explicitly does not create a change folder, write artifacts, or modify code.

That is the direct substitute for the research half of Plan Mode, with one crucial difference: explore refuses to produce a “plan document” that looks finished before you have actually decided.

Phase 2 — Propose instead of “Save plan to workspace”

When you run /opsx:propose add-rate-limiting, OpenSpec creates openspec/changes/add-rate-limiting/ with the planning pack. The CLI drives artifact order via openspec status --change ... --json so the agent does not skip dependencies.

This replaces the moment in Plan Mode when you review plan.md and click Build — except the output is structured for both product review and engineering execution.

Phase 3 — Apply instead of Agent mode “Build”

/opsx:apply reads the change context, shows task progress, implements pending tasks, and marks checkboxes in tasks.md. The apply skill guardrails require reading CLI-provided context files, pausing on ambiguity, and keeping edits scoped — the same “do not wander off the approved plan” intent as Plan Mode’s Build step, but anchored to a checklist that can be audited.

Phase 4 — Archive instead of “close the plan ticket”

After merge, /opsx:archive moves the change to openspec/changes/archive/ and offers to sync delta specs into openspec/specs/. Plan Mode has no equivalent standard step; OpenSpec treats recording what shipped as part of planning, not optional documentation.

How the Skills Are Written to Prevent Unwanted Changes

The most common fear when replacing Plan Mode is: “Will the agent still jump to implementation or pick a solution too early?”

OpenSpec addresses that in the skill and command text your assistant loads — not just in product marketing. This repo’s copies under .cursor/skills/openspec-explore/SKILL.md and .cursor/commands/opsx-explore.md are representative of what openspec init installs.

Explore: a stance, not a workflow

The explore skill opens with a hard constraint. This is the actual text openspec init writes into .cursor/skills/openspec-explore/SKILL.md:

Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.

**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.

**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.

The companion slash command repeats the same boundary at the top of .cursor/commands/opsx-explore.md, so both the skill discovery path and the explicit /opsx:explore invocation load identical guardrails.

That wording matters for two audiences:

• Engineers get permission to dig without triggering a scaffold commit.
• Non-engineers get a mode that will not silently edit the product because the conversation “felt decisive.”

Explore: agnostic by design

Three design choices keep explore from forcing an inferred solution:

1. Curious, not prescriptive

The stance section lists “Curious, not prescriptive” and “Open threads, not interrogations” — surface multiple directions instead of funneling through one questionnaire script.

2. No mandatory artifact

Under “What You Don’t Have To Do”:

• Do not produce a specific artifact
• Do not reach a conclusion
• Do not stay on topic if a tangent is valuable

Compare that to Plan Mode, which is optimized to produce a buildable plan as its success condition. Explore explicitly allows ending with clarity but no file.

3. Offer capture; never auto-capture

When a change already exists, the skill tells the agent to offer updates — not perform them silently:

4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.

The guardrails section reinforces the same idea:

## Guardrails

- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
- **Don't fake understanding** - If something is unclear, dig deeper
- **Don't rush** - Discovery is thinking time, not task time
- **Don't force structure** - Let patterns emerge naturally
- **Don't auto-capture** - Offer to save insights, don't just do it

That is the guardrail non-engineers feel most in practice: the assistant suggests; the human commits.

Official explore docs align with the skills

The upstream explore guide lists the same boundaries:

• Does: read/search codebase, compare options, diagram, narrow scope, hand off to propose
• Does not: create a change folder, write artifacts, write or modify code

It also recommends: “Bring the problem, not the solution.” Example: say “logins feel slow” instead of “add Redis,” so the investigation stays honest.

Propose and apply: complementary guardrails

Explore is intentionally permissionless. The next phases tighten discipline:

Propose (openspec-propose skill):

• Requires understanding what to build before creating a change
• Uses CLI artifact dependencies — no skipping straight to tasks without specs when the schema requires them
• Treats context and rules from CLI instructions as agent constraints, not text to paste into files

Apply (openspec-apply-change skill):

• Reads all context files from openspec instructions apply --json before coding
• Marks tasks complete one at a time
• Pauses on ambiguity instead of guessing
• Allows artifact updates when implementation reveals design issues — fluid, not phase-locked

The apply skill’s guardrails block is explicit about pausing rather than guessing:

**Guardrails**
- Keep going through tasks until done or blocked
- Always read context files before starting (from the apply instructions output)
- If task is ambiguous, pause and ask before implementing
- If implementation reveals issues, pause and suggest artifact updates
- Keep code changes minimal and scoped to each task
- Update task checkbox immediately after completing each task
- Pause on errors, blockers, or unclear requirements - don't guess
- Use contextFiles from CLI output, don't assume specific file names

Together, these skills implement a progressive commit model:

explore     -> zero repo commitment
propose     -> planning commitment (artifacts in git)
apply       -> code commitment (scoped to tasks.md)
archive     -> historical commitment (merged specs)

Plan Mode collapses the first two stages into one UI mode. OpenSpec separates them so “thinking” and “agreeing” are different safety levels.

Implementation: Switch Your Default in Cursor or Claude Code

One-time setup

npm install -g @fission-ai/openspec@latest
cd your-project
openspec init

Pick Cursor and/or Claude Code during init. Restart the IDE so slash commands register. OpenSpec creates skills/commands (in .cursor/ or tool-specific paths) plus openspec/config.yaml.

Replace your planning habit

Example: duplicate checkout orders (from OpenSpec docs)

OpenSpec’s explore guide walks a realistic handoff:

You: /opsx:explore
     Our checkout sometimes creates duplicate orders.

AI:  [reads order service, webhook handler, client submit logic]
     Two root causes: double client submit vs duplicate webhook handling.
     Three fixes ranked; idempotency key fits existing payment-intent storage.

You: /opsx:propose add-order-idempotency-key

AI:  Created change folder with proposal + delta spec grounded in exploration.

Notice the separation: exploration could have ended at “not worth fixing yet” with zero repo noise. Plan Mode would still pressure toward a buildable plan.

Team operating rule (engineers + PMs)

1. PM or engineer opens /opsx:explore for fuzzy requests
2. Engineer runs /opsx:propose when scope is concrete
3. PM reviews proposal.md + spec scenarios (behavior, not files)
4. Engineer runs /opsx:apply on a feature branch
5. PR links to the change folder
6. After merge, /opsx:archive

Non-engineers participate in steps 1–3 and 5 without touching Agent mode. Engineers own 4 and 6. That division is harder to maintain when the plan lives only in chat or an unsaved home-directory file.

Optional: project rules that reinforce the replacement

Add a short rule to .cursor/rules or CLAUDE.md:

## Planning default

- Use OpenSpec instead of Plan Mode for non-trivial work.
- Fuzzy idea -> /opsx:explore (no artifacts, no code)
- Ready to agree -> /opsx:propose
- Ready to build -> /opsx:apply on a feature branch
- Do not skip propose and jump to apply for multi-file features.

This does not disable Plan Mode. It steers the team toward durable artifacts.

ASCII: Plan Mode vs OpenSpec Control Flow

PLAN MODE (single mode, two outcomes)
=====================================
        +------------------+
        |    Plan Mode     |
        |  read + question |
        +--------+---------+
                 |
       +---------+---------+
       |                   |
       v                   v
  plan.md (optional    Build -> code
  git save)            (same session)


OPEN SPEC (explicit gates)
==========================
 +----------+    +----------+    +--------+    +---------+
 | explore  | -> | propose  | -> | apply  | -> | archive |
 | no write |    | artifacts|    | code   |    | history |
 +----------+    +----------+    +--------+    +---------+
      |               |
      |               +--> proposal.md  (why)
      |               +--> specs/       (what behavior)
      |               +--> design.md    (how)
      |               +--> tasks.md     (steps)
      |
      +--> safe to stop with zero files

What You Give Up — and When I Still Use Plan Mode

OpenSpec is not free:

• Extra files in the repo (usually a feature for teams, friction for solo throwaway spikes)
• Initial setup (openspec init, command discovery) vs Shift+Tab immediately
• Explore is slower when you already know the exact change — the upstream docs say to skip explore in that case

I still use native Plan Mode when:

• the change is truly single-file and reversible
• I do not need behavior specs or team review
• I want the fastest possible personal plan → build loop with no git artifact

For everything that might survive the week — features, bug fixes with behavioral impact, cross-team requests — OpenSpec is the better default.

How this differs from other planning articles on this devlog

• AI Planning Tools: Claude Code, Cursor, and Beads compares three different tools and treats planning as one layer among many. This article makes a narrower claim: OpenSpec can be your default planning layer inside Cursor or Claude Code.
• The OpenSpec Workflows series parts 1–2 cover getting started and advanced OPSX. This article focuses on why explore/propose guardrails replace Plan Mode, with internal skill design as evidence.

If you are evaluating OpenSpec against GitHub Spec Kit or need expanded commands like /opsx:verify, read Advanced OpenSpec rather than treating this as the only OpenSpec guide.

Sources

Primary sources (retrieved or verified July 6, 2026):

• Cursor Docs: Plan Mode — plan-before-build behavior, Shift+Tab, optional workspace save
• Cursor Blog: Introducing Plan Mode — plan editor, clarifying questions, build from plan
• Cursor Blog: Agent Best Practices — when to plan vs agent directly, .cursor/plans/ tip
• Anthropic Claude Code Docs: Common Workflows — claude --permission-mode plan, plan-before-editing guidance
• OpenSpec — openspec.dev — lightweight, brownfield-first, cross-session planning positioning
• Fission-AI/OpenSpec README — OPSX workflow, core profile commands (explore, propose, apply, sync, archive)
• OpenSpec docs: explore.md — explore does/does-not boundaries, handoff to propose
• OpenSpec supported tools documentation — assistant integrations installed by openspec init
• Local install artifacts in this repository: .cursor/skills/openspec-explore/SKILL.md, .cursor/commands/opsx-explore.md, .cursor/skills/openspec-propose/SKILL.md, .cursor/skills/openspec-apply-change/SKILL.md

Related reading on this devlog:

• How to Get Started with OpenSpec
• OpenSpec Across the Full Development Workflow
• Advanced OpenSpec: Expanded Workflows and Custom Schemas
• AI Planning Tools: Claude Code, Cursor, and Beads — complementary tools framing (Beads for task persistence)