OpenSpec vs planning-with-files
Which should you use? A side-by-side look at what each one does, who it suits, what it costs, how hard it is to set up, and where each falls short.
Open source · MIT
Plain-text specs that your AI coding assistant and you agree on before any code is written.
Open source · MIT
A file-based planning skill that keeps AI coding agents on track across resets and crashes.
The short answer
Choose OpenSpec if you need…
- Developers who use AI coding assistants and want to agree on requirements before code is written
- Teams working on existing (brownfield) codebases, which the README names as a design goal
- Solo developers who want their AI to stay on a defined plan within one repo
- Teams that want to share specs across several repositories (Stores, in beta)
Choose planning-with-files if you need…
- Developers running long multi-step tasks in Claude Code or Codex CLI
- People who lose agent progress when the context window fills or is cleared
- Teams wanting a plan that lives in the project as plain markdown files
- Users of agents that support the Agent Skills standard
Side-by-side
| OpenSpec | planning-with-files | |
|---|---|---|
| Type | Dev tool | Dev tool |
| Price | Free and open source | Free and open source |
| Licence | MIT | MIT |
| GitHub stars | 73.7k | 27.8k |
| Setup difficulty | Beginner | Beginner |
| How you get it | Install with a package manager | Install with a package manager |
| Main language | TypeScript | Shell |
| Last code update | 4 days ago | 6 days ago |
What each one is
OpenSpec
OpenSpec is a command-line tool that adds a lightweight specification layer to AI coding assistants. Before the assistant writes code, you and the AI create a proposal, requirement specs, a design, and a task list in an openspec/ folder inside your project. You review that plan, then the AI implements it and archives the change when done.
planning-with-files
This is a skill for AI coding agents that stores a task plan, research notes, and progress log as markdown files in your project. Lifecycle hooks re-inject that planning context so the agent can pick up where it left off after /clear, context compaction, or a crash. The README says it works across 60+ agents via the Agent Skills standard, with native plugins for several hosts including Claude Code and Codex CLI.
Best for
OpenSpec
- Developers who use AI coding assistants and want to agree on requirements before code is written
- Teams working on existing (brownfield) codebases, which the README names as a design goal
- Solo developers who want their AI to stay on a defined plan within one repo
- Teams that want to share specs across several repositories (Stores, in beta)
planning-with-files
- Developers running long multi-step tasks in Claude Code or Codex CLI
- People who lose agent progress when the context window fills or is cleared
- Teams wanting a plan that lives in the project as plain markdown files
- Users of agents that support the Agent Skills standard
Strengths
OpenSpec
- Plain Markdown specs with no special syntax to learn
- Works with 30+ AI assistants via slash commands, according to the README
- Ships as a single binary install that the README says needs no Node.js
planning-with-files
- Plain markdown files on disk that you can read, edit, and version-control or gitignore
- Works through the Agent Skills standard across many agents, with native plugins for several hosts
- MIT licensed with a published benchmark and install options via npm, the Claude Code marketplace, or npx
Not ideal for
OpenSpec
- People who want a rigid, phase-gated process: the README positions OpenSpec as fluid and iterative, not waterfall
- Projects that do not use an AI coding assistant, since the workflow is built around slash commands in those tools
- Anyone needing a stable cross-repo feature, because Stores are described as beta
planning-with-files
- Short one-off questions where a plan file adds overhead
- People who want a hosted service rather than local files in their repo
- Users of hosts not listed in the README, since native support depends on the host and results may vary
Trade-offs
OpenSpec
- Stores, the cross-repo feature, are labeled beta in the README
- Slash command names vary by tool (for example /opsx-propose in Cursor and GitHub Copilot), which adds some setup confusion
- Value depends on your AI assistant following the spec files reliably, which the README does not measure
planning-with-files
- Benchmark figures are from the project's own measurements and are reported with stated limits; independent verification is not shown in the README
- Commands and tools vary by host, so the experience differs between integrations
- Session catchup modes can read local agent session records, which the README says requires an explicit opt-in
Getting started
OpenSpec
Install with npm (requires Node.js 20.19.0+)
npm install -g @fission-ai/openspec@latestInstall with Homebrew
brew install openspecplanning-with-files
Install the skill globally via npx skills
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -gFrequently asked questions
What is the difference between OpenSpec and planning-with-files?
OpenSpec: Plain-text specs that your AI coding assistant and you agree on before any code is written. planning-with-files: A file-based planning skill that keeps AI coding agents on track across resets and crashes. OpenSpec suits developers who use ai coding assistants and want to agree on requirements before code is written, while planning-with-files suits developers running long multi-step tasks in claude code or codex cli.
Are OpenSpec and planning-with-files free?
OpenSpec: Free and open source. planning-with-files: Free and open source.
Is OpenSpec or planning-with-files more popular?
OpenSpec has more GitHub stars (73.7k) than planning-with-files (27.8k). Popularity isn't the same as fit — check which one matches your use case above.
What are other alternatives to OpenSpec and planning-with-files?
Other options people compare them with include Spec Kit, OpenHands, wshobson/agents, 9Router, Ruflo.
Keep comparing
Built from our catalogue entries for both products: open-source details come from each project's README (AI-assisted, refreshed weekly) and GitHub data; AI-tool details are editorial. Spotted something wrong? Let us know from either product's page.