spec-manager 0.1.0 → 0.2.0

package/dist/schemas/change.d.ts

@@ -23,23 +23,23 @@ export declare const ChangeEntrySchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     code: string;
     op: "ADDED" | "MODIFIED" | "REMOVED" | "RENAMED";
-    content?: string | undefined;
+    parentCode?: string | null | undefined;
     level?: "L0" | "L1" | "L2" | "L3" | undefined;
     title?: string | undefined;
-    parentCode?: string | null | undefined;
+    content?: string | undefined;
+    newCode?: string | undefined;
     changeSummary?: string | undefined;
     affectedCriteria?: string[] | undefined;
-    newCode?: string | undefined;
 }, {
     code: string;
     op: "ADDED" | "MODIFIED" | "REMOVED" | "RENAMED";
-    content?: string | undefined;
+    parentCode?: string | null | undefined;
     level?: "L0" | "L1" | "L2" | "L3" | undefined;
     title?: string | undefined;
-    parentCode?: string | null | undefined;
+    content?: string | undefined;
+    newCode?: string | undefined;
     changeSummary?: string | undefined;
     affectedCriteria?: string[] | undefined;
-    newCode?: string | undefined;
 }>;
 export declare const DeltaSpecSchema: z.ZodObject<{
     name: z.ZodString;
@@ -58,35 +58,35 @@ export declare const DeltaSpecSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         code: string;
         op: "ADDED" | "MODIFIED" | "REMOVED" | "RENAMED";
-        content?: string | undefined;
+        parentCode?: string | null | undefined;
         level?: "L0" | "L1" | "L2" | "L3" | undefined;
         title?: string | undefined;
-        parentCode?: string | null | undefined;
+        content?: string | undefined;
+        newCode?: string | undefined;
         changeSummary?: string | undefined;
         affectedCriteria?: string[] | undefined;
-        newCode?: string | undefined;
     }, {
         code: string;
         op: "ADDED" | "MODIFIED" | "REMOVED" | "RENAMED";
-        content?: string | undefined;
+        parentCode?: string | null | undefined;
         level?: "L0" | "L1" | "L2" | "L3" | undefined;
         title?: string | undefined;
-        parentCode?: string | null | undefined;
+        content?: string | undefined;
+        newCode?: string | undefined;
         changeSummary?: string | undefined;
         affectedCriteria?: string[] | undefined;
-        newCode?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     changes: {
         code: string;
         op: "ADDED" | "MODIFIED" | "REMOVED" | "RENAMED";
-        content?: string | undefined;
+        parentCode?: string | null | undefined;
         level?: "L0" | "L1" | "L2" | "L3" | undefined;
         title?: string | undefined;
-        parentCode?: string | null | undefined;
+        content?: string | undefined;
+        newCode?: string | undefined;
         changeSummary?: string | undefined;
         affectedCriteria?: string[] | undefined;
-        newCode?: string | undefined;
     }[];
     name: string;
     created?: string | undefined;
@@ -95,13 +95,13 @@ export declare const DeltaSpecSchema: z.ZodObject<{
     changes: {
         code: string;
         op: "ADDED" | "MODIFIED" | "REMOVED" | "RENAMED";
-        content?: string | undefined;
+        parentCode?: string | null | undefined;
         level?: "L0" | "L1" | "L2" | "L3" | undefined;
         title?: string | undefined;
-        parentCode?: string | null | undefined;
+        content?: string | undefined;
+        newCode?: string | undefined;
         changeSummary?: string | undefined;
         affectedCriteria?: string[] | undefined;
-        newCode?: string | undefined;
     }[];
     name: string;
     created?: string | undefined;
@@ -119,16 +119,16 @@ export declare const ProposalSchema: z.ZodObject<{
     name: string;
     why: string;
     scope: string;
-    created?: string | undefined;
     affectedCriteria?: string[] | undefined;
+    created?: string | undefined;
     risk?: string | undefined;
     rollback?: string | undefined;
 }, {
     name: string;
     why: string;
     scope: string;
-    created?: string | undefined;
     affectedCriteria?: string[] | undefined;
+    created?: string | undefined;
     risk?: string | undefined;
     rollback?: string | undefined;
 }>;

package/dist/schemas/spec.d.ts

@@ -108,12 +108,12 @@ export declare const SpecFrontmatterSchema: z.ZodObject<{
     changeSummary: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     project: number;
-    status: "draft" | "confirmed" | "frozen" | "implemented" | "archived";
-    topic: string;
     code: string;
+    status: "draft" | "confirmed" | "frozen" | "implemented" | "archived";
+    parentCode: string | null;
     level: "L0" | "L1" | "L2" | "L3";
     title: string;
-    parentCode: string | null;
+    topic: string;
     aiSummary: string;
     coveredTasks: string[];
     relations: {
@@ -133,18 +133,18 @@ export declare const SpecFrontmatterSchema: z.ZodObject<{
         latencyMs?: number | undefined;
         reportedAt?: string | undefined;
     }[] | undefined;
+    changeSummary?: string | undefined;
+    created?: string | undefined;
     id?: string | undefined;
     milestone?: string | undefined;
-    created?: string | undefined;
     updated?: string | undefined;
-    changeSummary?: string | undefined;
 }, {
-    status: "draft" | "confirmed" | "frozen" | "implemented" | "archived";
-    topic: string;
     code: string;
+    status: "draft" | "confirmed" | "frozen" | "implemented" | "archived";
+    parentCode: string | null;
     level: "L0" | "L1" | "L2" | "L3";
     title: string;
-    parentCode: string | null;
+    topic: string;
     project?: number | undefined;
     steps?: {
         stepNo: string | number;
@@ -159,6 +159,8 @@ export declare const SpecFrontmatterSchema: z.ZodObject<{
         latencyMs?: number | undefined;
         reportedAt?: string | undefined;
     }[] | undefined;
+    changeSummary?: string | undefined;
+    created?: string | undefined;
     id?: string | undefined;
     milestone?: string | undefined;
     aiSummary?: string | undefined;
@@ -167,9 +169,7 @@ export declare const SpecFrontmatterSchema: z.ZodObject<{
         type: "based_on" | "supersedes" | "implements" | "references";
         target: string;
     }[] | undefined;
-    created?: string | undefined;
     updated?: string | undefined;
-    changeSummary?: string | undefined;
 }>;
 export declare const PlanStepSchema: z.ZodObject<{
     stepNo: z.ZodUnion<[z.ZodNumber, z.ZodString]>;
@@ -222,12 +222,12 @@ export declare const DecisionInputSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     topic: string;
     what: string;
-    why?: string | undefined;
     affectedCriteria?: string[] | undefined;
+    why?: string | undefined;
 }, {
     topic: string;
     what: string;
-    why?: string | undefined;
     affectedCriteria?: string[] | undefined;
+    why?: string | undefined;
 }>;
 //# sourceMappingURL=spec.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-manager",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "spec-manager: local-first spec-driven development platform. Pure markdown storage, no network, no MCP. Portable CLI + multi-agent instructions.",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,7 @@
     "delta-spec"
   ],
   "dependencies": {
+    "@inquirer/prompts": "^7.10.1",
     "commander": "^12.0.0",
     "gray-matter": "^4.0.3",
     "yaml": "^2.4.0",

package/rules/flow-control.md

@@ -14,7 +14,7 @@ applies_to: [L1_create, L2_create, L3_create]
 
 每次 `spec-manager spec update <code> --content` 写入后，**必须停下**，告知用户文件路径，等用户明确说"批准"/"已确认"/"继续"/"通过"等。
 
-**严禁一口气做**：`new L1 → update --content → confirm → new L2 → update → confirm → new L3 → freeze → task create → start`。
+**严禁一口气做**：`new L1 → update --content → confirm → new L2 → update → confirm → new L3 → confirm → task create → start`。
 
 ## R2 — 状态推进是用户行为,不是 AI 行为
 
@@ -25,7 +25,7 @@ added: 0.1.0
 applies_to: [L1_confirm, L2_confirm, L3_confirm, L3_freeze, user_approve]
 ---
 
-`draft → confirmed` 和 `confirmed → frozen` 都是用户审核意见的体现。AI agent **不能**在未获用户明确批准前主动调用 `spec-manager spec confirm` / `freeze`。
+L1/L2 的 `draft → confirmed`、L3 的 `draft → frozen`，以及历史 L3 的 `confirmed → frozen` 都是用户审核意见的体现。L3 一次明确批准后直接进入 frozen，不再要求对同一正文重复批准。AI agent **不能**在未获用户明确批准前主动调用 `spec-manager spec confirm` / `freeze`。
 
 **唯一例外**：`frozen → implemented` 由 `spec-manager task complete` 自动触发，允许 AI agent 执行。
 
@@ -60,6 +60,6 @@ applies_to: [L1_confirm, L2_confirm, L3_confirm]
 
 > 人工审计:本规则依赖人工判断,无法通过系统强制执行,实际执行由人工审核保障。
 
-L1 PRD 审核、L2 Design 审核、L3 Impl 审核是**三个独立的停止点**。不能因为 L1 批准了就连带假设 L2 也批准。
+L1 PRD 审核、L2 Design 审核、L3 Impl 审核是**三个独立的停止点**。不能因为 L1 批准了就连带假设 L2 也批准；L3 自身只需一次明确批准，批准后直接 frozen。
 
 **人工审计说明**：本规则依赖人工判断，无法通过系统强制执行。hooks 作为辅助提醒，实际执行由人工审核保障。

package/skill/SKILL.md

@@ -41,6 +41,17 @@ PRD → Design → Spec → Agent Task → 部署。**纯本地**，所有数据
 | L2 Design | 技术设计 | confirmed 才能进实施 |
 | L3 Impl | 实施规格 | ≤20 步，frozen 后建 Task |
 
+## Unified Rules
+
+- Feature work MUST go through `spec-manager`.
+- New or non-trivial work follows L1 -> L2 -> L3 -> Agent Task.
+- Never write implementation code without a frozen L3 spec.
+- L1/L2 approval advances `draft -> confirmed`; one explicit L3 approval (an explicit user approval) advances `draft -> frozen`.
+- Before code edits, read the frozen L3 spec and create/start an Agent Task.
+- planJson `coveredSpecs` MUST include the current L3 specCode.
+- Validate L3 markdown plans with `spec-manager spec validate-plan --from-spec <L3-code>`.
+- Record execution with `spec-manager task step`; finish with `spec-manager task complete`.
+
 ## 规则（24 条，按 applies_to 过滤）
 
 | 主题 | 规则 | 文件 |
@@ -55,8 +66,9 @@ PRD → Design → Spec → Agent Task → 部署。**纯本地**，所有数据
 ## Spec 状态流
 
 ```
-draft → confirmed → frozen → implemented
- AI agent 用户      用户     task_complete
+L1/L2: draft → confirmed
+L3:    draft → frozen → implemented
+        AI agent  用户      task_complete
 ```
 
 ## CLI 概要

package/skill/subskills/impl.md

@@ -40,9 +40,9 @@
    > ☑ **R13** / **R21** — `--ai-summary` ≤300 字符（CLI 截断,>300 自动 warn）
    > ☑ **R14** / **R22** — 流程规则,人工把关
 6. 🛑 **等用户审核**（R1）— 流程规则,停下等用户信号
-7. 用户批准 → `spec-manager spec confirm <code>` → 用户再批准 → `spec-manager spec freeze <code>`
+7. 用户一次批准 → `spec-manager spec confirm <code>`，L3 直接进入 `frozen`
    > ☑ **R2** / **R4** — 流程规则:状态由用户推进,每层独立审核
-   > CLI 在 `confirm`/`freeze` 之前会校验 R22（contentTemplate 非空）
+   > CLI 在批准进入 `frozen` 之前会校验 R22（contentTemplate 非空）
 
 ### Agent Task 执行
 

package/templates/L3-impl.md

@@ -13,7 +13,7 @@ Expert guidelines:
   - 每步实施必须精确到函数/方法级别,禁止"修改相关代码"等模糊表述
   - planJson 字段名必须从 templates/agent-plan.json 读取,禁止凭记忆(R12/INC-005)
   - step_report 每步必须携带 outputJson(R15),格式见下方模板
-  - coveredSpecs: 若本 Task 实际覆盖多条 L3,必须在 planJson 中声明
+  - coveredSpecs: 必须包含当前 L3 specCode；若本 Task 实际覆盖多条 L3,列出所有 specCode
   - 验证命令必须可直接粘贴执行,含预期输出的精确匹配串
   - 回滚方案不是可选项,每个 L3 必须说明"改坏了怎么恢复"
   - 写 L3 前必须执行 Level 3 文件级分析(R23,见 rules/codebase-survey.md)
@@ -95,7 +95,7 @@ Expert guidelines:
 
 ```json
 {
-  "coveredSpecs": ["<若覆盖多条 L3,列出所有 specCode;单条则省略此字段>"],
+  "coveredSpecs": ["<本 L3 specCode>"],
   "steps": [
     {"stepNo": 1, "stepType": "mcp_tool", "name": "上下文收集: spec-manager spec show(L3 + 父 L2)"},
     {"stepNo": 2, "stepType": "mcp_tool", "name": "<动词+宾语+文件>"},

package/templates/agent-plan.json

@@ -3,11 +3,12 @@
   "_constraints": [
     "step 1 必须是上下文收集(读 L3 spec + 父 L2 + 历史任务)",
     "末步必须是可执行的验证命令(R10)",
+    "coveredSpecs 必须包含当前 L3 specCode；若覆盖多条 L3,列出所有 specCode",
     "单 Agent Task = 单 L3 spec,步数 ≤ 20(R11);超 16 步必拆 L3",
     "每步 name 必须含 verb+object+file,禁止'优化/改进/处理'等模糊动词",
     "stepType 仅限 llm_call / mcp_tool / human_gate"
   ],
-  "coveredSpecs": ["2026-06-04-c3d4e5"],
+  "coveredSpecs": ["<current-L3-specCode>"],
   "steps": [
     {"stepNo": 1, "stepType": "mcp_tool", "name": "上下文收集: spec-manager spec show L3 + 父 L2 + 读 templates/agent-plan.json"},
     {"stepNo": 2, "stepType": "mcp_tool", "name": "编辑 <ServiceName>.java 新增方法 <verb>"},

package/templates/agents/AGENTS.md

@@ -4,14 +4,16 @@ This file is the spec-manager skill-like entrypoint for Codex, OpenCode, and oth
 
 This project uses `spec-manager` for local-first spec-driven development. Specs, tasks, decisions, changes, and audit data are stored as markdown/JSON files in the repository.
 
-## Mandatory Workflow
+## Unified Rules
 
-- Feature work MUST go through `spec-manager`; do not jump directly from a user request to implementation code.
-- New or non-trivial work follows L1 PRD -> L2 Design -> L3 Impl -> Agent Task.
-- Never write implementation code unless the relevant L3 spec is `frozen`.
-- `draft -> confirmed` and `confirmed -> frozen` are user review actions. After writing spec content, stop and wait for explicit user approval.
+- Feature work MUST go through `spec-manager`.
+- New or non-trivial work follows L1 -> L2 -> L3 -> Agent Task.
+- Never write implementation code without a frozen L3 spec.
+- L1/L2 approval advances `draft -> confirmed`; one explicit L3 approval (an explicit user approval) advances `draft -> frozen`.
 - Before creating a new spec, inspect existing specs and decisions with `spec-manager spec list` and `spec-manager decision list --topic <topic>`.
-- Before code edits, read the relevant frozen L3 spec and create/start an Agent Task.
+- Before code edits, read the frozen L3 spec and create/start an Agent Task.
+- planJson `coveredSpecs` MUST include the current L3 specCode.
+- Validate L3 markdown plans with `spec-manager spec validate-plan --from-spec <L3-code>`.
 - Record execution with `spec-manager task step`; finish with `spec-manager task complete`.
 
 ## Common Commands

package/templates/agents/CLAUDE.md

@@ -2,10 +2,14 @@
 
 This project uses `spec-manager` via the `/spec-manager` skill.
 
-- All feature work MUST go through `/spec-manager`; no direct code changes for non-trivial work.
+- Feature work MUST go through `spec-manager`.
+- New or non-trivial work follows L1 -> L2 -> L3 -> Agent Task.
 - Never write implementation code without a frozen L3 spec.
-- Never skip human review gates. L1, L2, and L3 each require explicit user approval.
-- Status transitions (`confirm` and `freeze`) are user actions, not AI actions.
+- L1/L2 approval advances `draft -> confirmed`; one explicit L3 approval (an explicit user approval) advances `draft -> frozen`.
+- Before code edits, read the frozen L3 spec and create/start an Agent Task.
+- planJson `coveredSpecs` MUST include the current L3 specCode.
+- Validate L3 markdown plans with `spec-manager spec validate-plan --from-spec <L3-code>`.
+- Record execution with `spec-manager task step`; finish with `spec-manager task complete`.
 - For research, prefer `spec-manager spec show` metadata first, then `--include-content` when full context is required.
 
 Use the installed `.claude/skills/spec-manager/` skill when the user invokes `/spec-manager` or approves the next spec-manager step.

package/templates/agents/CODEBUDDY.md

@@ -2,15 +2,17 @@
 
 This project uses `spec-manager` for local-first spec-driven development. CodeBuddy should use the project skill at `.codebuddy/skills/spec-manager/` when the user asks for `/spec-manager` or asks to follow the spec-manager workflow.
 
-## Rules
+## Unified Rules
 
-- Feature work MUST go through `spec-manager`; avoid direct code edits for non-trivial work.
-- New or non-trivial work follows L1 PRD -> L2 Design -> L3 Impl -> Agent Task.
-- Never write implementation code unless the relevant L3 spec is `frozen`.
-- `confirm` and `freeze` are user review actions. Stop after writing spec content and wait for explicit approval.
+- Feature work MUST go through `spec-manager`.
+- New or non-trivial work follows L1 -> L2 -> L3 -> Agent Task.
+- Never write implementation code without a frozen L3 spec.
+- L1/L2 approval advances `draft -> confirmed`; one explicit L3 approval (an explicit user approval) advances `draft -> frozen`.
 - Before creating a new spec, inspect existing specs and decisions.
-- Before code edits, read the relevant frozen L3 spec and create/start an Agent Task.
-- Record each execution step with `spec-manager task step`; complete with `spec-manager task complete`.
+- Before code edits, read the frozen L3 spec and create/start an Agent Task.
+- planJson `coveredSpecs` MUST include the current L3 specCode.
+- Validate L3 markdown plans with `spec-manager spec validate-plan --from-spec <L3-code>`.
+- Record execution with `spec-manager task step`; finish with `spec-manager task complete`.
 
 ## Useful Commands
 

package/templates/agents/CURSOR.md

@@ -0,0 +1,28 @@
+# spec-manager Workflow Capsule
+
+This file is the spec-manager entrypoint for Cursor. Cursor reads project rules from `.cursorrules`; route feature work through `spec-manager`.
+
+This project uses `spec-manager` for local-first spec-driven development. Specs, tasks, decisions, changes, and audit data are stored as markdown/JSON files in the repository.
+
+## Unified Rules
+
+- Feature work MUST go through `spec-manager`.
+- New or non-trivial work follows L1 -> L2 -> L3 -> Agent Task.
+- Never write implementation code without a frozen L3 spec.
+- L1/L2 approval advances `draft -> confirmed`; one explicit L3 approval (an explicit user approval) advances `draft -> frozen`.
+- Before code edits, read the frozen L3 spec and create/start an Agent Task.
+- planJson `coveredSpecs` MUST include the current L3 specCode.
+- Validate L3 markdown plans with `spec-manager spec validate-plan --from-spec <L3-code>`.
+- Record execution with `spec-manager task step`; finish with `spec-manager task complete`.
+
+## Common Commands
+
+```bash
+spec-manager project status
+spec-manager spec list
+spec-manager spec show <code> --include-content
+spec-manager decision list --topic <topic>
+spec-manager task list --topic <topic>
+```
+
+When the user asks for `/spec-manager <request>` or asks to use spec-manager, treat it as a request to follow this workflow.

package/templates/agents/WINDSURF.md

@@ -0,0 +1,28 @@
+# spec-manager Workflow Capsule
+
+This file is the spec-manager entrypoint for Windsurf. Windsurf reads project rules from `.windsurfrules`; route feature work through `spec-manager`.
+
+This project uses `spec-manager` for local-first spec-driven development. Specs, tasks, decisions, changes, and audit data are stored as markdown/JSON files in the repository.
+
+## Unified Rules
+
+- Feature work MUST go through `spec-manager`.
+- New or non-trivial work follows L1 -> L2 -> L3 -> Agent Task.
+- Never write implementation code without a frozen L3 spec.
+- L1/L2 approval advances `draft -> confirmed`; one explicit L3 approval (an explicit user approval) advances `draft -> frozen`.
+- Before code edits, read the frozen L3 spec and create/start an Agent Task.
+- planJson `coveredSpecs` MUST include the current L3 specCode.
+- Validate L3 markdown plans with `spec-manager spec validate-plan --from-spec <L3-code>`.
+- Record execution with `spec-manager task step`; finish with `spec-manager task complete`.
+
+## Common Commands
+
+```bash
+spec-manager project status
+spec-manager spec list
+spec-manager spec show <code> --include-content
+spec-manager decision list --topic <topic>
+spec-manager task list --topic <topic>
+```
+
+When the user asks for `/spec-manager <request>` or asks to use spec-manager, treat it as a request to follow this workflow.

package/templates/agents/codebuddy-skill/SKILL.md

@@ -13,6 +13,17 @@ Use this skill when the user invokes `/spec-manager`, asks for a new feature, PR
 - `/spec-manager <request>` — start from the user's requirement and route to the right subskill.
 - `/spec-manager run <taskId>` — execute an existing Agent Task.
 
+## Unified Rules
+
+- Feature work MUST go through `spec-manager`.
+- New or non-trivial work follows L1 -> L2 -> L3 -> Agent Task.
+- Never write implementation code without a frozen L3 spec.
+- L1/L2 approval advances `draft -> confirmed`; one explicit L3 approval (an explicit user approval) advances `draft -> frozen`.
+- Before code edits, read the frozen L3 spec and create/start an Agent Task.
+- planJson `coveredSpecs` MUST include the current L3 specCode.
+- Validate L3 markdown plans with `spec-manager spec validate-plan --from-spec <L3-code>`.
+- Record execution with `spec-manager task step`; finish with `spec-manager task complete`.
+
 ## Route Table
 
 | Signal | Subskill |
@@ -36,7 +47,7 @@ If intent is unclear, ask the user one concise clarification question before tak
 
 - Do not write implementation code without a frozen L3 spec.
 - Stop after writing L1/L2/L3 content and wait for explicit user approval.
-- Status transitions (`confirm` and `freeze`) are user actions.
+- Status transitions are user actions; one L3 `confirm` approval advances directly to frozen.
 - Agent Tasks can only be created from frozen L3 specs.
 - Before code edits, read the relevant spec and inspect the actual source files.