@alenfitz/spec-copilot 1.0.0 → 1.2.0

package/README.md

@@ -50,7 +50,8 @@ The framework auto-detects your tool on subsequent commands (`update`, `doctor`,
 | `/spec:smoke <name>` | After /spec:apply | Build + API smoke test |
 | `/spec:review <name>` | After /spec:smoke | Spec compliance + code quality report |
 | `/spec:fix <name>` | After review issues | Fix commits + doc sync |
-| `/spec:archive <name>` | After review passes | Knowledge captured, merge prompt |
+| `/spec:archive <name>` | After review passes | Knowledge captured, docs updated, merge prompt |
+| `/spec:docs [type]` | Anytime | README + API + Architecture + Deploy docs |
 | `/spec:hotfix <desc>` | Production incident | Minimal fix on hotfix branch |
 | `/spec:test <name>` | Need automated tests | Test code + run results |
 
@@ -71,9 +72,11 @@ npx @alenfitz/spec-copilot uninstall --confirm       # Remove framework
 your-project/
 ├── <tool-specific prompt file>        ← AI reads this
 ├── <tool-specific commands/>          ← Native commands (if supported)
+├── README.md                          ← Auto-generated project docs
+├── docs/                              ← API, architecture, deploy docs
 │
 └── spec_copilot/
-    ├── commands/                      ← 11 command definitions
+    ├── commands/                      ← 12 command definitions
     ├── rules/
     │   ├── coding-style.md            ← Universal coding standards
     │   ├── security.md                ← Security red lines

package/README.zh-CN.md

@@ -50,7 +50,8 @@ npx @alenfitz/spec-copilot doctor
 | `/spec:smoke <变更名>` | /spec:apply 完成后 | 编译 + 接口冒烟报告 |
 | `/spec:review <变更名>` | /spec:smoke 通过后 | Spec 合规 + 代码质量审查报告 |
 | `/spec:fix <变更名>` | review 有问题 | 修复 commit + 文档同步 |
-| `/spec:archive <变更名>` | review 通过后 | 知识沉淀 + 分支合并提示 |
+| `/spec:archive <变更名>` | review 通过后 | 知识沉淀 + 文档更新 + 分支合并提示 |
+| `/spec:docs [类型]` | 任何时候 | README + API + 架构 + 部署文档 |
 | `/spec:hotfix <描述>` | 线上故障 | 最小修复 + hotfix 分支 |
 | `/spec:test <变更名>` | 补自动化测试 | 测试代码 + 运行报告 |
 
@@ -72,8 +73,11 @@ npx @alenfitz/spec-copilot uninstall --confirm       # 移除框架
 ├── <工具专属提示词文件>               ← AI 读取
 ├── <工具专属命令目录/>               ← 原生命令（如支持）
 │
+├── README.md                          ← 自动生成的项目文档
+├── docs/                              ← API、架构、部署文档
+│
 └── spec_copilot/
-    ├── commands/                      ← 11 个命令定义
+    ├── commands/                      ← 12 个命令定义
     ├── rules/
     │   ├── coding-style.md            ← 编码通用规范
     │   ├── security.md                ← 安全红线

package/commands/spec:apply.md

@@ -12,16 +12,45 @@ description: 执行编码（逐 task 推进，每个 task 停顿等确认）
 2. Gate 通过后：`git checkout -b feature/<变更名>`（如已在分支则跳过）
 3. 告知用户当前分支名
 
-## 逐 task 执行规则
+## 逐 task 执行规则（铁律：一个 task 一停）
+
+> **🛑 这是最重要的规则：完成一个 task 后必须完全停止，等用户说"继续"才执行下一个 task。**
+> **禁止连续执行多个 task。禁止在一次回复中完成两个或更多 task。**
+> **即使用户说"全部执行"或"一口气做完"，仍必须逐 task 停顿。**
+
+每个 task 的执行流程：
+1. 编码实现
+2. 验证（编译/构建/运行）
+3. 展示验证证据（截取关键输出）
+4. 立即 `git commit`
+5. 更新 tasks.md 该 task 状态为 ✅
+6. **🛑 停止。输出以下提示后结束回复：**
+   ```
+   ✅ T<n> 完成（<简述>）
+   验证：<编译/测试结果>
+   Commit: <hash> <message>
+   
+   → 下一步：T<n+1>: <描述>
+   → 说"继续"执行下一个 task
+   ```
+7. **等用户回复后才开始下一个 task**
 
-- 每完成一个 task：展示验证证据 → 立即 commit → **停下来等用户说"继续"**
 - 用户反馈后修改完 → 再次停下确认，不得自动进入下一 task
 - Spec-Code 偏差当场记录到 log.md（log.md 已在 /spec:propose 时从 `spec_copilot/changes/templates/log.md` 模板创建，直接编辑已有文件，不得重建）
 
-## 结束时自动执行
+## 全部 task 完成后
 
 1. 填写 tasks.md "变更摘要"
-2. → `/spec:smoke <变更名>`
-3. Smoke 通过后读取 spec.md §2 复杂度等级，自动触发下一阶段
-
-核心原则：AI 负责执行，用户负责推进。
+2. 输出完成报告：
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   /spec:apply 全部完成 ✓
+   总 Task：<N> 个
+   总 Commit：<N> 个
+   
+   → 下一步：/spec:smoke <变更名>
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+3. **停止。等用户触发 /spec:smoke。**
+
+核心原则：**AI 负责执行，用户负责推进节奏。** 任何阶段跳转都需要用户显式触发。

package/commands/spec:archive.md

@@ -16,14 +16,25 @@ description: 归档变更 + 知识沉淀
 3. 移动 `spec_copilot/changes/<变更名>/` → `spec_copilot/archives/<YYYY-MM>/<变更名>/`
 4. 提示合并分支：`git merge feature/<变更名> --no-ff`
 
+## 自动生成/更新项目文档
+
+归档完成后，**自动执行 `/spec:docs`**，生成或更新：
+- `README.md` — 项目说明（根目录）
+- `docs/api.md` — API 接口文档
+- `docs/architecture.md` — 系统架构（含 Mermaid ER 图、状态机图）
+- `docs/deploy.md` — 部署指南
+
+> 这是确保项目文档与代码同步的关键机制。每次归档 = 文档自动刷新。
+
 ## 结束后
 
 ```
 需求 [变更名] 已归档 ✓
 知识已沉淀：<N> 条
+文档已更新：README.md + docs/（api + architecture + deploy）
 请执行：git merge feature/<变更名> --no-ff
 
 → 下一个需求：/spec:propose <描述>
 ```
 
-没有 /archive，knowledge/ 永远是空的，知识飞轮不转。
+没有 /archive，knowledge/ 永远是空的，知识飞轮不转。文档不更新，新人永远看不懂项目。

package/commands/spec:docs.md

@@ -0,0 +1,132 @@
+---
+description: 生成/更新项目文档（README + API + 架构 + 部署）
+---
+
+# /spec:docs — 项目文档生成
+
+**参数**：$ARGUMENTS（可选，指定只更新某个文档：readme / api / architecture / deploy）
+
+## 数据源
+
+文档内容从以下来源自动提取，**不凭空编造**：
+
+| 来源 | 提取什么 |
+|------|---------|
+| `spec_copilot/rules/project-context.md` | 项目概况、技术栈、目录结构、启动命令、依赖版本 |
+| `spec_copilot/archives/` | 所有已归档需求的功能清单、业务规则、数据模型 |
+| `spec_copilot/changes/` | 进行中的变更（标注为 WIP） |
+| `spec_copilot/stack-adapters/<栈>.md` | 技术规范、分层架构 |
+| 源代码 | Controller 路由扫描（API 文档）、Entity 扫描（ER 图） |
+
+## 产出文件
+
+### 1. `README.md`（项目根目录）
+
+```markdown
+# 项目名称
+
+> 项目简介（来自 project-context.md §1）
+
+## 技术栈
+（来自 project-context.md §1 + §4）
+
+## 快速开始
+（来自 project-context.md §8）
+
+## 目录结构
+（来自 project-context.md §2）
+
+## 功能模块
+（从 archives/ 聚合所有已完成需求，每个需求一行：名称 + 简介 + 完成日期）
+
+## API 概览
+（从 docs/api.md 提取摘要表格）
+
+## 开发规范
+> 详见 spec_copilot/ 目录下的规范文件
+
+## License
+```
+
+### 2. `docs/api.md`（API 接口文档）
+
+**生成方式**：扫描所有 Controller 类，提取 `@RequestMapping` / `@GetMapping` / `@PostMapping` 等注解。
+
+```markdown
+# API 接口文档
+
+## 概览
+| 模块 | 前缀 | 接口数 |
+|------|------|--------|
+
+## 详细接口
+
+### 模块名
+#### GET /api/xxx — 接口说明
+- **参数**：（从 DTO 类提取字段+注释）
+- **返回**：（从 VO 类提取字段+注释）
+- **业务规则**：（从对应 spec.md §4 提取）
+```
+
+> 对于非 Java 项目（Node/Python/Go），扫描对应框架的路由定义文件。
+
+### 3. `docs/architecture.md`（系统架构）
+
+```markdown
+# 系统架构
+
+## 分层架构
+（来自 stack-adapter §6，Mermaid 流程图）
+
+## 数据模型
+（扫描 Entity 类 / schema.sql，生成 Mermaid ER 图）
+
+## 状态机
+（如存在状态枚举，生成 Mermaid 状态图）
+
+## 外部依赖
+（从 spec.md 提取外部服务清单）
+
+## 模块关系
+（Mermaid 组件图，展示模块间调用关系）
+```
+
+### 4. `docs/deploy.md`（部署指南）
+
+```markdown
+# 部署指南
+
+## 环境要求
+（从 project-context.md §4 提取版本要求）
+
+## 配置说明
+（从 project-context.md §9 和 stack-adapter §4 提取）
+
+## 构建命令
+（从 project-context.md §8 提取）
+
+## 数据库初始化
+（检测 schema.sql / flyway / liquibase）
+
+## 注意事项
+（从 knowledge/index.md 提取 #deploy 标签的知识条目）
+```
+
+## 执行规则
+
+1. **增量更新**：如果文档已存在，只更新有变化的章节，保留用户手动添加的内容（通过 `<!-- auto-generated -->` 和 `<!-- /auto-generated -->` 标记区分）
+2. **Mermaid 图表**：使用 Mermaid 语法，GitHub/GitLab 原生渲染
+3. **不编造内容**：所有文档内容必须有数据源出处。无法提取的章节标注 `> TODO: 待补充`
+4. **中文输出**：与项目语言一致
+
+## 结束后
+
+```
+文档已生成/更新 ✓
+├── README.md          （项目说明）
+├── docs/api.md        （N 个接口）
+├── docs/architecture.md（含 ER 图 + 状态机图）
+└── docs/deploy.md     （部署指南）
+
+→ 建议：git commit -m "docs: 更新项目文档"
+```

package/commands/spec:fix.md

@@ -1,20 +1,28 @@
 ---
-description: Review 后修正迭代
+description: Review 后修正迭代（修复→重新验证闭环）
 ---
 
 请按 AGENTS.md 中定义的 /fix 流程执行：
 
 **变更名 + 描述**：$ARGUMENTS
 
-1. 读取问题列表，逐项修复
-2. 每个修复同步更新文档（spec.md / tasks.md / log.md）
-3. 修复完成 commit：`[变更名] fix: <简述>`
+## 修复流程
 
-## 结束后
+1. 读取 spec.md §12 审查结论和 log.md 中的问题列表
+2. 逐项修复：
+   - 每修一个问题，在 log.md 记录：`| 时间 | fix | 修复 <问题描述> |`
+   - 修改涉及的文档同步更新（spec.md / tasks.md）
+3. 全部修复后一次 commit：`[变更名] fix: <修复概述>`
+4. 更新 tasks.md 变更摘要中的"遗留问题"
 
-修复完成后**自动回到触发源**：
+## 修复后自动重新验证（必须执行）
 
-| 触发源 | 自动执行 |
-|--------|---------|
-| /spec:smoke 失败 | → `/spec:smoke <变更名>` |
-| /spec:review Critical | → `/spec:review <变更名>` |
+修复完成后**必须自动回到触发源重新验证**，不等用户确认：
+
+| 触发源 | 自动执行 | 说明 |
+|--------|---------|------|
+| /spec:smoke 失败 | → 自动执行 `/spec:smoke <变更名>` | 验证编译/构建修复 |
+| /spec:review Critical>0 | → 自动执行 `/spec:review <变更名>` | 重新两阶段审查 |
+
+> **铁律**：fix → re-verify 是一个原子闭环。修了不验证等于没修。
+> 如果重新验证仍然失败，再次停下来报告问题，不要无限循环。

package/commands/spec:test.md

@@ -16,7 +16,25 @@ description: 补充自动化测试
 - 异常路径（非法参数、依赖服务失败）
 
 文件位置和命名遵循对应 stack adapter §8。
-生成后立即运行，全部通过后 commit：`[变更名] test: 补充自动化测试`
+文件位置和命名遵循对应 stack adapter §8。
+
+## 执行与报告
+
+1. 生成测试代码
+2. 运行全部测试
+3. **输出详细报告**（不能只说"全部通过"）：
+   ```
+   ## 测试报告：<变更名>
+   
+   | 测试类 | 用例数 | 通过 | 失败 | 覆盖范围 |
+   |--------|-------|------|------|---------|
+   | XxxTest | N | N | 0 | 说明测试了什么 |
+   
+   总计：<N> 个用例，<N> 通过，<N> 失败
+   覆盖率：核心 Service > 80%（如工具支持）
+   ```
+4. 全部通过后 commit：`[变更名] test: 补充自动化测试（<N> 用例）`
+5. 记录到 log.md
 
 ## 结束后
 

package/framework/AGENTS.md.template

@@ -24,6 +24,11 @@
 - 涉及外部 API 密钥/敏感信息 → 必须通过配置文件管理，禁止硬编码
 - 有价值的发现 → 主动建议沉淀到 knowledge/
 
+### 节奏控制（铁律）
+- **逐 task 停顿**：/spec:apply 期间，完成一个 task 就停下来，展示验证证据，等用户说"继续"才执行下一个。**禁止连续执行多个 task。**
+- **阶段跳转等确认**：每个阶段（propose/apply/smoke/review/fix/test/archive）完成后停下来，告知下一步是什么，等用户显式触发。
+- **唯一例外**：/spec:flow 全自动模式下，阶段间自动推进（但仅限 🟢/🟡 需求）。
+
 ## 启动检查（每次会话开始时执行）
 
 **执行 `/spec:init`** — 该命令自动完成规范加载、项目扫描、栈适配、变更检测、状态报告。这是每次会话的唯一起点。
@@ -50,6 +55,7 @@
 | "帮我看看代码" / "review 一下" | → /spec:review |
 | "写测试" / "补单测" | → /spec:test |
 | "归档 xxx" | → /spec:archive |
+| "生成文档" / "更新文档" / "README" | → /spec:docs |
 | "线上出问题了" / "紧急修" | → /spec:hotfix |
 
 ## 必读规则文件

package/framework/CHANGELOG.md

@@ -4,6 +4,48 @@
 
 ---
 
+## [1.6.0] - 2026-05-21
+
+### 新增
+
+**`/spec:docs` — 项目文档自动生成：**
+- 新增第 12 个命令 `/spec:docs`，从 project-context、archives、源代码自动生成四类文档
+- `README.md`：项目说明（技术栈、快速开始、功能模块、API 概览）
+- `docs/api.md`：API 接口文档（扫描 Controller 注解自动提取）
+- `docs/architecture.md`：系统架构（分层架构、Mermaid ER 图、状态机图、模块关系图）
+- `docs/deploy.md`：部署指南（环境要求、配置说明、构建命令、数据库初始化）
+- 增量更新机制：通过 `<!-- auto-generated -->` 标记区分自动生成和手动编写内容
+
+**`/spec:archive` 自动触发文档更新：**
+- 归档完成后自动执行 `/spec:docs`，确保每次归档 = 文档同步刷新
+- 解决"所有文档锁在 spec_copilot/ 里、新人看不到"的问题
+
+---
+
+## [1.5.0] - 2026-05-21
+
+### 变更（基于真实项目端到端测试反馈）
+
+**逐 Task 停顿强化（P0）：**
+- `spec:apply` 命令新增「铁律」区块，三重强调：完成一个 task 必须停下等用户确认
+- 禁止连续执行多个 task，即使用户说"全部执行"
+- 每个 task 完成后输出标准化停顿提示（含 commit hash、下一步 task 描述）
+- AGENTS.md 新增「节奏控制」章节，全局声明逐 task 停顿规则
+
+**Fix → Re-verify 闭环（P0）：**
+- `spec:fix` 命令重写，修复完成后必须自动重新验证（smoke/review），不等用户触发
+- 明确 fix → re-verify 是原子闭环，增加无限循环保护
+
+**阶段跳转等确认（P1）：**
+- `spec:apply` 结束时不再自动触发 smoke，改为输出完成报告后等待用户显式触发
+- 核心原则调整为"AI 负责执行，用户负责推进节奏"
+
+**测试报告详细化（P1）：**
+- `spec:test` 命令要求输出详细报告表格（测试类/用例数/通过数/覆盖范围）
+- 不再接受"全部通过"的笼统报告
+
+---
+
 ## [1.4.0] - 2026-05-21
 
 ### 新增

package/framework/VERSION

@@ -1 +1 @@
-1.4.0
+1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alenfitz/spec-copilot",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Spec-Driven Development Framework — one package, six AI coding tools (opencode, Claude Code, Cursor, Windsurf, GitHub Copilot, Cline)",
   "keywords": [
     "ai-coding",