@gavin-hjw/sddflow 0.3.2 → 0.3.4

package/dist/core/dependency-check.js

@@ -1,6 +1,6 @@
 import { execSync } from 'child_process';
-import { cmdExists, fileExists, dirExists, exec } from '../utils/shell.js';
-import { DEPS, TOOL_PATHS } from './constants.js';
+import { cmdExists, fileExists, dirExists, exec, execOrThrow } from '../utils/shell.js';
+import { DEPS, TOOL_PATHS, SUPERPOWERS_INSTALL_HINTS, SUPERPOWERS_PLUGIN_CACHE_DIRS, SUPERPOWERS_REQUIRED_SKILLS, OPENSPEC_INIT_MARKERS, } from './constants.js';
 import { logger } from '../utils/logger.js';
 import path from 'path';
 import os from 'os';
@@ -9,39 +9,189 @@ export function checkDependencies(options = {}) {
     const home = os.homedir();
     const cwd = options.cwd ?? process.cwd();
     const tools = options.tools?.length ? options.tools : Object.keys(TOOL_PATHS);
-    // Check OpenSpec
     const openspecInstalled = cmdExists(DEPS.openspec.cliCmd);
     let openspecVersion;
     if (openspecInstalled) {
         openspecVersion = exec('openspec --version') || undefined;
     }
-    // Check Superpowers in the selected tools' local and global skill dirs.
-    const superpowersSkillPaths = getSuperpowersSkillPaths(cwd, home, tools);
-    const superpowersSkillPath = superpowersSkillPaths.find((candidate) => fs.existsSync(candidate));
-    const superpowersInstalled = Boolean(superpowersSkillPath);
+    const pluginInstalled = isSuperpowersPluginInstalled(home, tools);
+    const skills = checkSuperpowersSkills(cwd, home, tools);
+    const allSkillsInstalled = skills.every((skill) => skill.installed);
     return {
         openspec: {
             installed: openspecInstalled,
             version: openspecVersion,
         },
         superpowers: {
-            installed: superpowersInstalled,
-            hint: superpowersInstalled ? undefined : DEPS.superpowers.installHint,
-            path: superpowersSkillPath,
-            checkedPaths: superpowersSkillPaths,
+            pluginInstalled,
+            skills,
+            allSkillsInstalled,
+            installed: allSkillsInstalled,
         },
     };
 }
-function getSuperpowersSkillPaths(cwd, home, tools) {
-    const candidates = new Set();
+function isSuperpowersPluginInstalled(home, tools) {
+    for (const tool of tools) {
+        const cacheDir = SUPERPOWERS_PLUGIN_CACHE_DIRS[tool];
+        if (!cacheDir)
+            continue;
+        const cacheRoot = path.join(home, cacheDir);
+        if (!dirExists(cacheRoot))
+            continue;
+        const versions = fs.readdirSync(cacheRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+        if (versions.length > 0)
+            return true;
+    }
+    return false;
+}
+export function checkSuperpowersSkills(cwd, home, tools) {
+    return SUPERPOWERS_REQUIRED_SKILLS.map((skillName) => {
+        const skillPath = findSuperpowersSkillPath(cwd, home, tools, skillName);
+        return {
+            name: skillName,
+            installed: Boolean(skillPath),
+            path: skillPath,
+        };
+    });
+}
+function findSuperpowersSkillPath(cwd, home, tools, skillName) {
     for (const tool of tools) {
         const toolPaths = TOOL_PATHS[tool];
         if (!toolPaths)
             continue;
-        candidates.add(path.join(cwd, toolPaths.skillsDir, DEPS.superpowers.checkPath));
-        candidates.add(path.join(home, toolPaths.skillsDir, DEPS.superpowers.checkPath));
+        const localPath = path.join(cwd, toolPaths.skillsDir, skillName, 'SKILL.md');
+        if (fileExists(localPath))
+            return localPath;
+        const globalPath = path.join(home, toolPaths.skillsDir, skillName, 'SKILL.md');
+        if (fileExists(globalPath))
+            return globalPath;
+        const pluginCacheDir = SUPERPOWERS_PLUGIN_CACHE_DIRS[tool];
+        if (pluginCacheDir) {
+            const cached = findSkillInPluginCache(path.join(home, pluginCacheDir), skillName);
+            if (cached)
+                return cached;
+        }
+    }
+    return undefined;
+}
+function findSkillInPluginCache(pluginCacheRoot, skillName) {
+    if (!dirExists(pluginCacheRoot))
+        return undefined;
+    for (const entry of fs.readdirSync(pluginCacheRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const skillPath = path.join(pluginCacheRoot, entry.name, 'skills', skillName, 'SKILL.md');
+        if (fileExists(skillPath))
+            return skillPath;
     }
-    return [...candidates];
+    return undefined;
+}
+/** 阶段 1：检测 OpenSpec CLI + Superpowers 插件是否已安装 */
+export function validateComponentInstallation(depStatus, tools) {
+    const failures = [];
+    const toolsLabel = tools.join(',');
+    if (!depStatus.openspec.installed) {
+        failures.push({
+            id: 'openspec-cli',
+            name: DEPS.openspec.name,
+            reason: '未检测到 OpenSpec CLI（openspec 命令不可用）',
+            installSteps: [
+                DEPS.openspec.installHint,
+                `安装完成后重新运行: sddflow init --tools ${toolsLabel}`,
+            ],
+        });
+    }
+    if (!depStatus.superpowers.pluginInstalled) {
+        const installSteps = new Set([DEPS.superpowers.installHint]);
+        for (const tool of tools) {
+            for (const hint of SUPERPOWERS_INSTALL_HINTS[tool] ?? []) {
+                installSteps.add(hint);
+            }
+        }
+        installSteps.add(`安装完成后重新运行: sddflow init --tools ${toolsLabel}`);
+        failures.push({
+            id: 'superpowers-plugin',
+            name: DEPS.superpowers.name,
+            reason: '未检测到 Superpowers 插件',
+            installSteps: [...installSteps],
+        });
+    }
+    return failures;
+}
+/** 阶段 2：检测 Superpowers 必需 skills 是否齐全 */
+export function validateSuperpowersSkills(depStatus, tools) {
+    const missing = depStatus.superpowers.skills.filter((skill) => !skill.installed);
+    if (missing.length === 0)
+        return [];
+    const toolsLabel = tools.join(',');
+    const installSteps = new Set([DEPS.superpowers.installHint]);
+    for (const tool of tools) {
+        for (const hint of SUPERPOWERS_INSTALL_HINTS[tool] ?? []) {
+            installSteps.add(hint);
+        }
+    }
+    installSteps.add(`安装完成后重新运行: sddflow init --tools ${toolsLabel}`);
+    return [
+        {
+            id: 'superpowers-skills',
+            name: `${DEPS.superpowers.name} Skills`,
+            reason: `缺少 ${missing.length} 个必需 skill: ${missing.map((s) => s.name).join(', ')}`,
+            installSteps: [...installSteps],
+        },
+    ];
+}
+export function verifyOpenSpecInitIntegrity(cwd, tools) {
+    const missing = [];
+    for (const tool of tools) {
+        const markers = OPENSPEC_INIT_MARKERS[tool];
+        if (!markers)
+            continue;
+        const found = markers.some((marker) => fileExists(path.join(cwd, marker)));
+        if (!found) {
+            missing.push(`${tool}: openspec init marker not found (expected one of: ${markers.join(', ')})`);
+        }
+    }
+    return { ok: missing.length === 0, missing };
+}
+export function runOpenSpecInit(cwd, tools) {
+    const toolsFlag = tools.join(',');
+    try {
+        execOrThrow(`openspec init --tools ${toolsFlag}`, { cwd, stdio: 'inherit' });
+        return true;
+    }
+    catch {
+        logger.error(`openspec init --tools ${toolsFlag} 执行失败`);
+        return false;
+    }
+}
+export function printInitPrerequisiteFailures(failures, title = '初始化已中止：缺少必要依赖，请先安装后再运行 sddflow init') {
+    logger.blank();
+    logger.error(title);
+    logger.blank();
+    for (const failure of failures) {
+        logger.warn(`${failure.name}: ${failure.reason}`);
+        logger.info('  安装步骤:');
+        for (const step of failure.installSteps) {
+            logger.info(`    ${step}`);
+        }
+        logger.blank();
+    }
+}
+export function printIntegrityFailures(result, tools) {
+    printInitPrerequisiteFailures([
+        {
+            id: 'openspec-init',
+            name: 'OpenSpec 初始化完整性',
+            reason: `openspec init 后仍缺少 ${result.missing.length} 个文件`,
+            installSteps: [
+                '请检查 openspec init 输出是否有报错',
+                `手动重试: openspec init --tools ${tools.join(',')}`,
+                `缺失文件:`,
+                ...result.missing.map((file) => `  - ${file}`),
+                `修复后重新运行: sddflow init --tools ${tools.join(',')}`,
+            ],
+        },
+    ], '初始化已中止：OpenSpec 文件完整性校验未通过');
 }
 export function tryAutoInstall(pkg) {
     logger.step(`Installing ${pkg} ...`);
@@ -66,7 +216,7 @@ export function readState(cwd) {
             return JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
         }
         catch {
-            return null;
+            continue;
         }
     }
     return null;

package/dist/core/skill-generator.js

@@ -10,9 +10,8 @@ const __dirname = path.dirname(__filename);
 // Resolve templates dir: from dist/core/ → ../../templates/
 const TEMPLATES_DIR = path.resolve(__dirname, '..', '..', 'templates');
 const PHASES = [
-    { name: 'proposal', description: 'Quick requirement capture' },
     { name: 'brainstorming', description: 'Deep design exploration' },
-    { name: 'spec', description: 'Generate OpenSpec specs and translate to plan-ready.md' },
+    { name: 'spec', description: 'Complete OpenSpec artifacts per AGENTS.md, then plan-ready and writing-plans' },
     { name: 'amend', description: 'Revise requirements/specs before close' },
     { name: 'build', description: 'Execute implementation' },
     { name: 'close', description: 'Verify consistency and archive' },
@@ -66,10 +65,6 @@ function generateSkillFile(skillsDir, filename, depStatus) {
     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}`);
@@ -109,21 +104,23 @@ argument-hint: "[optional context]"
 5. 如果 \`$ARGUMENTS\` 中有额外需求或上下文，将它作为 ${phase} 阶段输入
 `;
 }
-function injectRuntimeDepCheck(content, depStatus) {
+function injectRuntimeDepCheck(content, _depStatus) {
     const checkSection = `
 ### 0. 依赖检测
 
-执行前检查以下依赖是否可用：
+执行前检查以下依赖是否可用（**不在 build 阶段生成或重写计划文件**）：
 
 | 依赖 | 检测方式 | 不可用时 |
 |------|----------|----------|
-| Superpowers writing-plans | 当前工具的本地或全局 skills 目录下是否存在 \`writing-plans/SKILL.md\` | 降级为手动拆解 plan-ready.md 中的步骤，逐条执行 |
-| OpenSpec CLI | \`openspec\` 命令是否可执行 | 不影响 build 阶段，但 close 阶段归档需手动 mv |
+| 详细实现计划 | \`docs/superpowers/plans/\` 下存在含变更名的 \`.md\` 文件 | **终止 build**，提示先完成 \`/sddflow spec\` |
+| Superpowers subagent-driven-development | skills 目录下是否存在 \`subagent-driven-development/SKILL.md\` | 降级为按 plan 文件逐步手动执行 |
+| Superpowers test-driven-development | skills 目录下是否存在 \`test-driven-development/SKILL.md\` | 提示安装；仍按 plan 执行，须自述遵守 TDD |
+| OpenSpec CLI | \`openspec\` 命令是否可执行 | 不影响 build；close 归档可改用 \`OpenSpec: Archive\` 或 \`openspec archive\` |
 
-如果 Superpowers 不可用，提示用户：
-> "Superpowers 未安装，build 将使用手动执行模式。安装后体验更佳：${DEPS.superpowers.installHint}"
+如果 Superpowers 子技能缺失，提示用户：
+> "Superpowers 未完整安装，build 将使用手动执行模式。安装后体验更佳：${DEPS.superpowers.installHint}"
 
-如果 Superpowers 可用，调用其 \`writing-plans\` skill 生成详细实现计划。
+**禁止**在 build 阶段调用 \`writing-plans\`；计划必须在 spec 阶段已生成。
 `;
     // Insert after the first heading
     const lines = content.split('\n');
@@ -136,107 +133,10 @@ function injectRuntimeDepCheck(content, depStatus) {
     }
     return lines.join('\n');
 }
-function injectSpecRuntimeCheck(content, depStatus) {
-    const checkNote = `
-> **OpenSpec 检测**：根据 proposal.md 生成 design.md + specs/ + tasks.md；如果 \`openspec\` CLI 可用，生成后运行 \`openspec validate <变更名> --strict\` 校验。
-`;
-    const lines = content.split('\n');
-    const validateIdx = lines.findIndex((l) => l.includes('openspec validate'));
-    if (validateIdx >= 0) {
-        lines.splice(validateIdx, 0, checkNote);
+function getInlineTemplate(filename, _depStatus) {
+    const templatePath = path.join(TEMPLATES_DIR, filename);
+    if (fileExists(templatePath)) {
+        return fs.readFileSync(templatePath, 'utf-8');
     }
-    return lines.join('\n');
-}
-function getInlineTemplate(filename, depStatus) {
-    const templates = {
-        'SKILL.md': `---
-name: sddflow
-description: “OpenSpec + Superpowers 工作流协调器。使用 /sddflow proposal 轻量提问、/sddflow brainstorming 深度设计、/sddflow spec 生成规格、/sddflow amend 在归档前修订需求、/sddflow build 执行实现、/sddflow close 验证归档。串联需求规格与工程执行，消除格式鸿沟。”
-argument-hint: “proposal | brainstorming | spec | amend | build | close”
----
-
-# sddflow - 工作流协调器
-
-根据用户调用的子命令和项目当前状态，路由到对应阶段。
-
-## 续接与中断恢复
-
-如果本轮没有显式 \`/sddflow ...\` 子命令，但上一轮已经进入 sddflow 任一阶段，并且用户是在补充范围、回答确认问题、说”继续”、修正需求、或说明新增/移除边界：
-
-1. 默认继续上一 sddflow 阶段，不把该回复当作普通编码请求
-2. 如果上一阶段是 proposal、brainstorming、spec 或 amend，只能继续产出/更新 OpenSpec 文档和计划文档，不得修改任何代码或实现文件
-3. 如果上一阶段是 build，但用户补充的是需求、验收条件或规格边界变更，切到 \`/sddflow amend\`，不要直接改代码
-4. 只有用户显式调用 \`/sddflow build\`，或状态检测明确进入 build 阶段后，才允许修改代码或实现文件
-5. 中断后恢复时，先重新读取当前阶段文件和 \`openspec/changes/\` 状态，再继续执行
-
-典型场景：
-- proposal 阶段整理需求后，用户补充“运营端也要做回显”。这仍是需求范围修正，必须继续 proposal 文档收敛，不能直接进入代码实现。
-- brainstorming 阶段询问“是否只覆盖企业端？”后，用户回复“运营端也要做回显”。这仍是设计范围修正，必须继续 brainstorming/proposal 文档收敛，不能直接进入代码实现。
-
-## 阶段写入边界
-
-| 阶段 | 允许写入 | 禁止写入 |
-|------|----------|----------|
-| proposal | \`openspec/changes/**/proposal.md\` | 任何代码或实现文件 |
-| brainstorming | \`openspec/changes/**/proposal.md\` | 任何代码或实现文件 |
-| spec | \`openspec/changes/**\`、\`plan-ready.md\` | 任何代码或实现文件 |
-| amend | \`openspec/changes/**\`、\`plan-ready.md\`、\`docs/superpowers/plans/*.md\` | 代码、测试、其他实现文件 |
-| build | 代码、测试、实现计划状态 | 规格文档（除非另开变更） |
-| close | 归档、验证记录、\`close-issues.md\` | 代码、测试、其他实现文件 |
-
-如果用户在 proposal/brainstorming/spec/amend 阶段提出“就按这个做”“范围改成 X”“继续”等话术，不代表进入 build；必须先完成该阶段文档产物并提示下一步。
-
-## 子命令
-
-| 命令 | 阶段 | 说明 |
-|------|------|------|
-| \`/sddflow proposal\` | proposal | 轻量提问，快速收敛需求 |
-| \`/sddflow brainstorming\` | brainstorming | 深度设计，多轮探索 |
-| \`/sddflow spec\` | spec | 调用 OpenSpec 生成规格 + 翻译 |
-| \`/sddflow amend\` | amend | build/close 前受控修改需求、规格和计划 |
-| \`/sddflow build\` | build | 调用 Superpowers 执行实现 |
-| \`/sddflow close\` | close | 验证一致性 + 归档 |
-
-## 状态检测
-
-当用户调用 \`/sddflow\` 不带子命令，或调用某个子命令需要确认前置条件时，执行以下状态检测：
-
-| 检查项 | 怎么查 | 结果 |
-|--------|--------|------|
-| 有活跃变更？ | \`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. 如果这是上一 sddflow 阶段的续接回复，先按”续接与中断恢复”保持阶段
-2. 如果用户在 build 中明确提出需求变更、补充 spec、修改验收条件或重新生成规格，路由到 amend
-3. 如果用户指定了子命令（如 \`/sddflow build\`），优先按指定阶段执行，但检查前置条件
-4. 如果用户只输入 \`/sddflow\`，执行状态检测，自动路由到对应阶段
-5. 读取当前 sddflow skill 目录下的阶段文件：\`<阶段>.md\`（与本 \`SKILL.md\` 同目录；不要依赖 Claude 专属环境变量）
-6. 按阶段文件中的流程执行，并遵守阶段写入边界
-
-### 前置条件检查
-
-| 阶段 | 前置条件 | 不满足时提示 |
-|------|----------|-------------|
-| proposal | 无 | — |
-| brainstorming | 无 | — |
-| spec | 需要有活跃变更目录或有用户需求 | "请先用 /sddflow proposal 或 /sddflow brainstorming 描述需求" |
-| amend | 需要有活跃变更目录，通常需要 plan-ready.md | "还没有可修订的活跃变更，请先完成 /sddflow spec" |
-| build | 需要存在 plan-ready.md | "请先完成 /sddflow spec 生成规格和翻译" |
-| close | 需要实现已完成 | "实现尚未完成，请先用 /sddflow build 执行" |
-`,
-    };
-    return templates[filename] ?? `# ${filename}\n\nTODO: implement\n`;
+    return `# ${filename}\n\nTODO: implement\n`;
 }

package/dist/utils/shell.d.ts

@@ -1,6 +1,11 @@
 export declare function exec(cmd: string, options?: {
     stdio?: 'inherit' | 'pipe';
+    cwd?: string;
 }): string;
+export declare function execOrThrow(cmd: string, options?: {
+    stdio?: 'inherit' | 'pipe';
+    cwd?: string;
+}): void;
 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

@@ -4,15 +4,26 @@ export function exec(cmd, options) {
         return execSync(cmd, {
             encoding: 'utf-8',
             stdio: options?.stdio ?? 'pipe',
+            cwd: options?.cwd,
         }).trim();
     }
     catch {
         return '';
     }
 }
+export function execOrThrow(cmd, options) {
+    execSync(cmd, {
+        encoding: 'utf-8',
+        stdio: options?.stdio ?? 'inherit',
+        cwd: options?.cwd,
+    });
+}
+import fs from 'fs';
 export function cmdExists(cmd) {
+    // Windows: 用 where；Unix: 用 which
+    const checkCmd = process.platform === 'win32' ? `where ${cmd}` : `which ${cmd}`;
     try {
-        execSync(`which ${cmd}`, { encoding: 'utf-8', stdio: 'pipe' });
+        execSync(checkCmd, { encoding: 'utf-8', stdio: 'pipe' });
         return true;
     }
     catch {
@@ -21,8 +32,7 @@ export function cmdExists(cmd) {
 }
 export function fileExists(path) {
     try {
-        execSync(`test -f ${path}`, { stdio: 'pipe' });
-        return true;
+        return fs.existsSync(path) && fs.statSync(path).isFile();
     }
     catch {
         return false;
@@ -30,8 +40,7 @@ export function fileExists(path) {
 }
 export function dirExists(path) {
     try {
-        execSync(`test -d ${path}`, { stdio: 'pipe' });
-        return true;
+        return fs.existsSync(path) && fs.statSync(path).isDirectory();
     }
     catch {
         return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavin-hjw/sddflow",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "OpenSpec + Superpowers workflow orchestrator for Claude Code",
   "bin": {
     "sddflow": "bin/sddflow.js"

package/templates/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: sddflow
-description: "OpenSpec + Superpowers workflow orchestrator. Use /sddflow proposal for quick capture, /sddflow brainstorming for deep design, /sddflow spec to generate specs + translate, /sddflow amend to revise requirements before close, /sddflow build to execute, /sddflow close to verify and archive. Bridges requirements specs and engineering execution."
-argument-hint: "proposal | brainstorming | spec | amend | build | close"
+description: "OpenSpec + Superpowers workflow orchestrator. Use /sddflow brainstorming for design exploration, /sddflow spec to generate specs + translate, /sddflow amend to revise requirements before close, /sddflow build to execute, /sddflow close to verify and archive. Bridges requirements specs and engineering execution."
+argument-hint: "brainstorming | spec | amend | build | close"
 ---
 
 # sddflow - 工作流协调器
@@ -13,35 +13,39 @@ argument-hint: "proposal | brainstorming | spec | amend | build | close"
 如果本轮没有显式 `/sddflow ...` 子命令，但上一轮已经进入 sddflow 任一阶段，并且用户是在补充范围、回答确认问题、说“继续”、修正需求、或说明新增/移除边界：
 
 1. 默认继续上一 sddflow 阶段，不把该回复当作普通编码请求
-2. 如果上一阶段是 proposal、brainstorming、spec 或 amend，只能继续产出/更新 OpenSpec 文档和计划文档，不得修改任何代码或实现文件
+2. 如果上一阶段是 brainstorming、spec 或 amend，只能继续产出/更新 OpenSpec 文档和计划文档，不得修改任何代码或实现文件
 3. 如果上一阶段是 build，但用户补充的是需求、验收条件或规格边界变更，切到 `/sddflow amend`，不要直接改代码
 4. 只有用户显式调用 `/sddflow build`，或状态检测明确进入 build 阶段后，才允许修改代码或实现文件
 5. 中断后恢复时，先重新读取当前阶段文件和 `openspec/changes/` 状态，再继续执行
 
+**路由优先级（高于文件状态推断）：**
+
+1. **续接回复** — 无显式子命令时，保持上一 sddflow 阶段；不因目录中已有 `plan-ready.md` 而自动进入 build
+2. **显式子命令** — 用户指定 `/sddflow <phase>` 时，按该阶段执行并检查前置条件
+3. **裸 `/sddflow`** — 仅此时执行下方「状态检测」自动路由
+4. **build 中需求变更** — 路由到 amend
+
 典型场景：
-- proposal 阶段整理需求后，用户补充“运营端也要做回显”。这仍是需求范围修正，必须继续 proposal 文档收敛，不能直接进入代码实现。
-- brainstorming 阶段询问“是否只覆盖企业端？”后，用户回复“运营端也要做回显”。这仍是设计范围修正，必须继续 brainstorming/proposal 文档收敛，不能直接进入代码实现。
+- brainstorming 阶段询问“是否只覆盖企业端？”后，用户回复“运营端也要做回显”。这仍是设计范围修正，必须继续 brainstorming 文档收敛，不能直接进入代码实现。
 
 ## 阶段写入边界
 
 | 阶段 | 允许写入 | 禁止写入 |
 |------|----------|----------|
-| proposal | `openspec/changes/**/proposal.md` | 任何代码或实现文件 |
 | brainstorming | `openspec/changes/**/proposal.md` | 任何代码或实现文件 |
-| spec | `openspec/changes/**`、`plan-ready.md` | 任何代码或实现文件 |
+| spec | `openspec/changes/**`、`plan-ready.md`、`docs/superpowers/plans/*.md` | 任何代码或实现文件 |
 | amend | `openspec/changes/**`、`plan-ready.md`、`docs/superpowers/plans/*.md` | 代码、测试、其他实现文件 |
-| build | 代码、测试、实现计划状态 | 规格文档（除非另开变更） |
+| build | 代码、测试、实现计划 checkbox 状态 | 规格文档（除非另开变更）；勿运行 OpenSpec Apply（与 sddflow build 冲突） |
 | close | 归档、验证记录、`close-issues.md` | 代码、测试、其他实现文件 |
 
-如果用户在 proposal/brainstorming/spec/amend 阶段提出“就按这个做”“范围改成 X”“继续”等话术，不代表进入 build；必须先完成该阶段文档产物并提示下一步。
+如果用户在 brainstorming/spec/amend 阶段提出“就按这个做”“范围改成 X”“继续”等话术，不代表进入 build；必须先完成该阶段文档产物并提示下一步。
 
 ## 子命令
 
 | 命令 | 阶段 | 说明 |
 |------|------|------|
-| `/sddflow proposal` | proposal | 轻量提问，快速收敛需求 |
-| `/sddflow brainstorming` | brainstorming | 深度设计，多轮探索 |
-| `/sddflow spec` | spec | 调用 OpenSpec 生成规格 + 翻译 |
+| `/sddflow brainstorming` | brainstorming | 深度设计，多轮探索，产出 `proposal.md` |
+| `/sddflow spec` | spec | 按 OpenSpec: Proposal + AGENTS.md 补齐规格，再翻译与 writing-plans |
 | `/sddflow amend` | amend | build/close 前受控修改需求、规格和计划 |
 | `/sddflow build` | build | 调用 Superpowers 执行实现 |
 | `/sddflow close` | close | 验证一致性 + 归档 |
@@ -58,8 +62,9 @@ argument-hint: "proposal | brainstorming | spec | amend | build | close"
 | 实现已完成？ | 计划文件全部 checkbox 已勾选 | 是→close 阶段 |
 
 判定结果：
-- 无活跃变更 → proposal 阶段
-- 有规格但无 plan-ready.md → spec 阶段（补生成翻译）
+- 无活跃变更 → brainstorming 阶段
+- 有变更但无 `proposal.md` → brainstorming 阶段
+- 有 `proposal.md` 但无 plan-ready.md → spec 阶段（补生成翻译）
 - 有 plan-ready.md 但实现未开始 → build 阶段
 - 实现进行中 → 继续 build 阶段（断点恢复）
 - 实现已完成 → close 阶段
@@ -68,10 +73,10 @@ argument-hint: "proposal | brainstorming | spec | amend | build | close"
 
 根据子命令或状态检测结果，读取对应阶段文件并执行：
 
-1. 如果这是上一 sddflow 阶段的续接回复，先按“续接与中断恢复”保持阶段
+1. 如果这是上一 sddflow 阶段的续接回复，先按“续接与中断恢复”保持阶段（**不得**因已有 `plan-ready.md` 覆盖为 build）
 2. 如果用户在 build 中明确提出需求变更、补充 spec、修改验收条件或重新生成规格，路由到 amend
-3. 如果用户指定了子命令（如 `/sddflow build`），优先按指定阶段执行，但检查前置条件
-4. 如果用户只输入 `/sddflow`，执行状态检测，自动路由到对应阶段
+3. 如果用户指定了子命令（如 `/sddflow build`），按指定阶段执行，但检查前置条件
+4. 如果用户只输入 `/sddflow`（无子命令、非续接），执行状态检测，自动路由到对应阶段
 5. 读取当前 sddflow skill 目录下的阶段文件：`<阶段>.md`（与本 `SKILL.md` 同目录；不要依赖 Claude 专属环境变量）
 6. 按阶段文件中的流程执行，并遵守阶段写入边界
 
@@ -79,9 +84,8 @@ argument-hint: "proposal | brainstorming | spec | amend | build | close"
 
 | 阶段 | 前置条件 | 不满足时提示 |
 |------|----------|-------------|
-| proposal | 无 | — |
 | brainstorming | 无 | — |
-| spec | 需要有活跃变更目录或有用户需求 | "请先用 /sddflow proposal 或 /sddflow brainstorming 描述需求" |
+| spec | 需要有活跃变更目录或有用户需求 | "请先用 /sddflow brainstorming 描述需求" |
 | amend | 需要有活跃变更目录，通常需要 plan-ready.md | "还没有可修订的活跃变更，请先完成 /sddflow spec" |
 | build | 需要存在 plan-ready.md | "请先完成 /sddflow spec 生成规格和翻译" |
 | close | 需要实现已完成 | "实现尚未完成，请先用 /sddflow build 执行" |

package/templates/amend.md

@@ -17,7 +17,7 @@ description: Revise active OpenSpec requirements during build, regenerate plan-r
 
 不适用：
 - 只是代码没有实现现有 spec → 继续 `/sddflow build`
-- 变更已经 close/archive → 开新的 `/sddflow proposal` 或 `/sddflow brainstorming`
+- 变更已经 close/archive → 开新的 `/sddflow brainstorming`
 - 只是文案、注释或实现细节调整，且不改变行为 → 继续当前实现阶段
 
 ## 前置条件
@@ -27,10 +27,10 @@ description: Revise active OpenSpec requirements during build, regenerate plan-r
 - 通常应已存在 `plan-ready.md`；如果没有，优先回到 `/sddflow spec`
 
 如果没有 active change，提示：
-> "还没有活跃变更。请先用 /sddflow proposal 或 /sddflow brainstorming 创建需求。"
+> "还没有活跃变更。请先用 /sddflow brainstorming 创建需求。"
 
 如果变更已归档，提示：
-> "该变更已经归档。归档后的需求调整应开启新的 /sddflow proposal。"
+> "该变更已经归档。归档后的需求调整应开启新的 /sddflow brainstorming。"
 
 ## 流程
 
@@ -62,16 +62,18 @@ description: Revise active OpenSpec requirements during build, regenerate plan-r
 
 ### 3. 修改 OpenSpec 文档
 
+**必须**遵循 `openspec/AGENTS.md` 与 **OpenSpec: Proposal** 中的格式与 delta 规则（与 `/sddflow spec` 步骤 2 相同，不得使用 sddflow 自订 spec 格式）。
+
 按影响范围更新：
 
-- `proposal.md`：追加 `## Amendments`，记录本次需求变更的日期、原因和摘要
-- `design.md`：仅当技术方案或约束变化时修改
-- `specs/<capability>/spec.md`：使用 `ADDED`、`MODIFIED`、`REMOVED` 或 `RENAMED Requirements` 表达 delta
-- `tasks.md`：追加新任务；不要重写或删除已完成任务
+- `proposal.md`：追加 `## Amendments`，记录本次需求变更的日期、原因和摘要（不改变 OpenSpec 既有章节语义）
+- `design.md`：仅当 AGENTS.md「Creating Change Proposals」判定需要 technical decisions 时修改
+- `specs/<capability>/spec.md`：仅使用 AGENTS.md 规定的 `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` 与 `#### Scenario:` 格式
+- `tasks.md`：追加新任务；不要重写或删除已完成任务；格式与 OpenSpec: Proposal 步骤 6 一致
 
-要求：
-- 每个新增或修改的 requirement 必须至少有一个 `#### Scenario:`
-- `MODIFIED Requirements` 必须包含完整的新 requirement 文本，不只写差异片段
+要求（摘自 AGENTS.md，不得简化）：
+- 每个新增或修改的 requirement 至少一个 `#### Scenario:`
+- `MODIFIED Requirements` 必须包含完整 requirement 文本（从 `openspec/specs/` 复制后再编辑）
 - 已完成任务保留原 checkbox 状态
 
 ### 4. 校验 OpenSpec
@@ -115,14 +117,16 @@ openspec validate <变更名> --strict
 
 ### 6. 同步详细实现计划
 
+若需新增或调整实现任务，**追加部分须遵循** Superpowers `writing-plans` skill（与 `/sddflow spec` 步骤 5 相同），并满足 spec 中「**三文档 Checkbox 对齐扩展**」（tasks / plan-ready / superpowers plan 均保留任务级与 Step 级 checkbox），为每个新 `### Task N` 填写 `> **trace:**` / `> **sync:**`。
+
 如果 `docs/superpowers/plans/YYYY-MM-DD-<变更名>.md` 已存在：
-- 已勾选任务不动
-- 未完成任务可按新需求调整
-- 追加新 task，保留 checkbox
+- 已勾选 Task/Step 不动
+- 未完成任务可按新需求调整（仍符合 writing-plans 无占位符规则）
+- 追加新 Task 时同步更新 `plan-ready.md` 对应 `### Task` 与 **任务完成** checkbox、`tasks.md` 新条目
 - 记录本次 amend 来源路径
 
 如果详细实现计划还不存在：
-- 不创建代码实现计划，提示下一步用 `/sddflow build`
+- 不创建实现计划，提示先 `/sddflow spec` 完成步骤 5
 
 ### 7. 提示下一步