# Ospec Change > Create or advance a lightweight OSpec change using the classic fast workflow. Use when this capability is needed. - Skill: `tomevault-io/ospec-change` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/ospec-change` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ospec-change/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/ospec-change --- # OSpec Change Use this skill for small or routine requirements where the classic OSpec 1.0 change flow is enough. ## Scope This skill is the fast change lifecycle inside an initialized OSpec project: - requirement intake - change naming or matching - proposal and task refinement - implementation guidance - verification - archive readiness check - finalize closeout Use `ospec-goal` instead when the work needs design docs, implementation planning, task graph dispatch, parallel workers, document review, evidence artifacts, or full review gates. ## Read Order 1. `.skillrc` 2. `.ospec/SKILL.index.json` for nested projects, or root `SKILL.index.json` for legacy classic projects 3. `.ospec/for-ai/ai-guide.md` for nested projects, or legacy `for-ai/ai-guide.md` 4. `.ospec/for-ai/execution-protocol.md` for nested projects, or legacy `for-ai/execution-protocol.md` 5. `.ospec/changes/active//proposal.md` for nested projects, or legacy `changes/active//proposal.md` 6. `.ospec/changes/active//tasks.md` for nested projects, or legacy `changes/active//tasks.md` 7. `.ospec/changes/active//state.json` for nested projects, or legacy `changes/active//state.json` 8. `.ospec/changes/active//verification.md` for nested projects, or legacy `changes/active//verification.md` 9. `.ospec/changes/active//review.md` for nested projects, or legacy `changes/active//review.md` ## Language - Follow the project-adopted document language from managed `for-ai/` guidance, `.skillrc` `documentLanguage`, and existing change docs. - Write every change document you author (`proposal.md`, `tasks.md`, `verification.md`, `review.md`, and brainstorm content) in that one language. Do not mix Chinese and English within a change. - Keep Chinese projects in Chinese unless the repo explicitly adopts English. ## Visibility & Decisions - `Announce-Before-Act`: never run the change flow silently. Announce in one line which skill you are using (`ospec-change`) and the current stage, which `ospec` command you are about to run and the artifact it writes, and which gate is blocking when progress stops. - `Brainstorm-First`: before implementing, confirm scope and acceptance with the user when anything is ambiguous, and ask one question at a time instead of silently assuming direction, API, UI, risk, or scope. Record the agreed scope in `proposal.md` rather than guessing. **NEVER auto-select the recommended option or resolve a decision gate yourself — `recommended` is only a hint to show the user; present every gate and wait for the user's actual choice instead of running the change in one shot.** **Present each open decision using the best interactive mechanism your harness has — a native question UI (Claude Code `AskUserQuestion`, Gemini `ask_user`) if available, otherwise your plan/approval UI (Codex Plan mode) if available, otherwise plain chat text — you always ask the user, only the presentation differs.** When you run `ospec brainstorm`, do not leave it as an unanswered template: ask the user the decision gates and record each answer with `ospec brainstorm resolve [path] --brainstorm --gate --select ` so the brainstorm has a result. - `Zero-Setup`: the user only describes the change; you run every `ospec` command yourself and never ask them to type setup or execution commands. In a Claude Code harness, if `.claude/settings.json` does not yet reference `.ospec/hooks/claude/ospec-claude-hook.cjs`, run `ospec session hook --target claude --apply` once (idempotent). ## Required Logic 1. Inspect repository state first when posture is unclear. 2. If the repo is not initialized, stop at initialization guidance instead of forcing a change. 3. If the request is a new requirement, derive a concise kebab-case change name and create it with `ospec new [path]`. 4. If the matching active change already exists, continue it instead of duplicating it. 5. Keep the work inside the active change container. 6. Keep `proposal.md`, `tasks.md`, `state.json`, `verification.md`, and `review.md` aligned with actual execution. 7. Do not create `design.md`, `implementation-plan.md`, task graphs, worker packets, or review artifacts for routine small changes. 8. Use `ospec-goal` when the requirement is complex enough to need the full workflow. 9. Use OSpec closeout commands instead of inventing a parallel process. 10. Closeout is automatic when ready: once implementation, `verification.md`, and `review.md` are aligned and `ospec verify [changes/active/]` passes, run `ospec finalize [changes/active/]` yourself. Do not stop at `ospec archive ... --check` (it is a preview only) and do not wait for the user to ask before archiving. **Closeout uses `direct-closeout` (archive locally, no PR) and `manual` merge as defaults — do NOT ask the user about PR, merge, branch, or worktree strategy; uncommitted change/OSpec files in the working tree are normal and do not block archive. Only open a PR if the user explicitly asked.** Only pause closeout when a gate genuinely needs a human: a pending required user decision, an unapproved blocking plugin gate (e.g. Checkpoint), real blockers reported by verify or archive, or an explicit user request to preview or approve before archiving. ## Commands ```bash ospec status [path] ospec new [path] ospec changes status [path] ospec progress [changes/active/] ospec verify [changes/active/] ospec archive [changes/active/] --check # optional preview only — do not stop here ospec finalize [changes/active/] # run automatically once verify passes and no human gate is pending ``` ## Guardrails - Do not assume dashboard workflows exist. - Do not confuse repository initialization with change execution. - Do not enter queue mode unless the user explicitly asks for queue behavior. - Do not escalate to the full goal workflow unless the work is complex, cross-cutting, high-risk, or explicitly requested as a goal. - Do not claim completion until implementation, verification notes, and closeout status are aligned. - If real project tests exist, run or recommend them separately from `ospec verify`. --- > Source: [clawplays/ospec](https://github.com/clawplays/ospec) — distributed by [TomeVault](https://tomevault.io).