@alenfitz/spec-copilot 1.1.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: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/framework/AGENTS.md.template

@@ -55,6 +55,7 @@
 | "帮我看看代码" / "review 一下" | → /spec:review |
 | "写测试" / "补单测" | → /spec:test |
 | "归档 xxx" | → /spec:archive |
+| "生成文档" / "更新文档" / "README" | → /spec:docs |
 | "线上出问题了" / "紧急修" | → /spec:hotfix |
 
 ## 必读规则文件

package/framework/CHANGELOG.md

@@ -4,6 +4,24 @@
 
 ---
 
+## [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
 
 ### 变更（基于真实项目端到端测试反馈）

package/framework/VERSION

@@ -1 +1 @@
-1.5.0
+1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alenfitz/spec-copilot",
-  "version": "1.1.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",