openspec-zcode/README.md

# 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.