specwf 0.2.0 → 0.2.2

package/dist/cli.js

@@ -4,7 +4,7 @@
 import { program } from "commander";
 
 // src/commands/specwf-init.ts
-import { join as join5 } from "path";
+import { join as join8 } from "path";
 
 // src/core/config.ts
 import { join } from "path";
@@ -468,66 +468,9 @@ async function runBrownfieldInit(rootDir, specwfDir, info) {
   return domains;
 }
 
-// src/commands/specwf-init.ts
-function register(program2) {
-  program2.command("init").description("\u521D\u59CB\u5316 specwf \u9879\u76EE\u7ED3\u6784").option("--dir <path>", "\u76EE\u6807\u76EE\u5F55", ".").option("--profile <profile>", "\u5DE5\u4F5C\u6D41\u4E25\u683C\u5EA6 (lite|standard|strict)", "standard").option("--brownfield", "\u5B58\u91CF\u9879\u76EE\u6A21\u5F0F\uFF08codebase mapping + spec bootstrap\uFF09").option("--yes", "\u8DF3\u8FC7\u786E\u8BA4\u4F7F\u7528\u9ED8\u8BA4\u503C").action(initHandler);
-}
-async function initHandler(options) {
-  const baseDir = options.dir.startsWith("/") ? options.dir : join5(process.cwd(), options.dir);
-  const specwfDir = join5(baseDir, "specwf");
-  if (isInitialized(specwfDir)) {
-    console.error("specwf \u5DF2\u521D\u59CB\u5316\u3002\u8FD0\u884C `specwf update` \u66F4\u65B0\u5E73\u53F0\u6587\u4EF6\u3002");
-    process.exit(1);
-  }
-  const wizard = await runInitWizard({ profile: options.profile, yes: options.yes });
-  const profile = wizard.profile;
-  const platform = wizard.platform;
-  const isBrownfield = options.brownfield || wizard.brownfield;
-  createSpecwfStructure(specwfDir);
-  console.log("\u2713 \u521B\u5EFA specwf/ \u76EE\u5F55\u7ED3\u6784");
-  saveConfig(specwfDir, {
-    version: 1,
-    platform,
-    profile,
-    context: wizard.context,
-    workflow: {},
-    review: {},
-    change: {},
-    git: { branching: "none", create_tag: true },
-    conventions: { inject: true },
-    models: {}
-  });
-  console.log("\u2713 \u521B\u5EFA project.yml (profile: " + profile + ")");
-  saveState(specwfDir, {
-    project: {
-      name: baseDir.split("/").pop() || "project",
-      status: "initialized",
-      current_milestone: null,
-      current_phase: null
-    },
-    active_context: {
-      type: "project",
-      ref: null,
-      step: "init"
-    },
-    changes: [],
-    adhoc: []
-  });
-  console.log("\u2713 \u521B\u5EFA state.md");
-  if (isBrownfield) {
-    const info = detectProjectInfo(process.cwd());
-    const domains = await runBrownfieldInit(process.cwd(), specwfDir, info);
-    console.log("\u2713 \u5B58\u91CF\u9879\u76EE codebase mapping \u5B8C\u6210 (" + domains.length + " \u4E2A spec \u57DF)");
-  }
-  console.log("specwf \u521D\u59CB\u5316\u5B8C\u6210\u3002\u8FD0\u884C `specwf update` \u751F\u6210\u5E73\u53F0\u6587\u4EF6\u3002");
-}
-
-// src/commands/specwf-update.ts
-import { join as join9 } from "path";
-
 // src/generators/omp-commands.ts
 import { readFileSync as readFileSync6 } from "fs";
-import { join as join6, dirname } from "path";
+import { join as join5, dirname } from "path";
 import { fileURLToPath } from "url";
 var STEP_DEFS = [
   { step: "init", name: "specwf:init", description: "\u521D\u59CB\u5316 specwf \u9879\u76EE\u7ED3\u6784", usesAgent: true, agents: ["researcher"] },
@@ -548,9 +491,9 @@ var STEP_DEFS = [
   { step: "continue", name: "specwf:continue", description: "\u81EA\u52A8\u63A8\u8FDB \u2014 \u8BFB STATE \u786E\u5B9A\u4E0B\u4E00\u6B65", usesAgent: false, agents: [] }
 ];
 var __dirname = dirname(fileURLToPath(import.meta.url));
-var TEMPLATES_DIR = join6(__dirname, "templates", "commands");
+var TEMPLATES_DIR = join5(__dirname, "templates", "commands");
 function loadTemplate(step) {
-  return readFileSync6(join6(TEMPLATES_DIR, `${step}.md`), "utf-8");
+  return readFileSync6(join5(TEMPLATES_DIR, `${step}.md`), "utf-8");
 }
 function renderTemplate(template, vars) {
   return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? "");
@@ -634,12 +577,12 @@ function generateAllCommands(config) {
 
 // src/generators/omp-agents.ts
 import { readFileSync as readFileSync7 } from "fs";
-import { join as join7, dirname as dirname2 } from "path";
+import { join as join6, dirname as dirname2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
-var TEMPLATES_DIR2 = join7(__dirname2, "templates", "agents");
+var TEMPLATES_DIR2 = join6(__dirname2, "templates", "agents");
 function loadTemplate2(role) {
-  return readFileSync7(join7(TEMPLATES_DIR2, `${role}.md`), "utf-8");
+  return readFileSync7(join6(TEMPLATES_DIR2, `${role}.md`), "utf-8");
 }
 function renderTemplate2(template, vars) {
   return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? "");
@@ -750,12 +693,12 @@ function generateAllAgents(config) {
 
 // src/generators/skills.ts
 import { readFileSync as readFileSync8 } from "fs";
-import { join as join8, dirname as dirname3 } from "path";
+import { join as join7, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 var __dirname3 = dirname3(fileURLToPath3(import.meta.url));
-var TEMPLATES_DIR3 = join8(__dirname3, "templates", "skills");
+var TEMPLATES_DIR3 = join7(__dirname3, "templates", "skills");
 function loadTemplate3(step) {
-  return readFileSync8(join8(TEMPLATES_DIR3, `${step}.md`), "utf-8");
+  return readFileSync8(join7(TEMPLATES_DIR3, `${step}.md`), "utf-8");
 }
 function renderTemplate3(template, vars) {
   return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? "");
@@ -828,7 +771,69 @@ function writeGeneratedFiles(files) {
   }
 }
 
+// src/commands/specwf-init.ts
+function register(program2) {
+  program2.command("init").description("\u521D\u59CB\u5316 specwf \u9879\u76EE\u7ED3\u6784").option("--dir <path>", "\u76EE\u6807\u76EE\u5F55", ".").option("--profile <profile>", "\u5DE5\u4F5C\u6D41\u4E25\u683C\u5EA6 (lite|standard|strict)", "standard").option("--brownfield", "\u5B58\u91CF\u9879\u76EE\u6A21\u5F0F\uFF08codebase mapping + spec bootstrap\uFF09").option("--yes", "\u8DF3\u8FC7\u786E\u8BA4\u4F7F\u7528\u9ED8\u8BA4\u503C").action(initHandler);
+}
+async function initHandler(options) {
+  const baseDir = options.dir.startsWith("/") ? options.dir : join8(process.cwd(), options.dir);
+  const specwfDir = join8(baseDir, "specwf");
+  if (isInitialized(specwfDir)) {
+    console.error("specwf \u5DF2\u521D\u59CB\u5316\u3002\u8FD0\u884C `specwf update` \u66F4\u65B0\u5E73\u53F0\u6587\u4EF6\u3002");
+    process.exit(1);
+  }
+  const wizard = await runInitWizard({ profile: options.profile, yes: options.yes });
+  const profile = wizard.profile;
+  const platform = wizard.platform;
+  const isBrownfield = options.brownfield || wizard.brownfield;
+  createSpecwfStructure(specwfDir);
+  console.log("\u2713 \u521B\u5EFA specwf/ \u76EE\u5F55\u7ED3\u6784");
+  saveConfig(specwfDir, {
+    version: 1,
+    platform,
+    profile,
+    context: wizard.context,
+    workflow: {},
+    review: {},
+    change: {},
+    git: { branching: "none", create_tag: true },
+    conventions: { inject: true },
+    models: {}
+  });
+  console.log("\u2713 \u521B\u5EFA project.yml (profile: " + profile + ")");
+  saveState(specwfDir, {
+    project: {
+      name: baseDir.split("/").pop() || "project",
+      status: "initialized",
+      current_milestone: null,
+      current_phase: null
+    },
+    active_context: {
+      type: "project",
+      ref: null,
+      step: "init"
+    },
+    changes: [],
+    adhoc: []
+  });
+  console.log("\u2713 \u521B\u5EFA state.md");
+  if (isBrownfield) {
+    const info = detectProjectInfo(process.cwd());
+    const domains = await runBrownfieldInit(process.cwd(), specwfDir, info);
+    console.log("\u2713 \u5B58\u91CF\u9879\u76EE codebase mapping \u5B8C\u6210 (" + domains.length + " \u4E2A spec \u57DF)");
+  }
+  console.log("specwf \u521D\u59CB\u5316\u5B8C\u6210\u3002");
+  try {
+    const files = generateAll({ version: 1, platform, profile, context: wizard.context, workflow: {}, review: {}, change: {}, git: { branching: "none", create_tag: true }, conventions: { inject: true }, models: {} });
+    writeGeneratedFiles(files);
+    console.log(`\u2713 \u5E73\u53F0\u6587\u4EF6\u5DF2\u751F\u6210 (${files.length} \u4E2A)`);
+  } catch {
+    console.log("\u26A0 \u5E73\u53F0\u6587\u4EF6\u751F\u6210\u5931\u8D25\uFF0C\u53EF\u7A0D\u540E\u8FD0\u884C `specwf update` \u91CD\u8BD5");
+  }
+}
+
 // src/commands/specwf-update.ts
+import { join as join9 } from "path";
 function register2(program2) {
   program2.command("update").description("\u66F4\u65B0\u5E73\u53F0\u6587\u4EF6\uFF08commands + agents\uFF09").option("--dir <path>", "specwf \u76EE\u5F55", "specwf").action(updateHandler);
 }
@@ -882,7 +887,128 @@ function findSpecwfDir() {
 }
 
 // src/commands/specwf-state.ts
+import { join as join12 } from "path";
+
+// src/core/state-validator.ts
+import { existsSync as existsSync6, readFileSync as readFileSync9, readdirSync as readdirSync3 } from "fs";
 import { join as join11 } from "path";
+var EXIT_CRITERIA = [
+  // milestone/active → 必须有 requirements.md
+  {
+    type: "milestone",
+    step: "active",
+    checks: [
+      { path: "requirements.md", description: "requirements.md \u4E0D\u5B58\u5728" }
+    ]
+  },
+  // project/requirements-defined → 必须有完整的 requirements.md
+  {
+    type: "project",
+    step: "requirements-defined",
+    checks: [
+      { path: "requirements.md", description: "requirements.md \u5185\u5BB9\u4E3A\u6A21\u677F\uFF0C\u8BF7\u586B\u5199\u540E\u91CD\u8BD5" }
+    ]
+  },
+  // project/researched → 必须有调研产出
+  {
+    type: "project",
+    step: "researched",
+    checks: [
+      { path: "research/summary.md", description: "research/summary.md \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u5B8C\u6210\u8C03\u7814" }
+    ]
+  },
+  // phase/discuss → 必须有 context.md
+  {
+    type: "phase",
+    step: "discuss",
+    checks: [
+      { path: "roadmap.md", description: "roadmap.md \u4E0D\u5B58\u5728\uFF0C\u8BF7\u5148\u62C6\u5206\u8DEF\u7EBF\u56FE" }
+    ]
+  },
+  // phase/research → 必须有 research.md
+  {
+    type: "phase",
+    step: "research",
+    checks: [
+      { path: "roadmap.md", description: "roadmap.md \u4E0D\u5B58\u5728" }
+    ]
+  },
+  // adhoc/proposal → proposal.md 不能是模板
+  {
+    type: "adhoc",
+    step: "proposal",
+    checks: [
+      { path: "changes/", description: "change \u7684 proposal.md \u4E3A\u6A21\u677F\u7A7A\u58F3\uFF0C\u8BF7\u586B\u5199\u540E\u91CD\u8BD5" }
+    ]
+  },
+  // change/planning → design.md + tasks.md 不能是模板
+  {
+    type: "change",
+    step: "planning",
+    checks: [
+      { path: "changes/", description: "design.md \u6216 tasks.md \u4E3A\u6A21\u677F\u7A7A\u58F3\uFF0C\u8BF7\u586B\u5199\u540E\u91CD\u8BD5" }
+    ]
+  }
+];
+function isTemplateFile(filePath) {
+  try {
+    const content = readFileSync9(filePath, "utf-8");
+    const placeholders = content.match(/\{\{[a-zA-Z_-]+\}\}/g);
+    return (placeholders?.length ?? 0) > 3;
+  } catch {
+    return false;
+  }
+}
+function findChangeDir(specwfDir) {
+  const changesDir = join11(specwfDir, "changes");
+  if (!existsSync6(changesDir)) return [];
+  try {
+    return readdirSync3(changesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+function checkExitCondition(specwfDir, check) {
+  const fullPath = join11(specwfDir, check.path);
+  if (check.path.endsWith("/") || check.description.includes("\u7684 ")) {
+    const changes = findChangeDir(specwfDir);
+    for (const change of changes) {
+      for (const doc of ["proposal.md", "design.md", "tasks.md"]) {
+        const docPath = join11(specwfDir, "changes", change, doc);
+        if (existsSync6(docPath) && isTemplateFile(docPath)) {
+          return `changes/${change}/${doc} \u4ECD\u4E3A\u6A21\u677F\u7A7A\u58F3\uFF0C\u8BF7\u586B\u5199\u540E\u91CD\u8BD5`;
+        }
+      }
+    }
+    return null;
+  }
+  if (!existsSync6(fullPath)) {
+    return check.description;
+  }
+  if (isTemplateFile(fullPath)) {
+    return check.description;
+  }
+  return null;
+}
+function validateStepAdvance(contextType, contextStep, cwd) {
+  const specwfDir = join11(cwd, "specwf");
+  const criteria = EXIT_CRITERIA.find(
+    (c) => c.type === contextType && c.step === contextStep
+  );
+  if (!criteria) {
+    return { valid: true, errors: [] };
+  }
+  const errors = [];
+  for (const check of criteria.checks) {
+    const error = checkExitCondition(specwfDir, check);
+    if (error) {
+      errors.push(error);
+    }
+  }
+  return { valid: errors.length === 0, errors };
+}
+
+// src/commands/specwf-state.ts
 function register4(program2) {
   const cmd = program2.command("state").description("\u67E5\u770B/\u4FEE\u6539\u5F53\u524D\u72B6\u6001");
   cmd.command("show").description("\u67E5\u770B\u5F53\u524D\u72B6\u6001").action(showState);
@@ -892,7 +1018,7 @@ function register4(program2) {
   cmd.action(showState);
 }
 function findSpecwfDir2() {
-  return join11(process.cwd(), "specwf");
+  return join12(process.cwd(), "specwf");
 }
 function showState() {
   const specwfDir = findSpecwfDir2();
@@ -915,13 +1041,13 @@ function setMilestone(id) {
   updateState(specwfDir, (state) => {
     state.project.current_milestone = id;
     state.project.current_phase = null;
-    state.active_context.type = "phase";
+    state.active_context.type = "milestone";
     state.active_context.ref = `milestones/${id}`;
-    state.active_context.step = "discuss";
-    state.project.status = "phase-discuss";
+    state.active_context.step = "active";
+    state.project.status = "milestone-active";
   });
-  console.log(`\u2713 \u5207\u6362\u5230 milestone: ${id}\uFF08\u72B6\u6001: phase-discuss\uFF09`);
-  console.log("\u2192 \u4E0B\u4E00\u6B65: /specwf:discuss");
+  console.log(`\u2713 \u5207\u6362\u5230 milestone: ${id}\uFF08\u72B6\u6001: milestone-active\uFF09`);
+  console.log("\u2192 \u4E0B\u4E00\u6B65: \u5B9A\u4E49\u91CC\u7A0B\u7891\u9700\u6C42: /specwf:grill");
 }
 function setPhase(id) {
   const specwfDir = findSpecwfDir2();
@@ -937,18 +1063,51 @@ function setPhase(id) {
 }
 function setStep(step) {
   const specwfDir = findSpecwfDir2();
-  updateState(specwfDir, (state) => {
-    state.active_context.step = step;
+  const state = loadState(specwfDir);
+  const ctx = state.active_context;
+  let currentStatus;
+  switch (ctx.type) {
+    case "project":
+      currentStatus = state.project.status;
+      break;
+    case "milestone":
+      currentStatus = "milestone-active";
+      break;
+    case "phase":
+      currentStatus = `phase-${ctx.step}`;
+      break;
+    case "change":
+      currentStatus = `change-${ctx.step}`;
+      break;
+    case "adhoc":
+      currentStatus = `adhoc-${ctx.step}`;
+      break;
+    default:
+      currentStatus = state.project.status;
+  }
+  const result = validateStepAdvance(ctx.type, ctx.step, process.cwd());
+  if (!result.valid) {
+    console.log("\u2500".repeat(50));
+    console.log("\u274C \u524D\u7F6E\u6761\u4EF6\u672A\u6EE1\u8DB3\uFF0C\u65E0\u6CD5\u63A8\u8FDB:");
+    for (const err of result.errors) {
+      console.log(`   \u2022 ${err}`);
+    }
+    ;
+    console.log("\u2500".repeat(50));
+    return;
+  }
+  updateState(specwfDir, (state2) => {
+    state2.active_context.step = step;
   });
   console.log(`\u2713 \u5F53\u524D\u6B65\u9AA4: ${step}`);
 }
 
 // src/commands/specwf-context.ts
-import { join as join13 } from "path";
+import { join as join14 } from "path";
 
 // src/core/spec-injector.ts
-import { join as join12 } from "path";
-import { readdirSync as readdirSync3, existsSync as existsSync6, statSync as statSync2 } from "fs";
+import { join as join13 } from "path";
+import { readdirSync as readdirSync4, existsSync as existsSync7, statSync as statSync2 } from "fs";
 var PROJECT_STEPS = ["init", "grill", "research", "roadmap"];
 var PHASE_STEPS = ["discuss", "research-phase", "split"];
 var CHANGE_STEPS = ["plan", "apply", "review", "verify", "archive"];
@@ -973,7 +1132,7 @@ function generateContext(specwfDir, step) {
     requirements: []
   };
   result.conventions = getAllConventions(specwfDir);
-  if (existsSync6(join12(specwfDir, "requirements.md"))) {
+  if (existsSync7(join13(specwfDir, "requirements.md"))) {
     result.requirements.push({ path: "requirements.md", description: "\u9700\u6C42\u89C4\u683C" });
   }
   if (isProjectStep(step)) {
@@ -987,7 +1146,7 @@ function generateContext(specwfDir, step) {
   return result;
 }
 function getAllSpecs(specwfDir) {
-  const specsDir = join12(specwfDir, "specs");
+  const specsDir = join13(specwfDir, "specs");
   return listSpecFiles(specsDir, "specs");
 }
 function getRelatedSpecs(specwfDir, state) {
@@ -1002,34 +1161,34 @@ function getRelatedSpecs(specwfDir, state) {
   return related.length > 0 ? related : allSpecs;
 }
 function getAllConventions(specwfDir) {
-  const convDir = join12(specwfDir, "conventions");
-  if (!existsSync6(convDir)) return [];
-  return readdirSync3(convDir).filter((f) => f.endsWith(".md")).map((f) => ({ path: `conventions/${f}`, description: "\u9879\u76EE\u7EA6\u5B9A" }));
+  const convDir = join13(specwfDir, "conventions");
+  if (!existsSync7(convDir)) return [];
+  return readdirSync4(convDir).filter((f) => f.endsWith(".md")).map((f) => ({ path: `conventions/${f}`, description: "\u9879\u76EE\u7EA6\u5B9A" }));
 }
 function getChangeArtifacts(specwfDir, state) {
   const ref = state.active_context.ref;
   if (!ref) return [];
-  const changeDir = join12(specwfDir, ref);
-  if (!existsSync6(changeDir)) return [];
+  const changeDir = join13(specwfDir, ref);
+  if (!existsSync7(changeDir)) return [];
   const artifacts = [];
   for (const file of ["proposal.md", "design.md", "tasks.md", ".specwf.yaml"]) {
-    const fullPath = join12(changeDir, file);
-    if (existsSync6(fullPath)) {
+    const fullPath = join13(changeDir, file);
+    if (existsSync7(fullPath)) {
       artifacts.push({ path: `${ref}/${file}`, description: "change \u4EA7\u7269" });
     }
   }
-  const specsDir = join12(changeDir, "specs");
-  if (existsSync6(specsDir)) {
+  const specsDir = join13(changeDir, "specs");
+  if (existsSync7(specsDir)) {
     const deltaSpecs = listSpecFiles(specsDir, `${ref}/specs`);
     artifacts.push(...deltaSpecs);
   }
   return artifacts;
 }
 function listSpecFiles(dir, prefix) {
-  if (!existsSync6(dir)) return [];
+  if (!existsSync7(dir)) return [];
   const results = [];
-  for (const entry of readdirSync3(dir)) {
-    const fullPath = join12(dir, entry);
+  for (const entry of readdirSync4(dir)) {
+    const fullPath = join13(dir, entry);
     const stat = statSync2(fullPath);
     if (stat.isDirectory()) {
       results.push(...listSpecFiles(fullPath, `${prefix}/${entry}`));
@@ -1084,7 +1243,7 @@ function register5(program2) {
   program2.command("context <step>").description("\u8F93\u51FA\u5F53\u524D\u6B65\u9AA4\u4E0A\u4E0B\u6587\u6587\u4EF6\u6E05\u5355").option("--json", "JSON \u683C\u5F0F\u8F93\u51FA").action(contextHandler);
 }
 function contextHandler(step, options) {
-  const specwfDir = join13(process.cwd(), "specwf");
+  const specwfDir = join14(process.cwd(), "specwf");
   const result = generateContext(specwfDir, step);
   if (options.json) {
     console.log(JSON.stringify(result, null, 2));
@@ -1094,7 +1253,7 @@ function contextHandler(step, options) {
 }
 
 // src/commands/specwf-continue.ts
-import { join as join14 } from "path";
+import { join as join15 } from "path";
 
 // src/types/state.ts
 var STATE_TRANSITIONS = [
@@ -1117,6 +1276,8 @@ var STATE_TRANSITIONS = [
   { from: "change-verifying", command: "replan", to: "change-planning", slashCommand: "/specwf:plan", subagent: true },
   { from: "change-verifying", command: "reapply", to: "change-applying", slashCommand: "/specwf:apply", subagent: true },
   { from: "change-reviewing", command: "fix", to: "change-applying", slashCommand: "/specwf:apply", subagent: true },
+  // Milestone 层（新里程碑 = 项目流程 - init）
+  { from: "milestone-active", command: "grill", to: "requirements-defined", slashCommand: "/specwf:grill" },
   // Ship
   { from: "change-archived", command: "ship-phase", to: "phase-shipped", slashCommand: "/specwf:ship" },
   { from: "phase-shipped", command: "next-phase", to: "phase-discuss", slashCommand: "/specwf:discuss" },
@@ -1144,9 +1305,10 @@ function determineChangeNextStep(specwfDir, changeName) {
   }
   const adhoc = state.adhoc.find((c) => c.name === changeName);
   if (adhoc) {
+    const prefix = adhoc.status === "proposal" ? "adhoc" : "change";
     return determineFromChangeStatus(
       changeName,
-      `adhoc-${adhoc.status}`,
+      `${prefix}-${adhoc.status}`,
       "adhoc"
     );
   }
@@ -1154,6 +1316,95 @@ function determineChangeNextStep(specwfDir, changeName) {
     error: `change \u4E0D\u5B58\u5728: ${changeName}\u3002\u53EF\u7528: ${listAvailableChanges(state)}`
   };
 }
+var STEP_INFO = {
+  grill: {
+    command: "grill",
+    description: "\u901A\u8FC7\u9010\u6761\u63D0\u95EE\u6536\u96C6\u9700\u6C42\uFF0C\u4EA7\u51FA requirements.md",
+    artifacts: ["specwf/requirements.md"],
+    fileRef: ".omp/commands/specwf-grill.md"
+  },
+  research: {
+    command: "research",
+    description: "\u5E76\u884C\u8C03\u7814\u6280\u672F\u65B9\u5411\u548C\u67B6\u6784\u65B9\u6848",
+    artifacts: ["specwf/research/stack.md", "specwf/research/architecture.md", "specwf/research/pitfalls.md", "specwf/research/summary.md"],
+    fileRef: ".omp/commands/specwf-research.md"
+  },
+  "research-done": {
+    command: "research-done",
+    description: "\u6807\u8BB0\u8C03\u7814\u5B8C\u6210\uFF0C\u8FDB\u5165\u8DEF\u7EBF\u56FE\u62C6\u5206",
+    artifacts: [],
+    fileRef: ""
+  },
+  roadmap: {
+    command: "roadmap",
+    description: "\u5C06\u9879\u76EE\u62C6\u5206\u4E3A Milestone \xD7 Phase",
+    artifacts: ["specwf/roadmap.md"],
+    fileRef: ".omp/commands/specwf-roadmap.md"
+  },
+  discuss: {
+    command: "discuss",
+    description: "Phase \u8BA8\u8BBA\uFF0C\u6355\u83B7\u5B9E\u73B0\u51B3\u7B56",
+    artifacts: ["milestones/<ms>/phases/<ph>/context.md"],
+    fileRef: ".omp/commands/specwf-discuss.md"
+  },
+  "research-phase": {
+    command: "research-phase",
+    description: "\u5BF9\u5F53\u524D phase \u8FDB\u884C\u6280\u672F\u8C03\u7814",
+    artifacts: ["milestones/<ms>/phases/<ph>/research.md"],
+    fileRef: ".omp/commands/specwf-research-phase.md"
+  },
+  split: {
+    command: "split",
+    description: "\u5C06 phase \u62C6\u5206\u4E3A\u591A\u4E2A change\uFF0C\u786E\u5B9A\u4F9D\u8D56\u56FE",
+    artifacts: ["specwf/roadmap.md\uFF08\u66F4\u65B0\uFF09"],
+    fileRef: ".omp/commands/specwf-split.md"
+  },
+  plan: {
+    command: "plan",
+    description: "Change \u8BBE\u8BA1\uFF1A\u8BBE\u8BA1\u6280\u672F\u65B9\u6848\u3001\u62C6\u5206\u4EFB\u52A1\u3001\u9884\u5199 delta-specs",
+    artifacts: ["design.md", "tasks.md", "specs/<domain>/spec.md"],
+    fileRef: ".omp/commands/specwf-plan.md"
+  },
+  apply: {
+    command: "apply",
+    description: "\u6309 tasks.md \u5B9E\u73B0\u4EE3\u7801\uFF0Ctype:behavior \u8D70 RED\u2192GREEN\u2192REFACTOR",
+    artifacts: ["\u4EE3\u7801\u53D8\u66F4", "\u6D4B\u8BD5"],
+    fileRef: ".omp/commands/specwf-apply.md"
+  },
+  review: {
+    command: "review",
+    description: "\u4E09\u91CD\u5BA1\u67E5\uFF1A\u89C4\u683C\u5BA1\u67E5 + \u8D28\u91CF\u5BA1\u67E5 + \u76EE\u6807\u5BA1\u67E5",
+    artifacts: ["REVIEW.md"],
+    fileRef: ".omp/commands/specwf-review.md"
+  },
+  verify: {
+    command: "verify",
+    description: "\u8FD0\u884C\u6D4B\u8BD5\uFF0C\u8BCA\u65AD\u6839\u56E0\uFF0C\u8DEF\u7531\u56DE\u73AF",
+    artifacts: ["VERIFICATION.md"],
+    fileRef: ".omp/commands/specwf-verify.md"
+  },
+  archive: {
+    command: "archive",
+    description: "Delta-spec \u5408\u5E76 + \u4EE3\u7801\u8BA4\u77E5\u56DE\u704C + \u76EE\u5F55\u5F52\u6863",
+    artifacts: ["archive/<change-id>/"],
+    fileRef: ".omp/commands/specwf-archive.md"
+  },
+  "ship-phase": {
+    command: "ship-phase",
+    description: "\u521B\u5EFA PR + \u66F4\u65B0 state.md",
+    artifacts: ["GitHub PR", "state.md \u66F4\u65B0"],
+    fileRef: ".omp/commands/specwf-ship.md"
+  },
+  "ship-milestone": {
+    command: "ship-milestone",
+    description: "\u53D1\u5E03 release tag + \u66F4\u65B0\u7248\u672C\u53F7",
+    artifacts: ["git tag", "RELEASE.md", "npm publish"],
+    fileRef: ".omp/commands/specwf-ship.md"
+  }
+};
+function getStepInfo(command) {
+  return STEP_INFO[command];
+}
 function determineFromChangeStatus(name, statusKey, type) {
   const available = getNextSteps(statusKey);
   const availableSteps = available.map((t) => ({
@@ -1169,7 +1420,8 @@ function determineFromChangeStatus(name, statusKey, type) {
     slashCommand: first?.slashCommand || null,
     needsSubagent: first?.subagent ?? false,
     availableSteps,
-    hint: available.length === 0 ? "\u8BE5 change \u5DF2\u6CA1\u6709\u53EF\u7528\u4E0B\u4E00\u6B65\u3002\u521B\u5EFA\u65B0 change \u7EE7\u7EED\u3002" : null
+    hint: available.length === 0 ? "\u8BE5 change \u5DF2\u6CA1\u6709\u53EF\u7528\u4E0B\u4E00\u6B65\u3002\u521B\u5EFA\u65B0 change \u7EE7\u7EED\u3002" : null,
+    nextStepInfo: first ? getStepInfo(first.command) : void 0
   };
 }
 function listAvailableChanges(state) {
@@ -1197,7 +1449,8 @@ function determineFromState(state) {
     slashCommand: first?.slashCommand || null,
     needsSubagent: first?.subagent ?? false,
     availableSteps,
-    hint
+    hint,
+    nextStepInfo: first ? getStepInfo(first.command) : void 0
   };
 }
 function resolveStatus(state) {
@@ -1263,14 +1516,27 @@ function formatContinueResult(result) {
   console.log(`\u5F53\u524D\u4F4D\u7F6E: ${result.context}`);
   console.log(`\u5F53\u524D\u6B65\u9AA4: ${result.currentStep}`);
   if (result.nextCommand) {
+    const info = result.nextStepInfo;
     console.log("");
-    console.log(`\u2192 \u63A8\u8350\u4E0B\u4E00\u6B65: ${result.nextCommand}`);
+    console.log(`\u2192 \u4E0B\u4E00\u6B65: ${result.nextCommand}`);
     if (result.slashCommand) {
       console.log(`   Slash \u547D\u4EE4: ${result.slashCommand}`);
     }
     if (result.needsSubagent) {
       console.log(`   \u9700\u8981\u5B50\u4EE3\u7406: \u662F`);
     }
+    if (info) {
+      console.log(`   \u63CF\u8FF0: ${info.description}`);
+      if (info.artifacts.length > 0) {
+        console.log(`   \u4EA7\u51FA\u7269:`);
+        for (const a of info.artifacts) {
+          console.log(`     - ${a}`);
+        }
+      }
+      if (info.fileRef) {
+        console.log(`   \u53C2\u8003: ${info.fileRef}`);
+      }
+    }
   } else {
     console.log("");
     console.log("\u2192 \u5F53\u524D\u65E0\u53EF\u7528\u4E0B\u4E00\u6B65");
@@ -1281,12 +1547,12 @@ function formatContinueResult(result) {
   console.log("\u2500".repeat(50));
 }
 function continueHandler() {
-  const specwfDir = join14(process.cwd(), "specwf");
+  const specwfDir = join15(process.cwd(), "specwf");
   const result = determineNextStep(specwfDir);
   formatContinueResult(result);
 }
 function continueChangeHandler(name) {
-  const specwfDir = join14(process.cwd(), "specwf");
+  const specwfDir = join15(process.cwd(), "specwf");
   const result = determineChangeNextStep(specwfDir, name);
   if ("error" in result) {
     console.log("\u2500".repeat(50));
@@ -1298,12 +1564,12 @@ function continueChangeHandler(name) {
 }
 
 // src/commands/specwf-archive.ts
-import { join as join16 } from "path";
-import { existsSync as existsSync9, readdirSync as readdirSync5, mkdirSync as mkdirSync5, copyFileSync } from "fs";
+import { join as join17 } from "path";
+import { existsSync as existsSync10, readdirSync as readdirSync6, mkdirSync as mkdirSync5, copyFileSync } from "fs";
 
 // src/core/delta-merge.ts
 import { createHash } from "crypto";
-import { readFileSync as readFileSync10, writeFileSync as writeFileSync6, existsSync as existsSync7 } from "fs";
+import { readFileSync as readFileSync11, writeFileSync as writeFileSync6, existsSync as existsSync8 } from "fs";
 
 // src/parser/heading-tree.ts
 function parseHeadings(markdown) {
@@ -1438,8 +1704,8 @@ function renderNodes(nodes, lines) {
   }
 }
 function mergeAndWrite(liveSpecPath, deltaSpecPath, baseFingerprint) {
-  const baseSpec = readFileSync10(liveSpecPath, "utf-8");
-  const deltaSpec = readFileSync10(deltaSpecPath, "utf-8");
+  const baseSpec = readFileSync11(liveSpecPath, "utf-8");
+  const deltaSpec = readFileSync11(deltaSpecPath, "utf-8");
   const result = mergeDeltaSpec(baseSpec, deltaSpec, baseFingerprint);
   if (result.type === "ok") {
     writeFileSync6(liveSpecPath, result.merged, "utf-8");
@@ -1449,8 +1715,8 @@ function mergeAndWrite(liveSpecPath, deltaSpecPath, baseFingerprint) {
 
 // src/core/code-extract.ts
 import { execSync } from "child_process";
-import { existsSync as existsSync8, readFileSync as readFileSync11, writeFileSync as writeFileSync7, mkdirSync as mkdirSync4, readdirSync as readdirSync4 } from "fs";
-import { join as join15 } from "path";
+import { existsSync as existsSync9, readFileSync as readFileSync12, writeFileSync as writeFileSync7, mkdirSync as mkdirSync4, readdirSync as readdirSync5 } from "fs";
+import { join as join16 } from "path";
 function extractFromGitDiff(repoDir, changeDir) {
   const diff = getGitDiff(repoDir);
   if (diff === null) {
@@ -1486,10 +1752,10 @@ function getGitDiff(repoDir) {
   }
 }
 function detectDomains(changeDir) {
-  const specsDir = join15(changeDir, "specs");
-  if (!existsSync8(specsDir)) return ["general"];
+  const specsDir = join16(changeDir, "specs");
+  if (!existsSync9(specsDir)) return ["general"];
   try {
-    return readdirSync4(specsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    return readdirSync5(specsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
   } catch {
     return ["general"];
   }
@@ -1527,11 +1793,11 @@ function extractConstraints(diff, _domain) {
   return constraints;
 }
 function writeExtractionToSpec(specsDir, extraction) {
-  const domainDir = join15(specsDir, extraction.domain);
-  const specPath = join15(domainDir, "spec.md");
+  const domainDir = join16(specsDir, extraction.domain);
+  const specPath = join16(domainDir, "spec.md");
   let existing = "";
-  if (existsSync8(specPath)) {
-    existing = readFileSync11(specPath, "utf-8");
+  if (existsSync9(specPath)) {
+    existing = readFileSync12(specPath, "utf-8");
   }
   const section = generateAutoExtractedSection(extraction);
   const updated = existing.trim() ? `${existing.trim()}
@@ -1570,14 +1836,14 @@ function register7(program2) {
   program2.command("archive <change>").description("\u5F52\u6863 change\uFF08delta \u5408\u5E76 + \u4EE3\u7801\u56DE\u704C\uFF09").action(archiveHandler);
 }
 function archiveHandler(changePath) {
-  const specwfDir = join16(process.cwd(), "specwf");
-  const fullChangePath = join16(process.cwd(), changePath);
-  if (!existsSync9(fullChangePath)) {
+  const specwfDir = join17(process.cwd(), "specwf");
+  const fullChangePath = join17(process.cwd(), changePath);
+  if (!existsSync10(fullChangePath)) {
     console.error(`\u9519\u8BEF: change \u76EE\u5F55\u4E0D\u5B58\u5728: ${changePath}`);
     process.exit(1);
   }
-  const specsDir = join16(fullChangePath, "specs");
-  if (existsSync9(specsDir)) {
+  const specsDir = join17(fullChangePath, "specs");
+  if (existsSync10(specsDir)) {
     mergeDeltaSpecs(specsDir, specwfDir);
     console.log("\u2713 delta-specs \u5408\u5E76\u5B8C\u6210");
   }
@@ -1585,7 +1851,7 @@ function archiveHandler(changePath) {
   const extractResult = extractFromGitDiff(repoDir, fullChangePath);
   if (extractResult.available && extractResult.extractions.length > 0) {
     for (const extraction of extractResult.extractions) {
-      writeExtractionToSpec(join16(specwfDir, "specs"), extraction);
+      writeExtractionToSpec(join17(specwfDir, "specs"), extraction);
     }
     if (extractResult.extractions.length > 0) {
       console.log(`\u2713 \u4EE3\u7801\u8BA4\u77E5\u63D0\u53D6\u5B8C\u6210 (${extractResult.extractions.length} \u4E2A\u57DF)`);
@@ -1612,14 +1878,14 @@ function archiveHandler(changePath) {
   console.log("\u5F52\u6863\u5B8C\u6210\u3002");
 }
 function mergeDeltaSpecs(deltaDir, specwfDir) {
-  const entries = readdirSync5(deltaDir, { withFileTypes: true });
+  const entries = readdirSync6(deltaDir, { withFileTypes: true });
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const deltaSpecPath = join16(deltaDir, entry.name, "spec.md");
-    const liveSpecPath = join16(specwfDir, "specs", entry.name, "spec.md");
-    if (!existsSync9(deltaSpecPath)) continue;
-    if (!existsSync9(liveSpecPath)) {
-      mkdirSync5(join16(specwfDir, "specs", entry.name), { recursive: true });
+    const deltaSpecPath = join17(deltaDir, entry.name, "spec.md");
+    const liveSpecPath = join17(specwfDir, "specs", entry.name, "spec.md");
+    if (!existsSync10(deltaSpecPath)) continue;
+    if (!existsSync10(liveSpecPath)) {
+      mkdirSync5(join17(specwfDir, "specs", entry.name), { recursive: true });
       copyFileSync(deltaSpecPath, liveSpecPath);
       continue;
     }
@@ -1634,12 +1900,12 @@ function mergeDeltaSpecs(deltaDir, specwfDir) {
 }
 
 // src/commands/specwf-list.ts
-import { join as join17 } from "path";
+import { join as join18 } from "path";
 function register8(program2) {
   program2.command("list").description("\u5217\u51FA milestones/phases/changes").option("--all", "\u5305\u542B\u5F52\u6863").action(listHandler);
 }
 function listHandler(options) {
-  const specwfDir = join17(process.cwd(), "specwf");
+  const specwfDir = join18(process.cwd(), "specwf");
   let hasItems = false;
   const milestones = listMilestones(specwfDir);
   if (milestones.length > 0) {
@@ -1683,11 +1949,11 @@ function listHandler(options) {
 }
 
 // src/commands/specwf-template.ts
-import { join as join18, dirname as dirname4 } from "path";
-import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync8, existsSync as existsSync10, readFileSync as readFileSync13 } from "fs";
+import { join as join19, dirname as dirname4 } from "path";
+import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync8, existsSync as existsSync11, readFileSync as readFileSync14 } from "fs";
 import { fileURLToPath as fileURLToPath4 } from "url";
 var __dirname4 = dirname4(fileURLToPath4(import.meta.url));
-var TEMPLATES_DIR4 = join18(__dirname4, "templates", "artifacts");
+var TEMPLATES_DIR4 = join19(__dirname4, "templates", "artifacts");
 var TEMPLATE_TYPES = [
   "proposal",
   "design",
@@ -1710,12 +1976,12 @@ function templateHandler(type, options) {
     console.error(`\u672A\u77E5\u6A21\u677F\u7C7B\u578B: ${type}\u3002\u53EF\u9009: ${TEMPLATE_TYPES.join(", ")}`);
     process.exit(1);
   }
-  const templatePath = join18(TEMPLATES_DIR4, type.endsWith(".yml") || type.endsWith(".md") ? type : `${type}.md`);
-  if (!existsSync10(templatePath)) {
+  const templatePath = join19(TEMPLATES_DIR4, type.endsWith(".yml") || type.endsWith(".md") ? type : `${type}.md`);
+  if (!existsSync11(templatePath)) {
     console.error(`\u6A21\u677F\u6587\u4EF6\u4E0D\u5B58\u5728: ${templatePath}`);
     process.exit(1);
   }
-  let content = readFileSync13(templatePath, "utf-8");
+  let content = readFileSync14(templatePath, "utf-8");
   const name = options.name;
   const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   content = content.replace(/\{\{name\}\}/g, name);
@@ -1725,24 +1991,24 @@ function templateHandler(type, options) {
   let targetDir;
   let filename;
   if (options.dir) {
-    targetDir = options.dir.startsWith("/") ? options.dir : join18(process.cwd(), options.dir);
+    targetDir = options.dir.startsWith("/") ? options.dir : join19(process.cwd(), options.dir);
     filename = type;
   } else if (type === "project.yml" || type === "state.md") {
-    targetDir = join18(process.cwd(), "specwf");
+    targetDir = join19(process.cwd(), "specwf");
     filename = type;
   } else {
-    targetDir = join18(process.cwd(), "specwf", "changes", name);
+    targetDir = join19(process.cwd(), "specwf", "changes", name);
     filename = type.endsWith(".yml") ? type : `${type}.md`;
   }
   mkdirSync6(targetDir, { recursive: true });
-  const fullPath = join18(targetDir, filename);
+  const fullPath = join19(targetDir, filename);
   writeFileSync8(fullPath, content, "utf-8");
   console.log(`\u2713 \u521B\u5EFA ${fullPath}`);
 }
 
 // src/commands/specwf-change.ts
-import { join as join19, dirname as dirname5 } from "path";
-import { existsSync as existsSync11, readFileSync as readFileSync14, writeFileSync as writeFileSync9 } from "fs";
+import { join as join20, dirname as dirname5 } from "path";
+import { existsSync as existsSync12, readFileSync as readFileSync15, writeFileSync as writeFileSync9 } from "fs";
 import { fileURLToPath as fileURLToPath5 } from "url";
 var __dirname5 = dirname5(fileURLToPath5(import.meta.url));
 function register10(program2) {
@@ -1753,23 +2019,23 @@ function register10(program2) {
   });
 }
 function newChange(name, options) {
-  const specwfDir = join19(process.cwd(), options.dir);
+  const specwfDir = join20(process.cwd(), options.dir);
   const changeDir = createAdhocChangeDir(specwfDir, name);
   console.log(`\u2713 \u521B\u5EFA change \u76EE\u5F55: changes/${name}/`);
-  const templatesDir = join19(__dirname5, "templates", "artifacts");
+  const templatesDir = join20(__dirname5, "templates", "artifacts");
   const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
   for (const file of ["proposal.md", "design.md", "tasks.md"]) {
-    const tplPath = join19(templatesDir, file);
+    const tplPath = join20(templatesDir, file);
     let content;
-    if (existsSync11(tplPath)) {
-      content = readFileSync14(tplPath, "utf-8");
+    if (existsSync12(tplPath)) {
+      content = readFileSync15(tplPath, "utf-8");
       content = content.replace(/\{\{name\}\}/g, name);
       content = content.replace(/\{\{date\}\}/g, date);
     } else {
       content = `# ${file.replace(".md", "")}: ${name}
 `;
     }
-    writeFileSync9(join19(changeDir, file), content, "utf-8");
+    writeFileSync9(join20(changeDir, file), content, "utf-8");
   }
   console.log("\u2713 \u521B\u5EFA\u6A21\u677F\u6587\u4EF6: proposal.md, design.md, tasks.md");
   try {

package/dist/templates/commands/init.md

@@ -1,10 +1,23 @@
 # 初始化项目
 
-执行 `specwf init` 创建 specwf 目录结构。
+运行 `specwf init` 创建 specwf/ 目录结构 + platform.yml + state.md。
 
 ## 存量项目
 
-如果已有代码，执行 `specwf init --brownfield`，CLI 自动完成 codebase mapping + spec bootstrap。
+已有代码的项目使用 brownfield 模式：
+
+```bash
+specwf init --brownfield
+```
+
+CLI 创建目录结构后，**agent 需使用 specwf 子代理并行执行以下任务**：
+
+1. **Codebase Mapping**（`specwf-researcher`）— 分析技术栈、模块结构、依赖关系
+   - 产出: `specwf/research/STACK.md` + `specwf/research/ARCHITECTURE.md`
+2. **Spec Bootstrap**（`specwf-researcher`）— 从核心模块提取行为契约
+   - 产出: `specwf/specs/<domain>/spec.md`（标记 BOOTSTRAPPED）
+
+使用 task 工具 fan-out 两个 specwf-researcher 并行执行。
 
 ## 上下文
 
@@ -13,8 +26,12 @@ specwf context init
 specwf state
 ```
 
+可参考 @specwf/conventions/coding.md。
+
 ## 下一步
 
+完成后：
+
 ```bash
 specwf continue
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specwf",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "规格驱动开发工作流 — spec-driven development workflow for AI coding agents",
   "type": "module",
   "bin": {