kiro-spec-engine 1.45.13 → 1.46.0

package/docs/troubleshooting.md

@@ -249,7 +249,7 @@ No Specs found in .kiro/specs/
 
 **Create your first Spec:**
 ```bash
-kse create-spec 01-00-my-feature
+kse spec bootstrap --name 01-00-my-feature --non-interactive
 ```
 
 **Or check if Specs exist:**
@@ -263,7 +263,7 @@ ls -la .kiro/specs/
 
 **Symptoms:**
 ```bash
-$ kse create-spec my-feature
+$ kse spec bootstrap --name my-feature --non-interactive
 Error: Invalid Spec name format
 Expected: {number}-{number}-{kebab-case-name}
 ```
@@ -275,13 +275,13 @@ Expected: {number}-{number}-{kebab-case-name}
 **Use correct format:**
 ```bash
 # ✅ Correct
-kse create-spec 01-00-user-login
-kse create-spec 02-01-fix-auth-bug
+kse spec bootstrap --name 01-00-user-login --non-interactive
+kse spec bootstrap --name 02-01-fix-auth-bug --non-interactive
 
 # ❌ Wrong
-kse create-spec user-login
-kse create-spec 01-user-login
-kse create-spec UserLogin
+kse spec bootstrap --name user-login --non-interactive
+kse spec bootstrap --name 01-user-login --non-interactive
+kse spec bootstrap --name UserLogin --non-interactive
 ```
 
 ---
@@ -302,7 +302,7 @@ Error: Failed to export context
 ls .kiro/specs/01-00-user-login/
 
 # If not, create it
-kse create-spec 01-00-user-login
+kse spec bootstrap --name 01-00-user-login --non-interactive
 ```
 
 **2. Missing Spec files:**
@@ -1063,7 +1063,7 @@ ls -la .kiro/
 Context export fails for Spec with Chinese characters in filename
 
 ## Steps to Reproduce
-1. Create Spec: kse create-spec 01-00-用户登录
+1. Create Spec: kse spec bootstrap --name 01-00-用户登录 --non-interactive
 2. Run: kse context export 01-00-用户登录
 3. Error occurs
 
@@ -1132,3 +1132,4 @@ kse docs cleanup --dry-run
 
 **Version**: 1.42.0  
 **Last Updated**: 2026-02-11
+

package/docs/zh/quick-start.md

@@ -4,8 +4,8 @@
 
 ---
 
-**版本**: 1.42.0  
-**最后更新**: 2026-02-11  
+**版本**: 1.46.0  
+**最后更新**: 2026-02-13  
 **预计时间**: 5 分钟  
 **目标读者**: 初学者
 
@@ -100,7 +100,7 @@ kse adopt
 ✅ 项目成功采用 kse！
 
 下一步：
-  1. 创建你的第一个 Spec：kse create-spec 01-00-my-feature
+  1. 创建你的第一个 Spec：kse spec bootstrap --name 01-00-my-feature --non-interactive
   2. 阅读指南：.kiro/README.md
 ```
 
@@ -130,20 +130,20 @@ Status: Ready
 
 ---
 
-## 步骤 3：创建你的第一个 Spec（2 分钟）
+## 步骤 3：生成你的第一个 Spec 初稿（2 分钟）
 
-让我们为用户登录功能创建一个 Spec：
+让我们为用户登录功能生成一个 Spec 初稿：
 
 ```bash
-kse create-spec 01-00-user-login
+kse spec bootstrap --name 01-00-user-login --non-interactive
 ```
 
 **预期输出：**
 ```
-✓ 创建 spec：01-00-user-login
-✓ 创建 requirements.md
-✓ 创建 design.md
-✓ 创建 tasks.md
+✓ 生成 Spec 初稿：01-00-user-login
+✓ 生成 requirements.md
+✓ 生成 design.md
+✓ 生成 tasks.md
 
 📝 下一步：
   1. 编辑 requirements.md 定义你要构建什么
@@ -151,6 +151,14 @@ kse create-spec 01-00-user-login
   3. 编辑 tasks.md 分解实现步骤
 ```
 
+多 Spec 场景下可直接使用：
+
+```bash
+kse spec bootstrap --specs "01-00-user-login,01-01-user-session" --max-parallel 3
+```
+
+上述命令会默认切换到 orchestrate 模式并并行推进。
+
 ### 3.1 编写需求
 
 打开 `.kiro/specs/01-00-user-login/requirements.md` 并编写：
@@ -477,6 +485,13 @@ graph TD
 
 现在你的 Spec 已完成，为你的 AI 工具导出它：
 
+（可选）先执行标准化流程和闸口检查：
+
+```bash
+kse spec pipeline run --spec 01-00-user-login
+kse spec gate run --spec 01-00-user-login --json
+```
+
 ```bash
 kse context export 01-00-user-login
 ```
@@ -696,16 +711,17 @@ ls .kiro/specs/
 
 **kse 工作流：**
 ```
-创建 Spec → 导出上下文 → AI 实现 → 更新任务 → 重复
+bootstrap Spec → pipeline/gate → 导出上下文 → AI 实现 → 更新任务 → 重复
 ```
 
 **准备好构建你的下一个功能了吗？** 🚀
 
 ```bash
-kse create-spec 02-00-your-next-feature
+kse spec bootstrap --name 02-00-your-next-feature --non-interactive
 ```
 
 ---
 
-**版本**: 1.42.0  
-**最后更新**: 2026-02-11
+**版本**: 1.46.0  
+**最后更新**: 2026-02-13
+

package/docs/zh/tools/claude-guide.md

@@ -129,7 +129,7 @@ Claude 通过 Web 界面工作，无需特殊配置。只需导出上下文并
 
 ```bash
 # 1. 创建 Spec
-kse create-spec 01-00-user-login
+kse spec bootstrap --name 01-00-user-login --non-interactive
 
 # 2. 编写 requirements.md、design.md、tasks.md
 
@@ -346,3 +346,4 @@ Claude 擅长解释。询问：
 
 **版本**: 1.42.0  
 **最后更新**: 2026-02-11
+

package/docs/zh/tools/cursor-guide.md

@@ -173,7 +173,7 @@
 
 ```bash
 # 1. 创建 Spec
-kse create-spec 01-00-user-login
+kse spec bootstrap --name 01-00-user-login --non-interactive
 
 # 2. 编写 requirements.md、design.md、tasks.md
 
@@ -278,3 +278,4 @@ kse prompt generate 01-00-user-login 1.1
 
 **版本**: 1.42.0  
 **最后更新**: 2026-02-11
+

package/docs/zh/tools/generic-guide.md

@@ -50,7 +50,7 @@ kse --version
 kse adopt
 
 # 创建 Spec
-kse create-spec 01-00-my-feature
+kse spec bootstrap --name 01-00-my-feature --non-interactive
 ```
 
 **使用：**
@@ -79,7 +79,7 @@ npm install -g kiro-spec-engine
 kse adopt
 
 # 创建 Spec
-kse create-spec 01-00-my-feature
+kse spec bootstrap --name 01-00-my-feature --non-interactive
 ```
 
 **使用：**
@@ -128,7 +128,7 @@ kse watch add --pattern ".kiro/specs/*/design.md" --action "kse context export {
 ### 步骤 1：创建 Spec
 
 ```bash
-kse create-spec 01-00-my-feature
+kse spec bootstrap --name 01-00-my-feature --non-interactive
 ```
 
 ### 步骤 2：编写 Spec
@@ -292,7 +292,7 @@ kse prompt generate 01-00-my-feature 1.1
 
 ```bash
 # 1. 创建并编写 Spec
-kse create-spec 01-00-user-login
+kse spec bootstrap --name 01-00-user-login --non-interactive
 # 编辑 requirements.md、design.md、tasks.md
 
 # 2. 导出上下文
@@ -315,7 +315,7 @@ cat .kiro/specs/01-00-user-login/context-export.md | pbcopy
 
 ```bash
 # 1. 创建并编写 Spec
-kse create-spec 01-00-user-login
+kse spec bootstrap --name 01-00-user-login --non-interactive
 
 # 2. 生成任务特定提示
 kse prompt generate 01-00-user-login 1.1
@@ -334,7 +334,7 @@ kse prompt generate 01-00-user-login 1.1
 
 ```bash
 # 1. 创建并编写 Spec
-kse create-spec 01-00-user-login
+kse spec bootstrap --name 01-00-user-login --non-interactive
 
 # 2. 在 Windsurf 中告诉 AI：
 "使用 kse 检查 01-00-user-login 的 spec 并实现任务 1.1"
@@ -352,7 +352,7 @@ kse create-spec 01-00-user-login
 
 ```bash
 # 1. 创建并编写 Spec
-kse create-spec 01-00-user-login
+kse spec bootstrap --name 01-00-user-login --non-interactive
 
 # 2. 创建实现文件
 # src/auth/AuthController.js
@@ -496,3 +496,4 @@ cp -r .kiro/templates/api-feature-template .kiro/specs/02-00-new-feature
 
 **版本**: 1.42.0  
 **最后更新**: 2026-02-11
+

package/docs/zh/tools/vscode-guide.md

@@ -211,7 +211,7 @@
 
 ```bash
 # 1. 创建 Spec
-kse create-spec 01-00-user-login
+kse spec bootstrap --name 01-00-user-login --non-interactive
 
 # 2. 在 VS Code 中编写 Spec
 # - 打开 requirements.md
@@ -446,3 +446,4 @@ Copilot 使用所有打开文件的上下文。
 
 **版本**: 1.42.0  
 **最后更新**: 2026-02-11
+

package/docs/zh/tools/windsurf-guide.md

@@ -150,7 +150,7 @@ kse watch start
 
 ```bash
 # 1. 创建 Spec
-kse create-spec 01-00-user-login
+kse spec bootstrap --name 01-00-user-login --non-interactive
 
 # 2. 编写 requirements.md、design.md、tasks.md
 
@@ -375,3 +375,4 @@ kse watch stop
 
 **版本**: 1.42.0  
 **最后更新**: 2026-02-11
+

package/lib/commands/orchestrate.js

@@ -14,6 +14,108 @@ const fs = require('fs-extra');
 const SPECS_DIR = '.kiro/specs';
 const STATUS_FILE = '.kiro/config/orchestration-status.json';
 
+/**
+ * Run orchestration programmatically.
+ *
+ * @param {object} options
+ * @param {string} [options.specs] - Comma separated spec names
+ * @param {string[]} [options.specNames] - Explicit spec names array
+ * @param {number} [options.maxParallel]
+ * @param {boolean} [options.json]
+ * @param {boolean} [options.silent]
+ * @param {object} dependencies
+ * @param {string} [dependencies.workspaceRoot]
+ * @returns {Promise<object>}
+ */
+async function runOrchestration(options = {}, dependencies = {}) {
+  const workspaceRoot = dependencies.workspaceRoot || process.cwd();
+  const specNames = Array.isArray(options.specNames)
+    ? options.specNames.map(name => `${name}`.trim()).filter(Boolean)
+    : _parseSpecNamesOption(options.specs);
+
+  if (specNames.length === 0) {
+    throw new Error('No specs specified');
+  }
+
+  const maxParallel = options.maxParallel;
+  if (maxParallel !== undefined && (isNaN(maxParallel) || maxParallel < 1)) {
+    throw new Error('--max-parallel must be >= 1');
+  }
+
+  const missing = await _validateSpecs(workspaceRoot, specNames);
+  if (missing.length > 0) {
+    throw new Error(`Specs not found: ${missing.join(', ')}`);
+  }
+
+  const { OrchestratorConfig } = require('../orchestrator/orchestrator-config');
+  const { BootstrapPromptBuilder } = require('../orchestrator/bootstrap-prompt-builder');
+  const { AgentSpawner } = require('../orchestrator/agent-spawner');
+  const { StatusMonitor } = require('../orchestrator/status-monitor');
+  const { OrchestrationEngine } = require('../orchestrator/orchestration-engine');
+
+  const DependencyManager = require('../collab/dependency-manager');
+  const MetadataManager = require('../collab/metadata-manager');
+  const { AgentRegistry } = require('../collab/agent-registry');
+  const { SpecLifecycleManager } = require('../collab/spec-lifecycle-manager');
+  const { MachineIdentifier } = require('../lock/machine-identifier');
+
+  let contextSyncManager = null;
+  try {
+    const { ContextSyncManager } = require('../steering/context-sync-manager');
+    contextSyncManager = new ContextSyncManager(workspaceRoot);
+  } catch (_err) {
+    // Non-fatal — status sync will be skipped
+  }
+
+  const orchestratorConfig = new OrchestratorConfig(workspaceRoot);
+  const config = await orchestratorConfig.getConfig();
+  const effectiveMaxParallel = maxParallel || config.maxParallel;
+
+  const bootstrapPromptBuilder = new BootstrapPromptBuilder(workspaceRoot, orchestratorConfig);
+  const machineIdentifier = new MachineIdentifier(
+    path.join(workspaceRoot, '.kiro', 'config')
+  );
+  const agentRegistry = new AgentRegistry(workspaceRoot, machineIdentifier);
+  const agentSpawner = new AgentSpawner(
+    workspaceRoot, orchestratorConfig, agentRegistry, bootstrapPromptBuilder
+  );
+  const metadataManager = new MetadataManager(workspaceRoot);
+  const dependencyManager = new DependencyManager(metadataManager);
+  const specLifecycleManager = new SpecLifecycleManager(
+    workspaceRoot, contextSyncManager, agentRegistry
+  );
+  const statusMonitor = new StatusMonitor(specLifecycleManager, contextSyncManager);
+
+  const engine = new OrchestrationEngine(workspaceRoot, {
+    agentSpawner,
+    dependencyManager,
+    specLifecycleManager,
+    statusMonitor,
+    orchestratorConfig,
+    agentRegistry,
+  });
+
+  if (!options.silent && !options.json) {
+    console.log(
+      chalk.blue('🚀'),
+      `Starting orchestration for ${specNames.length} spec(s) (max-parallel: ${effectiveMaxParallel})...`
+    );
+  }
+
+  const result = await engine.start(specNames, { maxParallel: effectiveMaxParallel });
+  await _writeStatus(workspaceRoot, engine.getStatus());
+
+  if (!options.silent) {
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      _printResult(result);
+    }
+  }
+
+  return result;
+}
+
 /**
  * Register orchestrate commands on the given Commander program.
  * @param {import('commander').Command} program
@@ -32,100 +134,7 @@ function registerOrchestrateCommands(program) {
     .option('--json', 'Output in JSON format')
     .action(async (options) => {
       try {
-        const workspaceRoot = process.cwd();
-        const specNames = options.specs
-          .split(',')
-          .map(s => s.trim())
-          .filter(Boolean);
-
-        if (specNames.length === 0) {
-          _errorAndExit('No specs specified', options.json);
-        }
-
-        // Validate maxParallel
-        const maxParallel = options.maxParallel;
-        if (maxParallel !== undefined && (isNaN(maxParallel) || maxParallel < 1)) {
-          _errorAndExit('--max-parallel must be >= 1', options.json);
-        }
-
-        // Validate spec existence
-        const missing = await _validateSpecs(workspaceRoot, specNames);
-        if (missing.length > 0) {
-          _errorAndExit(
-            `Specs not found: ${missing.join(', ')}`,
-            options.json
-          );
-        }
-
-        // Lazy-require orchestrator modules
-        const { OrchestratorConfig } = require('../orchestrator/orchestrator-config');
-        const { BootstrapPromptBuilder } = require('../orchestrator/bootstrap-prompt-builder');
-        const { AgentSpawner } = require('../orchestrator/agent-spawner');
-        const { StatusMonitor } = require('../orchestrator/status-monitor');
-        const { OrchestrationEngine } = require('../orchestrator/orchestration-engine');
-
-        // Lazy-require collab modules
-        const DependencyManager = require('../collab/dependency-manager');
-        const MetadataManager = require('../collab/metadata-manager');
-        const { AgentRegistry } = require('../collab/agent-registry');
-        const { SpecLifecycleManager } = require('../collab/spec-lifecycle-manager');
-        const { MachineIdentifier } = require('../lock/machine-identifier');
-
-        // Optional: ContextSyncManager
-        let contextSyncManager = null;
-        try {
-          const { ContextSyncManager } = require('../steering/context-sync-manager');
-          contextSyncManager = new ContextSyncManager(workspaceRoot);
-        } catch (_err) {
-          // Non-fatal — status sync will be skipped
-        }
-
-        // Wire dependencies
-        const orchestratorConfig = new OrchestratorConfig(workspaceRoot);
-        const config = await orchestratorConfig.getConfig();
-        const effectiveMaxParallel = maxParallel || config.maxParallel;
-
-        const bootstrapPromptBuilder = new BootstrapPromptBuilder(workspaceRoot, orchestratorConfig);
-        const machineIdentifier = new MachineIdentifier(
-          path.join(workspaceRoot, '.kiro', 'config')
-        );
-        const agentRegistry = new AgentRegistry(workspaceRoot, machineIdentifier);
-        const agentSpawner = new AgentSpawner(
-          workspaceRoot, orchestratorConfig, agentRegistry, bootstrapPromptBuilder
-        );
-        const metadataManager = new MetadataManager(workspaceRoot);
-        const dependencyManager = new DependencyManager(metadataManager);
-        const specLifecycleManager = new SpecLifecycleManager(
-          workspaceRoot, contextSyncManager, agentRegistry
-        );
-        const statusMonitor = new StatusMonitor(specLifecycleManager, contextSyncManager);
-
-        const engine = new OrchestrationEngine(workspaceRoot, {
-          agentSpawner,
-          dependencyManager,
-          specLifecycleManager,
-          statusMonitor,
-          orchestratorConfig,
-          agentRegistry,
-        });
-
-        if (!options.json) {
-          console.log(
-            chalk.blue('🚀'),
-            `Starting orchestration for ${specNames.length} spec(s) (max-parallel: ${effectiveMaxParallel})...`
-          );
-        }
-
-        const result = await engine.start(specNames, { maxParallel: effectiveMaxParallel });
-
-        // Persist status for the `status` subcommand
-        await _writeStatus(workspaceRoot, engine.getStatus());
-
-        if (options.json) {
-          console.log(JSON.stringify(result, null, 2));
-        } else {
-          _printResult(result);
-        }
+        const result = await runOrchestration(options);
 
         if (result.status === 'failed') {
           process.exit(1);
@@ -312,4 +321,23 @@ function _errorAndExit(message, json) {
   process.exit(1);
 }
 
-module.exports = { registerOrchestrateCommands };
+/**
+ * Parse a comma-separated specs option.
+ * @param {string} specsOption
+ * @returns {string[]}
+ */
+function _parseSpecNamesOption(specsOption) {
+  if (!specsOption || typeof specsOption !== 'string') {
+    return [];
+  }
+
+  return specsOption
+    .split(',')
+    .map(item => item.trim())
+    .filter(Boolean);
+}
+
+module.exports = {
+  registerOrchestrateCommands,
+  runOrchestration,
+};

package/lib/commands/spec-bootstrap.js

@@ -0,0 +1,147 @@
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+const { runOrchestration } = require('./orchestrate');
+const {
+  parseSpecTargets,
+  runMultiSpecViaOrchestrate
+} = require('../spec/multi-spec-orchestrate');
+
+const { ContextCollector } = require('../spec/bootstrap/context-collector');
+const { QuestionnaireEngine } = require('../spec/bootstrap/questionnaire-engine');
+const { DraftGenerator } = require('../spec/bootstrap/draft-generator');
+const { TraceEmitter } = require('../spec/bootstrap/trace-emitter');
+
+async function runSpecBootstrap(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+
+  const specTargets = parseSpecTargets({
+    spec: options.spec || options.name,
+    specs: options.specs
+  });
+
+  if (specTargets.length > 1) {
+    const executeOrchestration = dependencies.runOrchestration || runOrchestration;
+    return runMultiSpecViaOrchestrate({
+      specTargets,
+      projectPath,
+      commandOptions: options,
+      runOrchestration: executeOrchestration,
+      commandLabel: 'Multi-spec bootstrap',
+      nextActionLabel: 'Multi-spec bootstrap defaulted to orchestrate mode.'
+    });
+  }
+
+  const contextCollector = dependencies.contextCollector || new ContextCollector(projectPath);
+  const questionnaireEngine = dependencies.questionnaireEngine || new QuestionnaireEngine({
+    prompt: dependencies.prompt,
+    maxQuestions: dependencies.maxQuestions
+  });
+  const draftGenerator = dependencies.draftGenerator || new DraftGenerator();
+  const traceEmitter = dependencies.traceEmitter || new TraceEmitter();
+
+  if (options.nonInteractive && specTargets.length === 0) {
+    throw new Error('--name is required in non-interactive mode');
+  }
+
+  const context = await contextCollector.collect();
+  const answers = await questionnaireEngine.collect({
+    nonInteractive: options.nonInteractive,
+    specName: specTargets[0] || options.name,
+    profile: options.profile,
+    template: options.template
+  });
+
+  const specName = (specTargets[0] || options.name || answers.specName || '').trim();
+  if (!specName) {
+    throw new Error('Spec name is required');
+  }
+
+  const draft = draftGenerator.generate({
+    specName,
+    profile: options.profile || 'general',
+    template: options.template || 'default',
+    context,
+    answers
+  });
+
+  const specPath = path.join(projectPath, '.kiro', 'specs', specName);
+  const files = {
+    requirements: path.join(specPath, 'requirements.md'),
+    design: path.join(specPath, 'design.md'),
+    tasks: path.join(specPath, 'tasks.md')
+  };
+
+  if (!options.dryRun) {
+    await fs.ensureDir(specPath);
+    await fs.writeFile(files.requirements, draft.requirements, 'utf8');
+    await fs.writeFile(files.design, draft.design, 'utf8');
+    await fs.writeFile(files.tasks, draft.tasks, 'utf8');
+  }
+
+  const result = {
+    success: true,
+    specName,
+    specPath: path.relative(projectPath, specPath),
+    dryRun: !!options.dryRun,
+    files: {
+      requirements: path.relative(projectPath, files.requirements),
+      design: path.relative(projectPath, files.design),
+      tasks: path.relative(projectPath, files.tasks)
+    },
+    trace: {
+      template: options.template || 'default',
+      profile: options.profile || 'general',
+      parameters: {
+        nonInteractive: !!options.nonInteractive,
+        dryRun: !!options.dryRun,
+        json: !!options.json
+      },
+      context: {
+        totalSpecs: context.totalSpecs,
+        preferredLanguage: context.preferredLanguage
+      },
+      mapping: draft.metadata.mapping
+    },
+    preview: {
+      requirements: draft.requirements,
+      design: draft.design,
+      tasks: draft.tasks
+    }
+  };
+
+  traceEmitter.emit(result, { json: options.json });
+  return result;
+}
+
+function registerSpecBootstrapCommand(program) {
+  program
+    .command('spec-bootstrap')
+    .description('Bootstrap requirements/design/tasks draft (use: kse spec bootstrap)')
+    .option('--name <spec-name>', 'Spec name to generate')
+    .option('--spec <name>', 'Alias of --name')
+    .option('--specs <names>', 'Comma-separated Spec identifiers (multi-spec defaults to orchestrate mode)')
+    .option('--template <template-id>', 'Template hint for draft generation')
+    .option('--profile <profile-id>', 'Profile for default generation strategy')
+    .option('--non-interactive', 'Disable prompts and use arguments/defaults only')
+    .option('--dry-run', 'Preview generation result without writing files')
+    .option('--json', 'Output machine-readable JSON')
+    .option('--max-parallel <n>', 'Maximum parallel agents when orchestrate mode is used', parseInt)
+    .action(async (options) => {
+      try {
+        await runSpecBootstrap(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ Spec bootstrap failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  registerSpecBootstrapCommand,
+  runSpecBootstrap
+};