Skip to content
Back to search

ospec

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/clawplays--ospec/badge.svg)](/listings/clawplays--ospec)

HTML

<a href="/listings/clawplays--ospec"><img src="/api/listings/clawplays--ospec/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

npm install -g @clawplays/ospec-cli

Official package: `@clawplays/ospec-cli` Command: `ospec` Verify install: `ospec --help`

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 93 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: ospec
  3. description: Document-driven OSpec workflow for initialization, change/goal routing, validation, archiving, and durable project knowledge.
  4. tags: [cli, workflow, automation, ospec]
  5. ---
  6. # OSpec Router
  7. Use this root skill as a compact router. Keep invariant safety and workflow-selection rules here; load detailed commands and stage protocols from the initialized project's indexed files only when that stage is active.
  8. ## Default Entry
  9. When the user asks to initialize a project, run `ospec init [path]`. In AI-assisted initialization, pass the explicit or conversational language with `--document-language`. If useful context is missing, ask once for a short project summary or tech stack; if the user skips it, continue with placeholders. Verify the generated files on disk and stop before creating work unless the user explicitly asks for a change or goal.
  10. Initialization is change-ready only when `.skillrc`, the managed `.ospec/` or classic OSpec directory, active and archived change directories, `SKILL.md`, `SKILL.index.json`, the index builder (`.ospec/tools/build-index-auto.cjs`), `for-ai/` protocol files, and baseline `docs/project/` knowledge files exist. Verify those managed files on disk yourself and never claim initialization is complete before you have: a command that exited zero is not evidence that the files are there.
  11. Do not hand-write an approximation of `ospec init`. Do not assume a web stack, apply business scaffold, generate `docs/project/bootstrap-summary.md`, create queue work, or create the first change without explicit intent.
  12. ## Workflow Router
  13. - Use `ospec change` / `ospec-change` when the user selects a Change. Its source of truth is `changes/active/<change>/proposal.md`, `changes/active/<change>/tasks.md`, `state.json`, `verification.md`, and `review.md`; `ospec new` remains a compatibility alias.
  14. - Use `ospec goal` / `ospec-goal` only when the user selects a Goal. It additionally owns `changes/active/<change>/design.md`, `changes/active/<change>/implementation-plan.md`, `changes/active/<change>/artifacts/agents/task-graph.json`, worker/reviewer artifacts, and evidence gates.
  15. - Never auto-promote, reject, or replace a user-selected Change because of complexity, risk, file count, parallelism, or batch size. The user's explicit profile choice is authoritative.
  16. - Enter queue mode only when the user explicitly asks to queue or execute multiple changes.
  17. For an initialized project, read in this order:
  18. 1. `.skillrc` for layout, language, workflow policy, and model profiles.
  19. 2. the `Table of Contents` section of `.ospec/session-brief.md` to see which archived changes and knowledge documents exist, then `ospec docs locate --feature <slug>` / `--affects <path>` to jump straight to the section that describes a behavior, and `ospec index query <keyword...>` as the keyword router into `SKILL.index.json`; never read the whole index file — it grows without bound as changes archive.
  20. 3. The current session brief, bootstrap, dispatch, review, or repair packet.
  21. 4. Only the indexed project documents, change files, and target files named by that packet.
  22. Do not load every historical change or every protocol file by default. `for-ai/ai-guide.md` is a router into the protocol that owns each profile, not a rule file — the `ospec-change` and `ospec-goal` skills carry the operating rules for their profile. Behind them: `for-ai/change-protocol.md` is the classic-change contract in full, and `for-ai/execution-protocol.md` is the goal controller reference, opened only when a named situation needs its detail and never by a classic change, which that file forbids. Use `ospec help` or subcommand help instead of carrying the complete CLI catalog in context.
  23. ## Visibility And Decisions
  24. - `Announce-Before-Act`: before workflow actions, state the OSpec workflow and stage, the command and artifact it writes, and any blocking gate. Only in the goal controller layer, also state the native agent count and the actual native mechanism; the classic change flow launches no subagents and must not announce one.
  25. - `Brainstorm-First`: before locking a goal design, surface open direction, architecture, API, data, UI, risk, and scope decisions one at a time. Prefer a durable required decision over a silent assumption.
  26. - `Zero-Setup`: the user states the requirement; the AI runs OSpec controller commands and the user only answers decisions. Do not ask the user to operate routine setup commands.
  27. - Required pending decisions block worker dispatch. Preserve `PENDING`, `NEEDS_CONTEXT`, `BLOCKED`, `DONE_WITH_CONCERNS`, and `DONE` rather than hiding uncertainty.
  28. Decision gates belong to the user on every harness: never auto-select a `recommended` option or resolve a gate yourself, present each gate through the capability ladder — a harness-native question UI (Claude Code `AskUserQuestion`, Gemini `ask_user`), else a plan/approval UI, else the decision report `Chat Prompt` in chat — and wait for the user's actual answer. You always ask; only the presentation differs. The full contract is stated where your profile is already sent: `for-ai/change-protocol.md` for a classic change, the `ospec-goal` skill and `for-ai/execution-protocol.md` for a goal.
  29. In Claude Code, install the managed hook once with `ospec session hook --target claude --apply` when missing; `PreToolUse(Task)` is then a hard dispatch gate and prompt hooks stay silent unless a required decision is pending. That hook is a Claude-only, opt-in convenience — `ospec session hook --target` accepts no other harness and `ospec init` writes no `.claude/` — so it never replaces the documented contract.
  30. ## Goal Controller Layer
  31. Use the full `ospec execute ...` task-graph/controller layer only for Goal work. A classic Change may use the shared `ospec execute decision` command for durable user choices, but it must not enter Goal bootstrap, workspace, dispatch, review, evidence, or Loop commands.
  32. A router routes: the controller invariants — preflight staging, the combined planning review and its repair allowance, worker profiles, dispatch and review binding, reviewer independence, evidence and archive gates — are not restated here. Load the ones you act on from the `ospec-goal` skill; `for-ai/execution-protocol.md` holds their authoritative detail, including the logical model-profile names, and is opened only when a named situation calls for it. Detailed goal artifacts live under `changes/active/<change>/artifacts/agents/` and `artifacts/reviews/`; read the current dispatch, review, or repair packet for exact paths and commands.
  33. Do not archive while task graph, review, decision, documentation, optional-step, worker-status, or verification gates are unresolved during normal closeout.
  34. ## Documentation And Archive
  35. Archiving a finalized change or goal writes its `SKILL.index.json.archived_changes` entry (carrying `features` and `doc_updates`), refreshes the affected `docs/project/feature-catalog.md` rows, and replaces each touched feature section's `ospec:last-change` traceability comment idempotently — the engine's only write into a human-owned document, and a comment failure warns instead of blocking. No file is generated under `docs/project/changes/`; render an archived change on demand with `ospec changes show <archive>`. Behavior, architecture, module, API, or operational changes must additionally update the relevant human-maintained `docs/project/` files. When the task graph enables the documentation contract, every task declares `documentation_updates`; use `[]` only when no project documentation changes are needed, include each declared document in `target_files`, and preserve dispatch-to-completion evidence of a meaningful normalized-content change.
  36. Use `ospec verify` for the active workflow. For normal closeout, use `ospec finalize [changes/active/<change>]`; use `ospec archive --check` only for preview. Finalize must verify completeness, archive, rebuild `docs/project/feature-catalog.md`, and rebuild `SKILL.index.json` so its `documents` and `archived_changes` sections locate the completed behavior and link declared durable project documents. Git commit remains separate.
  37. Force archive requires explicit user acceptance and is never an automatic fallback. First report the failing gates and every `NOT_VERIFIED` item to the user, then take their explicit acceptance; the CLI enforces its own exact-name confirmation and reason flags. Never infer that authorization from urgency, a blocker, or a request to "finish". A forced archive bypasses completion gates only — it preserves failed checks and pending state, and must never be described as completed behavior. The full procedure lives on the path that needs it: `for-ai/change-protocol.md` for a classic change, `for-ai/execution-protocol.md` for a goal.
  38. After archive, verify:
  39. - the completed behavior is discoverable through `docs/project/feature-catalog.md` and `ospec docs locate`;
  40. - the archived change renders from its index entry via `ospec changes show <archive>`;
  41. - project docs and archived change records are present in `SKILL.index.json`;
  42. - section offsets are stable under LF-normalized content;
  43. - no required documentation update was omitted.
  44. Use `ospec docs generate` for a docs-only repair or refresh. Do not create a change merely to repair project knowledge unless the user asks for one.
  45. ## Compact Command Routes
  46. ```text
  47. Initialize: ospec init [path] -> verify generated project shell
  48. Change: ospec change <name> -> implement -> ospec verify -> ospec finalize
  49. Goal: ospec goal <name> -> preflights -> task graph -> combined planning review -> workers/task reviews -> final review -> verify/finalize
  50. Docs: ospec docs generate [path] -> ospec docs status -> ospec index check
  51. Resume: ospec session [path] -> read brief/index -> run the persisted next safe command
  52. Troubleshoot: ospec status [path] -> ospec help
  53. ```
  54. Use CLI commands for initialization, verification, index generation, and archive. Do not replace managed operations with ad hoc filesystem edits.
  55. ## Completion Discipline
  56. Before claiming completion:
  57. 1. Verify the active workflow and fresh project checks.
  58. 2. Confirm relevant docs and documentation contracts.
  59. 3. Confirm worker/reviewer/decision/evidence gates for goals.
  60. 4. Confirm skills and indexes when knowledge changed.
  61. 5. After archive, confirm the feature and its documents are discoverable without replaying conversation history.
README.md · README · 360 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1><a href="https://ospec.ai/" target="_blank" rel="noopener noreferrer">OSpec.ai</a></h1>
  2. <p align="center">
  3. <a href="https://www.npmjs.com/package/@clawplays/ospec-cli"><img src="https://img.shields.io/npm/v/%40clawplays%2Fospec-cli?style=for-the-badge&logo=npm&label=npm" alt="npm"></a>
  4. <a href="https://www.npmjs.com/package/@clawplays/ospec-cli"><img src="https://img.shields.io/npm/dm/%40clawplays%2Fospec-cli?style=for-the-badge&logo=npm&label=downloads&cacheSeconds=300" alt="npm downloads"></a>
  5. <a href="https://github.com/clawplays/ospec/stargazers"><img src="https://img.shields.io/github/stars/clawplays/ospec?style=for-the-badge&logo=github" alt="GitHub stars"></a>
  6. <a href="LICENSE"><img src="https://img.shields.io/github/license/clawplays/ospec?style=for-the-badge&color=green" alt="License"></a>
  7. </p>
  8. <p align="center">
  9. <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 18+">
  10. <img src="https://img.shields.io/badge/npm-8%2B-CB3837?style=flat-square&logo=npm&logoColor=white" alt="npm 8+">
  11. <img src="https://img.shields.io/badge/language-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
  12. <img src="https://img.shields.io/badge/workflow-3_steps-0F766E?style=flat-square" alt="3-step workflow">
  13. </p>
  14. <p align="center">
  15. <strong>English</strong> |
  16. <a href="docs/README.zh-CN.md">中文</a> |
  17. <a href="docs/README.ja.md">日本語</a> |
  18. <a href="docs/README.ar.md">العربية</a>
  19. </p>
  20. The official OSpec CLI package is `@clawplays/ospec-cli`, and the official command is `ospec`. OSpec is a spec-driven, agentic workflow framework for AI coding agents — it brings spec-driven development (SDD) and Loop Engineering (a verifiable plan → act → verify goal loop) to Claude Code, Codex, Gemini, OpenCode, MCP-based agents, and plain CLI workflows.
  21. <p align="center">
  22. <a href="docs/prompt-guide.md">Prompt Guide</a> |
  23. <a href="docs/usage.md">Usage</a> |
  24. <a href="docs/project-overview.md">Overview</a> |
  25. <a href="docs/installation.md">Installation</a> |
  26. <a href="docs/skills-installation.md">Skills Installation</a> |
  27. <a href="https://github.com/clawplays/ospec/issues">Issues</a>
  28. </p>
  29. ## Why OSpec?
  30. AI coding assistants are powerful, but requirements that live only in chat history are hard to inspect, review, and close out cleanly. OSpec adds a lightweight workflow layer so the repository can hold the change context before code is written and after the work ships.
  31. - **Spec-driven work, saved to your repo** — OSpec turns a request into files (proposal, design, plan, tasks, reviews, verification evidence) that live in your repo instead of in chat history, so any assistant (Codex/GPT, Claude Code, Gemini, OpenCode, or plain CLI) can pick up exactly where the last one stopped.
  32. - **`ospec change` — the everyday fast flow** — one requirement becomes one active change on a short `init -> change -> verify/finalize` path, kept lightweight and easy to review.
  33. - **`ospec goal` for larger or riskier work** — describe the result you need; the AI asks important questions, writes an inspectable plan, implements the work, runs tests, requests an independent review, updates project docs, and continues until the result is proven.
  34. - **One predictable Goal workflow** — every Goal uses the same fast quality path, pauses for material user decisions, and saves progress in the repository so a later session can resume it.
  35. ## Install With npm
  36. ```bash
  37. npm install -g @clawplays/ospec-cli
  38. ```
  39. Official package: `@clawplays/ospec-cli`
  40. Command: `ospec`
  41. Verify install: `ospec --help`
  42. ## Quick Start
  43. OSpec only takes 3 steps:
  44. 1. initialize OSpec in your project directory
  45. 2. create and advance one change for a requirement, document update, or bug fix
  46. 3. archive the accepted change after deployment and validation are complete
  47. ### 1. Initialize OSpec In Your Project Directory
  48. Recommended prompt:
  49. ```text
  50. OSpec, initialize this project.
  51. ```
  52. Claude / Codex skill mode:
  53. ```text
  54. /ospec initialize this project.
  55. ```
  56. <details>
  57. <summary>Command line</summary>
  58. ```bash
  59. ospec init .
  60. ospec init . --summary "Internal admin portal for operations"
  61. ospec init . --summary "Internal admin portal for operations" --tech-stack node,react,postgres
  62. ospec init . --architecture "Single web app with API and shared auth" --document-language en-US
  63. ```
  64. CLI notes:
  65. - `--summary`: project overview text written into the generated docs
  66. - `--tech-stack`: comma-separated stack list such as `node,react,postgres`
  67. - `--architecture`: short architecture description
  68. - `--document-language`: generated doc language, choose from `en-US`, `zh-CN`, `ja-JP`, or `ar`
  69. - AI-first language resolution order: explicit language request in the conversation -> current conversation language -> persisted project language in `.skillrc`
  70. - CLI language resolution order: explicit `--document-language` -> persisted project language in `.skillrc` -> existing project docs / managed `for-ai/*` guidance / asset manifest -> fallback `en-US`
  71. - OSpec persists the chosen project document language in `.skillrc` and reuses it for `for-ai` guidance, `ospec change`, and `ospec update`
  72. - new projects initialized by `ospec init` default to the nested layout: root `.skillrc` and `README.md`, with OSpec-managed files under `.ospec/`
  73. - 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
  74. - CLI commands still accept shorthand like `changes/active/<change-name>`, but the physical path in nested projects is `.ospec/changes/active/<change-name>`
  75. - if you pass these values, OSpec uses them directly when generating project docs
  76. - if you do not pass them, OSpec reuses existing docs when possible and otherwise creates placeholder docs first
  77. </details>
  78. ### 2. Create And Advance A Change
  79. Use this for requirement delivery, documentation updates, refactors, and bug fixes.
  80. Recommended prompt:
  81. ```text
  82. OSpec, create and advance a change for this requirement.
  83. ```
  84. Claude / Codex skill mode:
  85. ```text
  86. /ospec-change create and advance a change for this requirement.
  87. /ospec-goal create and advance a full goal for this requirement.
  88. ```
  89. <details>
  90. <summary>Command line</summary>
  91. ```bash
  92. ospec change docs-homepage-refresh .
  93. ospec change fix-login-timeout .
  94. ospec change update-billing-copy .
  95. ```
  96. </details>
  97. ### Agent Execution (Goal Workflow)
  98. The classic change flow above stays simple: `proposal.md` → `tasks.md` → implement → `verification.md` → `review.md`, with no controller layer. The agent controller layer — parallel worker dispatch, reviewer gates, and durable evidence — belongs to the full goal workflow. Use it with `ospec goal`, or on a single change only when you explicitly opt into agent/worker execution. OSpec keeps the controller state in repo artifacts, and the current AI harness starts native worker agents when available.
  99. ```bash
  100. ospec session .
  101. ospec execute bootstrap changes/active/<goal-name>
  102. ospec execute workspace changes/active/<goal-name>
  103. ospec execute status changes/active/<goal-name>
  104. ospec execute dispatch changes/active/<goal-name> --limit 3
  105. ospec execute launch changes/active/<goal-name> --task <task-id> --target codex
  106. ospec execute complete <task-id> changes/active/<goal-name> --status DONE --summary "..."
  107. ospec loop tick changes/active/<goal-name> # issues task/final reviews with executor provenance
  108. ospec execute verify changes/active/<goal-name> --command "npm test" --status PASSED --exit-code 0
  109. ```
  110. `launch` writes `artifacts/agents/launch-plan.md`; it does not start workers by itself. Codex/GPT use `spawn_agent` plus bounded `wait_agent`, Claude Code uses bounded background Task polling when available, Gemini uses `@generalist`, and OpenCode uses `@mention`. Every native adapter returns from one wait within 60 seconds, refreshes heartbeats, persists each completed child immediately, and re-ticks. The 60-second boundary limits one controller poll, not the AI task runtime: a live child continues across polls up to its configurable absolute action deadline. OSpec never starts Orca, Codex, Claude, or another agent CLI as a fallback. If the current model harness cannot provide native subagents, executable dispatch blocks until a supported harness reports a fresh capability.
  111. For a controller-owned Goal, task and final reviews are always issued by `ospec loop tick` so the dispatch is atomically bound to the real reviewer executor. Use `ospec execute review` directly only in a non-controller workflow.
  112. ### 3. Archive After Acceptance
  113. After the requirement has passed deployment, testing, QA, or other acceptance checks, archive the validated change.
  114. Recommended prompt:
  115. ```text
  116. OSpec, archive this accepted change.
  117. ```
  118. Claude / Codex skill mode:
  119. ```text
  120. /ospec archive this accepted change.
  121. ```
  122. <details>
  123. <summary>Command line</summary>
  124. ```bash
  125. ospec verify changes/active/<change-name>
  126. ospec finalize changes/active/<change-name>
  127. ```
  128. Explicit incomplete archive, only after the user accepts the unresolved risk:
  129. ```bash
  130. ospec finalize changes/active/<change-name> --force-archive --confirm-force-archive <exact-change-name> --reason "Accepted unresolved verification risk"
  131. ```
  132. Archive notes:
  133. - run your project-specific deploy, test, and QA flow first
  134. - use `ospec verify` to confirm the active change is ready
  135. - use `ospec finalize` to rebuild indexes and archive the accepted change
  136. - force archive is never automatic: it requires the force flag, an exact change-name confirmation, and an audit reason; it refuses any missing, `issued`, or `running` Loop item, but may preserve an unconsumed pointer whose items are all terminal; the archive is marked `forced`, `incomplete`, and `accepted-risk` instead of completed
  137. - new nested projects archive under `.ospec/changes/archived/YYYY-MM/YYYY-MM-DD/<change-name>`; CLI shorthand under `changes/archived/...` still works
  138. - existing flat archives are reorganized by `ospec update`
  139. </details>
  140. ### Goal: Use It For Work That Needs More Care
  141. Use a Goal only when you choose the full workflow. A user-selected Change remains a Change regardless of complexity, file count, risk, or batch size; create it with `ospec change` (`ospec new` remains an alias).
  142. A Change uses compact stage-aware guidance, one lightweight current-AI review, and derived closeout state. When verification, documentation, and review gates pass, `APPROVED` or `APPROVED_WITH_CONCERNS` may finalize and archive automatically; explicit batches stay sequential in the queue.
  143. Start from a terminal:
  144. ```bash
  145. ospec goal improve-checkout --target codex --execution-model controller --harness-interactive true --native-subagents supported
  146. ```
  147. Then tell the AI what outcome you need in ordinary language. You can also skip the terminal command and say: "Use OSpec goal for this requirement and carry it through to completion."
  148. That is all a normal user needs to operate. The AI will:
  149. 1. Ask only the choices that materially change the result.
  150. 2. Write the proposal, design, and implementation plan, then run deterministic design and plan preflights without launching reviewer children.
  151. 3. Derive the task graph and run one independent combined planning review across requirements, architecture, task boundaries, dependencies, and verification coverage.
  152. 4. If that review finds issues, repair the planning set once as a group and run one fresh combined planning review. A repeated failure stops instead of looping.
  153. 5. Run conflict-safe implementation workers, independent task reviews, an integration-focused final review, verification, documentation sync, and archive.
  154. You remain in control. The AI explains what it is about to do, pauses when it needs a decision, and records task, review, repair, verification, and loop progress in the repository so a fresh worker or later session can continue without replaying the conversation. You do not need to run the internal `ospec execute` commands yourself.
  155. Every Goal uses the same fast quality workflow. Required user decisions always block implementation. The integrated goal loop reads `task-graph.json`, emits a bounded conflict-safe parallel batch, and explains whether configured limits, graph conflicts, token funding, an optional configured allowlist, or known harness capacity reduced it. Unknown native capacity uses an implementation fallback of three; a larger positive session-bound capacity can support configured batches such as 5-10 when the graph, shared resources, token budget, and `maxParallel` allow. The current IDE AI launches one fresh native subagent per referenced packet, polls with bounded waits, refreshes heartbeats, persists each finished result immediately, and continues ticking without another user prompt. If the IDE lacks native subagents, controller dispatch fails clearly.
  156. To see progress, child executor ids, heartbeat due times, leases, token sources, and concurrency reasons, run `ospec loop status --brief`; controller agents should use `ospec loop run --once --compact-json` to avoid repeating large runtime-adapter objects. Use `ospec loop configure` for concurrency, budgets, action runtime limits, evidence-result grace, and optional allowlists. IDE controllers persist child ownership with `ospec loop heartbeat` and atomically commit successful evidence plus executor outcome with `ospec loop finalize`. After a confirmed session or child loss, `ospec loop recover --force` expires only unfinished items. Task and final repair convergence guards prevent repeated finding sets from cycling indefinitely. Durable worker blockers are not redispatched, technical executor failures remain retryable, and independent ready tasks run first. Advanced loop and triage commands are documented in [docs/loop-engineering.md](docs/loop-engineering.md).
  157. Internally, OSpec validates design and implementation-plan readiness inline before task graph derivation, keeps implementation and code review separate, feeds blocked work and review findings into transactional retry or grouped repair, and requires current test evidence before the goal is considered complete.
  158. Claude Code hard enforcement (one-time; the AI runs this for you automatically in a Claude Code harness):
  159. ```bash
  160. ospec session hook --target claude --apply
  161. ```
  162. This writes a hook bundle under `.ospec/hooks/claude/` and merges it into `.claude/settings.json` (idempotent and reversible). The hooks:
  163. - announce every subagent dispatch and every `ospec` command at the tool level,
  164. - hard-block subagent dispatch while a required decision is still pending,
  165. - inject the static Announce-Before-Act / Brainstorm-First contract only on startup, clear, or compact, while prompt submission stays silent unless a required decision is pending.
  166. Hooks load at session start, so they take effect from the next Claude Code session.
  167. ## Update With npm
  168. For an existing OSpec project, after upgrading the CLI with npm, run this in the project directory to refresh the project's OSpec files:
  169. ```bash
  170. ospec update
  171. ```
  172. `ospec update` also migrates legacy root-level `build-index-auto.cjs` / `build-index-auto.js` tooling into `.ospec/tools/build-index-auto.cjs` and refreshes OSpec-managed hook entrypoints to use the new location.
  173. It also repairs older OSpec projects that still have an OSpec footprint but are missing newer core runtime directories, and refreshes managed skills and archive layout metadata.
  174. For nested projects that still carry legacy knowledge under `.ospec/src/` or `.ospec/tests/`, `ospec update` migrates those paths into `.ospec/knowledge/src/` and `.ospec/knowledge/tests/`.
  175. It does not upgrade the CLI itself, and it does not migrate active / queued changes automatically.
  176. It also does not switch a classic project layout to nested automatically.
  177. If you want to convert an older classic project to the new layout, run `ospec layout migrate --to nested` explicitly.
  178. ## How The OSpec Workflow Works
  179. ```text
  180. ┌─────────────────────────────────────────────────────────────────┐
  181. │ 1. USER REQUEST │
  182. │ "OSpec, create and advance a change for this task." │
  183. └─────────────────────────────────────────────────────────────────┘
  184. │
  185. ▼
  186. ┌─────────────────────────────────────────────────────────────────┐
  187. │ 2. INIT TO CHANGE-READY │
  188. │ ospec init │
  189. │ - .skillrc │
  190. │ - README.md │
  191. │ - .ospec/ │
  192. │ - .ospec/changes/active + .ospec/changes/archived │
  193. │ - .ospec/SKILL.md + .ospec/SKILL.index.json + .ospec/for-ai│
  194. │ - .ospec/docs/project/* baseline knowledge docs │
  195. │ - reuse docs or fall back to placeholders │
  196. └─────────────────────────────────────────────────────────────────┘
  197. │
  198. ▼
  199. ┌─────────────────────────────────────────────────────────────────┐
  200. │ 3. EXECUTION │
  201. │ ospec change <change-name> # classic fast change │
  202. │ ospec goal <goal-name> # full goal workflow │
  203. │ ospec brainstorm / plan (optional pre-change aids) │
  204. │ ospec session │
  205. │ ospec session hook │
  206. │ ospec progress │
  207. │ ospec execute bootstrap / handoff / preflight / status │
  208. │ ospec execute next │
  209. │ ospec execute workspace / worktree / worktree --create │
  210. │ ospec execute worktree --cleanup / finish │
  211. │ ospec execute dispatch / launch / collect / retry / review │
  212. │ ospec execute debug │
  213. │ ospec execute tdd │
  214. │ ospec execute verify │
  215. │ ospec execute sync │
  216. └─────────────────────────────────────────────────────────────────┘
  217. │
  218. ▼
  219. ┌─────────────────────────────────────────────────────────────────┐
  220. │ 4. DEPLOY + VALIDATE │
  221. │ project deploy / test / QA │
  222. │ ospec verify │
  223. └─────────────────────────────────────────────────────────────────┘
  224. │
  225. ▼
  226. ┌─────────────────────────────────────────────────────────────────┐
  227. │ 5. ARCHIVE │
  228. │ ospec finalize │
  229. │ rebuild index + archive │
  230. └─────────────────────────────────────────────────────────────────┘
  231. ```
  232. ## Core Concepts
  233. | Concept | What It Means |
  234. |---------|---------------|
  235. | **Protocol Shell** | The minimum collaboration skeleton: root `.skillrc` and `README.md`, plus managed OSpec files under `.ospec/` for change state, SKILL docs, index state, `for-ai/` guidance, and project docs. |
  236. | **Project Knowledge Layer** | Explicit project context such as `docs/project/*`, layered skill files, and index state that AI can read consistently. |
  237. | **Active Change** | A dedicated execution container for one small or routine requirement, using the classic fast files: `proposal.md`, `tasks.md`, `state.json`, `verification.md`, and `review.md`. |
  238. | **Active Goal** | A full-workflow execution container created with `ospec goal`, adding `design.md`, `implementation-plan.md`, `artifacts/agents/task-graph.json`, handoff artifacts, document-review artifacts, launch-plan artifacts, worker-run artifacts, reviewer-run artifacts, retry artifacts, review artifacts, `artifacts/agents/worker-status.md`, and evidence artifacts. |
  239. ## Features
  240. - **Change-ready initialization**: `ospec init` creates the protocol shell and baseline project knowledge docs in one pass.
  241. - **Guided initialization**: AI-assisted init can ask once for missing summary or tech stack; direct CLI init falls back to placeholder docs when context is missing.
  242. - **Stable project language**: the chosen document language is stored in `.skillrc` so later guidance and generated change docs stay consistent unless you explicitly change it.
  243. - **Living feature docs with a locator**: feature sections in human-owned docs declare `<!-- ospec:feature <slug> code:<paths> -->`; `docs/project/feature-catalog.md` carries one row per declared feature — slug, one line, `doc#section`, status, last-change archive — and `ospec docs locate --feature <slug>` or `--affects <path>` returns that one section's location and line range so an agent reads one section instead of a document.
  244. - **Archived changes render on demand**: archiving writes the change's index entry (with its features and documentation updates), refreshes the affected catalogue rows, and replaces the section's `ospec:last-change` traceability comment idempotently — the engine's only write into a human-owned document, and a comment failure warns instead of blocking. Nothing is generated under `docs/project/changes/`; `ospec changes show <archive>` renders the summary, affects, file list, and verification commands from the index and the archive directory. Goals still update the relevant human-maintained architecture, API, module, or operational docs.
  245. - **Documentation obligations**: at planning time `ospec docs obligations --apply` derives this change's obligations from its `change_type` and features (falling back to `affects` resolution through the `code:` declarations) with the resolved `path#section` already filled in — a fix checks the section for the pre-fix wrong behaviour, a refactor verifies it and may record `verified_unchanged` with `ospec docs confirm`. `.skillrc` `docs_contract.mode: warn|strict` decides whether an unmet required obligation warns or blocks archiving. `ospec docs audit` lists feature sections whose `code:` paths changed since their last recorded change, and `ospec docs migrate` converts legacy generated documents into feature docs through four gated phases.
  246. - **Scoped review evidence and cost metrics**: task and final review dispatches write `artifacts/agents/review-packages/*.diff` with scoped Git evidence, while `artifacts/agents/execution-metrics.json` records packet/report/package bytes and task duration. Goal task graphs can enable `documentation_updates` so missing or undeclared project docs block archive.
  247. - **Tracked requirement execution**: small changes keep proposal, tasks, state, verification, and review files aligned; full goals also keep design, implementation plan, task graph, handoff, review, worker status, and evidence artifacts aligned.
  248. - **Goal experience contracts**: every goal runs with `Announce-Before-Act` (the AI announces its skill and stage, the `ospec execute …` command and the artifact it writes, and each subagent dispatch), `Brainstorm-First` (open direction, architecture, API, UI, risk, and scope decisions are asked one at a time through the native question UI before design is locked), and `Zero-Setup` (you only start a goal and describe the requirement — the AI runs every `ospec` command itself). In Claude Code, `ospec session hook --target claude --apply` adds hooks that announce every dispatch and hard-block subagent dispatch while a required decision is still pending.
  249. - **Optional pre-change aids**: `ospec brainstorm` writes durable exploration artifacts under `.ospec/brainstorms/`, with an optional static visual companion; `ospec plan` writes plan drafts under `.ospec/plans/` and only updates `implementation-plan.md` when `--apply` is passed. The Change flow starts with `ospec change` (`ospec new` is an alias); the Goal flow starts with `ospec goal` only when selected by the user.
  250. - **Session brief and hooks**: `ospec session` writes `.ospec/session-brief.json` and `.ospec/session-brief.md` so agents or humans entering an existing project can see active changes, queued changes, queue-run state, indexed document and archived-feature counts, a cache fingerprint, and the next safe command before touching a change; `ospec session hook --target claude` writes opt-in harness startup artifacts plus a Claude Code hook bundle under `.ospec/hooks/`, and `--apply` idempotently merges it into `.claude/settings.json`.
  251. - **Integrated goal loop**: `ospec loop run --once` (or `ospec loop tick`) emits token-bounded planning, task, review, and verification actions for fresh model-native subagents. It uses packet paths instead of duplicating the whole goal, persists pending actions, and stops repeated repair findings instead of cycling. Optional configured allowlists add an explicit path and command boundary without creating another workflow level.
  252. - **Task graph controller**: `ospec execute bootstrap` writes a one-change startup/resume snapshot; `preflight` records deterministic design and implementation-plan evidence under `artifacts/agents/planning-preflights/`; `workspace` records git safety; `dispatch`, `launch`, `complete`, and `review` settle native-subagent packets; `debug`, `tdd`, and `verify` record durable evidence; `sync` rebuilds derived status.
  253. - **Fast planning quality**: deterministic preflights cost no model round trip, while one independent combined planning reviewer checks requirement, architecture, task-graph, dependency, and verification semantics. A `NEEDS_CHANGES` decision permits one grouped planning repair and at most one delta-scoped re-review; a repair executor failure with no planning edits re-arms instead of consuming the allowance, and all-medium-or-lower findings settle deterministically as `APPROVED_WITH_CONCERNS` after the repair. Planning approvals are invalidated only by semantic planning changes, never by execution progress; repeated semantic failure is a stable blocker.
  254. - **Measured execution and grouped repair**: command runners can write authoritative usage to `OSPEC_USAGE_FILE` for automatic ingestion, while `--usage-file` remains a manual input. Metrics distinguish complete, partial, and missing coverage. `ospec execute repair` turns all structured `NEEDS_CHANGES` findings into one repair task.
  255. - **Verified durable documentation**: declared documentation targets capture before/after normalized content hashes, so an unchanged file cannot satisfy a new run. The feature catalogue links completed work directly to the durable project documents it updated.
  256. - **Queue helpers**: `queue` and `run` support explicit multi-change execution when one active change is not enough.
  257. - **Skill management**: install and inspect OSpec skills for Codex and Claude Code.
  258. - **Standard closeout**: `finalize` verifies and archives the change, then refreshes the feature catalogue and knowledge index before manual Git commit. It never overwrites human-maintained architecture, module, or API prose.
  259. ## Documentation
  260. ### Core Docs
  261. - [Prompt Guide](docs/prompt-guide.md)
  262. - [Usage](docs/usage.md)
  263. - [Project Overview](docs/project-overview.md)
  264. - [Installation](docs/installation.md)
  265. - [Skills Installation](docs/skills-installation.md)
  266. ## Repository Structure
  267. ```text
  268. dist/ Compiled CLI runtime
  269. assets/ Managed protocol assets, hooks, and skill payloads
  270. docs/ Public documentation
  271. scripts/ Release and installation helpers
  272. .ospec/templates/hooks/ Hook templates shipped with the package
  273. ```
  274. ## License
  275. This project is licensed under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.