163483eb50
Port of @fission-ai/openspec@1.4.1 workflow templates into ZCode-native skills and slash commands. - 11 skills (skills/openspec-*/SKILL.md): auto-trigger + /skill force-load - 11 commands (commands/opsx/*.md): /opsx:explore, /opsx:propose, /opsx:apply, /opsx:sync, /opsx:archive, /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard - install.sh / install.ps1 (idempotent, copies to ~/.zcode/) - uninstall.sh / uninstall.ps1 - README.md with command table, install/update/uninstall, upstream mapping Skill instruction text is ported verbatim from the upstream get…SkillTemplate().instructions fields, with three ZCode adaptations: 1. /opsx:<cmd> cross-refs inside skill bodies → /skill openspec-<name> 2. Task tool → Agent tool (one occurrence in openspec-archive-change) 3. Source-version comment header in each SKILL.md
159 lines
6.6 KiB
Markdown
159 lines
6.6 KiB
Markdown
# openspec-zcode
|
|
|
|
[OpenSpec](https://github.com/Fission-AI/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:
|
|
```bash
|
|
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):
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
git clone https://gts.meratalk.online/keboss/openspec-zcode.git
|
|
cd openspec-zcode
|
|
./install.sh
|
|
```
|
|
|
|
### Native Windows (PowerShell)
|
|
|
|
```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`:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
cd openspec-zcode
|
|
git pull
|
|
./install.sh # or .\install.ps1
|
|
```
|
|
|
|
The install scripts are idempotent — re-running overwrites existing copies cleanly.
|
|
|
|
## Uninstall
|
|
|
|
```bash
|
|
./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.
|