@lininn/openflow 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emerson Towne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @lininn/openflow
+
+OpenSpec + Superpowers 工作流协调器，串联需求规格与工程执行，消除格式鸿沟。
+
+## 安装
+
+```bash
+npm install -g @lininn/openflow
+```
+
+## 使用
+
+### 初始化项目
+
+```bash
+cd your-project
+openflow init --tools claude
+```
+
+`init` 会自动：
+1. 检测并引导安装 OpenSpec CLI
+2. 检测 Superpowers 并提示安装方式
+3. 检测项目 OpenSpec 初始化状态
+4. 生成 openflow skills 到项目 `.claude/skills/openflow/`
+
+支持的工具：`claude`、`codex`、`cursor`（逗号分隔，如 `--tools claude,codex`）
+
+### 查看状态
+
+```bash
+openflow status
+```
+
+显示依赖安装状态和项目中的活跃变更。
+
+### 更新 skills
+
+```bash
+openflow update
+```
+
+升级 npm 包后运行，重新生成项目内的 skills 文件。
+
+## 工作流命令
+
+| 命令 | 阶段 | 说明 |
+|------|------|------|
+| `/openflow proposal` | proposal | 轻量提问，3-5 问快速收敛需求 |
+| `/openflow brainstorming` | brainstorming | 深度设计，多轮方案探索 |
+| `/openflow spec` | spec | 调用 OpenSpec 生成规格 + 自动翻译 |
+| `/openflow build` | build | 调用 Superpowers 执行实现 |
+| `/openflow close` | close | 验证一致性 + 归档 |
+
+## 依赖策略
+
+```
+Best with: OpenSpec + Superpowers
+Works without them: yes, with manual-file fallback
+```
+
+| 依赖 | 安装方式 | 缺失时降级 |
+|------|----------|-----------|
+| OpenSpec | `npm install -g @fission-ai/openspec@latest` | 手动创建 `openspec/changes/` 目录和文件 |
+| Superpowers | `/plugin install superpowers@claude-plugins-official` | build 阶段手动拆解 plan-ready.md 步骤执行 |
+
+## 架构
+
+```
+用户需求
+   │
+   ├── 轻量 ──→ /openflow proposal ──┐
+   │          3-5问快速收敛          │
+   │                                 ├─→ proposal.md
+   └── 深度 ──→ /openflow brainstorming ─┘ (openspec/changes/<name>/)
+               多轮方案探索
+                                     │
+                          ┌──────────▼───────────┐
+                          │  /openflow spec        │
+                          │  OpenSpec 生成规格      │
+                          └──────────┬───────────┘
+                                     │
+                          ┌──────────▼───────────┐
+                          │   翻译层 (核心)        │
+                          │  需求视角 → 工程视角    │
+                          └──────────┬───────────┘
+                                     │
+                                plan-ready.md
+                                     │
+                          ┌──────────▼───────────┐
+                          │  /openflow build       │
+                          │  Superpowers 执行      │
+                          │  TDD 铁律 + 断点恢复   │
+                          └──────────┬───────────┘
+                                     │
+                          ┌──────────▼───────────┐
+                          │  /openflow close       │
+                          │  验证一致性 + 归档      │
+                          └──────────────────────┘
+```
+
+## License
+
+MIT

package/bin/openflow.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { run } from '../dist/cli/index.js';
+
+run();

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+export declare function run(): void;

package/dist/cli/index.js

@@ -0,0 +1,15 @@
+import { Command } from 'commander';
+import { initCommand } from './init.js';
+import { statusCommand } from './status.js';
+import { updateCommand } from './update.js';
+export function run() {
+    const program = new Command();
+    program
+        .name('openflow')
+        .description('OpenSpec + Superpowers 工作流协调器')
+        .version('0.1.0');
+    program.addCommand(initCommand);
+    program.addCommand(statusCommand);
+    program.addCommand(updateCommand);
+    program.parse();
+}

package/dist/cli/init.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const initCommand: Command;

package/dist/cli/init.js

@@ -0,0 +1,105 @@
+import { Command } from 'commander';
+import inquirer from 'inquirer';
+import { checkDependencies, tryAutoInstall, checkOpenSpecInitialized, writeState } from '../core/dependency-check.js';
+import { generateSkills } from '../core/skill-generator.js';
+import { TOOL_PATHS, DEPS } from '../core/constants.js';
+import { logger } from '../utils/logger.js';
+import { exec } from '../utils/shell.js';
+const SUPPORTED_TOOLS = Object.keys(TOOL_PATHS);
+export const initCommand = new Command('init')
+    .description('在当前项目初始化 openflow skills')
+    .option('-t, --tools <tools>', '目标工具，逗号分隔', 'claude')
+    .action(async (options) => {
+    const cwd = process.cwd();
+    const tools = options.tools.split(',').map((t) => t.trim());
+    logger.blank();
+    logger.info('openflow init — 初始化工作流协调器');
+    logger.blank();
+    // Step 1: Check OpenSpec
+    logger.step('检测 OpenSpec ...');
+    let depStatus = checkDependencies();
+    if (!depStatus.openspec.installed) {
+        logger.warn('OpenSpec CLI 未安装');
+        const { installOpenSpec } = await inquirer.prompt([
+            {
+                type: 'confirm',
+                name: 'installOpenSpec',
+                message: `是否自动安装？(npm install -g ${DEPS.openspec.npmPkg}@latest)`,
+                default: true,
+            },
+        ]);
+        if (installOpenSpec) {
+            const ok = tryAutoInstall(DEPS.openspec.npmPkg);
+            depStatus = checkDependencies(); // recheck
+            if (ok)
+                depStatus.openspec.autoInstalled = true;
+        }
+        else {
+            logger.warn('跳过 OpenSpec 安装，spec 阶段将使用手动降级模式');
+        }
+    }
+    else {
+        logger.success(`OpenSpec CLI 已安装${depStatus.openspec.version ? ` (v${depStatus.openspec.version})` : ''}`);
+    }
+    // Step 2: Check Superpowers
+    logger.step('检测 Superpowers ...');
+    if (!depStatus.superpowers.installed) {
+        logger.warn('Superpowers 未安装');
+        logger.info(DEPS.superpowers.installHint);
+        logger.info('安装后可重新运行 openflow init，或 build 阶段将使用手动降级模式');
+    }
+    else {
+        logger.success('Superpowers 已安装');
+    }
+    // Step 3: Check if OpenSpec is initialized in project
+    logger.step('检测项目 OpenSpec 初始化 ...');
+    if (!checkOpenSpecInitialized(cwd)) {
+        if (depStatus.openspec.installed) {
+            const { initOpenSpec } = await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'initOpenSpec',
+                    message: '项目未初始化 OpenSpec，是否运行 openspec init？',
+                    default: true,
+                },
+            ]);
+            if (initOpenSpec) {
+                const toolsFlag = tools.map((t) => t).join(',');
+                exec(`openspec init --tools ${toolsFlag}`, { stdio: 'inherit' });
+                logger.success('OpenSpec 项目初始化完成');
+            }
+        }
+        else {
+            logger.info('项目未初始化 OpenSpec，将在首次使用 /openflow proposal 时自动创建目录');
+        }
+    }
+    else {
+        logger.success('OpenSpec 项目已初始化');
+    }
+    // Step 4: Generate skills
+    logger.step('生成 openflow skills ...');
+    generateSkills({ cwd, tools, depStatus });
+    // Step 5: Write state
+    writeState(cwd, {
+        openspec: depStatus.openspec.installed,
+        superpowers: depStatus.superpowers.installed,
+        openspecProjectInitialized: checkOpenSpecInitialized(cwd),
+        createdAt: new Date().toISOString(),
+        tools,
+    });
+    logger.blank();
+    logger.success('openflow 初始化完成！');
+    logger.blank();
+    if (!depStatus.superpowers.installed) {
+        logger.warn('提示: Superpowers 未安装，/openflow build 将使用手动执行模式');
+        logger.info(`  安装方式: ${DEPS.superpowers.installHint}`);
+        logger.blank();
+    }
+    logger.info('可用命令:');
+    logger.info('  /openflow proposal      轻量需求捕获');
+    logger.info('  /openflow brainstorming  深度设计探索');
+    logger.info('  /openflow spec           生成规格 + 翻译');
+    logger.info('  /openflow build          执行实现');
+    logger.info('  /openflow close          验证归档');
+    logger.blank();
+});

package/dist/cli/status.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const statusCommand: Command;

package/dist/cli/status.js

@@ -0,0 +1,79 @@
+import { Command } from 'commander';
+import path from 'path';
+import fs from 'fs';
+import { checkDependencies, readState, checkOpenSpecInitialized } from '../core/dependency-check.js';
+import { logger } from '../utils/logger.js';
+import { dirExists } from '../utils/shell.js';
+export const statusCommand = new Command('status')
+    .description('显示依赖状态和活跃变更')
+    .action(() => {
+    const cwd = process.cwd();
+    logger.blank();
+    logger.info('openflow status');
+    logger.blank();
+    // Dependencies
+    logger.step('依赖:');
+    const depStatus = checkDependencies();
+    if (depStatus.openspec.installed) {
+        logger.success(`OpenSpec CLI${depStatus.openspec.version ? ` v${depStatus.openspec.version}` : ''}`);
+    }
+    else {
+        logger.warn('OpenSpec CLI — 未安装');
+    }
+    if (depStatus.superpowers.installed) {
+        logger.success('Superpowers');
+    }
+    else {
+        logger.warn('Superpowers — 未安装 (build 阶段将使用手动模式)');
+    }
+    logger.blank();
+    // Project state
+    logger.step('项目:');
+    const state = readState(cwd);
+    if (state) {
+        logger.success(`已初始化 (${state.tools.join(', ')})`);
+        logger.info(`  初始化时间: ${state.createdAt}`);
+    }
+    else {
+        logger.warn('未初始化，请运行 openflow init');
+        return;
+    }
+    if (checkOpenSpecInitialized(cwd)) {
+        logger.success('OpenSpec 项目已初始化');
+    }
+    else {
+        logger.warn('OpenSpec 项目未初始化');
+    }
+    logger.blank();
+    // Active changes
+    logger.step('活跃变更:');
+    const changesDir = path.join(cwd, 'openspec', 'changes');
+    const archiveDir = path.join(changesDir, 'archive');
+    if (!dirExists(changesDir)) {
+        logger.info('  无');
+        return;
+    }
+    const entries = fs.readdirSync(changesDir, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && d.name !== 'archive');
+    if (entries.length === 0) {
+        logger.info('  无');
+        return;
+    }
+    for (const entry of entries) {
+        const changeDir = path.join(changesDir, entry.name);
+        const hasPlanReady = fs.existsSync(path.join(changeDir, 'plan-ready.md'));
+        const hasProposal = fs.existsSync(path.join(changeDir, 'proposal.md'));
+        let status = '';
+        if (hasPlanReady) {
+            status = '→ ready for /openflow build';
+        }
+        else if (hasProposal) {
+            status = '→ needs /openflow spec';
+        }
+        else {
+            status = '→ needs /openflow proposal';
+        }
+        logger.info(`  ${entry.name} ${status}`);
+    }
+    logger.blank();
+});

package/dist/cli/update.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const updateCommand: Command;

package/dist/cli/update.js

@@ -0,0 +1,32 @@
+import { Command } from 'commander';
+import { checkDependencies, readState, writeState, checkOpenSpecInitialized } from '../core/dependency-check.js';
+import { generateSkills } from '../core/skill-generator.js';
+import { logger } from '../utils/logger.js';
+export const updateCommand = new Command('update')
+    .description('重新生成项目内的 openflow skills')
+    .action(() => {
+    const cwd = process.cwd();
+    const state = readState(cwd);
+    if (!state) {
+        logger.error('项目未初始化，请先运行 openflow init');
+        return;
+    }
+    logger.blank();
+    logger.info('openflow update — 重新生成 skills');
+    logger.blank();
+    const depStatus = checkDependencies();
+    generateSkills({
+        cwd,
+        tools: state.tools,
+        depStatus,
+    });
+    writeState(cwd, {
+        ...state,
+        openspec: depStatus.openspec.installed,
+        superpowers: depStatus.superpowers.installed,
+        openspecProjectInitialized: checkOpenSpecInitialized(cwd),
+    });
+    logger.blank();
+    logger.success('skills 已更新');
+    logger.blank();
+});

package/dist/core/constants.d.ts

@@ -0,0 +1,23 @@
+export declare const PKG_NAME = "@lininn/openflow";
+export declare const PKG_BIN = "openflow";
+export declare const SKILL_NAME = "openflow";
+export declare const COMMAND_PREFIX = "/openflow";
+export declare const DEPS: {
+    readonly openspec: {
+        readonly name: "OpenSpec";
+        readonly cliCmd: "openspec";
+        readonly npmPkg: "@fission-ai/openspec";
+        readonly installHint: "npm install -g @fission-ai/openspec@latest";
+        readonly autoInstallable: true;
+    };
+    readonly superpowers: {
+        readonly name: "Superpowers";
+        readonly checkPath: "writing-plans/SKILL.md";
+        readonly installHint: "请在 Claude Code 中执行: /plugin install superpowers@claude-plugins-official";
+        readonly autoInstallable: false;
+    };
+};
+export declare const TOOL_PATHS: Record<string, {
+    skillsDir: string;
+    commandsDir?: string;
+}>;

package/dist/core/constants.js

@@ -0,0 +1,31 @@
+export const PKG_NAME = '@lininn/openflow';
+export const PKG_BIN = 'openflow';
+export const SKILL_NAME = 'openflow';
+export const COMMAND_PREFIX = '/openflow';
+export const DEPS = {
+    openspec: {
+        name: 'OpenSpec',
+        cliCmd: 'openspec',
+        npmPkg: '@fission-ai/openspec',
+        installHint: 'npm install -g @fission-ai/openspec@latest',
+        autoInstallable: true,
+    },
+    superpowers: {
+        name: 'Superpowers',
+        checkPath: 'writing-plans/SKILL.md',
+        installHint: '请在 Claude Code 中执行: /plugin install superpowers@claude-plugins-official',
+        autoInstallable: false,
+    },
+};
+export const TOOL_PATHS = {
+    claude: {
+        skillsDir: '.claude/skills',
+        commandsDir: '.claude/commands',
+    },
+    codex: {
+        skillsDir: '.codex/skills',
+    },
+    cursor: {
+        skillsDir: '.cursor/skills',
+    },
+};

package/dist/core/dependency-check.d.ts

@@ -0,0 +1,23 @@
+export interface DepStatus {
+    openspec: {
+        installed: boolean;
+        version?: string;
+        autoInstalled?: boolean;
+    };
+    superpowers: {
+        installed: boolean;
+        hint?: string;
+    };
+}
+export declare function checkDependencies(): DepStatus;
+export declare function tryAutoInstall(pkg: string): boolean;
+export declare function checkOpenSpecInitialized(cwd: string): boolean;
+export interface InitState {
+    openspec: boolean;
+    superpowers: boolean;
+    openspecProjectInitialized: boolean;
+    createdAt: string;
+    tools: string[];
+}
+export declare function readState(cwd: string): InitState | null;
+export declare function writeState(cwd: string, state: InitState): void;

package/dist/core/dependency-check.js

@@ -0,0 +1,63 @@
+import { execSync } from 'child_process';
+import { cmdExists, fileExists, dirExists, exec } from '../utils/shell.js';
+import { DEPS } from './constants.js';
+import { logger } from '../utils/logger.js';
+import path from 'path';
+import os from 'os';
+import fs from 'fs';
+export function checkDependencies() {
+    const home = os.homedir();
+    // Check OpenSpec
+    const openspecInstalled = cmdExists(DEPS.openspec.cliCmd);
+    let openspecVersion;
+    if (openspecInstalled) {
+        openspecVersion = exec('openspec --version') || undefined;
+    }
+    // Check Superpowers
+    const superpowersSkillPath = path.join(home, '.claude', 'skills', DEPS.superpowers.checkPath);
+    const superpowersInstalled = fileExists(superpowersSkillPath);
+    return {
+        openspec: {
+            installed: openspecInstalled,
+            version: openspecVersion,
+        },
+        superpowers: {
+            installed: superpowersInstalled,
+            hint: superpowersInstalled ? undefined : DEPS.superpowers.installHint,
+        },
+    };
+}
+export function tryAutoInstall(pkg) {
+    logger.step(`正在安装 ${pkg} ...`);
+    try {
+        execSync(`npm install -g ${pkg}@latest`, { stdio: 'inherit' });
+        logger.success(`${pkg} 安装成功`);
+        return true;
+    }
+    catch {
+        logger.error(`${pkg} 安装失败，请手动执行: npm install -g ${pkg}@latest`);
+        return false;
+    }
+}
+export function checkOpenSpecInitialized(cwd) {
+    return dirExists(path.join(cwd, 'openspec'));
+}
+export function readState(cwd) {
+    const stateFile = path.join(cwd, '.claude', 'openflow-state.json');
+    if (!fileExists(stateFile))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeState(cwd, state) {
+    const stateDir = path.join(cwd, '.claude');
+    if (!dirExists(stateDir)) {
+        fs.mkdirSync(stateDir, { recursive: true });
+    }
+    const stateFile = path.join(stateDir, 'openflow-state.json');
+    fs.writeFileSync(stateFile, JSON.stringify(state, null, 2) + '\n');
+}

package/dist/core/skill-generator.d.ts

@@ -0,0 +1,7 @@
+import type { DepStatus } from './dependency-check.js';
+export interface GenerateOptions {
+    cwd: string;
+    tools: string[];
+    depStatus: DepStatus;
+}
+export declare function generateSkills(options: GenerateOptions): void;

package/dist/core/skill-generator.js

@@ -0,0 +1,154 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { fileExists, dirExists } from '../utils/shell.js';
+import { logger } from '../utils/logger.js';
+import { SKILL_NAME, TOOL_PATHS, DEPS } from './constants.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Resolve templates dir: from dist/core/ → ../../templates/
+const TEMPLATES_DIR = path.resolve(__dirname, '..', '..', 'templates');
+export function generateSkills(options) {
+    const { cwd, tools, depStatus } = options;
+    for (const tool of tools) {
+        const toolPaths = TOOL_PATHS[tool];
+        if (!toolPaths) {
+            logger.warn(`未知工具: ${tool}，跳过`);
+            continue;
+        }
+        const skillsDir = path.join(cwd, toolPaths.skillsDir, SKILL_NAME);
+        logger.step(`生成 ${tool} skills 到 ${path.relative(cwd, skillsDir)}/`);
+        if (!dirExists(skillsDir)) {
+            fs.mkdirSync(skillsDir, { recursive: true });
+        }
+        // Generate main SKILL.md
+        generateSkillFile(skillsDir, 'SKILL.md', depStatus);
+        // Generate phase files
+        const phases = ['proposal', 'brainstorming', 'spec', 'build', 'close'];
+        for (const phase of phases) {
+            generateSkillFile(skillsDir, `${phase}.md`, depStatus);
+        }
+        logger.success(`${tool} skills 生成完成`);
+    }
+}
+function generateSkillFile(skillsDir, filename, depStatus) {
+    const templatePath = path.join(TEMPLATES_DIR, filename);
+    let content;
+    if (fileExists(templatePath)) {
+        content = fs.readFileSync(templatePath, 'utf-8');
+    }
+    else {
+        // Fallback: use inline template
+        content = getInlineTemplate(filename, depStatus);
+    }
+    // Inject runtime dependency checks into build.md
+    if (filename === 'build.md') {
+        content = injectRuntimeDepCheck(content, depStatus);
+    }
+    // Inject runtime dependency checks into spec.md for OpenSpec
+    if (filename === 'spec.md') {
+        content = injectSpecRuntimeCheck(content, depStatus);
+    }
+    const targetPath = path.join(skillsDir, filename);
+    fs.writeFileSync(targetPath, content);
+    logger.step(`  ${filename}`);
+}
+function injectRuntimeDepCheck(content, depStatus) {
+    const checkSection = `
+### 0. 依赖检测
+
+执行前检查以下依赖是否可用：
+
+| 依赖 | 检测方式 | 不可用时 |
+|------|----------|----------|
+| Superpowers writing-plans | \\\`~/.claude/skills/writing-plans/SKILL.md\\\` 是否存在 | 降级为手动拆解 plan-ready.md 中的步骤，逐条执行 |
+| OpenSpec CLI | \\\`openspec\\\` 命令是否可执行 | 不影响 build 阶段，但 close 阶段归档需手动 mv |
+
+如果 Superpowers 不可用，提示用户：
+> "Superpowers 未安装，build 将使用手动执行模式。安装后体验更佳：${DEPS.superpowers.installHint}"
+
+如果 Superpowers 可用，调用其 \\\`writing-plans\\\` skill 生成详细实现计划。
+`;
+    // Insert after the first heading
+    const lines = content.split('\n');
+    const firstH2Idx = lines.findIndex((l) => l.startsWith('## '));
+    if (firstH2Idx >= 0) {
+        lines.splice(firstH2Idx + 1, 0, checkSection);
+    }
+    else {
+        lines.unshift(checkSection);
+    }
+    return lines.join('\n');
+}
+function injectSpecRuntimeCheck(content, depStatus) {
+    const checkNote = `
+> **OpenSpec 检测**：如果 \\\`openspec\\\` CLI 可用，调用 \\\`openspec propose\\\` 生成完整规格；否则手动根据 proposal.md 生成 design.md + specs/ + tasks.md。
+`;
+    const lines = content.split('\n');
+    const proposeIdx = lines.findIndex((l) => l.includes('openspec propose'));
+    if (proposeIdx >= 0) {
+        lines.splice(proposeIdx + 1, 0, checkNote);
+    }
+    return lines.join('\n');
+}
+function getInlineTemplate(filename, depStatus) {
+    const templates = {
+        'SKILL.md': `---
+name: openflow
+description: "OpenSpec + Superpowers 工作流协调器。使用 /openflow proposal 轻量提问、/openflow brainstorming 深度设计、/openflow spec 生成规格、/openflow build 执行实现、/openflow close 验证归档。串联需求规格与工程执行，消除格式鸿沟。"
+---
+
+# openflow: 工作流协调器
+
+根据用户调用的子命令和项目当前状态，路由到对应阶段。
+
+## 子命令
+
+| 命令 | 阶段 | 说明 |
+|------|------|------|
+| \\\`/openflow proposal\\\` | proposal | 轻量提问，快速收敛需求 |
+| \\\`/openflow brainstorming\\\` | brainstorming | 深度设计，多轮探索 |
+| \\\`/openflow spec\\\` | spec | 调用 OpenSpec 生成规格 + 翻译 |
+| \\\`/openflow build\\\` | build | 调用 Superpowers 执行实现 |
+| \\\`/openflow close\\\` | close | 验证一致性 + 归档 |
+
+## 状态检测
+
+当用户调用 \\\`/openflow\\\` 不带子命令，或调用某个子命令需要确认前置条件时，执行以下状态检测：
+
+| 检查项 | 怎么查 | 结果 |
+|--------|--------|------|
+| 有活跃变更？ | \\\`openspec/changes/\\\` 下是否有非 archive 子目录 | 有→继续 |
+| 有 plan-ready.md？ | 变更目录下是否有 \\\`plan-ready.md\\\` | 有→看实现状态 |
+| 实现已开始？ | \\\`docs/superpowers/plans/\\\` 下是否有计划文件 | 有→看是否完成 |
+| 实现已完成？ | 计划文件全部 checkbox 已勾选 | 是→close 阶段 |
+
+判定结果：
+- 无活跃变更 → proposal 阶段
+- 有规格但无 plan-ready.md → spec 阶段（补生成翻译）
+- 有 plan-ready.md 但实现未开始 → build 阶段
+- 实现进行中 → 继续 build 阶段（断点恢复）
+- 实现已完成 → close 阶段
+
+## 路由
+
+根据子命令或状态检测结果，读取对应阶段文件并执行：
+
+1. 如果用户指定了子命令（如 \\\`/openflow build\\\`），优先按指定阶段执行，但检查前置条件
+2. 如果用户只输入 \\\`/openflow\\\`，执行状态检测，自动路由到对应阶段
+3. 读取阶段文件：\\\`\\\${CLAUDE_SKILL_DIR}/<阶段>.md\\\`
+4. 按阶段文件中的流程执行
+
+### 前置条件检查
+
+| 阶段 | 前置条件 | 不满足时提示 |
+|------|----------|-------------|
+| proposal | 无 | — |
+| brainstorming | 无 | — |
+| spec | 需要有活跃变更目录或有用户需求 | "请先用 /openflow proposal 或 /openflow brainstorming 描述需求" |
+| build | 需要存在 plan-ready.md | "请先完成 /openflow spec 生成规格和翻译" |
+| close | 需要实现已完成 | "实现尚未完成，请先用 /openflow build 执行" |
+`,
+    };
+    return templates[filename] ?? `# ${filename}\n\nTODO: implement\n`;
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,8 @@
+export declare const logger: {
+    info: (msg: string) => void;
+    success: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    step: (msg: string) => void;
+    blank: () => void;
+};

package/dist/utils/logger.js

@@ -0,0 +1,9 @@
+import chalk from 'chalk';
+export const logger = {
+    info: (msg) => console.log(chalk.cyan('ℹ'), msg),
+    success: (msg) => console.log(chalk.green('✔'), msg),
+    warn: (msg) => console.log(chalk.yellow('⚠'), msg),
+    error: (msg) => console.log(chalk.red('✖'), msg),
+    step: (msg) => console.log(chalk.gray('→'), msg),
+    blank: () => console.log(),
+};

package/dist/utils/shell.d.ts

@@ -0,0 +1,6 @@
+export declare function exec(cmd: string, options?: {
+    stdio?: 'inherit' | 'pipe';
+}): string;
+export declare function cmdExists(cmd: string): boolean;
+export declare function fileExists(path: string): boolean;
+export declare function dirExists(path: string): boolean;

package/dist/utils/shell.js

@@ -0,0 +1,39 @@
+import { execSync } from 'child_process';
+export function exec(cmd, options) {
+    try {
+        return execSync(cmd, {
+            encoding: 'utf-8',
+            stdio: options?.stdio ?? 'pipe',
+        }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+export function cmdExists(cmd) {
+    try {
+        execSync(`which ${cmd}`, { encoding: 'utf-8', stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function fileExists(path) {
+    try {
+        execSync(`test -f ${path}`, { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function dirExists(path) {
+    try {
+        execSync(`test -d ${path}`, { stdio: 'pipe' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@lininn/openflow",
+  "version": "0.1.0",
+  "description": "OpenSpec + Superpowers workflow orchestrator for Claude Code",
+  "bin": {
+    "openflow": "./bin/openflow.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node ./scripts/postinstall.js"
+  },
+  "keywords": [
+    "claude-code",
+    "openspec",
+    "superpowers",
+    "workflow",
+    "skill"
+  ],
+  "author": "lininn",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lininn/openflow.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "templates",
+    "scripts"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "inquirer": "^13.4.3",
+    "ora": "^8.0.0",
+    "yaml": "^2.4.0"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,12 @@
+console.log(`
+openflow — OpenSpec + Superpowers 工作流协调器
+
+初始化项目:
+  openflow init --tools claude
+
+查看状态:
+  openflow status
+
+更新 skills:
+  openflow update
+`);

package/templates/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: openflow
+description: "OpenSpec + Superpowers 工作流协调器。使用 /openflow proposal 轻量提问、/openflow brainstorming 深度设计、/openflow spec 生成规格、/openflow build 执行实现、/openflow close 验证归档。串联需求规格与工程执行，消除格式鸿沟。"
+---
+
+# openflow: 工作流协调器
+
+根据用户调用的子命令和项目当前状态，路由到对应阶段。
+
+## 子命令
+
+| 命令 | 阶段 | 说明 |
+|------|------|------|
+| `/openflow proposal` | proposal | 轻量提问，快速收敛需求 |
+| `/openflow brainstorming` | brainstorming | 深度设计，多轮探索 |
+| `/openflow spec` | spec | 调用 OpenSpec 生成规格 + 翻译 |
+| `/openflow build` | build | 调用 Superpowers 执行实现 |
+| `/openflow close` | close | 验证一致性 + 归档 |
+
+## 状态检测
+
+当用户调用 `/openflow` 不带子命令，或调用某个子命令需要确认前置条件时，执行以下状态检测：
+
+| 检查项 | 怎么查 | 结果 |
+|--------|--------|------|
+| 有活跃变更？ | `openspec/changes/` 下是否有非 archive 子目录 | 有→继续 |
+| 有 plan-ready.md？ | 变更目录下是否有 `plan-ready.md` | 有→看实现状态 |
+| 实现已开始？ | `docs/superpowers/plans/` 下是否有计划文件 | 有→看是否完成 |
+| 实现已完成？ | 计划文件全部 checkbox 已勾选 | 是→close 阶段 |
+
+判定结果：
+- 无活跃变更 → proposal 阶段
+- 有规格但无 plan-ready.md → spec 阶段（补生成翻译）
+- 有 plan-ready.md 但实现未开始 → build 阶段
+- 实现进行中 → 继续 build 阶段（断点恢复）
+- 实现已完成 → close 阶段
+
+## 路由
+
+根据子命令或状态检测结果，读取对应阶段文件并执行：
+
+1. 如果用户指定了子命令（如 `/openflow build`），优先按指定阶段执行，但检查前置条件
+2. 如果用户只输入 `/openflow`，执行状态检测，自动路由到对应阶段
+3. 读取阶段文件：`${CLAUDE_SKILL_DIR}/<阶段>.md`
+4. 按阶段文件中的流程执行
+
+### 前置条件检查
+
+| 阶段 | 前置条件 | 不满足时提示 |
+|------|----------|-------------|
+| proposal | 无 | — |
+| brainstorming | 无 | — |
+| spec | 需要有活跃变更目录或有用户需求 | "请先用 /openflow proposal 或 /openflow brainstorming 描述需求" |
+| build | 需要存在 plan-ready.md | "请先完成 /openflow spec 生成规格和翻译" |
+| close | 需要实现已完成 | "实现尚未完成，请先用 /openflow build 执行" |

package/templates/brainstorming.md

@@ -0,0 +1,65 @@
+---
+name: openflow/brainstorming
+description: 深度设计 — 多轮探索，确认架构和方案
+---
+
+# Brainstorming: 深度设计
+
+## 目标
+
+通过多轮对话，深入探索需求、方案取舍和架构决策。产出比 proposal 更完整的需求描述和设计方向。
+
+## 流程
+
+### 1. 理解背景
+
+先快速检查项目上下文：
+- 最近的相关 git 提交
+- 现有代码结构
+- 相关文档
+
+### 2. 逐个提问
+
+一次只问一个问题，逐步深入。问题类型：
+
+- **目的** — "这个功能的核心用户场景是什么？"
+- **取舍** — "A 方案更简单但扩展性差，B 方案更灵活但复杂。你倾向哪个？"
+- **边界** — "如果 X 情况发生，期望的行为是什么？"
+- **优先级** — "这几个需求里，哪个最重要？"
+
+### 3. 提出 2-3 种方案
+
+基于讨论，提出 2-3 种实现方案，附上取舍分析。推荐一种并说明理由。
+
+### 4. 确认设计
+
+用户选定方案后，整理设计要点并与用户确认：
+
+> "确认的设计方向：[方案名]。核心决策：[2-3 条]。这样对吗？"
+
+### 5. 创建 OpenSpec 变更
+
+用户确认后，调用 OpenSpec 创建变更：
+
+```bash
+openspec new <变更名>
+```
+
+如果 OpenSpec CLI 不可用，手动创建目录结构：
+
+```bash
+mkdir -p openspec/changes/<变更名>/specs
+```
+
+将确认的需求描述和设计方向写入 `openspec/changes/<变更名>/proposal.md`。
+
+### 6. 提示下一步
+
+> "需求已记录。接下来可以用 `/openflow spec` 生成完整规格。"
+
+## 注意
+
+- 不要写代码
+- 不要跳过取舍讨论直接给答案
+- 如果项目很大，建议先拆分成独立的子项目
+- 允许用户改变方向，不要过早锁定

package/templates/build.md

@@ -0,0 +1,74 @@
+---
+name: openflow/build
+description: 调用 Superpowers 执行实现，支持断点恢复
+---
+
+# Build: Superpowers 执行
+
+## 目标
+
+读取 plan-ready.md，调用 Superpowers 的 writing-plans 生成详细实现计划，然后按 TDD 铁律执行。
+
+## 前置条件
+
+- `openspec/changes/<变更名>/plan-ready.md` 存在
+
+如果不满足，提示：
+> "还没生成 plan-ready.md。请先完成 /openflow spec。"
+
+## 流程
+
+### 1. 检测状态
+
+检查以下文件确定当前状态：
+
+| 检查 | 怎么查 | 结果 |
+|------|--------|------|
+| 有活跃变更？ | `openspec/changes/` 下非 archive 子目录 | 找到变更名 |
+| 有 plan-ready.md？ | 变更目录下是否存在 | 不存在→提示先 spec |
+| 实现已开始？ | `docs/superpowers/plans/` 下是否有对应计划文件 | 已开始→断点恢复 |
+
+如果有多个活跃变更，列出并让用户选择。
+
+### 2. 断点恢复（如适用）
+
+如果检测到已有计划文件，检查其中 checkbox 状态：
+
+- 全部勾选 → 提示实现已完成，建议 /openflow close
+- 部分勾选 → 从未完成的 task 继续执行
+- 无勾选 → 从头开始
+
+### 3. 生成详细实现计划
+
+调用 Superpowers 的 `writing-plans` skill，以 `plan-ready.md` 为输入，生成符合 Superpowers 格式的详细实现计划。
+
+每个步骤：
+- 2-5 分钟工作量
+- 包含代码、文件路径、验证命令
+- 使用 checkbox 语法 `- [ ]` 跟踪
+
+将实现计划保存到：
+```
+docs/superpowers/plans/YYYY-MM-DD-<变更名>.md
+```
+
+### 4. 执行实现
+
+按照 Superpowers 的执行流程：
+
+1. **TDD 铁律**：先写失败测试，再写实现代码
+2. **每个 task 一个 commit**
+3. 多任务可派子代理并行（参见 subagent-driven-development skill）
+4. 编译/测试不通过不让提交
+
+### 5. 执行完成
+
+所有 task 完成后，提示用户：
+
+> "所有实现任务已完成。接下来可以用 /openflow close 验证一致性并归档。"
+
+## 关键原则
+
+- **不允许在 build 阶段修改规格文档** — 发现问题先记录，留到 close 阶段处理
+- plan-ready.md 是锁定的设计决策，Superpowers 按计划展开执行，不重新理解需求
+- 断点恢复依赖文件系统状态，不依赖 AI 的会话记忆

package/templates/close.md

@@ -0,0 +1,80 @@
+---
+name: openflow/close
+description: 验证实现一致性并归档
+---
+
+# Close: 验证归档
+
+## 目标
+
+验证代码实现与设计文档一致，确认规格变更全部体现，然后归档。
+
+## 前置条件
+
+- `docs/superpowers/plans/` 下的实现计划全部 checkbox 已勾选
+- `openspec/changes/<变更名>/plan-ready.md` 存在
+
+## 流程
+
+### 1. 确认实现状态
+
+检查 `docs/superpowers/plans/` 下对应的计划文件，确认所有 checkbox 已勾选。
+
+如果有未完成的 task：
+> "还有 N 个任务未完成。请先用 /openflow build 完成实现。"
+
+### 2. 验证设计一致性
+
+读取 `openspec/changes/<变更名>/design.md`，逐项检查代码实现：
+
+- design.md 中的技术决策是否在代码中体现？
+- 标记的架构选择是否与代码结构一致？
+
+对每一项，给出判定：✅ 一致 / ❌ 不一致（附具体差异）
+
+### 3. 验证规格完整性
+
+读取 `openspec/changes/<变更名>/specs/` 目录，检查每个规格变更：
+
+- 标记为"新增"的功能是否已实现？
+- 标记为"修改"的行为是否已更新？
+- 标记为"删除"的旧逻辑是否已移除？
+
+对每一项，给出判定：✅ 已体现 / ❌ 未体现（附具体缺失）
+
+### 4. 处理不一致
+
+如果发现不一致：
+- **不在 close 阶段改代码**
+- 将不一致项记录到 `openspec/changes/<变更名>/close-issues.md`
+- 提示用户：
+  > "发现 N 处不一致，已记录到 close-issues.md。是否需要开启新的变更来修复？"
+
+### 5. 归档
+
+全部一致（或用户接受不一致项）后，执行归档：
+
+```bash
+openspec archive <变更名>
+```
+
+如果 OpenSpec CLI 不可用，手动归档：
+
+```bash
+mkdir -p openspec/changes/archive
+mv openspec/changes/<变更名> openspec/changes/archive/$(date +%Y-%m-%d)-<变更名>/
+```
+
+归档后确认：
+- 规格增量已合并到主规格库（如适用）
+- 变更记录已移到 archive 目录
+
+### 6. 完成提示
+
+> "变更 '<变更名>' 已验证并归档。可以开始下一个变更了。"
+
+## 关键原则
+
+- close 阶段不做代码修改，只做验证和归档
+- 不一致先记录，不现场修复
+- 防止边写代码边改需求的恶性循环

package/templates/proposal.md

@@ -0,0 +1,55 @@
+---
+name: openflow/proposal
+description: 轻量需求捕获 — 3-5 个问题快速收敛需求
+---
+
+# Proposal: 轻量需求捕获
+
+## 目标
+
+用最少的提问，把用户脑子里的需求变成可执行的变更描述。不做深度设计，不生成代码。
+
+## 流程
+
+### 1. 提出关键问题
+
+一次性提出以下 3-5 个核心问题（根据上下文调整措辞）：
+
+1. **做什么** — 你想实现什么功能/变更？
+2. **为什么** — 解决什么问题？给谁用的？
+3. **成功标准** — 怎样算做完了？验收条件是什么？
+4. **边界** — 什么不在范围内？
+5. **现有约束** — 有没有技术栈、兼容性、时间上的限制？
+
+### 2. 确认需求
+
+用户回答后，整理成一段简洁的需求描述，与用户确认：
+
+> "我理解的需求是：[一句话概括]。具体来说：[2-3 条要点]。这样理解对吗？"
+
+### 3. 创建 OpenSpec 变更
+
+用户确认后，调用 OpenSpec 创建变更：
+
+```bash
+openspec new <变更名>
+```
+
+如果 OpenSpec CLI 不可用，手动创建目录结构：
+
+```bash
+mkdir -p openspec/changes/<变更名>/specs
+```
+
+将确认的需求描述写入 `openspec/changes/<变更名>/proposal.md`。
+
+### 4. 提示下一步
+
+> "需求已记录。接下来可以用 `/openflow spec` 生成完整规格，或继续补充细节。"
+
+## 注意
+
+- 不要做技术设计，那是 spec 和 brainstorming 的事
+- 不要写代码
+- 问题要具体，不要泛泛而谈
+- 如果用户的需求很大（跨多个独立子系统），建议拆分

package/templates/spec.md

@@ -0,0 +1,104 @@
+---
+name: openflow/spec
+description: 调用 OpenSpec 生成规格文档，确认后自动翻译为 plan-ready.md
+---
+
+# Spec: 生成规格并翻译
+
+## 目标
+
+调用 OpenSpec 生成完整的规格文档（proposal.md, design.md, specs/, tasks.md），用户确认后自动翻译成 Superpowers 可执行的 plan-ready.md。
+
+## 前置条件
+
+- `openspec/changes/` 下存在活跃变更目录（由 proposal 或 brainstorming 阶段创建）
+- 变更目录下至少有 `proposal.md`
+
+## 流程
+
+### 1. 确认活跃变更
+
+检查 `openspec/changes/` 下是否有活跃变更（非 archive 子目录）。
+
+如果没有，提示用户：
+> "还没有活跃变更。请先用 /openflow proposal 或 /openflow brainstorming 创建需求。"
+
+如果有多个，列出并让用户选择：
+> "检测到多个活跃变更：[列表]。要对哪个生成规格？"
+
+### 2. 调用 OpenSpec 生成规格
+
+调用 OpenSpec 的 propose 命令（或 OPSX 工作流）生成完整规格：
+
+```bash
+openspec propose <变更名>
+```
+
+如果 OpenSpec CLI 不可用，手动根据 proposal.md 的内容生成以下文件：
+
+- `openspec/changes/<变更名>/proposal.md` — 已存在，可补充
+- `openspec/changes/<变更名>/design.md` — 技术方案
+- `openspec/changes/<变更名>/specs/` — 具体规格变更（标记新增/修改/删除）
+- `openspec/changes/<变更名>/tasks.md` — 实现任务清单
+
+### 3. 与用户确认规格
+
+展示规格摘要，逐项确认：
+
+> "以下是规格摘要：
+> - **提案**：[proposal.md 核心内容]
+> - **设计**：[design.md 核心决策]
+> - **任务**：[tasks.md 任务列表]
+>
+> 有需要调整的地方吗？"
+
+用户确认后才进入翻译步骤。
+
+### 4. 自动生成 plan-ready.md（翻译层）
+
+用户确认后，自动将 OpenSpec 四文件翻译为 Superpowers 可执行的格式。
+
+**翻译规则：**
+1. 每个 OpenSpec Task 拆成 2-5 个细粒度步骤（对应 2-5 分钟工作量）
+2. 每个步骤必须指明改哪个文件
+3. 每个步骤必须有验证方式
+4. **按执行依赖排序，不是按功能模块排序**
+5. 记录来源路径，方便回溯
+
+读取以下文件作为翻译输入：
+- `openspec/changes/<变更名>/proposal.md`
+- `openspec/changes/<变更名>/design.md`
+- `openspec/changes/<变更名>/specs/` 目录下所有文件
+- `openspec/changes/<变更名>/tasks.md`
+
+生成 `openspec/changes/<变更名>/plan-ready.md`，格式如下：
+
+```markdown
+# 实现计划：<变更名>
+
+## 来源
+- 提案：openspec/changes/<变更名>/proposal.md
+- 设计：openspec/changes/<变更名>/design.md
+- 规格：openspec/changes/<变更名>/specs/
+- 任务：openspec/changes/<变更名>/tasks.md
+
+## 实现步骤
+
+### Task 1: <任务名>
+- 目标：<做什么>
+- 改动文件：<哪些文件>
+- 验证方式：<怎么验证>
+
+### Task 2: ...
+```
+
+### 5. 提示下一步
+
+> "规格已确认，plan-ready.md 已生成。接下来可以用 `/openflow build` 开始实现。"
+
+## 关键原则
+
+- **一条代码都不许写** — spec 阶段只产出文档
+- 翻译必须在用户确认后自动生成，不需要用户手动触发
+- plan-ready.md 的 ## 来源 部分必须写明路径，方便 Superpowers 执行时回溯
+- 按执行依赖排序是翻译的关键步骤：先依赖后依赖方