openspec-zcode/README.md

openspec-zcode

OpenSpec spec-driven development (SDD) skills and /opsx:* slash commands for the ZCode harness.

This repo ports the 11 OpenSpec workflow commands (the /opsx:* family) into ZCode-native skills (auto-triggering instructions) plus matching slash commands (so you can type /opsx:propose in chat, exactly like in Claude Code or Cursor).

The skills are thin steering wrappers around the OpenSpec CLI (@fission-ai/openspec), which remains the engine for artifact-dependency resolution, schema handling, and path resolution. You need the CLI installed and a project initialized with openspec init.

What you get

• 11 skills (openspec-*) — full workflow instructions, auto-triggered by intent or force-loaded via /skill openspec-<name>.
• 11 slash commands (/opsx:*) — thin wrappers that mount the matching skill and pass $ARGUMENTS through.

/opsx command	Skill	Purpose
/opsx:explore	openspec-explore	Thinking partner — investigate, brainstorm, clarify. No implementation.
/opsx:propose	openspec-propose	Create a change + generate all artifacts (proposal/specs/design/tasks) in one step.
/opsx:apply	openspec-apply-change	Work through tasks.md, writing code and checking off items.
/opsx:sync	openspec-sync-specs	Merge a change's delta specs into main specs without archiving.
/opsx:archive	openspec-archive-change	Finalize a change: completion check, optional sync, move to archive.
/opsx:new	openspec-new-change	Scaffold a new change folder and show the first artifact template, then stop.
/opsx:continue	openspec-continue-change	Create the next single ready artifact.
/opsx:ff	openspec-ff-change	Fast-forward: create all planning artifacts in dependency order at once.
/opsx:verify	openspec-verify-change	Validate implementation (Completeness/Correctness/Coherence).
/opsx:bulk-archive	openspec-bulk-archive-change	Archive multiple changes at once with cross-change conflict resolution.
/opsx:onboard	openspec-onboard	Guided end-to-end tutorial on a real task in your codebase.

Prerequisites

1. Node.js 18+ and npm.
2. OpenSpec CLI, installed globally:

   npm install -g @fission-ai/openspec
   openspec --version   # should print e.g. 1.4.1
   

3. A project initialized with OpenSpec (run once per repo):

   cd /path/to/your/project
   openspec init
   

   This creates openspec/config.yaml, openspec/specs/, and openspec/changes/.
4. ZCode (this harness).

Install

Linux / macOS / Git Bash on Windows

git clone https://gts.meratalk.online/keboss/openspec-zcode.git
cd openspec-zcode
./install.sh

Native Windows (PowerShell)

git clone https://gts.meratalk.online/keboss/openspec-zcode.git
cd openspec-zcode
.\install.ps1

Both scripts copy:

• skills/openspec-* → ~/.zcode/skills/openspec-*/
• commands/opsx/*.md → ~/.zcode/commands/opsx/*.md

Override the target directory with ZCODE_HOME:

ZCODE_HOME=/custom/path ./install.sh
# PowerShell: $env:ZCODE_HOME = "C:\custom\path"; .\install.ps1

Restart ZCode (or start a new session) after installing so it re-scans the skills and commands directories.

Update

cd openspec-zcode
git pull
./install.sh      # or .\install.ps1

The install scripts are idempotent — re-running overwrites existing copies cleanly.

Uninstall

./uninstall.sh     # or .\uninstall.ps1

Removes ~/.zcode/skills/openspec-*/ and ~/.zcode/commands/opsx/*.md. Leaves the rest of your ZCode config untouched.

Usage

Open ZCode in any project with openspec/ initialized. Two ways to invoke:

Slash commands (explicit, like the upstream OpenSpec UX):

/opsx:propose add-realtime-presence
/opsx:apply add-realtime-presence
/opsx:archive add-realtime-presence

Skills (auto-trigger by intent, or force-load):

/skill openspec-propose
"Let's think through the auth redesign"   → auto-triggers openspec-explore

Layout

openspec-zcode/
├── skills/
│   └── openspec-{explore,propose,apply-change,sync-specs,archive-change,
│                  new-change,continue-change,ff-change,verify-change,
│                  bulk-archive-change,onboard}/SKILL.md
├── commands/opsx/
│   └── {explore,propose,apply,sync,archive,new,continue,ff,verify,
│         bulk-archive,onboard}.md
├── install.sh / install.ps1
├── uninstall.sh / uninstall.ps1
├── .gitignore
└── README.md

How it maps to upstream OpenSpec

Upstream OpenSpec (@fission-ai/openspec) ships per-AI-tool installers that generate two artifacts per command: a skill file and a command file. The table of supported tools (Claude Code, Cursor, Codex, Windsurf, …) lives in the upstream docs/supported-tools.md. This repo adds the ZCode entry to that matrix:

Artifact	ZCode path
Skills	~/.zcode/skills/openspec-<name>/SKILL.md
Commands	~/.zcode/commands/opsx/<name>.md → /opsx:<name>

The skill bodies are ported verbatim from @fission-ai/openspec@1.4.1 (dist/core/templates/workflows/*.js, the instructions field of each get…SkillTemplate()), with three minimal adaptations for the ZCode harness:

1. Cross-references inside skill bodies: /opsx:<cmd> → /skill openspec-<name> (the slash commands themselves keep /opsx:*).
2. Task tool (subagent_type: "general-purpose") → Agent tool (subagent_type: "general-purpose") (one occurrence, in openspec-archive-change).
3. A source-comment header in each SKILL.md recording the upstream version for future re-syncs.

Everything else — all openspec … --json CLI calls, all AskUserQuestion tool / TodoWrite tool references (both exist natively in ZCode), all artifact dependency logic — is unchanged, because the OpenSpec CLI remains the engine.

Re-syncing after an OpenSpec upgrade

When @fission-ai/openspec releases a new version and you want the latest skill instructions:

1. npm install -g @fission-ai/openspec@latest
2. Re-extract the instructions field of each get…SkillTemplate() from the new dist/core/templates/workflows/*.js.
3. Re-apply the three adaptations above.
4. Bump the version comment in each SKILL.md header.
5. ./install.sh to redeploy.

The skill names and command names are stable across versions; only the instruction text changes.

License

The skill instruction text is ported from @fission-ai/openspec (MIT licensed). Everything else in this repo is provided under MIT as well.