spec-agent 2.0.2 → 2.0.3

package/.cursor/rules/spec-agent-assistant.mdc

@@ -0,0 +1,34 @@
+---
+description: spec-agent onboarding and execution guidance
+alwaysApply: true
+---
+
+# Spec-Agent Assistant Rule
+
+When user intent is about running `spec-agent`, apply this workflow:
+
+1. Verify installation first:
+   - Prefer running `spec-agent --version`.
+   - If command is missing, provide manual install command for public npm:
+     - `npm install -g spec-agent --registry=https://registry.npmjs.org/`
+   - Then ask user to re-run version check.
+
+2. Guide minimum happy path:
+   - `spec-agent pipeline --input ./docs --output ./output`
+   - `spec-agent status --workspace ./output`
+   - `spec-agent round --workspace ./output --input ./docs --target cursor --max-parallel 4`
+
+3. If user wants multi-agent execution loop:
+   - Run handoff:
+     - `spec-agent handoff --workspace ./output --target cursor --include-summaries`
+   - Run execution:
+     - `spec-agent execute --workspace ./output --max-parallel 4`
+   - Prefer one-round command:
+     - `spec-agent round --workspace ./output --input ./docs --target cursor --max-parallel 4`
+   - Use `--complete` / `--fail` feedback loop.
+
+4. Keep responses action-oriented:
+   - Provide exact commands.
+   - Explain expected output paths (`output/handoff`, `output/execution`).
+   - Avoid claiming completion without command evidence.
+   - Prefer invoking `spec-agent-product-dev-agent` when user asks requirement-to-development end-to-end.

package/.cursor/skills/spec-agent-execution-orchestrator/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: spec-agent-execution-orchestrator
+description: Orchestrates spec-agent handoff and execute loops for Cursor-based multi-agent delivery. Use when the user asks to run one execution round, continue task scheduling, update run_state, or reduce manual steps in spec-agent workflow.
+---
+# Spec-Agent Execution Orchestrator
+
+## Purpose
+
+Run the spec-agent execution loop with minimal manual steps:
+
+1. Generate or refresh handoff bundle
+2. Schedule executable tasks
+3. Present current inbox tasks
+4. Apply completion/failure feedback
+5. Continue next round
+
+## When To Use
+
+Use this skill when user asks:
+
+- "执行一轮"
+- "继续调度"
+- "回填任务结果"
+- "减少手动步骤"
+- "让 Cursor 按产物自动跑"
+
+## Workflow
+
+Copy this checklist and keep it updated:
+
+```text
+Execution Round Checklist
+- [ ] Step 1: Ensure handoff bundle exists
+- [ ] Step 2: Run orchestrate decision
+- [ ] Step 3: Run execute scheduling
+- [ ] Step 4: Read inbox and summarize tasks
+- [ ] Step 5: Ask/collect task outcomes
+- [ ] Step 6: Apply complete/fail updates
+- [ ] Step 7: Re-run orchestrate + execute for next batch
+```
+
+### Step 1: Ensure handoff bundle
+
+Default workspace is `./output`.
+
+Run:
+
+```bash
+spec-agent handoff --workspace ./output --target cursor --include-summaries
+```
+
+Skip this if `output/handoff/handoff_bundle.json` already exists and user did not request refresh.
+
+### Step 2: Schedule tasks
+
+Run:
+
+```bash
+spec-agent round --workspace ./output --input ./docs --target cursor --max-parallel 4
+```
+
+If user asks reset:
+
+```bash
+spec-agent execute --workspace ./output --reset --max-parallel 4
+```
+
+### Step 3: Read current inbox
+
+Inspect:
+
+- `output/execution/inbox/*.md`
+- `output/execution/execution_report.json`
+
+Return a concise batch summary:
+
+- scheduled task IDs
+- pending/running/succeeded/failed/blocked counts
+- which task to execute first
+
+### Step 4: Collect outcomes
+
+Ask user for result IDs, or parse explicit feedback from chat.
+
+### Step 5: Apply feedback
+
+Complete tasks:
+
+```bash
+spec-agent execute --workspace ./output --complete T001,T002
+```
+
+Fail tasks:
+
+```bash
+spec-agent execute --workspace ./output --fail T003 --error "compile failed"
+```
+
+### Step 6: Continue next batch
+
+Run scheduling again:
+
+```bash
+spec-agent round --workspace ./output --input ./docs --target cursor --max-parallel 4
+```
+
+## Response Format
+
+Use this output template:
+
+```markdown
+本轮执行结果：
+- 调度任务：<ids>
+- 当前状态：pending <n> / running <n> / succeeded <n> / failed <n> / blocked <n>
+- 建议下一步：<one action>
+
+如需回填，请回复：
+- 完成：Txxx,Tyyy
+- 失败：Tzzz，原因：...
+```
+
+## Guardrails
+
+- Do not claim tasks are complete unless `--complete` was applied.
+- Do not edit `run_state.json` manually; only use `spec-agent execute` flags.
+- If inbox is empty but pending remains, check blocked dependencies and report them.
+- Prefer small rounds (2-6 tasks) to reduce rollback cost.
+- Use `orchestrator_context.json` as decision reference when available.
+
+## Additional Reference
+
+- For command quick reference, see [reference.md](reference.md)
+- For copy-ready agent system prompts, see [agent-prompts.md](agent-prompts.md)

package/.cursor/skills/spec-agent-execution-orchestrator/agent-prompts.md

@@ -0,0 +1,113 @@
+# Agent Prompt Templates
+
+## 1) Orchestrator Agent（调度者）
+
+用于专门驱动 `handoff + execute + 回填 + 下一轮` 的 Agent。
+
+```text
+你是 Spec-Agent 执行编排助手，只负责调度与状态推进，不直接实现业务代码。
+
+你的目标：
+1) 确保 handoff 包存在且最新
+2) 运行 execute 调度一轮
+3) 汇总 inbox 任务与 execution_report
+4) 根据用户反馈回填 complete/fail
+5) 继续推进下一轮
+
+严格规则：
+- 不要手动编辑 run_state.json，必须通过 spec-agent execute --complete/--fail 更新状态
+- 不要宣称任务完成，除非已执行回填命令
+- 当 pending>0 且 inbox 为空时，检查 blocked 任务并明确原因
+- 每轮输出统一格式：
+  - 调度任务ID
+  - 状态统计（pending/running/succeeded/failed/blocked）
+  - 下一步建议（只给一个最小动作）
+
+默认命令：
+- spec-agent round --workspace ./output --input ./docs --target cursor --max-parallel 4
+- spec-agent handoff --workspace ./output --target cursor --include-summaries
+- spec-agent execute --workspace ./output --max-parallel 4
+- spec-agent execute --workspace ./output --complete T001,T002
+- spec-agent execute --workspace ./output --fail T003 --error "compile failed"
+```
+
+## 2) Worker Agent（执行者）
+
+用于执行单个 `inbox/Txxx.md` 任务的 Agent。
+
+```text
+你是任务执行 Agent，请严格按提供的 Task Handoff 文档实现。
+
+输入：
+- 当前任务文档：output/execution/inbox/Txxx.md
+- 参考资料：spec_summary.json, task_plan.json, dispatch_plan.json, summaries/
+
+执行规则：
+- 仅实现当前任务及其已满足依赖，不扩大范围
+- 信息不足先列缺失项，不臆造接口/字段
+- 输出必须包含：
+  1) 修改文件列表
+  2) 关键实现说明（why/what）
+  3) 可复现实测命令
+  4) 结果结论：SUCCESS 或 FAILED（含失败原因）
+
+完成后不要自行修改 run_state.json，由调度 Agent 回填状态。
+```
+
+## 3) 快捷触发语句
+
+### 给 Orchestrator
+
+```text
+按 spec-agent 执行一轮，workspace=./output，max-parallel=4。
+```
+
+### 给 Worker
+
+```text
+执行任务 output/execution/inbox/T001.md，按模板输出结果。
+```
+
+## 4) 多会话并行执行清单（4 Worker）
+
+每轮先让 Orchestrator 调度：
+
+```bash
+spec-agent execute --workspace ./output --max-parallel 4
+```
+
+然后把 `output/execution/inbox/` 前 4 个任务分给 4 个 Worker 会话。
+
+### 分配模板
+
+```text
+Worker-A: Txxx
+Worker-B: Tyyy
+Worker-C: Tzzz
+Worker-D: Twww
+```
+
+### 并行执行步骤
+
+1. 每个 Worker 只执行自己那一个 `inbox/Txxx.md`
+2. 每个 Worker 返回统一结论：
+   - SUCCESS: `TASK_ID`
+   - FAILED: `TASK_ID` | reason: `ERROR_TEXT`
+3. Orchestrator 汇总后一次回填：
+
+```bash
+spec-agent execute --workspace ./output --complete Txxx,Tyyy
+spec-agent execute --workspace ./output --fail Tzzz --error "compile failed"
+```
+
+1. 回填后继续下一轮调度。
+
+### 结果汇总模板（给 Orchestrator）
+
+```text
+本轮汇总：
+- SUCCESS: Txxx,Tyyy
+- FAILED: Tzzz (reason: compile failed)
+- RUNNING/WAIT: Twww
+下一步：回填并继续调度下一轮
+```

package/.cursor/skills/spec-agent-execution-orchestrator/reference.md

@@ -0,0 +1,37 @@
+# Command Reference
+
+## Initialize / refresh handoff
+
+```bash
+spec-agent handoff --workspace ./output --target cursor --include-summaries
+```
+
+## Schedule next execution batch
+
+```bash
+spec-agent round --workspace ./output --input ./docs --target cursor --max-parallel 4
+```
+
+## Reset run state
+
+```bash
+spec-agent execute --workspace ./output --reset --max-parallel 4
+```
+
+## Mark tasks completed
+
+```bash
+spec-agent round --workspace ./output --input ./docs --complete T001,T002
+```
+
+## Mark tasks failed
+
+```bash
+spec-agent round --workspace ./output --input ./docs --fail T003 --error "compile failed"
+```
+
+## Read progress
+
+- `output/execution/run_state.json`
+- `output/execution/execution_report.json`
+- `output/execution/inbox/*.md`

package/.cursor/skills/spec-agent-onboarding-agent/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: spec-agent-onboarding-agent
+description: Checks whether spec-agent is installed, provides install/fix commands, and guides users through pipeline and execution setup. Use when users ask how to start, run, install, or troubleshoot spec-agent usage.
+---
+# Spec-Agent Onboarding Agent
+
+## Goal
+
+Turn spec-agent into a callable assistant workflow with minimal user friction:
+
+1. Check tool availability
+2. Provide install/fix commands if missing
+3. Guide first successful pipeline run
+4. Optionally bootstrap handoff + execute loop
+
+## Step 1: Installation Check
+
+Run:
+
+```bash
+spec-agent --version
+```
+
+If missing command:
+
+```bash
+npm install -g spec-agent --registry=https://registry.npmjs.org/
+```
+
+Then verify again:
+
+```bash
+spec-agent --version
+```
+
+## Step 2: Minimum Run Path
+
+```bash
+spec-agent pipeline --input ./docs --output ./output
+spec-agent status --workspace ./output
+spec-agent round --workspace ./output --input ./docs --target cursor --max-parallel 4
+```
+
+## Step 3: Multi-Agent Execution Bootstrap (Optional)
+
+```bash
+spec-agent handoff --workspace ./output --target cursor --include-summaries
+spec-agent execute --workspace ./output --max-parallel 4
+spec-agent round --workspace ./output --input ./docs --target cursor --max-parallel 4
+```
+
+If user provides result feedback:
+
+```bash
+spec-agent execute --workspace ./output --complete T001,T002
+spec-agent execute --workspace ./output --fail T003 --error "compile failed"
+```
+
+## Response Template
+
+```markdown
+当前状态：
+- spec-agent 安装：<installed|missing>
+- 建议执行：<next command>
+
+执行后你会看到：
+- `output/...` 关键产物路径
+
+如果报错，请贴终端输出，我会给你下一条命令。
+```
+
+## Notes
+
+- Prefer public npm registry explicitly in install commands.
+- If user is on private registry, provide one-time `--registry` command variant.
+- Do not skip verification commands.
+- Use `spec-agent round` as the primary one-round action.

package/.cursor/skills/spec-agent-product-dev-agent/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: spec-agent-product-dev-agent
+description: Drives end-to-end requirement-to-development workflow with spec-agent. Use when user provides requirement content and asks to analyze requirements, generate artifacts, and develop by execution tasks.
+---
+# Spec-Agent Product Dev Agent
+
+## Goal
+
+Turn requirement input into executable development workflow:
+
+1. Ensure `spec-agent` is available
+2. Build/refresh artifacts (`pipeline`)
+3. Generate handoff and execution context
+4. Execute one round and guide task implementation
+
+## Trigger Scenarios
+
+Use this skill when user says:
+
+- “分析需求并开发”
+- “根据文档直接开始做代码”
+- “跑完整流程并推进任务”
+
+## Workflow
+
+### Step 1: Ensure installation
+
+```bash
+spec-agent --version
+```
+
+If missing:
+
+```bash
+npm install -g spec-agent --registry=https://registry.npmjs.org/
+spec-agent --version
+```
+
+### Step 2: Prepare requirement input
+
+If requirement is in chat text, create/update `docs/requirement.md` first.
+
+If requirement already in files, verify `./docs` exists.
+
+### Step 3: Produce artifacts
+
+```bash
+spec-agent pipeline --input ./docs --output ./output
+```
+
+### Step 4: Build execution loop
+
+```bash
+spec-agent handoff --workspace ./output --target cursor --include-summaries
+spec-agent round --workspace ./output --input ./docs --target cursor --max-parallel 4
+```
+
+### Step 5: Development guidance
+
+Read:
+
+- `output/execution/inbox/*.md`
+- `output/orchestrator_context.json`
+
+Then guide user to execute current inbox tasks in coding sessions.
+
+### Step 6: Feedback loop
+
+When user provides outcomes, apply one command:
+
+```bash
+spec-agent round --workspace ./output --input ./docs --complete T001,T002 --fail T003 --error "compile failed"
+```
+
+## Response Template
+
+```markdown
+当前进度：
+- 状态：<state>
+- 本轮任务：<task ids>
+- 下一步：<single command>
+
+请回填：
+- 完成：Txxx,Tyyy
+- 失败：Tzzz，原因：...
+```
+
+## Guardrails
+
+- Do not skip pipeline if dispatch artifacts are missing.
+- Do not manually edit `run_state.json`; only update via CLI.
+- Always use `orchestrator_context.json` as current truth.

package/CURSOR_AGENT_PACK.md

@@ -0,0 +1,66 @@
+# Spec-Agent Cursor Agent Pack
+
+这是一套可分发给其他人的 `.cursor` 智能体配置，目标是让对方拿到后可以在对话框中：
+
+1. 检查并安装 `spec-agent`
+2. 分析需求并产出标准产物
+3. 基于产物进入执行闭环并推进开发
+
+## Pack Contents
+
+- `.cursor/rules/spec-agent-assistant.mdc`
+- `.cursor/skills/spec-agent-onboarding-agent/SKILL.md`
+- `.cursor/skills/spec-agent-execution-orchestrator/SKILL.md`
+- `.cursor/skills/spec-agent-execution-orchestrator/reference.md`
+- `.cursor/skills/spec-agent-execution-orchestrator/agent-prompts.md`
+- `.cursor/skills/spec-agent-product-dev-agent/SKILL.md`
+
+## How Others Use
+
+### 1) 获取仓库并安装 CLI
+
+```bash
+npm install -g spec-agent --registry=https://registry.npmjs.org/
+spec-agent --version
+```
+
+### 2) 在项目中准备需求
+
+- 将需求文档放入 `./docs`
+- 或让 Agent 将对话需求保存到 `docs/requirement.md`
+
+### 3) 对话触发（推荐语句）
+
+```text
+请按 spec-agent-product-dev-agent 流程，从需求分析开始，产出并推进一轮开发。
+```
+
+或：
+
+```text
+按 spec-agent 执行一轮，workspace=./output，input=./docs。
+```
+
+### 4) 回填执行结果
+
+```bash
+spec-agent round --workspace ./output --input ./docs --complete T001,T002 --fail T003 --error "compile failed"
+```
+
+## Standard Artifact Paths
+
+- `output/manifest.json`
+- `output/spec_summary.json`
+- `output/task_plan.json`
+- `output/dispatch_plan.json`
+- `output/handoff/handoff_bundle.json`
+- `output/execution/run_state.json`
+- `output/execution/execution_report.json`
+- `output/orchestrator_context.json`
+
+## Delivery Checklist
+
+- [ ] `spec-agent --version` 可用
+- [ ] `spec-agent pipeline --input ./docs --output ./output` 可跑通
+- [ ] `spec-agent round --workspace ./output --input ./docs` 可输出下一步
+- [ ] `.cursor` 目录已包含 rule + skills

package/README.md

@@ -162,6 +162,33 @@ Options:
   --dry-run              仅预览状态迁移，不写文件
 ```
 
+#### orchestrate - 产物驱动决策（v2 beta）
+```bash
+spec-agent orchestrate --workspace <dir> [options]
+
+Options:
+  --input <path>         pipeline 输入目录（用于下一步建议）(默认: ./docs)
+  --target <name>        执行目标: cursor, qcoder, codebuddy, generic
+  --max-parallel <count> execute 推荐并行度 (默认: 4)
+  --format <format>      输出格式: text, json (默认: text)
+  --dry-run              仅预览决策，不写 orchestrator_context.json
+```
+
+#### round - 单轮自动推进（v2 beta）
+```bash
+spec-agent round --workspace <dir> [options]
+
+Options:
+  --input <path>         pipeline 输入目录（默认: ./docs）
+  --target <name>        执行目标: cursor, qcoder, codebuddy, generic
+  --max-parallel <count> execute 并行度 (默认: 4)
+  --retry <count>        单任务失败重试次数 (默认: 1)
+  --complete <ids>       回填成功任务，如: T001,T002
+  --fail <ids>           回填失败任务，如: T003
+  --error <message>      配合 --fail 写入失败原因
+  --dry-run              仅预览，不执行实际命令
+```
+
 ### 退出码约定（用于脚本/CI）
 
 - `scan`:
@@ -294,3 +321,9 @@ npm run build
 # 开发模式
 npm run dev
 ```
+
+## Cursor 智能体分发
+
+如果你要把本工具作为“可直接调用的 Cursor 智能体”交付给其他人，请看：
+
+- `CURSOR_AGENT_PACK.md`

package/USAGE_FROM_NPM.md

@@ -166,6 +166,15 @@ spec-agent execute --workspace ./output --complete T001,T002
 
 # 回填失败并触发重试/最终失败
 spec-agent execute --workspace ./output --fail T003 --error "compile failed"
+
+# 生成下一步决策与上下文（orchestrator）
+spec-agent orchestrate --workspace ./output --input ./docs
+
+# 一轮自动推进（会自动选择 pipeline / handoff / execute）
+spec-agent round --workspace ./output --input ./docs --target cursor --max-parallel 4
+
+# 一条命令完成“回填 + 下一轮推进”
+spec-agent round --workspace ./output --input ./docs --complete T001,T002 --fail T003 --error "compile failed"
 ```
 
 ---

package/dist/commands/orchestrate.d.ts

@@ -0,0 +1,46 @@
+import { Command } from 'commander';
+interface OrchestrateOptions {
+    workspace: string;
+    input?: string;
+    target: string;
+    maxParallel: string;
+    format: string;
+    dryRun?: boolean;
+}
+type OrchestratorState = 'INIT' | 'READY' | 'PIPELINE_RUNNING' | 'PIPELINE_READY' | 'EXECUTION_RUNNING' | 'WAITING_FEEDBACK' | 'PARTIAL_FAILED' | 'DONE';
+interface ExecutionSummary {
+    pending: number;
+    running: number;
+    succeeded: number;
+    failed: number;
+    blocked: number;
+}
+interface OrchestratorContext {
+    version: string;
+    updatedAt: string;
+    workspace: string;
+    state: OrchestratorState;
+    checks: {
+        manifest: boolean;
+        specSummary: boolean;
+        taskPlan: boolean;
+        dispatchPlan: boolean;
+        handoffBundle: boolean;
+        runState: boolean;
+        executionReport: boolean;
+    };
+    metrics: ExecutionSummary;
+    lastAction: string | null;
+    lastError: string | null;
+    nextAction: string;
+    recommendedCommands: string[];
+}
+export declare function orchestrateCommand(options: OrchestrateOptions, command: Command): Promise<void>;
+export declare function buildOrchestratorContext(input: {
+    workspaceArg: string;
+    inputArg: string;
+    target: string;
+    maxParallel: number;
+}): Promise<OrchestratorContext>;
+export {};
+//# sourceMappingURL=orchestrate.d.ts.map

package/dist/commands/orchestrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrate.d.ts","sourceRoot":"","sources":["../../src/commands/orchestrate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,UAAU,kBAAkB;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,KAAK,iBAAiB,GAClB,MAAM,GACN,OAAO,GACP,kBAAkB,GAClB,gBAAgB,GAChB,mBAAmB,GACnB,kBAAkB,GAClB,gBAAgB,GAChB,MAAM,CAAC;AAEX,UAAU,gBAAgB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,mBAAmB;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,EAAE;QACN,QAAQ,EAAE,OAAO,CAAC;QAClB,WAAW,EAAE,OAAO,CAAC;QACrB,QAAQ,EAAE,OAAO,CAAC;QAClB,YAAY,EAAE,OAAO,CAAC;QACtB,aAAa,EAAE,OAAO,CAAC;QACvB,QAAQ,EAAE,OAAO,CAAC;QAClB,eAAe,EAAE,OAAO,CAAC;KAC1B,CAAC;IACF,OAAO,EAAE,gBAAgB,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B;AAWD,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAyCrG;AAED,wBAAsB,wBAAwB,CAAC,KAAK,EAAE;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAiF/B"}