OSpec: Turning Agent Requests Into Repo-Resident Specs
Spec-driven, agentic workflow framework for AI coding agents. Turn a request into a verifiable goal loop — plan, act, verify — with durable specs and evidence in your repo. Works with Claude Code, Codex, Gemini, OpenCode, and plain CLI.
At a glance
- What is it?
- OSpec is a Node.js CLI that writes proposals, plans, tasks, reviews and verification evidence into your repository so that Claude Code, Codex, Gemini, OpenCode or a plain shell can resume the same change. The value is durable context; the cost is a workflow layer you have to keep in sync with your code.
- Who is it for?
- Adopt OSpec if your team already runs coding agents and loses context between sessions, and if you are willing to commit .ospec/ and .skillrc alongside your source. Skip it if your work is one-off scripting or if you cannot review generated Markdown in pull requests.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 21 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The Chat History Problem OSpec Is Aimed At
The README states the problem plainly: requirements that live only in chat history are hard to inspect, review, and close out cleanly. That is a real failure mode for anyone driving an agent through a multi-step task. A session ends, the model's context is gone, and the next agent has to reconstruct intent from a diff. OSpec's answer is to make the repository the storage layer for change context, both before code is written and after the work ships.
The audience follows from that. This is not a tool for someone asking an assistant to rename a variable. It is for teams running agent-assisted delivery where a change needs a proposal, a design, a task list, a review and verification evidence that a human can read later. The README lists the surfaces it targets: Claude Code, Codex, Gemini, OpenCode, MCP-based agents, and plain CLI workflows. That breadth is the point. The artifacts are files, so the agent vendor is interchangeable between sessions.
Two Paths: ospec change And ospec goal
OSpec exposes two workflows with different weight. The everyday path is ospec change, described as one requirement becoming one active change on a short init -> change -> verify/finalize route. The README spells out the artifact sequence: proposal.md, then tasks.md, then implementation, then verification.md, then review.md. It also states that this classic flow has no controller layer.
The heavier path is ospec goal, for larger or riskier work. According to the README, the agent asks important questions, writes an inspectable plan, implements, runs tests, requests an independent review, updates project docs, and continues until the result is proven. The controller layer (parallel worker dispatch, reviewer gates, durable evidence) belongs to this goal workflow. You can pull that controller into a single change only by explicitly opting into agent or worker execution.
That split is the most interesting design decision in the project. Instead of one workflow with a complexity dial, OSpec ships two named flows and tells you which layer owns the reviewer gates. The trade-off is a vocabulary you have to learn: change and goal are not synonyms, and the README is explicit that the controller state lives in repo artifacts.
Installation And The Three-Step Loop
The official package is @clawplays/ospec-cli and the command is ospec. Installation is a global npm install:
npm install -g @clawplays/ospec-cli
The README gives ospec --help as the way to verify the install, and states Node.js 18+ and npm 8+ as the requirements.
The documented loop is three steps. Initialize the project, create and advance one change, then archive the accepted change after deployment and validation are complete. Initialization offers both a prompt form (OSpec, initialize this project.) and a CLI form. The CLI form takes flags that are worth reading closely:
ospec init . --summary "Internal admin portal for operations" --tech-stack node,react,postgres ospec init . --architecture "Single web app with API and shared auth" --document-language en-US
--summary writes project overview text into generated docs, --tech-stack takes a comma-separated list, --architecture is a short description, and --document-language accepts en-US, zh-CN, ja-JP or ar. The README notes that if you pass these values OSpec uses them directly, and if you do not it reuses existing docs when possible and otherwise creates placeholder docs first. Placeholder docs are a mild trap: they look like documentation until someone reads them.
Advancing a change is a positional command with the project directory:
ospec change docs-homepage-refresh . ospec change fix-login-timeout .
Skill mode is also documented, with /ospec-change and /ospec-goal as the Claude and Codex entry points.
Language Resolution, .skillrc And The Nested Layout
Two pieces of state govern where files land and what language they are written in, and both are easy to miss on a first read.
OSpec persists the chosen project document language in .skillrc and reuses it for for-ai guidance, ospec change and ospec update. The README gives two different resolution orders. For AI-first flows: an explicit language request in the conversation, then the current conversation language, then the persisted project language in .skillrc. For CLI flows: an explicit --document-language, then the persisted language in .skillrc, then existing project docs or managed for-ai/* guidance or the asset manifest, then a fallback of en-US. The asymmetry matters. A CLI invocation and a conversational one can resolve to different languages if the conversation is in a language the project has not persisted.
The layout is the second surprise. New projects initialized by ospec init default to a nested layout: root .skillrc and README.md, with OSpec-managed files under .ospec/. The README also notes that CLI commands still accept shorthand like changes/active/<change-name>, but the physical path in nested projects is .ospec/changes/active/<change-name>. So the shorthand in the docs is not the path on disk. Anyone writing scripts against the tree should use the .ospec/ prefix.
One more boundary the README draws: plain init does not create optional knowledge maps such as .ospec/knowledge/src/ or .ospec/knowledge/tests/. Those appear only when a project already has legacy knowledge content to migrate, or when future explicit knowledge-generation flows create them.
What OSpec Does Not Do, And Where It Gets Awkward
The documentation is candid that the classic change flow has no controller layer, which means no parallel worker dispatch and no reviewer gate unless you move to ospec goal. If you want the guarantees, you pay for them in workflow weight and in the number of artifacts a reviewer has to open.
There is a second, less advertised cost. OSpec writes Markdown into your repository, and generated documents drift. The 2.0.1 release notes mention index freshness and localized migration drafts, and 2.1.0 mentions a generated docs map plus coverage, bind and retire pipelines. That release cadence suggests the doc index needs active maintenance rather than being a write-once artifact. A stale docs map is worse than no docs map, because agents will trust it.
The nested layout is a third friction point. If your tooling, ignore rules or CI globs assume changes/active/ at the root, an init on a new project will place the real files under .ospec/ and your scripts will silently find nothing. The README flags the shorthand-versus-physical-path difference, but only inside the CLI notes.
Finally, OSpec is the wrong tool when the unit of work is a single edit. Initializing a project, generating placeholder docs and writing a proposal for a one-line fix adds review surface without adding information. The README's own framing, requirements that need to be inspected and closed out cleanly, describes work with a lifecycle. Work without a lifecycle does not benefit.
How OSpec Differs From A Plain AGENTS.md Convention
The obvious alternative is a hand-written instruction file at the repository root, the pattern many teams already use to give agents project context. The difference in approach is structural. A root instruction file is a single document that describes how to work; OSpec produces per-change artifacts (proposal, design, plan, tasks, reviews, verification evidence) that are scoped to one unit of work and archived when it closes.
That scoping is what lets a second agent pick up where the first stopped. A shared instruction file tells a new session about the project, not about the half-finished change. OSpec's files carry the change itself, which is why the README can claim any assistant can resume exactly where the last one stopped.
The cost of the structural approach is volume. One change produces several Markdown files, and they are generated, so they need the same review discipline as code. A single instruction file is cheaper to maintain and cheaper to read. If your agent sessions rarely outlive a single context window, the instruction file wins on cost. If they regularly do, the per-change artifacts are the part a shared file cannot replicate.
Licence, Maintenance And Upgrade Surface
OSpec is MIT-licensed, which permits commercial use and modification, and the repository is not archived. The README identifies @clawplays/ospec-cli as the official package, which is worth noting before installing anything similarly named. This is not legal advice; read the LICENSE file in the repository for the actual terms.
The maintenance picture from the release list is a project that ships frequently and changes its own generated surface. Between 2.0.1 and 2.1.0 the notes cover localized migration drafts, index freshness, a js-yaml security bump, feature-catalog links, categorised doc bindings, coverage/bind/retire pipelines and a generated docs map. Two of those releases are patch-level fixes to link resolution and index freshness, which is a reasonable signal that the doc layer is still settling.
For upgrade cost, the practical question is what happens to artifacts already in your repository when the doc schema changes. The 2.0.1 note about localized migration drafts implies that migrations exist and that they can be localized, but the README does not describe an upgrade command. Verify that before you commit a large body of changes to the format. The .skillrc file is the other thing to watch: it holds the persisted document language, so a migration that rewrites it changes the language of everything generated afterwards.
Who Should Adopt OSpec And What To Check First
Adopt OSpec if you run coding agents across sessions and lose the thread between them, and if your team is willing to review generated Markdown in pull requests the same way it reviews code. The MIT licence and the vendor-neutral artifact format make it low-risk to try on one repository.
Do not adopt it if your agent work is short-lived, if you cannot commit .ospec/ and .skillrc, or if nobody will read the proposals and verification files. Generated documents that no one opens are pure overhead, and the stale-index problem described in the release notes makes unread docs actively misleading to the next agent.
Before you commit, do three things in a scratch copy. Run ospec init . with your real --summary, --tech-stack and --architecture values so you see the actual generated docs rather than placeholders. Confirm the nested layout under .ospec/ matches your CI globs and ignore rules, since the shorthand paths in the docs are not the physical paths. And pick your document language deliberately, because .skillrc persists it and every later ospec change and ospec update inherits that choice.
Editorial conclusion
Adopt OSpec if your team already runs coding agents and loses context between sessions, and if you are willing to commit .ospec/ and .skillrc alongside your source. Skip it if your work is one-off scripting or if you cannot review generated Markdown in pull requests. Before committing, run ospec init . in a scratch copy, inspect the generated .ospec/ tree and .skillrc, and confirm the document language and nested layout match what your reviewers expect.
Community notes