@alenfitz/spec-copilot 1.0.0

package/commands/spec:apply.md

@@ -0,0 +1,27 @@
+---
+description: 执行编码（逐 task 推进，每个 task 停顿等确认）
+---
+
+请按 AGENTS.md 中定义的 /apply 流程执行：
+
+**变更名**：$ARGUMENTS
+
+## 前置检查（缺一不过）
+
+1. 运行 `npx @alenfitz/spec-copilot gate <变更名> apply`（跨平台门禁检查）
+2. Gate 通过后：`git checkout -b feature/<变更名>`（如已在分支则跳过）
+3. 告知用户当前分支名
+
+## 逐 task 执行规则
+
+- 每完成一个 task：展示验证证据 → 立即 commit → **停下来等用户说"继续"**
+- 用户反馈后修改完 → 再次停下确认，不得自动进入下一 task
+- Spec-Code 偏差当场记录到 log.md（log.md 已在 /spec:propose 时从 `spec_copilot/changes/templates/log.md` 模板创建，直接编辑已有文件，不得重建）
+
+## 结束时自动执行
+
+1. 填写 tasks.md "变更摘要"
+2. → `/spec:smoke <变更名>`
+3. Smoke 通过后读取 spec.md §2 复杂度等级，自动触发下一阶段
+
+核心原则：AI 负责执行，用户负责推进。

package/commands/spec:archive.md

@@ -0,0 +1,29 @@
+---
+description: 归档变更 + 知识沉淀
+---
+
+请按 AGENTS.md 中定义的 /archive 流程执行：
+
+**变更名**：$ARGUMENTS
+
+## 前置检查
+
+运行 `npx @alenfitz/spec-copilot gate <变更名> archive`（跨平台门禁检查）
+
+必做步骤：
+1. 逐条展示 log.md "知识发现"，用户确认后写入 `spec_copilot/knowledge/index.md`（带 tag）
+2. 更新 spec.md status → done
+3. 移动 `spec_copilot/changes/<变更名>/` → `spec_copilot/archives/<YYYY-MM>/<变更名>/`
+4. 提示合并分支：`git merge feature/<变更名> --no-ff`
+
+## 结束后
+
+```
+需求 [变更名] 已归档 ✓
+知识已沉淀：<N> 条
+请执行：git merge feature/<变更名> --no-ff
+
+→ 下一个需求：/spec:propose <描述>
+```
+
+没有 /archive，knowledge/ 永远是空的，知识飞轮不转。

package/commands/spec:bootstrap.md

@@ -0,0 +1,103 @@
+---
+description: 新项目引导 — 栈选型 + 脚手架搭建
+---
+
+# /bootstrap — 新项目引导 & 栈选型
+
+检测到当前项目为空壳（无可识别的构建文件：无 package.json/pom.xml/go.mod/requirements.txt 等）。
+
+你需要和用户协作完成技术栈选型，然后搭建项目骨架。
+
+## Step 1 — 需求澄清（先问再动）
+
+向用户提问以下信息（一次问完，不给四五个问题来回拉扯）。用户可用简答，AI 根据答案补全细节。
+
+### 必问三项
+
+1. **项目类型**：Web 全栈 / API 服务 / CLI 工具 / 定时任务 / 其他
+2. **预期规模**：个人小工具 / 团队协作 / 企业级（影响架构复杂度）
+3. **是否有技术偏好**：指定语言/框架/数据库，还是让 AI 推荐
+
+### 内网环境
+
+4. **依赖源**：公网下载依赖，还是公司有内部镜像仓库？
+   - 公网 → 跳过，不做任何配置
+   - 内网镜像 → 追问：registry URL？是否需要认证？认证方式（token / 用户名密码 / 证书）？
+   - 此信息记录到 `project-context.md` §9
+
+### 根据项目类型追问
+
+| 项目类型 | 追问 |
+|---------|------|
+| Web 全栈 | 前端偏好？SEO 重要吗（SSR/CSR）？ |
+| API 服务 | REST / GraphQL / gRPC？预期 QPS 量级？ |
+| CLI 工具 | 目标平台？需要交互式 UI？ |
+| 定时任务 | 调度平台？单次/周期性？ |
+
+## Step 2 — 推荐栈 & 等确认
+
+根据用户回答，推荐一个技术栈组合，必须说明**为什么这个组合适合**：
+
+```
+推荐栈：
+- 语言：TypeScript
+- 运行时：Node.js
+- 框架：Express.js
+- 数据库：PostgreSQL（本地开发用 SQLite 也行）
+- ORM：Prisma
+
+理由：
+- Node.js + Express 适合你描述的 QPS < 1000 的中型 API，团队上手快
+- TypeScript 提供静态检查，减少运行时类型错误
+- PostgreSQL 是此规模最稳妥的选择，支持 JSON 查询方便后续扩展
+```
+
+等用户确认或调整后再进入 Step 3。
+
+## Step 3 — 搭建脚手架
+
+用户确认栈选型后，AI 按以下顺序搭建：
+
+0. **配置依赖源**（仅内网环境，公网跳过）：
+   - Node.js：创建/追加 `.npmrc`（`registry=<url>`，如需要认证则配置 `//<registry>:_authToken=`）
+   - Java/Maven：创建/追加 `~/.m2/settings.xml` 或项目级 `.mvn/settings.xml`
+   - Python：创建/追加 `pip.conf` / `pip.ini` 或配置 `PIP_INDEX_URL` 环境变量
+   - Go：配置 `GOPROXY` 环境变量
+   - **不创建配置文件存认证凭据**，token/密码通过环境变量注入
+1. **初始化项目文件**：package.json / pom.xml / go.mod / requirements.txt 等（锁定版本，不用 ^/~）
+2. **创建目录结构**：按栈适配器模板的约定目录结构
+3. **最小可运行入口**：一个能编译/启动的空壳（如 Express hello world、Spring Boot 空项目）
+4. **基础配置**：.gitignore、环境变量示例 .env.example、README 占位
+   - `.gitignore` 必须包含 `.npmrc` / `pip.conf` / `settings.xml`（防止误提交内网地址）
+5. **选择栈适配器**：
+   - 已有匹配的 `spec_copilot/stack-adapters/<stack>.md` → 直接加载
+   - 无匹配 → 基于 `spec_copilot/stack-adapters/_template.md` 创建新的适配器文件
+
+## Step 4 — 填充工程上下文
+
+按 `spec_copilot/rules/project-context.md` 模板填充所有章节（应用名、技术栈、目录结构、分层架构、关键依赖、启动命令）。
+
+## Step 5 — 初始化 Git
+
+```bash
+git init
+git add .
+git commit -m "chore: project bootstrap — <栈简述>"
+```
+
+## 结束后
+
+```
+项目已初始化 ✓
+技术栈：<推荐栈>
+栈适配器：spec_copilot/stack-adapters/<file>.md
+本地启动：<启动命令>
+
+→ 可以开始第一个需求：/spec:propose <需求描述>
+```
+
+## 铁律
+
+- **不替用户做栈选型决策**，推荐并解释理由，等用户确认
+- 依赖版本锁定（不用 ^/~），安全红线见 `security.md §5`
+- 脚手架必须是可编译/启动的最小骨架，不加任何业务代码

package/commands/spec:fix.md

@@ -0,0 +1,20 @@
+---
+description: Review 后修正迭代
+---
+
+请按 AGENTS.md 中定义的 /fix 流程执行：
+
+**变更名 + 描述**：$ARGUMENTS
+
+1. 读取问题列表，逐项修复
+2. 每个修复同步更新文档（spec.md / tasks.md / log.md）
+3. 修复完成 commit：`[变更名] fix: <简述>`
+
+## 结束后
+
+修复完成后**自动回到触发源**：
+
+| 触发源 | 自动执行 |
+|--------|---------|
+| /spec:smoke 失败 | → `/spec:smoke <变更名>` |
+| /spec:review Critical | → `/spec:review <变更名>` |

package/commands/spec:flow.md

@@ -0,0 +1,100 @@
+---
+description: 全自动流水线 — propose → apply → smoke → review → archive
+---
+
+# /flow — 全自动开发流水线
+
+请自动完成以下需求的端到端开发：
+
+**需求描述**：$ARGUMENTS
+
+## 模式说明
+
+此为**自动模式**，AI 自主推进每个阶段，不停下等待用户确认。仅适用 🟢 + 🟡 需求。🔴 复杂需求拒绝执行，提示走手动流程。
+
+## 执行序列
+
+按以下顺序逐阶段执行，**任一步骤失败即停，不继续**。
+
+---
+
+### Phase 1: Propose
+
+1. 复杂度评估（按 AGENTS.md §复杂度分级 判定）
+   - 🔴 → 🛑 **立即终止**，输出：*"🔴 复杂需求不适用自动模式，请走手动流程 /spec:propose + /spec:apply"*
+   - 🟢 简单 → 跳过 spec 创建，直接编码后结束
+   - 🟡 中等 → 继续执行
+2. Research：Grep/Read 现有代码 + knowledge/
+3. 写文件：
+   - `spec_copilot/changes/<变更名>/spec.md`（按模板填充）
+   - `spec_copilot/changes/<变更名>/log.md`（模板原样写入，替换标题）
+4. §9 待澄清检查：
+   - 有 `- [ ]` 未解决项 → 🛑 **停下来**，列出问题，提示：*"以上问题需要确认后才能自动推进"*
+   - 已清空 → 继续
+5. 运行 lint
+
+---
+
+### Phase 2: Apply
+
+1. 运行 `npx @alenfitz/spec-copilot gate <变更名> apply`
+2. Gate 通过后逐 task 编码（**不停顿**，不等用户说"继续"）：
+   - 完成一个 task → 验证证据 → 立即 commit → 自动进入下一 task
+   - Spec-Code 偏差记录到 log.md
+3. 全部 task 完成后：
+   - 填写 tasks.md "变更摘要"（如有 tasks.md）
+   - 执行 Phase 3
+
+---
+
+### Phase 3: Smoke
+
+1. 编译/构建后端（命令见 `project-context.md` §8）
+2. 对 spec §6 每个接口执行 curl 验证
+3. **记录到 log.md**：在 `## 时间线` 追加 `| 当前时间 | smoke | 冒烟测试通过 ✓ |`
+4. 评估结果：
+   - 通过 → 执行 Phase 4
+   - 失败 → 🛑 **停下来**，输出失败详情，提示：*"冒烟失败，请检查后说'继续'或 /spec:fix"*
+
+---
+
+### Phase 4: Review
+
+1. 运行 `npx @alenfitz/spec-copilot gate <变更名> review`
+2. 阶段一 Spec Compliance（附录 A）：逐条验证功能点
+3. 阶段二 Code Quality（附录 B）：按 Critical/Important/Minor 审查
+4. 更新 spec.md §12 审查结论
+5. 评估结果：
+   - Critical = 0 → 执行 Phase 5
+   - Critical > 0 → 🛑 **停下来**，列出所有 Critical 问题，提示：*"审查未通过，修复后请说'继续'或 /spec:fix"*
+
+---
+
+### Phase 5: Archive
+
+1. 运行 `npx @alenfitz/spec-copilot gate <变更名> archive`
+2. 逐条展示 log.md "知识发现"，自动将可沉淀的写入 `spec_copilot/knowledge/index.md`
+3. 更新 spec.md status → done
+4. 移动 `spec_copilot/changes/<变更名>/` → `spec_copilot/archives/<YYYY-MM>/<变更名>/`
+5. 输出最终报告：
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+需求 [变更名] 已完成 ✓
+
+复杂度：🟡 中等
+耗时阶段：propose → apply → smoke → review → archive
+改动文件：<N> 个
+知识沉淀：<N> 条
+
+→ 下一步：git merge feature/<变更名> --no-ff
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 铁律
+
+- 逐阶段输出进度标题（`## Phase N: ...`），不跳步
+- 任一步骤失败立即停，不继续后续阶段
+- 🔴 复杂需求直接拒绝
+- §9 有未解决项直接拒绝
+- Spec-Code 偏差必须记录

package/commands/spec:hotfix.md

@@ -0,0 +1,26 @@
+---
+description: 紧急线上故障修复
+---
+
+请按 AGENTS.md 中定义的 /hotfix 流程执行：
+
+**问题描述**：$ARGUMENTS
+
+规则：
+1. 允许跳过 spec 三段生成，但必须产出精简 spec（≤100 字）
+2. 基于 hotfix 分支执行最小修复
+3. 单个原子 commit
+4. 必须跑 /smoke 验证
+
+铁律：禁止在 hotfix 分支做任何非修复动作。先止血，后治本。
+
+## 结束后
+
+```
+故障修复已完成 ✓
+
+⚠️  24 小时内必须补齐：
+  /spec:archive <变更名>（补完整 spec + review + 沉淀 #incident）
+
+治本方案：/spec:propose <根治方案描述>
+```

package/commands/spec:init.md

@@ -0,0 +1,82 @@
+---
+description: 会话启动 — 加载规范、初始化项目、报告状态
+---
+
+# /init — 会话启动 & 项目初始化
+
+你是 code-copilot。执行以下启动序列：
+
+## Step 1 — 加载规范核心
+
+读取以下文件到上下文：
+- `AGENTS.md` — 完整规范（核心法则、复杂度分级、Git 规范、调试流程）
+- `spec_copilot/VERSION` 和 `CHANGELOG.md`
+- `spec_copilot/rules/coding-style.md`
+- `spec_copilot/rules/security.md`
+- `spec_copilot/rules/domain-rules.md`
+
+## Step 2 — 项目类型判定
+
+### 2a — 检测项目状态
+
+检查项目是否有**实际应用代码**：
+
+已有项目特征（满足任一）：
+- 存在源代码目录：`src/` / `app/` / `lib/` / `cmd/` / `main/`
+- 构建文件中含应用级依赖（如 package.json 含 express/next/koa，pom.xml 含 spring-boot，go.mod 含 gin/echo）
+- 存在数据库迁移文件或 ORM 配置
+
+空壳项目特征（全部满足）：
+- 无源代码目录
+- 构建文件仅含框架自身依赖（`@alenfitz/spec-copilot`）或为空壳 `npm init -y` 产物
+- 无数据库/ORM 相关文件
+
+**空壳项目**：
+→ 🛑 停止，输出：*"检测到空项目，需要先完成栈选型和脚手架搭建。"*
+→ 自动触发 `/spec:bootstrap`
+
+**已有项目**：
+→ 继续 2b
+
+### 2b — 扫描项目，填充工程上下文
+
+分析项目根目录，识别：
+- 语言和框架（pom.xml / package.json / requirements.txt / go.mod 等）
+- 构建工具和版本
+- 目录结构和分层架构
+- 关键依赖及版本
+- **依赖源配置**：检测是否存在 `.npmrc` / `pip.conf` / `settings.xml` / `GOPROXY` 等镜像配置，有则填入 project-context.md §9
+
+按 `spec_copilot/rules/project-context.md` 模板填充所有章节。
+
+## Step 3 — 加载栈适配
+
+根据识别到的技术栈，加载对应 `spec_copilot/stack-adapters/<stack>.md`。
+- 有 → 加载并提示
+- 无 → 提示用户基于 `_template.md` 创建
+
+## Step 4 — 检查进行中的变更
+
+扫描 `spec_copilot/changes/` 下是否有 status != done 的需求。
+- 有 → 读取 spec/tasks/log，报告恢复点：`"检测到进行中的变更 [名称]，上次完成到 T<n>，下一步是 T<n+1>"`
+- 无 → 报告无进行中变更
+
+## Step 5 — 报告状态
+
+```
+规范版本：v<版本>
+技术栈：<识别到的栈>
+进行中的变更：<无 / 有 N 个>
+可用命令：/spec:propose /spec:apply /spec:smoke /spec:review /spec:fix /spec:archive /spec:hotfix /spec:test
+```
+
+## 结束后
+
+```
+规范已加载 ✓
+→ 新需求：/spec:propose <需求描述>
+→ 继续进行中的变更：/spec:apply <变更名>
+```
+
+> 每个结论必须有代码出处（文件路径），不猜测。
+> 切换项目时重新执行 /init 覆盖 project-context.md。

package/commands/spec:propose.md

@@ -0,0 +1,64 @@
+---
+description: 发起变更提案（评估复杂度、分段生成 spec）
+---
+
+请按 AGENTS.md 中定义的 /propose 流程处理以下需求：
+
+**需求描述**：$ARGUMENTS
+
+## Step 0 — 复杂度分级
+
+按**影响面**判定：
+
+| 级别 | 判定标准 | 制品 | 后续流程 |
+|------|---------|------|---------|
+| 🟢 简单 | 不改 API 契约 且 不改表结构 且 不改核心流程 且 不引入新依赖 | 无 | 直接编码 |
+| 🟡 中等 | 新增 1-3 接口 / 改 1-2 表非核心字段 / 引入新依赖 / 改核心流程的非关键分支 | spec.md | apply → smoke → review → archive |
+| 🔴 复杂 | 新子系统 / 改核心流程主路径 / 改核心表结构 / 并发或事务 / 数据迁移 / 外部服务集成 | spec.md + tasks.md | apply → smoke → review → test → archive |
+
+给出级别和理由（必须说明触及了哪条影响面），然后直接进入 Step 1，**不等待用户确认**。
+
+🟢 简单 → 直接编码，不创建文件。到此结束。
+
+## Step 1 — Research
+
+Grep/Read 现有代码和 knowledge/。
+
+## Step 2 — 写入文件（第一个动作）
+
+**在输出任何 spec 内容到对话之前，先用 Write 工具创建文件：**
+
+```
+mkdir -p spec_copilot/changes/<变更名>/
+Write: spec_copilot/changes/<变更名>/spec.md
+Write: spec_copilot/changes/<变更名>/log.md
+```
+
+- `spec.md` — 以 `spec_copilot/changes/templates/spec.md` 为模板，填充所有能填的章节。不确定的内容填入 §9 待澄清，标记为 `- [ ]`。
+- `log.md` — 以 `spec_copilot/changes/templates/log.md` 为模板，**原样写入**，仅替换标题中的"需求名称"为实际变更名。所有章节（时间线/知识发现/Spec-Code 偏差记录）必须保留。
+
+🔴 复杂需求还需额外创建 `tasks.md`（以 `spec_copilot/changes/templates/tasks.md` 为模板）。
+
+写完文件后，用 Read 确认内容，然后展示摘要。
+
+## Step 3 — §9 检查（自动模式关键决策点）
+
+检查 spec.md §9 待澄清：
+
+- **§9 有 `- [ ]` 未解决项** → 🛑 停下来，列出所有待澄清问题，提示：*"请回答以上问题后说'继续'"*
+- **§9 已清空** → 输出：
+  ```
+  spec 已就绪 ✓（§9 已清空，可自动推进）
+  文件：spec_copilot/changes/<变更名>/spec.md
+  → 下一步：/spec:apply <变更名>
+  → 全自动：/spec:flow <变更名>
+  ```
+
+## Step 4 — Lint
+
+`npx @alenfitz/spec-copilot lint <变更名>`
+
+## 铁律
+
+- **先说"我写入了 spec.md"，再展示内容。** 文件不存在 = propose 失败。
+- 禁止只在对话中总结。禁止跳过 Write 工具调用。

package/commands/spec:review.md

@@ -0,0 +1,48 @@
+---
+description: 两阶段审查（Spec 合规 + 代码质量）
+---
+
+请按 AGENTS.md 中定义的 /review 流程执行：
+
+**变更名**：$ARGUMENTS
+
+## 前置检查
+
+运行 `npx @alenfitz/spec-copilot gate <变更名> review`（跨平台门禁检查）
+
+**阶段一 Spec Compliance**（附录 A）：
+逐条验证 spec 功能点是否落地。PASS 后才进入阶段二。
+
+**阶段二 Code Quality**（附录 B）：
+按 Critical / Important / Minor 三级审查。
+加载 `spec_copilot/stack-adapters/<栈>.md` §10 栈相关检查项。
+
+完成后更新 spec.md §12 审查结论。
+
+## 结束后
+
+读取 spec.md §2 复杂度等级后输出：
+
+**通过（Critical=0）：**
+
+🟡 中等需求：
+```
+审查通过 ✓
+→ 下一步：/spec:archive <变更名>
+```
+
+🔴 复杂需求：
+```
+审查通过 ✓
+→ 下一步：/spec:test <变更名>
+（测试通过后 /spec:archive）
+```
+
+**需修复（Critical>0，所有等级）：**
+```
+审查未通过 ✗（<N> 个 Critical 问题）
+→ 下一步：/spec:fix <变更名> <问题描述>
+（修复后自动重新 /spec:review）
+```
+
+如参数含 --full，执行全量 review（扫描整个代码库）；否则仅扫描本次变更文件。

package/commands/spec:smoke.md

@@ -0,0 +1,40 @@
+---
+description: 冒烟验证（编译 + 核心接口测试）
+---
+
+请按 AGENTS.md 中定义的 /smoke 流程执行：
+
+**变更名**：$ARGUMENTS
+
+步骤：
+1. 编译/构建后端（命令见 `spec_copilot/rules/project-context.md` §8）
+2. 编译/构建前端（如有）
+3. 对 spec 中每个核心接口执行 curl 验证
+4. 如有前端页面，确认可渲染
+
+## 结束后
+
+1. **记录到 log.md**：在 `## 时间线` 表格尾部追加一行 `| 当前时间 | smoke | 冒烟测试通过 ✓ |`（失败则写 `| 当前时间 | smoke | 冒烟失败 ✗ <原因> |`）
+2. 读取 spec.md §2 复杂度等级后输出：
+
+**通过（编译 0 error + 核心接口返回正常）：**
+
+🟡 中等需求：
+```
+冒烟通过 ✓
+→ 下一步：/spec:review <变更名>
+```
+
+🔴 复杂需求：
+```
+冒烟通过 ✓
+→ 下一步：/spec:review <变更名>
+（审查通过后还需 /spec:test）
+```
+
+**失败（所有等级）：**
+```
+冒烟失败 ✗（<失败原因>）
+→ 下一步：/spec:fix <变更名> <问题描述>
+（修复后自动重新 /spec:smoke）
+```

package/commands/spec:test.md

@@ -0,0 +1,28 @@
+---
+description: 补充自动化测试
+---
+
+请按 AGENTS.md 中定义的 /test 流程执行：
+
+**变更名**：$ARGUMENTS
+
+## 前置检查
+
+运行 `npx @alenfitz/spec-copilot gate <变更名> test`（跨平台门禁检查）
+
+按 spec §8.5 测试策略生成测试用例，覆盖：
+- 正向路径（Happy Path）
+- 边界条件（空集合、最大值、临界时间）
+- 异常路径（非法参数、依赖服务失败）
+
+文件位置和命名遵循对应 stack adapter §8。
+生成后立即运行，全部通过后 commit：`[变更名] test: 补充自动化测试`
+
+## 结束后
+
+```
+测试已补充 ✓（<N> 个用例，全部通过）
+→ 下一步：/spec:archive <变更名>
+```
+
+> 注：/spec:test 是 🔴 复杂需求的必经阶段。🟡 中等需求可跳过直接 archive。