openspec
Spec-driven development with OpenSpec. Use when the user mentions OpenSpec, OPSX, spec-driven development, SDD, change proposals, delta specs, /opsx commands, or wants structured planning for features, migrations, refactors, or bug fixes.
- License 许可
- Unlicense
- 所属仓库
- saski/arnesto
- 最近更新
- 2026-11-12
- Stars
- ★ 6
- Forks
- 0
01 前言 Front Matter
- name
- openspec
- metadata
- { "owner": "engineering", "status": "active", "outputs": [ "change-proposal", "delta-spec", "design", "task-list", "implementation-verification" ], "pattern": "pipeline", "category": "workflow-automation", "review_cycle_days": 90, "benchmark_after_model_update": true }
- description
- Spec-driven development with OpenSpec. Use when the user mentions OpenSpec, OPSX, spec-driven development, SDD, change proposals, delta specs, /opsx commands, or wants structured planning for features, migrations, refactors, or bug fixes.
- compatibility
- Portable Agent Skills core; OpenSpec CLI is optional but preferred when installed.
02 资源文件 1
- 脚本scripts/install-openspec1.5 KB
03 SKILL.md 正文
OpenSpec
Use OpenSpec as the planning layer when work needs durable requirements, reviewable intent, or a multi-session implementation trail. Keep the repository's normal engineering rules active: start implementation with tests where applicable, work in small steps, and run the project's canonical checks.
Before You Start
- Check whether the current repository already has an
openspec/directory ordocs/openspec/. - Resolve and verify the CLI with the NVM-aware procedure below.
- If OpenSpec is missing and the user asked to adopt it, initialize it with the shared installer after confirming the target repository.
- If OpenSpec is present, read the relevant
openspec/specs/*/spec.mdand activeopenspec/changes/<change>/artifacts before proposing edits. Ifopenspec/is a symlink todocs/openspec/, keep usingopenspec/...paths for CLI compatibility while recognizing that the physical files live underdocs/openspec/. - Treat OpenSpec artifacts as source files: update them with the same care as code, keep language precise, and include them in validation.
CLI Runtime Resolution
Non-interactive clients such as Codex App may not inherit the shell that loads NVM. On this machine OpenSpec is managed by the NVM default Node installation; the exact Node version is intentionally not hard-coded. Before reporting a missing CLI, use this resolution sequence:
if ! openspec --version >/dev/null 2>&1; then
if [ -s "$HOME/.nvm/nvm.sh" ]; then
. "$HOME/.nvm/nvm.sh"
fi
fi
openspec --version
Do not conclude that OpenSpec is unavailable merely because it is absent from
the initial PATH, or because ~/.agents/bin/openspec reports
env: node: No such file or directory. Load NVM and retry first. Only treat it
as missing when the post-NVM openspec --version still fails.
Shared Installer
This tooling repo exposes a portable installer through the shared ~/.agents symlink:
~/.agents/skills/openspec/scripts/install-openspec
~/.agents/skills/openspec/scripts/install-openspec /path/to/repo
The installer uses this placement policy:
- If the target repository already has
docs/, createdocs/openspec/and a rootopenspec -> docs/openspecsymlink soopenspecCLI commands work from the repo root. - If the target repository has
thoughts/but nodocs/, createthoughts/openspec/and a rootopenspec -> thoughts/openspecsymlink. - If the target repository does not have
docs/orthoughts/, create the normal rootopenspec/directory. - Do not move an existing real root
openspec/directory automatically; treat it as an existing installation.
Default Workflow
Use the core OPSX path for most changes:
- Explore unclear requirements before creating artifacts.
- Propose the change and generate planning artifacts.
- Review and refine
proposal.md, delta specs,design.md, andtasks.md. - Apply tasks one at a time, checking off completed items in
tasks.md. - Verify implementation against the proposal, specs, design, and tasks.
- Sync and archive the change when the implementation is complete.
If slash commands are available in the active tool, prefer:
/opsx:explorefor investigation before committing to a change./opsx:propose <change>for the default proposal-to-tasks path./opsx:apply <change>for implementation./opsx:verify <change>when the expanded workflow is enabled./opsx:sync <change>to merge delta specs into canonical specs when needed./opsx:archive <change>to finalize completed work.
If the tool does not expose slash commands, perform the same workflow directly in files under openspec/changes/<change>/. In docs-first repositories, that path may resolve through the root symlink to docs/openspec/changes/<change>/.
CLI Use
Prefer CLI commands for repository state and validation when available:
openspec list
openspec list --specs
openspec show <change-or-spec>
openspec status <change>
openspec validate --all
Use --json for agent-readable output when the command supports it. Do not build long-lived automation on beta workspace commands unless the user explicitly asks for experimental workspace setup.
Artifact Standards
- Name change folders in kebab-case and avoid generic names like
updateorwip. - Write requirements with
SHALLstatements and concrete scenarios. - Keep scenarios in
GIVEN,WHEN,THEN, and optionalANDform. - Keep tasks small enough to implement and verify independently.
- Update the design when implementation decisions change.
- Run OpenSpec validation and the repository's canonical validation before claiming completion.
Brownfield Repositories
OpenSpec works incrementally. Do not try to generate a full specification library upfront unless the user asks for a documentation pass. For mature codebases, create or update specs around the change being made, then let the spec library grow through real work.
Setup Guidance
When initializing OpenSpec, choose the smallest tool scope that matches the user's request:
~/.agents/skills/openspec/scripts/install-openspec
openspec update
After upgrading the CLI, run openspec update in initialized repositories so generated tool instructions stay current.
04 同仓库更多 Skills
visualize
Use /visualize for creating compact charts, diagrams, or other visuals inline as part of the conversation itself. It chooses among Markdown tables, Mermaid, inline HTML, and other supported in-transcript forms. Use Canvas for durable artifacts outside the transcript that users may revisit, refine, or share.
update-cursor-settings
Modify Cursor/VSCode user settings in settings.json. Use when you want to change editor settings, preferences, configuration, themes, font size, tab size, format on save, auto save, keybindings, or any settings.json values.
update-cli-config
View and modify Cursor CLI configuration settings in ~/.cursor/cli-config.json. Use when the user wants to change CLI settings, configure permissions, switch approval mode, enable vim mode, toggle display options, configure sandbox, or manage any CLI preferences.
statusline
Configure a custom status line in the CLI. Use when the user mentions status line, statusline, statusLine, CLI status bar, prompt footer customization, or wants to add session context above the prompt.
split-to-prs
Split current work into small reviewable PRs. Use when the user asks to split a chat, set of changes, branch, or PR.
shell
Runs the rest of a /shell request as a literal shell command. Use only when the user explicitly invokes /shell and wants the following text executed directly in the terminal.