release: v0.9.1 portable runtime and isolate fixes

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "spec-superflow",
       "description": "8-state workflow engine with 9 collaborative skills. Bridges planning and execution via execution-contract.md. Embedded schema validation, TDD, SDD, code review, systematic debugging, and delta spec sync.",
-      "version": "0.9.0",
+      "version": "0.9.1",
       "source": "./",
       "author": {
         "name": "MageByte",

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-superflow",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Spec-first workflow: integrates OpenSpec planning engine + Superpowers execution discipline. 9 collaborative skills with embedded TDD, SDD, code review, debugging, and delta spec sync.",
   "source": "./",
   "author": {

.claude/always/phase-guard.md

@@ -1,3 +1,3 @@
-# spec-superflow v0.9.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# spec-superflow v0.9.1 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-superflow",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
   "author": {
     "name": "MageByte",

.cursor-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "Spec-first workflow plugin marketplace for Cursor",
-    "version": "0.9.0"
+    "version": "0.9.1"
   },
   "plugins": [
     {

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "spec-superflow",
   "displayName": "spec-superflow",
   "description": "Spec-first workflow: integrates OpenSpec planning engine + Superpowers execution discipline. 9 collaborative skills with embedded TDD, SDD, code review, debugging, and delta spec sync.",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "author": {
     "name": "MageByte",
     "url": "https://github.com/MageByte-Zero"

.github/plugin/marketplace.json

@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Spec-first workflow plugins and skills for AI coding agents.",
-    "version": "0.9.0"
+    "version": "0.9.1"
   },
   "plugins": [
     {
       "name": "spec-superflow",
       "description": "Spec-first workflow with planning artifacts, execution contracts, TDD, review gates, systematic debugging, and delta spec sync.",
-      "version": "0.9.0",
+      "version": "0.9.1",
       "source": ".",
       "author": {
         "name": "MageByte",

CHANGELOG.md

@@ -6,10 +6,21 @@ The format loosely follows Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-07-15
+
 ### Changed
 
+- **#52 — isolate optional name**: `ssf isolate <change-dir>` no longer forwards an absent optional name as the literal string `undefined`; explicit names and `--force` retain their existing behavior.
+- **#43 — portable skill runtime**: all nine canonical skills no longer require `${CLAUDE_PLUGIN_ROOT}`. Raw marketplace, cache, copy, and symlink loading use a semver-pinned package CLI; local installers rewrite that prefix to their bundled runtime tree.
+- **Cross-platform runtime diagnostics**: `ssf doctor` now detects stale root placeholders and missing runtime trees, while version sync and CI consistency checks include all nine canonical skill prefixes.
+- **Linked-worktree version hook**: `npm run setup-hooks` now locates Git's shared hooks directory, upgrades stale spec-superflow hooks, and validates the worktree being committed rather than a sibling checkout.
 - **#45 — Execution-mode recommendation**: DP-4 now runs `ssf execution recommend` to list Inline, Batch Inline, and SDD from task and wave evidence, with a recommendation. Every persisted plan at `<change>/.superpowers/sdd/execution-plan.json` requires explicit `--confirm`; a non-recommended selection records `--acknowledge-recommendation` instead of treating Inline as an override. Named waves, dependencies, and review receipts remain mandatory.
 
+### Added
+
+- Runtime distribution inventory for all 17 documented platforms plus the ZCODE compatibility installer path.
+- `npm run test:raw-mode` packages the current source and proves the canonical runtime works without plugin-root variables or a global `ssf` command.
+
 ## [0.9.0] - 2026-07-11
 
 ### Added

GEMINI.md

@@ -8,7 +8,7 @@ The workflow is self-contained and does not require OpenSpec or Superpowers at r
 
 
 <!-- spec-superflow-phase-guard-start -->
-# spec-superflow v0.9.0 | 阶段: {{state}} | 工作流: {{workflow}}
+# spec-superflow v0.9.1 | 阶段: {{state}} | 工作流: {{workflow}}
 当前阶段允许的操作由 workflow-start 路由规则定义。
 禁止跨越 DP gate 进入下一阶段。变更范围以 execution-contract.md 的 Intent Lock 为准。
 <!-- spec-superflow-phase-guard-end -->

INSTALL.md

@@ -7,7 +7,7 @@
 - [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) — 规划引擎（Schema 验证、Delta Spec、工件解析）
 - [obra/superpowers](https://github.com/obra/superpowers) — 执行纪律（TDD 铁律、SDD、系统化调试、代码审查）
 
-当前发布版本：**v0.9.0**。
+当前发布版本：**v0.9.1**。
 
 ---
 

README.md

@@ -161,8 +161,9 @@ npx spec-superflow list          # 或通过 npx 使用
 
 ### 版本
 
-- 当前版本：`v0.9.0`
-- v0.9.0 highlights：支持 Node 20/22、model profiles 只读解析，以及 code-reviewer 的最小性审查；详见 [CHANGELOG.md](CHANGELOG.md)
+- 当前版本：`v0.9.1`
+- v0.9.1 highlights：DP-4 执行模式推荐、跨 17 个平台的 portable runtime，以及无插件根路径的 raw-package smoke；详见 [CHANGELOG.md](CHANGELOG.md)
+- v0.9.0 highlights：支持 Node 20/22、model profiles 只读解析，以及 code-reviewer 的最小性审查
 - 自包含插件，不需要运行时安装 OpenSpec 或 Superpowers
 - 上游来源：[Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) 和 [obra/superpowers](https://github.com/obra/superpowers)
 - 版本历史见 [CHANGELOG.md](CHANGELOG.md)

docs/README_en.md

@@ -126,7 +126,8 @@ npm install -g spec-superflow
 
 ### Version
 
-- Current: `v0.9.0`
+- Current: `v0.9.1`
+- v0.9.1 highlights: DP-4 execution-mode recommendations, a portable runtime across 17 platforms, and a raw-package smoke with no plugin-root variable.
 - Self-contained — no OpenSpec or Superpowers runtime required
 - Upstream: [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec), [obra/superpowers](https://github.com/obra/superpowers)
 - Changelog: [CHANGELOG.md](../CHANGELOG.md)

docs/release-checklist.md

@@ -11,6 +11,7 @@ Use this checklist before publishing a new version of `spec-superflow`.
 - `LICENSE` is present
 - `ssf version <semver>` covers all manifests (JSON) + documentation (Markdown/shell)
 - `node scripts/check-version-consistency.mjs` passes (also runs in CI)
+- Verify all nine runtime-dependent canonical skills use the exact release version, and local installer output rewrites them to its bundled `scripts/spec-superflow.mjs`.
 - Verify `.github/plugin/marketplace.json` and `.claude-plugin/marketplace.json` versions match
 
 ## Workflow Integrity
@@ -46,6 +47,8 @@ For each example in `docs/examples/`:
 - `node scripts/check-version-consistency.mjs` — exits 0
 - `node scripts/spec-superflow.mjs --help` — all subcommands listed
 - `node scripts/spec-superflow.mjs install-workbuddy --dry-run` — finds all 9 skills and target paths
+- `npm run test:raw-mode` — packs the current source and runs a canonical runtime in an empty directory with no plugin-root variables or global `ssf`.
+- Run a representative local-installer smoke test.
 - `spec-superflow.config.json` absence still works (backward compatible defaults)
 - `package.json` `bin` field points to correct entry script
 
@@ -74,6 +77,7 @@ For each example in `docs/examples/`:
 
 ## Publishing Checks
 
+- Release preparation does not authorize `git tag`, `npm publish`, GitHub Release creation, marketplace publication, issue closure, or external issue comments. Perform those only after the maintainer explicitly authorizes publication.
 - there are no stray `TODO` or `TBD` markers
 - links and referenced paths are still valid
 - no local-only junk files are included

gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-superflow",
   "description": "Spec-first workflow plugin: clarified requirements → execution contract → disciplined implementation",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "contextFileName": "GEMINI.md"
 }

hooks/session-start

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# v0.9.0: conditional injection — detects artifacts, injects workflow-start pointer
+# v0.9.1: conditional injection — detects artifacts, injects workflow-start pointer
 msg="<EXTREMELY_IMPORTANT>\nYou have spec-superflow installed. Use /spec-superflow:workflow-start ONLY when you detect an active spec-superflow change in the workspace (look for \`.spec-superflow.yaml\`, \`proposal.md\`, \`execution-contract.md\`, or \`specs/\` directories), OR when the user explicitly invokes it by name. For ordinary coding tasks without spec-superflow artifacts, do NOT invoke workflow-start — just handle the request directly.\n</EXTREMELY_IMPORTANT>"
 
 # Three platforms share the same message, only output format differs.

llms.txt

@@ -3,7 +3,7 @@
 ## Overview
 spec-superflow is a self-contained workflow integration plugin for Claude Code, Cursor, OpenAI Codex CLI/App, GitHub Copilot CLI, Gemini CLI, OpenCode, WorkBuddy, and Trae. It merges spec-driven planning artifacts (proposal, specs, design, tasks) with disciplined execution guardrails (TDD, review gates, controlled handoff) into one unified workflow.
 
-Current version: v0.9.0.
+Current version: v0.9.1.
 
 ## Key Documents
 - README.md: Chinese homepage with full usage guide and FAQ

package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-superflow",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Spec-first workflow: integrates OpenSpec planning engine + Superpowers execution discipline via bridge contract. 9 collaborative skills for multi-agent coding tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,6 +12,7 @@
   "scripts": {
     "build": "tsc",
     "test": "node --test tests/e2e.test.mjs tests/lib/*.test.mjs",
+    "test:raw-mode": "node --test tests/lib/raw-mode-smoke.test.mjs",
     "validate": "node scripts/validate-artifacts",
     "version": "node scripts/spec-superflow.mjs version $npm_new_version && node scripts/check-version-consistency.mjs && git add -A",
     "check-versions": "node scripts/check-version-consistency.mjs",

plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spec-superflow",
   "description": "Spec-first workflow that bridges OpenSpec-style planning and Superpowers-style execution discipline.",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "author": {
     "name": "MageByte",
     "url": "https://github.com/MageByte-Zero"

scripts/check-version-consistency.mjs

@@ -83,6 +83,29 @@ for (const check of TEXT_CHECKS) {
   }
 }
 
+const RUNTIME_FILES = [
+  'workflow-start', 'need-explorer', 'spec-writer', 'contract-builder',
+  'build-executor', 'code-reviewer', 'bug-investigator', 'release-archivist', 'spec-merger',
+].map(skill => `skills/${skill}/SKILL.md`).concat([
+  'skills/build-executor/implementer-prompt.md',
+  'skills/build-executor/task-reviewer-prompt.md',
+  'skills/code-reviewer/code-reviewer-prompt.md',
+]);
+for (const file of RUNTIME_FILES) {
+  const fp = join(ROOT, file);
+  if (!existsSync(fp)) {
+    errors.push({ file, found: 'FILE_NOT_FOUND', expected: CANONICAL });
+    continue;
+  }
+  const versions = [...readFileSync(fp, 'utf8').matchAll(/npx --yes --package spec-superflow@(\d+\.\d+\.\d+) ssf/g)]
+    .map(match => match[1]);
+  if (versions.length === 0) {
+    errors.push({ file, found: 'RUNTIME_PREFIX_NOT_FOUND', expected: CANONICAL });
+  } else if (versions.some(version => version !== CANONICAL)) {
+    errors.push({ file, found: [...new Set(versions)].join(', '), expected: CANONICAL });
+  }
+}
+
 // ── Report ──
 if (errors.length === 0) {
   console.log(`✅ Version consistency check passed — all files at ${CANONICAL}`);

scripts/install-cursor.mjs

@@ -13,6 +13,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { parseArgs } from 'node:util';
+import { shellQuote } from './lib/shell-quote.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const defaultPluginRoot = dirname(__dirname); // repository root when running from clone
@@ -21,7 +22,7 @@ const targetRoot = process.cwd();
 const GITHUB_REPO = 'MageByte-Zero/spec-superflow';
 const GITHUB_API_URL = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
 
-// Directories needed at runtime by skills (referenced via ${CLAUDE_PLUGIN_ROOT})
+// Directories needed by local installer-rewritten runtime commands.
 const RUNTIME_DIRS = ['scripts', 'docs', 'templates', 'dist', 'hooks'];
 
 function ensureDir(dir) {
@@ -102,8 +103,12 @@ async function copySkillsWithRoot(sourceSkills, targetSkills, pluginRootAbs) {
       let content = readFileSync(skillMd, 'utf-8');
       if (content.includes('${CLAUDE_PLUGIN_ROOT}')) {
         content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRootAbs);
-        writeFileSync(skillMd, content, 'utf-8');
       }
+      content = content.replace(
+        /npx --yes --package spec-superflow@\d+\.\d+\.\d+ ssf/g,
+        `node ${shellQuote(join(pluginRootAbs, 'scripts', 'spec-superflow.mjs'))}`,
+      );
+      writeFileSync(skillMd, content, 'utf-8');
     }
     // Also fix sub-prompt files (implementer-prompt.md, etc.)
     const subFiles = readdirSync(dst).filter(f => f.endsWith('.md') && f !== 'SKILL.md');
@@ -112,8 +117,12 @@ async function copySkillsWithRoot(sourceSkills, targetSkills, pluginRootAbs) {
       let content = readFileSync(subPath, 'utf-8');
       if (content.includes('${CLAUDE_PLUGIN_ROOT}')) {
         content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRootAbs);
-        writeFileSync(subPath, content, 'utf-8');
       }
+      content = content.replace(
+        /npx --yes --package spec-superflow@\d+\.\d+\.\d+ ssf/g,
+        `node ${shellQuote(join(pluginRootAbs, 'scripts', 'spec-superflow.mjs'))}`,
+      );
+      writeFileSync(subPath, content, 'utf-8');
     }
   }
 

scripts/install-git-hooks.mjs

@@ -6,12 +6,18 @@
 // Automatically run post-install so every contributor gets the guard.
 
 import { writeFileSync, existsSync, chmodSync, readFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, '..');
-const HOOKS_DIR = join(ROOT, '.git', 'hooks');
+// Ask Git for the common hooks directory so linked worktrees install correctly.
+// `git rev-parse --git-path hooks` may be relative in a normal checkout.
+const HOOKS_DIR = resolve(ROOT, execFileSync('git', ['rev-parse', '--git-path', 'hooks'], {
+  cwd: ROOT,
+  encoding: 'utf8',
+}).trim());
 const HOOK_PATH = join(HOOKS_DIR, 'pre-commit');
 
 const HOOK_SCRIPT = `#!/usr/bin/env bash
@@ -21,7 +27,7 @@ const HOOK_SCRIPT = `#!/usr/bin/env bash
 
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+REPO_ROOT="$(git rev-parse --show-toplevel)"
 
 echo "🔍 spec-superflow: checking version consistency..."
 
@@ -41,16 +47,20 @@ if (!existsSync(HOOKS_DIR)) {
   process.exit(1);
 }
 
-// Preserve existing hook if it's not ours
+// Preserve an unrelated hook, but upgrade an older spec-superflow hook.
 const MARKER = '# spec-superflow pre-commit hook';
 if (existsSync(HOOK_PATH)) {
   const existing = readFileSync(HOOK_PATH, 'utf-8');
   if (existing.includes(MARKER)) {
-    console.log('✅ Pre-commit hook already installed (spec-superflow).');
-    process.exit(0);
+    if (existing === HOOK_SCRIPT) {
+      console.log('✅ Pre-commit hook already installed (spec-superflow).');
+      process.exit(0);
+    }
+    console.log('♻️  Updating existing pre-commit hook (spec-superflow).');
+  } else {
+    console.log('⚠️  Existing pre-commit hook found. Backing up to pre-commit.backup ...');
+    writeFileSync(`${HOOK_PATH}.backup`, existing);
   }
-  console.log('⚠️  Existing pre-commit hook found. Backing up to pre-commit.backup ...');
-  writeFileSync(`${HOOK_PATH}.backup`, existing);
 }
 
 writeFileSync(HOOK_PATH, HOOK_SCRIPT);

scripts/install-zcode.mjs

@@ -13,6 +13,7 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
 import { parseArgs } from 'node:util';
+import { shellQuote } from './lib/shell-quote.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const defaultPluginRoot = dirname(__dirname); // repository root when running from clone
@@ -21,7 +22,7 @@ const targetRoot = process.cwd();
 const GITHUB_REPO = 'MageByte-Zero/spec-superflow';
 const GITHUB_API_URL = `https://api.github.com/repos/${GITHUB_REPO}/releases/latest`;
 
-// Directories needed at runtime by skills (referenced via ${CLAUDE_PLUGIN_ROOT})
+// Directories needed by local installer-rewritten runtime commands.
 const RUNTIME_DIRS = ['scripts', 'docs', 'templates', 'dist', 'hooks'];
 
 function ensureDir(dir) {
@@ -102,8 +103,12 @@ async function copySkillsWithRoot(sourceSkills, targetSkills, pluginRootAbs) {
       let content = readFileSync(skillMd, 'utf-8');
       if (content.includes('${CLAUDE_PLUGIN_ROOT}')) {
         content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRootAbs);
-        writeFileSync(skillMd, content, 'utf-8');
       }
+      content = content.replace(
+        /npx --yes --package spec-superflow@\d+\.\d+\.\d+ ssf/g,
+        `node ${shellQuote(join(pluginRootAbs, 'scripts', 'spec-superflow.mjs'))}`,
+      );
+      writeFileSync(skillMd, content, 'utf-8');
     }
     // Also fix sub-prompt files (implementer-prompt.md, etc.)
     const subFiles = readdirSync(dst).filter(f => f.endsWith('.md') && f !== 'SKILL.md');
@@ -112,8 +117,12 @@ async function copySkillsWithRoot(sourceSkills, targetSkills, pluginRootAbs) {
       let content = readFileSync(subPath, 'utf-8');
       if (content.includes('${CLAUDE_PLUGIN_ROOT}')) {
         content = content.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, pluginRootAbs);
-        writeFileSync(subPath, content, 'utf-8');
       }
+      content = content.replace(
+        /npx --yes --package spec-superflow@\d+\.\d+\.\d+ ssf/g,
+        `node ${shellQuote(join(pluginRootAbs, 'scripts', 'spec-superflow.mjs'))}`,
+      );
+      writeFileSync(subPath, content, 'utf-8');
     }
   }