rk-sdd-harness

One-command installer for the sdd-spec-driven workflow harness — slash commands, per-phase model routing, a context loader, and a commit gate that blocks commits when tests are red. Supports Claude Code, opencode, or both coexisting in the same project.

Install into a project

# from the target project root — prompts for target runtime
npx @rickyrl/rk-sdd-harness install

# non-interactive: specify target directly
npx @rickyrl/rk-sdd-harness install --target claude
npx @rickyrl/rk-sdd-harness install --target opencode
npx @rickyrl/rk-sdd-harness install --target codex
npx @rickyrl/rk-sdd-harness install --target both
npx @rickyrl/rk-sdd-harness install --target all

Options:

--dir <path>            Target directory (default: current directory)
--target <t>            Target runtime: claude | opencode | codex | both | all (default: prompt)
--skill <name>          Skill to install (default: sdd-spec-driven)
--no-skill              Commands/hooks/scaffolding only, skip the skill files
--force, -f             Overwrite user-owned files (CLAUDE.md, AGENTS.md, STATE.md, gate.json, lessons)
--help, -h              Show help

What it installs

Shared (all targets)

| Path | What | On re-install | | ---- | ---- | ------------- | | .specs/ | STATE.md, lessons store, gate.json, features/ | user files kept |

Claude Code (--target claude or both)

| Path | What | On re-install | | ---- | ---- | ------------- | | .claude/commands/* | 11 /rk-* slash commands (model-routed) | overwritten (upgrade) | | .claude/hooks/* | SessionStart context loader + PreToolUse gate guard | overwritten | | .claude/settings.json | hooks + permission allowlist | merged, never clobbered | | .claude/skills/sdd-spec-driven/ | the bundled skill | overwritten (--no-skill to skip) | | CLAUDE.md | harness glue / guide | kept if present |

opencode (--target opencode or both)

| Path | What | On re-install | | ---- | ---- | ------------- | | .opencode/command/* | 11 /rk-* slash commands (model-routed) | overwritten (upgrade) | | .opencode/plugin/sdd-gate-guard.js | commit gate via tool.execute.before hook | overwritten | | .opencode/skills/sdd-spec-driven/ | the bundled skill | overwritten (--no-skill to skip) | | AGENTS.md | harness glue / guide | kept if present | | opencode.json | instructions + permission allowlist | merged, never clobbered |

Codex (--target codex or all)

| Path | What | On re-install | | ---- | ---- | ------------- | | .codex/skills/sdd-spec-driven/ | bundled workflow skill | overwritten (--no-skill to skip) | | .codex/hooks/ | resume-context and pre-commit gate hooks | overwritten (upgrade) | | .codex/hooks.json | project hook registration | merged, never clobbered | | AGENTS.md | workflow guide and natural-language prompt equivalents | kept if present |

both remains Claude Code + OpenCode for backward compatibility. Use all to install all three runtimes.

The installer is idempotent and safe: harness code is refreshed, but your CLAUDE.md, AGENTS.md, STATE.md, gate.json, and lessons are never overwritten (unless --force), and config files (settings.json, opencode.json) are structurally merged (hook/permission entries deduped).

Differences between runtimes

| Feature | Claude Code | opencode | | ------- | ----------- | -------- | | Slash commands | .claude/commands/ | .opencode/command/ | | Commit gate | PreToolUse hook (Python) | tool.execute.before plugin (JS) | | Session context | SessionStart hook (auto-injects Handoff) | manual /rk-status or /rk-resume | | Inline command exec in /rk-* | !backtick syntax | instructions in code blocks | | Glue doc | CLAUDE.md | AGENTS.md | | Config | .claude/settings.json | opencode.json | | Model routing | opus / sonnet / haiku | opencode-go/deepseek-v4-pro / flash |

Both share the same .specs/ workspace (STATE.md, lessons, gate.json, features/) — so you can switch runtimes or use both without losing project state.

After installing

1. Claude Code: open the project — the /rk-* commands are available. opencode: restart opencode to load the skill, commands, and plugin.
2. Before Execute, configure the real test/build command in .specs/gate.json, set "enabled": true, and point command / cwd / watch at the project. An enabled guard fails closed and does not allow git commit --no-verify to bypass it.
3. Start a feature: /rk-new <feature>.

Requirements

• Node ≥ 18 to run the installer.
• Python 3 in the project environment (the lessons layer is Python; available as python or python3). The Claude Code hooks are also Python; the opencode gate guard is JS (no Python needed for the gate itself).

Licensing

Installer code (bin/) and the generated harness (slash commands, hooks, plugin, CLAUDE.md, AGENTS.md, .specs/ scaffolding): MIT.

The bundled Spec-Driven Development skill (template/*/skills/sdd-spec-driven/) is a third-party work distributed under CC-BY-4.0; its original author and license are credited in NOTICE and preserved in the skill's SKILL.md metadata.

Publishing (for maintainers)

Prerequisite: an npm account that owns the @rickyrl scope.

1. npm login
2. npm pack --dry-run — verify the payload (must include NOTICE).
3. npm publish --access public — scoped public packages require --access public.