OSpec
Turn requests into verifiable goal loops — plan, act, verify — with durable specs and evidence in your repo, working across mainstream AI coding agents.
- Source repo
- clawplays/ospec
- Stars
- ★ 391
- Last updated
- 1mo ago
- License
- MIT
- Primary language
- JavaScript
- FA score
- 50/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Developers using Claude Code or Codex who want requirements, plans, and verification evidence in the repo rather than chat history for reviewability
- Not a fit if
- IDEs or terminals without native subagents — controller dispatch fails
- Teams unwilling to let OSpec merge hooks into .claude/settings.json
- Solo users who just want quick chat edits, not repo specs and evidence
- Source review
- 50/100 · Major gaps
What does this agent do, and when should you use it?
OSpec (official CLI package @clawplays/ospec-cli, command ospec) is a spec-driven, agentic workflow framework for AI coding agents. It addresses the problem that requirements living only in chat history are hard to inspect, review, and close out. OSpec turns a request into files in your repository — proposal, design, plan, tasks, reviews, and verification evidence — so any assistant (Claude Code, Codex/GPT, Gemini, OpenCode, or plain CLI) can resume exactly where the last one stopped. It offers two flows: the lightweight ospec change fast path (proposal → tasks → implement → verification → review) and the heavyweight ospec goal workflow with a task-graph controller, parallel worker dispatch, independent reviewer gates, and durable evidence. Written in TypeScript and installed globally via npm, it generates documentation in en-US, zh-CN, ja-JP, or ar.
Runs a three-step flow: 1) ospec init creates the protocol shell in your project (root .skillrc, README.md, and .ospec/ with changes/active, changes/archived, SKILL.md, for-ai guidance, and baseline project docs); 2) ospec change <name> or ospec goal <name> creates and advances work, producing artifacts like proposal.md, tasks.md, design.md, implementation-plan.md, and task-graph.json; ospec execute dispatch/launch/complete settles native-subagent packets (Codex uses spawn_agent, Claude Code bounded background Task polling, Gemini @generalist, OpenCode @mention), ospec loop tick issues reviews with executor provenance, and ospec execute verify records test evidence; 3) ospec verify plus ospec finalize archives accepted changes and rebuilds indexes and the feature catalogue. Supporting commands include ospec session (session briefs), ospec docs obligations (documentation duties), ospec brainstorm/plan (pre-change aids), and ospec update (legacy project migration).
- Developers using Claude Code or Codex who want requirements, plans, and verification evidence in the repo rather than chat history for reviewability
- Teams running larger or riskier refactors as a full Goal workflow with reviewer gates and parallel workers
- Multilingual projects (en-US/zh-CN/ja-JP/ar) that want generated specs and change docs to stay in one consistent language
- Projects with human-maintained architecture/API docs that want archiving to refresh the feature catalogue and enforce documentation obligations (warn or strict mode)
- Multi-session or hand-off projects that rely on ospec session briefs and persisted task-graph state so a fresh session can continue without replaying conversation
How do you install or deploy this agent?
Requires Node.js 18+ and npm 8+. Run: npm install -g @clawplays/ospec-cli, then verify with ospec --help.
How do you use this agent?
1) In your project directory run ospec init . (optionally with --summary, --tech-stack, --architecture, --document-language); 2) create a change: ospec change fix-login-timeout . or start a full Goal: ospec goal improve-checkout --target codex --execution-model controller --harness-interactive true --native-subagents supported; 3) after deploy/test/QA pass, run ospec verify changes/active/<change-name> and ospec finalize changes/active/<change-name> to archive. In Claude Code you can use natural-language prompts (e.g. "OSpec, initialize this project") or skill commands (/ospec, /ospec-change, /ospec-goal). After upgrading, run ospec update to refresh managed files.
What are this agent's strengths and limitations?
- Specs, tasks, reviews, and verification evidence persist as files in the repo, so any supported assistant can pick up the work — no lock-in to one tool's chat history
- The Goal workflow bakes in deterministic planning preflights, one independent combined planning review, grouped-repair convergence guards, and conflict-safe parallel execution
- Subagent dispatch uses bounded waits (≤60s per poll), heartbeats, and leases; after session loss, ospec loop recover --force expires only unfinished items
- Documentation obligations and the feature catalogue (ospec:feature locator comments, ospec docs locate/audit) tie code changes to traceability in human-owned docs
- The full Goal workflow has many concepts (task graphs, leases, heartbeats, token budgets, allowlists), so the learning and operational cost is nontrivial
- It depends on the current IDE/harness providing native subagents: without them, executable dispatch blocks and OSpec never falls back to launching another agent CLI
- Claude Code hard enforcement requires a one-time ospec session hook --target claude --apply that writes into .claude/settings.json — an invasive configuration step
- The new nested layout coexists with legacy flat archives; older projects need ospec update or ospec layout migrate --to nested explicitly
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| OSpec This agent | 50 · Major gaps | CLIFree + model costs | ★ 391 | 1mo ago | JavaScript | Codex · Claude Code |
| ZCF - Zero-Config Code Flow | 51 · Major gaps | CLIFree + model costs | ★ 6.1k | today | TypeScript | Codex · Claude Code |
| Smart Ralph | 73 · Some gaps | Agent plugin / skillFree + model costs | ★ 562 | 1mo ago | Shell | Codex · Claude Code |
| CoCo Super Intelligence | 69 · Some gaps | Agent plugin / skillFree + model costs | ★ 785 | today | Python | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Force-archive requires dual flags, exact-name confirmation, and an audit reason, and pending decisions block implementation (user_confirmation=2); the publish workflow scopes permissions to contents:read plus id-token:write with tag/version checks (dependency_security=2, only js-yaml/semver runtime deps). Deductions: the product writes .claude/settings., dispatches subagents, and runs arbitrary verify commands without a least-privilege statement or permission manifest (least_privilege=1); data flows are narrative only, with no statically checkable data boundaries (data_flow_transparency=1); sensitive-data handling (diffs, verification output) is undocumented (sensitive_data_handling=1); external effects (hooks, worktrees, subagent spawn) are described with little risk boundary (external_effects=1); hooks claim idempotent reversibility and update migrations exist, but no rollback command or recovery path is documented (rollback=1); author/repo links exist but the publisher is unverified, so attribution is self-asserted only (source_attribution=1).
Failure behavior is concrete: dispatch fails clearly when native subagents are unavailable, repair loops have convergence guards, and repeated failure stops (failure_messages=2); only two mature runtime dependencies, so availability risk is low (dependency_availability=2). Deduction: the (truncated) README makes many behavioral claims that cannot be statically verified and no tests/code in evidence corroborate internal consistency (self_consistency=1).
Audience (AI coding-agent users) and scenarios (change/goal workflows) are clearly described, with four agent platforms and four document languages (audience_and_scenarios=2); capability boundaries are explicit: 60-second poll bounds, no fallback to launching other agent CLIs, parallelism fallback of 3 (capability_boundaries=2); skill triggers vs CLI commands are distinguished (trigger_precision=2); Node 18+/npm 8+ and multi-harness fit are documented (environment_fit=2). Scores stay one notch below full because nothing is code-verified.
Repository layout (.ospec/ nesting, archive paths, migration) is well organized in docs (information_architecture=2); install steps, verification (ospec --help), and ospec update are complete (install_notes=2); naming aliases (ospec new/ospec change, CLI shorthand paths) have explicit compatibility notes (naming_stability=2); many CLI and prompt examples plus doc links (examples_and_faq=2); standard MIT LICENSE file (license=3). Deductions: no CHANGELOG or explicit known-limitations list (known_limitations=1, versioning_changelog=1, despite tag/version checks); unverified third-party publisher with only an issues link and author email for maintenance responsibility (maintenance_responsibility=1).
Outputs are structured repo artifacts (indexes, state, compact JSON, evidence packages) directly usable by later sessions or audits (output_usability=2); versus chat-history-only requirements, it provides a repo-checkin-able verifiable goal loop, so marginal value is documented (marginal_value=2). Deduction: cost/benefit is only asserted via token budgets and metrics files, with no statically verifiable benefit data (cost_benefit=1).
Claims link to docs, feature-locator comments, and archive traceability mechanisms (claim_traceability=2); behavioral claims vs execution effects are separated, e.g. 'launch writes launch-plan.md and does not start workers itself' (fact_inference_separation=2). Deduction: with only static files, npm downloads, publish state, and actual hook behavior cannot be corroborated across sources (cross_source_corroboration=1).
- Static review only; no commands were executed. Many behavioral claims in the README (hook blocking, subagent dispatch, convergence guards) are unverified and confidence is low.
- ospec session hook modifies .claude/settings. and registers tool-level hooks; inspect the written content manually and keep a backup before applying.
- The product executes user-supplied verify commands and spawns subagents — a higher-privilege agent workflow; try it first in an isolated or controlled environment.
- Publisher identity is unverified by the enterprise registry; check npm provenance against the repository before installing @clawplays/ospec-cli.
- No CHANGELOG or explicit known-limitations list was found; commit and back up the repository before upgrading (ospec update performs file migrations and re-layout).
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
2.1.0 2.1.0 - categorised doc bindings, coverage/bind/retire pipelines, and a generated docs map
Release notes excerpt
OSpec 2.1.0 extends the living-documentation engine from docs/features/ to every documentation category. Bindings can now be declared in docs/api/, docs/design/ and docs/project/ with <!-- ospec:doc <slug> code:... --> (same syntax and slug namespace as ospec:feature), and every binding carries a kind inferred from its path. Obligations become kind-aware: api sections follow the behaviour table, design decisions verify as verify_decision (still holds, or mark Superseded), project overviews verify as verify_structure, and planning/product documents stay reference-only. New onb …View on GitHub ↗ -
2.0.2 2.0.2 - feature-catalog links that actually resolve
Release notes excerpt
OSpec 2.0.2 fixes the generated docs/project/feature-catalog.md so its links work: heading anchors keep Unicode (CJK headings no longer anchor to an empty fragment), and hrefs resolve through the project layout (nested-layout projects no longer link through a doubled .ospec/). No breaking changes. After upgrading, run ospec index build in each project — the catalogue regenerates with working links; no re-migration is needed. Fixed …View on GitHub ↗ -
2.0.1 2.0.1 - localized migration drafts, index freshness, and a js-yaml security bump
Release notes excerpt
OSpec 2.0.1 fixes three defects found while migrating real projects to 2.0, and bumps js-yaml past a CPU-exhaustion advisory. No breaking changes; upgrade with npm install -g @clawplays/[email protected] and re-run ospec update in each project to refresh the protocol documents. Fixed - ospec docs migrate --plan now writes its draft-skeleton guidance in the project's documentLanguage (zh-CN, ja-JP, ar, en-US) instead of hardcoded English, following the same rule as the feature catalogue and the obligation copy. The status: draft line and the ospec:migration-draft marker stay mach …View on GitHub ↗