AI development workflow with structured context
Developer
OpenSpec brings a delta-based, artifact-driven workflow to AI-assisted development so your sessions don’t collapse under their own context, your decisions don’t vanish between sprints, and your PRs finally explain themselves.
The Problem With How We’re Building Today
Most developers using Claude Code or GitHub Copilot operate in a single long-running session: brainstorm, plan, implement, debug, all in one thread. It works until it doesn’t. Context windows fill. The model starts “forgetting.” You compact the conversation, quality drops. Or you hit daily token limits two hours into your morning.
There’s a structural fix for this, and it comes from treating your AI sessions the way you’d treat a well-run team: explicit handoffs, documented decisions, clear artifacts. OpenSpec is a framework that operationalizes exactly that.
What Is OpenSpec?
OpenSpec is an open-source spec kit for AI-assisted development, available on GitHub and installable via npm. It’s not a project management tool or a prompt library, but a structured workflow that sits between you and your coding agent, enforced through agentic skills and CLI commands.
The key differentiator from other spec kits (like Microsoft’s SpecKit) is its delta-based approach: OpenSpec doesn’t require full project specifications to exist upfront. It only operates on the changes relevant to the current feature. This makes it equally applicable to greenfield and brownfield projects — you can drop it into an existing repo with zero existing specs and start immediately.
# Install
npm install -g openspec
# Initialize in your repo
openspec init
# Generates skills in .claude/ or .github/ depending on your agent
Once initialized, OpenSpec lives in your repository as a set of markdown skill files. It supports both Claude Code and GitHub Copilot out of the box. And yes, you can run both simultaneously.
The Four-Step Workflow
Everything in OpenSpec maps to one of four slash commands. Three are mandatory; one is optional but recommended:
/opsx:explore
Explore — Discuss, Don’t Build
Opens a brainstorming conversation with the agent. No files are created or modified. You talk through the feature: implementation approaches, integration points, trade-offs.
/opsx:propose
Propose — Generate Artifacts
Based on the exploration conversation, the agent produces a structured set of markdown files: a Proposal MD (why + what + impact), a Design MD (decisions, alternatives, risks), a Tasks MD (checklist), and a Spec MD (requirement deltas). Your job: read and verify them before proceeding.
/opsx:apply
Apply — Generate Code
The agent implements the feature per the spec artifacts. As it works, it ticks off items in Tasks MD in real time. If the session crashes mid-implementation, a fresh session picks up where the checkmarks left off. Plus, no context reconstruction is needed.
/opsx:archive
Archive — Commit the History
Moves the planning artifacts from openspec/changes/ to openspec/changes/archive/ and updates the persistent spec files. No code changes, just pure documentation housekeeping that creates a queryable audit trail.
/review (built-in claude code skill)
Review — Fresh Eyes (Optional)
Runs a clean agent session with no conversation history. Only the artifacts and the code diff. Because the reviewer has no “memory” of the implementation decisions, it catches inconsistencies that the implementation agent would rationalize away.
The Real Benefit: Session Independence
This is what makes OpenSpec structurally different from other approaches. Because the plan lives in files — not in conversation history — you can run each phase in a completely separate agent session, or even a completely different agent.
Planning → Claude Code (Opus + extended thinking)
Expensive, but planning only needs the best reasoning
Apply → GitHub Copilot (Claude Sonnet or Codex)
Cheaper, but gets full spec artifacts as input
Review → Either, in a fresh session
No context needed — artifacts are the context
The result: hours of continuous coding without hitting daily Opus limits, without compacting conversations, and without quality degradation. For enterprise subscriptions, the benefit shifts: same-model all the way through, but the session isolation still protects against context window degradation on long features.
Benefits
| Hard — Technical | Soft — Organizational |
| Independent agent sessionsReduced cost and token usageBetter context for agentic / human PR reviewAutomatic specs generation | More organized way of AI-assisted developmentMore detailed and visually perceptive planningImproved possibilities for code audit (both human and AI)Simplified way of commits strategy |
OpenSpec vs. SpecKit: What Practitioners Say
| OpenSpec | Microsoft SpecKit |
| Delta-based — works on existing repos immediatelyTechnically oriented exploration — asks better engineering questionsHighly customizable schemas and agent skillsMinimal artifact footprint; archive folder keeps repo cleanNot phase-locked — update specs anytime | More opinionated workflow, requires branch conventionsExploration tends toward business requirements over technical designContext gaps between sessions require additional custom skills |
The exploration phase in OpenSpec asks technically deeper questions, which leads to better decision-making before any code is written. OpenSpec’s closest non-spec-kit competitor in terms of exploration quality is Superpowers’ brainstorming mode — but Superpowers produces no artifacts, which is ultimately the dealbreaker for structured multi-session development.