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, and finalize closeout.

The user owns profile selection. Once the user chooses a change, keep it on the classic flow regardless of complexity, flags, file count, or batch size. Never auto-promote, reject, or replace it with a Goal. Use ospec-goal only when the user explicitly selects a Goal.

Read Order

1. .skillrc
2. ospec index query <keyword...> for the relevant .ospec/SKILL.index.json entries (root SKILL.index.json in legacy classic projects) — never read the whole index file, which grows without bound as changes archive
3. .ospec/for-ai/change-protocol.md for nested projects, or legacy for-ai/change-protocol.md
4. .ospec/changes/active/<change>/proposal.md, tasks.md, and state.json for nested projects, or their legacy classic paths
5. Read verification.md only when entering verification
6. Read review.md only when entering closeout

change-protocol.md is the whole classic contract — the decision-gate ladder, force archive, and every other rule this profile needs are stated there in full. for-ai/execution-protocol.md is the goal controller layer and tells this profile not to open it, so never go there for a change rule. If change-protocol.md itself is missing, use for-ai/ai-guide.md to route back to the protocol for the active profile.

Language

Write every change document and brainstorm you author in the project document language (.skillrc documentLanguage / managed for-ai/ guidance / existing change docs). Never infer that language from product copy, site locale, or an "English-first" requirement, and never mix languages within one change.

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 (forked decisions only): raise a gate only for a genuine fork — mutually exclusive API shapes, competing UI approaches, data-model or storage choices, destructive or hard-to-reverse operations, or a scope conflict with what the user asked for. For routine unambiguous changes — an evident-cause bug fix, a mechanical refactor, a docs update, a small addition with one reasonable implementation — do not open a gate or run ospec brainstorm: proceed with the reasonable default and record your assumptions in proposal.md.
• On a genuine fork, ask one question at a time and never auto-select a recommended option or resolve a gate yourself — recommended is a hint you show the user, never a choice you may take. Present every gate through the capability ladder, in this order: a harness-native question UI when the harness has one (Claude Code AskUserQuestion, Gemini ask_user), otherwise its plan/approval UI (for example Codex plan mode), otherwise the decision report Chat Prompt as plain chat text. You always ask the user and wait for their actual answer; only the presentation differs, and a required pending decision blocks implementation and closeout identically on every harness. Record the gate with ospec execute decision [changes/active/<change>] --id <id> --question "..." --option id:label:impact [--recommended id] [--required] and the answer with --select <option-id> --answered-by user; that shared decision command is the one controller command a change may use. If you did run ospec brainstorm, do not leave it an unanswered template — record each answer with ospec brainstorm resolve [path] --brainstorm <id> --gate <gate-id> --select <option-id> --answered-by user. In Claude Code the managed session hook re-injects this contract at runtime, but it is a convenience for one harness, not the source of the rule: the contract above binds on Codex, Gemini, Grok, OpenCode, Cursor and Copilot too. Full text: for-ai/change-protocol.md.
• 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 change <change-name> [path] (ospec new remains a compatibility alias).
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.