Is OpenSpec the Most Developer‑Friendly Spec Tool? More Detailed Than Cursor Plan and Lighter Than spec‑kit

Hello, I’m Kate. I’ll give a systematic introduction and live demo of OpenSpec, a repository I shared three days ago that works well with Codex (built‑in GPT‑5).

What Is OpenSpec

OpenSpec aims to align humans and AI coding assistants through “spec‑driven development”.

Compared with my earlier shares of spec‑kit and BMAD‑METHOD, OpenSpec is lighter and more complete than Cursor’s current Plan mode while keeping the overall process simple.

Workflow Overview: Two Parts, Five Steps

Two parts: specs (current specification state) and changes (proposed evolution records).

Basic steps:

Propose

Review & align

Plan with feedback loop (AI repeatedly analyzes and generates a plan)

Implement

Archive & update specs

During the whole process you can let the AI keep analyzing, generating plans, and iterating in the feedback loop until satisfied, then implement and archive.

Tool Support and Interaction

Provides convenient command‑line operations.

Supports natural‑language dialogue‑driven workflow.

Compatible with AGENTS.md for easy installation and use in common development tools.

Installation and Initialization

After installation, navigate to your project and run openspec init.

Verify the setup and view changes with openspec list.

After init, you can create your change proposals.

Comparison with spec‑kit / Kiro

spec‑kit excels at “0‑to‑1” scaffolding.

Kiro differs from OpenSpec in that OpenSpec groups each functional change into its own folder, making it easier to track related specs, tasks, and designs.

Practical Demo: Improving an OpenJourney Project

OpenJourney is a Google‑employee open‑source project that mimics the Midjourney UI.

Previously I replaced the Gemini API with the Replicate API, adjusted image and video generation models, and enabled local data storage.

In this demo, I used Codex together with OpenSpec to replace the image model with Qwen Image because it is cheaper on Replicate and yields higher quality, and I added adjustable parameters such as inference steps, image size, output format, and quality.

Proposing and Validating with OpenSpec

Enter the project and run openspec init. The system confirms the AI coding tool (I chose Codex) and prompts three tasks: read project.md and fill detailed project info, create the first change proposal, and explain the OpenSpec workflow.

After initialization, two main folders are generated: openspec/changes and openspec/specs, along with AGENTS.md and project.md.

The AI reads project.md, translates it to Chinese for better comprehension, and then I propose changing the image model from “FLUX (Black Forest)” to Qwen.

A proposal document with a Why/What/Impact structure appears, and the system prompts me to run a validation command. The validation step rewrites normative terms to MUST to satisfy OpenSpec’s rules; after a second run the strict check passes.

Implementation and Debugging Highlights

When I started implementation, the UI accepted text, image, and video inputs, but a small error appeared on the left side.

The “embarrassing problem” turned out to be an expired API key that had been deleted months earlier; replacing it with a valid key restored normal generation.

Choosing the Expand mode shows a history of generated images, similar to Midjourney.

The initial settings lacked detailed image parameters. By prompting Codex through OpenSpec, the missing adjustable items (steps, size, format, quality, etc.) were filled in.

Finally, Codex fixed the page error, and image/video generation worked smoothly again.

Archiving and Queries

I instructed Codex to archive the changes with the archive command. A new spec.md for “image generation” appeared, showing ADDED Requirements at the top.

Common commands reviewed: openspec list (view current changes), openspec view (view existing specs), openspec show + change (if “no change found”, it is likely already archived).

After completion I checked tasks.md. The initial unchecked items were auto‑checked by the AI after a self‑inspection; a few manual steps (e.g., verifying prompts locally and saving to the gallery) remain.

When to Prefer OpenSpec

When modifying existing features or touching multiple specs, OpenSpec’s change grouping and spec‑driven flow are especially useful.

spec‑kit is better suited for “0‑to‑1” projects; when you need systematic tracking of “spec‑task‑design” evolution, OpenSpec’s structure facilitates collaboration and traceability.

Commands and Prompt Cheat Sheet

Common commands: openspec init → openspec list → openspec view → openspec show Prompt templates (system‑guided, no need to memorize):

“Create a change proposal (for …)”

“Validate proposal/spec” (the system will automatically suggest the next command at each step)

“Refine spec → implement → archive”

Summary and Review

In an existing project, run openspec init to generate project.md.

Let the AI review and enrich project.md.

Submit a change proposal; the AI produces a plan and tasks.

Human‑AI co‑review, revise, and strictly validate (e.g., enforce MUST).

After satisfaction, implement; locate and fix issues such as expired API keys.

Archive the change and check the completion status in tasks.md.

That’s my sharing on OpenSpec today. I hope it helps you run AI‑assisted coding workflows reliably.