OSpec
Turn requests into verifiable goal loops — plan, act, verify — with durable specs and evidence in your repo, working across mainstream AI coding agents.
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).
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.; 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
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. — 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 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.