@chongyan/autospec 1.0.1

package/plugins/commands/propose.md

@@ -0,0 +1,93 @@
+---
+description: "就这么干，方案写下来" — 方案设计阶段。包含技术方案设计。
+---
+
+# AutoSpec Propose — 方案设计
+
+## 用户输入
+
+```
+$ARGUMENTS
+```
+
+---
+
+## 前置处理
+
+【前置】读取流程协议：
+> **【重要】执行本command前必须先读取流程协议**
+> 1. 读取 `knowledge/guides/support/pipeline-protocol.md` 中的「流程能力」章节
+> 2. 执行以下步骤：
+>    - 解析命令与参数
+>    - 加载必要文件
+>    - 检查前置条件（确认需求分析已完成）
+> 3. 完成后继续执行本命令的具体逻辑
+>
+> **【注意】日志追踪已启用**
+> - 执行日志会自动记录到 `.autospec/logs/execution-{date}.json`
+> - 关键步骤（skill加载、agent调用、产物生成、阶段完成）都会被追踪
+
+---
+
+## 执行指令
+
+### Step 1: 检查上游依赖
+
+- 确认需求分析已完成（检查 state.json）
+- 未完成 → 阻断并提示先执行 explore
+
+### Step 2: 组织上下文
+
+- 加载需求契约（requirements.md）
+- 加载角色profile中的关注点
+
+### Step 3: AI技能自动检测
+
+- 按需加载 evaluation-planner/rag-analyzer 等
+
+### Step 4: 技术方案设计
+
+**【强制】必须读取并按照 design-planner 执行**
+- 使用 Read 工具读取 `knowledge/guides/stages/design-planner.md`
+- 生成技术方案到 `.autospec/specs/{feature}/design.md`
+
+### Step 5: 双层验证
+
+**【强制】必须按顺序执行：**
+
+1. **【强制】执行 Layer1 验证**
+   - 设计文档完整性检查
+   - 验证失败 → 修复后重试
+
+2. **【强制】调用 Layer2 审查**
+   - 使用 Agent 工具，subagent_type=independent-reviewer
+   - 传入审查标准：`knowledge/guides/stages/design-reviewer.md`
+   - 传入被审查文档：`.autospec/specs/{feature}/design.md`
+   - 等待审查完成后再继续
+
+3. **【强制】审查结果处理**
+   - 审查通过 → 进入 Step 6
+   - 审查不通过 → 执行修复循环（见下方）
+
+#### 修复循环机制
+
+当 Layer2 审查返回"不通过"时：
+
+```
+循环直到审查通过（最多3次）：
+  1. 提取 reviewer 的"必须修复（blocking）"清单
+  2. 读取 design-planner.md 并执行修复
+  3. 重新执行 Layer1 验证
+  4. 重新调用 Layer2 审查
+  5. 达到3次上限仍不通过 → 记录问题，标记需要人工介入
+```
+
+### Step 6: 更新 state.json
+
+**【强制】更新状态**
+- 记录阶段完成状态
+- 记录关键决策
+
+---
+
+**继续执行**: `/autospec:apply`

package/plugins/commands/review.md

@@ -0,0 +1,140 @@
+---
+description: 审查各阶段交付物（需求/设计/代码/测试），评估产出质量
+---
+
+# AutoSpec Review — 独立审查
+
+## 用户输入
+
+```
+$ARGUMENTS
+```
+
+---
+
+## 执行指令
+
+### Step 1: 解析参数
+
+解析用户输入，提取：
+- 审查类型：`requirement` | `design` | `code` | `test`
+- 审查目标：文件或目录路径，或 git 仓库地址
+- 分支名称（可选）：--branch <name>
+- 输出位置（可选）：--output path
+
+**参数格式**：
+```
+[type] [target] [--branch <name>] [--output path]
+
+示例：
+- review code ./src/main.js
+- review design ./docs/design.md
+- review requirement ./specs/requirement.md
+- review test ./tests/
+- review code ./src/ --output ./my-review.md
+- review code https://github.com/user/repo  # git 仓库
+- review code https://github.com/user/repo --branch develop  # 指定分支
+```
+
+### Step 2: 处理目标路径
+
+**规则 1：处理 target 类型**
+
+1. **如果是 git URL**（以 http://、https://、git@ 开头）：
+   - 确定目标目录：`/tmp/autospec-review-{repo-name}-{branch}`
+   - 克隆仓库：
+     - 有分支指定：`git clone -b <branch> <url>`
+     - 无分支指定：`git clone --depth 1 <url>`
+   - 在克隆目录中查找审查目标
+
+2. **如果是本地目录或文件**：
+   - 直接使用指定路径
+
+**规则 3：如果 type 未指定**：
+1. 读取 `.autospec/runtime/state.json` 获取当前阶段
+2. 根据当前阶段自动推断审查类型：
+   - Stage 01（需求分析）→ requirement
+   - Stage 02（方案设计）→ design
+   - Stage 03/04（编码实施/代码审查）→ code
+   - Stage 05（QA测试）→ test
+3. 直接执行审查，无需人类确认
+
+**规则 4：如果 target 未指定**：
+1. 根据 type 从标准位置查找产出物：
+   - requirement → `.autospec/specs/{feature}/requirement.md`
+   - design → `.autospec/specs/{feature}/design.md`
+   - code → `./src/`（项目根目录）
+   - test → `./tests/` 或 `./test/`
+2. 扫描项目中最新的相关文件
+
+**规则 5：如果 output 未指定**：
+- 默认写入：`.autospec/reviews/review-{type}-{timestamp}.md`
+
+**规则 6：完全无参数时**：
+1. 读取 state.json 确定当前阶段
+2. 根据阶段自动推断 type 和 target
+3. 直接执行审查，无需人类确认
+
+### Step 3: 加载审查标准
+
+根据审查类型，加载对应 reviewer skill：
+
+| type | 审查标准文件 |
+|------|-------------|
+| requirement | `{{knowledge}}/skills/stages/requirement-reviewer.md` |
+| design | `{{knowledge}}/skills/stages/design-reviewer.md` |
+| code | `{{knowledge}}/skills/stages/code-reviewer.md` |
+| test | `{{knowledge}}/skills/stages/test-reviewer.md` |
+
+### Step 4: 执行审查
+
+**【强制】** 调用 Agent 工具：
+
+```
+使用 **independent-reviewer** Agent 执行独立审查：
+  prompt: |
+    请审查以下产出物。
+
+    1. 先读取审查标准: {审查标准文件路径}
+    2. 被审查目标: {审查目标路径}
+    3. 注意：你是独立审查者，只看产出物和标准，不参考生产过程
+
+    审查完成后，将审查报告写入：{输出路径}
+```
+
+### Step 5: 输出报告
+
+- 写入指定位置或默认位置 `.autospec/reviews/`
+- 终端输出审查结论摘要
+
+---
+
+## 输出格式
+
+```markdown
+## 审查结论：通过 / 不通过
+
+### 基本信息
+- 审查类型：{requirement/design/code/test}
+- 审查目标：{文件路径}
+- 审查时间：{ISO 8601}
+- 审查标准：{skill文件路径}
+
+### 逐项判定
+| 检查项 | 结论 | 证据 | 备注 |
+|--------|------|------|------|
+| ... | PASS/FAIL | {证据} | {建议} |
+
+### 必须修复（blocking）
+- ...
+
+### 建议改进（non-blocking）
+- ...
+```
+
+---
+
+## 相关命令
+
+- `/autospec:validate` — Layer 1 确定性验证
+- `/autospec:status` — 查看流程状态

package/plugins/commands/run.md

@@ -0,0 +1,224 @@
+---
+description: 启动或恢复AutoSpec自主研发流程。统一控制瀑布迭代/敏捷迭代/实验模式/热修复四种模式，无人值守执行。
+---
+
+# AutoSpec Run — 启动自主流程
+
+## 用户输入
+
+```
+$ARGUMENTS
+```
+
+---
+
+## 前置处理
+
+【前置】读取流程协议：
+> **【重要】执行本command前必须先读取流程协议**
+> 1. 读取 `knowledge/guides/support/pipeline-protocol.md` 中的「流程能力」章节
+> 2. 执行以下步骤：
+>    - 解析命令与参数
+>    - 加载必要文件
+>    - 检查前置条件
+> 3. 完成后继续执行本命令的具体逻辑
+>
+> **【注意】日志追踪已启用**
+> - 执行日志会自动记录到 `.autospec/logs/execution-{date}.json`
+> - 关键步骤（skill加载、agent调用、产物生成、阶段完成）都会被追踪
+> - 可通过读取日志文件分析执行情况
+
+---
+
+## 执行指令
+
+### Step 0: 任务输入处理
+
+**【强制执行】**：
+
+1. **检查用户输入**：
+   - 如果 `$ARGUMENTS` 非空 → 使用用户提供的任务描述
+   - 如果 `$ARGUMENTS` 为空 → 进入上下文检测
+
+2. **上下文检测**（仅当参数为空时）：
+   ```
+   a. 检查 .autospec/runtime/state.json 是否存在
+   b. 检查 .autospec/specs/ 目录是否有需求文档
+   c. 检查 state.json 中的 currentStage 字段
+   ```
+
+3. **根据检测结果决定执行策略**：
+
+   **情况A：有已完成的探索阶段**
+   - 读取 `.autospec/specs/{feature}/requirement.md`
+   - 读取 `.autospec/runtime/state.json` 获取上下文
+   - 基于已有上下文继续执行，无需重新输入
+
+   **情况B：有中断的流程**
+   - 读取 state.json 确定 currentStage
+   - 从中断点恢复执行
+
+   **情况C：全新启动（无历史上下文）**
+   - **必须**向用户询问任务描述
+   - 格式：
+     ```
+     🚀 AutoSpec 自主流程启动
+
+     请提供任务描述，例如：
+     - 实现用户登录功能
+     - 添加订单导出功能
+     - 修复支付流程的并发问题
+
+     💡 提示：可以先运行 /autospec:explore 进行需求探索，
+        探索结果将作为自主运行的上下文，执行更精准。
+     ```
+   - 等待用户输入后继续
+
+### Step 1: 初始化与迭代模式确认
+
+**【强制执行】**：初始化和迭代模式确认在探索阶段之前完成。
+
+1. **读取配置文件**：
+   - 读取 pipeline/overview.md 选择工作流模板
+   - 加载角色profile（roles/{角色}-profile.md）
+   - 检查宪法门禁（读取 constitution.md）
+
+2. **解析 workflow 参数**：
+   - 优先使用 `$ARGUMENTS` 中指定的 `--workflow=` 参数
+   - 有效值：waterfall, agile, experiment, hotfix
+
+3. **用户确认迭代模式**（未指定参数时）：
+   - **【重要】** 迭代模式确认必须在探索阶段之前完成
+   - 读取 `knowledge/process/overview.md` 了解各模式适用场景
+   - 使用 AskUserQuestion 工具向用户确认迭代模式：
+     ```
+     🚀 请选择迭代模式：
+
+     1. waterfall（瀑布模式）- 完整流程，适合新功能开发
+     2. agile（敏捷模式）- 循环迭代，适合用户故事驱动
+     3. experiment（实验模式）- 原型验证，适合技术探索/AI
+     4. hotfix（热修复）- 快速通道，适合紧急修复
+     ```
+   - 等待用户选择后继续
+
+4. **记录到 state.json**：
+   - 记录选择的迭代模式
+   - 初始化关键假设追踪表
+
+### Step 2: 探索阶段 - 团队对齐与需求澄清
+
+**【强制执行】**：此阶段必须与人类进行深入交互，完成需求澄清后才能继续。
+
+**【重要】** 即使有详细的需求文档，也必须执行多Agent对抗分析和多轮澄清！需求文档是重要输入材料，澄清时要基于文档内容深入探讨，不能忽略文档中的信息。
+
+**【复用】** 读取 `plugins/skills/exploration-phase/SKILL.md` 并执行探索阶段逻辑：
+
+1. 复杂度评估 → 确定探索轮次上限（简单2-3轮，中等3-4轮，复杂5-6轮）
+2. 检查是否已有澄清记录（clarifications.md）
+3. **【强制】【不可跳过】** 使用 Agent 工具启动 2-3 个独立 Agent 进行对抗分析：
+   - Agent A - 乐观视角：支持理由、预期价值
+   - Agent B - 质疑视角：潜在问题、风险、伪需求可能性
+   - Agent C - 技术视角：技术可行性、实现难点
+4. **【强制】【不可跳过】** 使用 AskUserQuestion 工具进行多轮澄清：
+   - 每轮最多5个问题
+   - 每个问题附AI推荐答案
+   - 支持用户提前终止（说「足够」「清楚了」）
+   - **必须至少执行一轮澄清**
+5. 用户确认「足够」或达到轮次上限 → 探索完成
+6. 生成 requirement.md 并通过 Layer1/Layer2 验证
+
+**【禁止跳过】** 以下情况必须暂停并使用 AskUserQuestion 向用户确认：
+- 需求有歧义
+- 技术方案有多种选择
+- 涉及安全/性能/成本等关键决策
+- **即使需求文档很详细，也必须执行至少一轮澄清**
+- 用户说「足够」前不得跳过澄清环节
+
+**【自动执行】** 探索阶段完成后，自动进入后续阶段，无需人工确认。后续流程全自动执行，仅在以下情况暂停：
+- 安全制动触发（DP10）
+- 3次修复循环失败
+- 宪法门禁违反
+
+### Step 3: 阶段执行序列（全自动）
+
+**【强制执行】**：每个阶段执行「做→审→修复」循环，直到通过审查。
+
+**【自动执行】**：探索阶段完成后，按顺序自动执行以下阶段，无需人工确认。每个阶段完成后立即进入下一阶段：
+
+- **阶段1：需求探索** → 已在 Step 2 完成
+- **阶段2：方案设计** → Read design-planner.md → Read design-reviewer.md → 审查通过后自动进入下一阶段
+- **阶段3：编码实施** → Read code-implementer.md → Read code-reviewer.md → 审查通过后自动进入下一阶段
+- **阶段4：QA测试** → Read test-generator.md → Read test-reviewer.md + Agent测试执行（单元测试→集成测试→效果评测）→ 审查通过后自动进入下一阶段
+- **阶段5：交付归档** → Read release-checker.md
+
+### Step 4: 阶段执行循环（核心质量保障）
+
+**【强制执行】**：每个阶段必须通过「做→Layer1验证→Layer2审查→修复（如需）」循环。
+
+#### 4.1 阶段内执行循环
+
+```
+循环直到 reviewer 审查通过（最多3次）：
+
+  1. 【做】读取对应的 implementer/analyzer 文件并执行
+     → 生成阶段产出物
+
+  2. 【Layer1 验证】确定性验证
+     → 编译/测试/lint/类型检查
+     → 验证失败 → 修复后重试（内联重试）
+
+  3. 【Layer2 审查】使用 Agent 工具进行审查，传入审查标准文件路径
+     → 审查产出物质量
+
+  4. 【判定】
+     → 审查通过 → 进入下一阶段
+     → 审查不通过 → 执行修复循环
+```
+
+#### 4.2 修复循环（精准回退 DP6）
+
+当 reviewer 返回"不通过"时：
+
+```
+Level 1 - 内联重试（单次）：
+  - 如果是简单的格式/遗漏问题，reviewer 顺便修复
+  - 重新审查
+
+Level 2 - 修正循环（最多3次）：
+  - 提取 reviewer 的"必须修复（blocking）"清单
+  - 读取对应的 implementer 文件并执行修复
+  - 重新执行 Layer1 验证
+  - 重新调用 reviewer 审查
+  - 循环直到通过或达到3次上限
+
+Level 3 - 升级人工（3次后）：
+  - 记录无法自动解决的问题
+  - 标记需要人工介入
+  - 继续执行其他阶段（不阻塞流程）
+```
+
+#### 4.3 审查结果处理
+
+**【自动执行】** 审查通过后立即进入下一阶段，无需等待用户确认。
+
+reviewer 审查结果处理规则：
+
+| 审查结论 | 处理方式 |
+|---------|---------|
+| 通过 | **立即进入下一阶段**（不暂停、不询问） |
+| 不通过（有blocking项） | 触发修复循环 |
+| 不通过（超过3次） | 升级人工标记，继续下一阶段 |
+| 建议改进（non-blocking） | 记录但不阻塞，可后续优化 |
+
+### Step 5: 收尾
+
+全流程完成后：
+1. 汇总各阶段产出和关键假设最终状态
+2. 输出执行日志（含度量数据：回退次数、人工介入次数、各阶段耗时）
+3. 触发 skill-distiller 检查可沉淀的skills
+4. 触发 methodology-extractor 检查可沉淀的方法论
+5. 记录到 practice-log
+
+---
+
+**继续执行**: `/autospec:explore` 或 `/autospec:propose`

package/plugins/commands/status.md

@@ -0,0 +1,62 @@
+---
+description: 查看当前AutoSpec流程的执行状态
+---
+
+# AutoSpec Status — 状态查看
+
+## 用户输入
+
+```
+$ARGUMENTS
+```
+
+---
+
+## 执行指令
+
+### Step 1: 读取状态
+
+- 读取 state.json
+- 读取 metrics.json
+
+### Step 2: 展示状态
+
+- **单系统模式**：展示当前阶段、验证结果、假设追踪
+- **多系统模式**：展示各子系统状态表、效果指标
+
+### Step 3: 提供恢复建议
+
+- 根据当前状态给出下一步建议
+
+---
+
+## 输出格式
+
+```markdown
+## AutoSpec 状态
+
+### 基本信息
+- 任务: {taskName}
+- 工作流: {workflow}
+- 当前阶段: {currentStage}
+- 执行模式: {executionMode}
+
+### 阶段进度
+| 阶段 | 状态 | Layer1 | Layer2 |
+|-----|------|--------|--------|
+| 01-需求分析 | ✅ 完成 | ✅ | ✅ |
+| 02-方案设计 | 🔄 进行中 | ⏳ | - |
+| ... | ... | ... | ... |
+
+### 质量指标
+- Layer1 通过率: {layer1PassRate}%
+- Layer2 通过率: {layer2PassRate}%
+- 人工介入次数: {humanInterventions}
+
+### 下一步建议
+{nextSteps}
+```
+
+## 相关命令
+
+- `/evaluate` — 生成完整评测报告

package/plugins/commands/validate.md

@@ -0,0 +1,108 @@
+---
+description: 运行AutoSpec Layer 1确定性验证（编译/测试/lint），支持本地目录和git仓库
+---
+
+# AutoSpec Validate — Layer 1验证
+
+## 用户输入
+
+```
+$ARGUMENTS
+```
+
+---
+
+## 执行指令
+
+### Step 1: 解析参数
+
+解析用户输入，提取：
+- 目标路径：本地目录或 git 仓库地址
+- 分支名称（git 仓库时）：--branch <name>
+- 验证类型（可选）：--build | --test | --lint
+- 输出路径（可选）：--output <path>
+
+**参数格式**：
+```
+[target] [--branch <name>] [--build|--test|--lint] [--output path]
+
+示例：
+- validate                           # 当前项目
+- validate ./my-project             # 本地目录
+- validate https://github.com/user/repo  # git 仓库
+- validate https://github.com/user/repo --branch main  # 指定分支
+- validate ./src --test            # 只运行测试
+- validate ./src --output ./report.md  # 指定输出
+```
+
+### Step 2: 处理目标路径
+
+**规则 1：如果 target 未指定**
+- 默认使用当前项目目录（`.`）
+
+**规则 2：如果 target 是本地目录**
+- 直接在指定目录执行验证
+
+**规则 3：如果 target 是 git URL**
+1. 判断是否为 git 仓库（以 http://、https://、git@ 开头）
+2. 确定目标目录：
+   - 有分支指定：`/tmp/autospec-validate-{repo-name}-{branch}`
+   - 无分支指定：`/tmp/autospec-validate-{repo-name}-{default-branch}`
+3. 执行克隆：
+   - 使用 `git clone --depth 1` 减少克隆时间
+   - 指定分支：`git clone -b <branch>`
+4. 在克隆目录执行验证
+
+### Step 3: 确定验证模式
+
+**规则 4：如果未指定验证类型**
+- 默认执行全部：build + test + lint
+
+**规则 5：如果指定验证类型**
+- `--build`：只执行编译检查
+- `--test`：只执行测试
+- `--lint`：只执行 Lint 检查
+
+### Step 4: 执行Layer1验证
+
+根据 config.json 判断单系统/多系统，执行：
+- 编译检查
+- 测试执行
+- Lint检查
+- 类型检查（如适用）
+
+### Step 5: 输出验证报告
+
+- 默认写入：`.autospec/validation/validation-{timestamp}.md`
+- 或用户指定的输出路径
+- 每项结果附带执行日志
+
+---
+
+## 输出格式
+
+```markdown
+## 验证结论：通过 / 部分通过 / 失败
+
+### 验证目标
+- 目标路径：{本地目录/git URL}
+- 分支：{branch}（如适用）
+- 验证类型：{build/test/lint/all}
+
+### 验证结果
+| 验证项 | 状态 | 执行命令 | 结果 |
+|--------|------|---------|------|
+| 编译 | ✅ PASS | npm run build | ... |
+| 测试 | ❌ FAIL | npm test | 3 failed |
+| Lint | ✅ PASS | eslint . | 0 errors |
+
+### 执行日志
+{详细日志}
+```
+
+---
+
+## 相关命令
+
+- `/autospec:review` — Layer 2 独立审查
+- `/autospec:status` — 查看流程状态

package/plugins/hooks/README.en.md

@@ -0,0 +1,56 @@
+# Hooks Scripts Directory
+
+This directory contains all Claude Code hooks scripts, which are copied to `.autospec/plugins/hooks/` during the init process.
+
+## Directory Structure
+
+```
+hooks/
+├── trace-initialization.js        # Trace ID initialization
+├── frozen-zone-guard.js           # Frozen zone protection
+├── scope-sentinel.js              # Scope drift prevention
+├── constitution-guard.js          # Constitution gate
+├── layer1-validator.js            # Layer 1 validation
+├── environment-manager.js         # Environment management
+├── ai-project-guard.js            # AI project security
+├── execution-tracker.js           # Execution tracking
+├── artifact-evaluation-hook.js    # Artifact evaluation
+├── pipeline-observer.js           # Pipeline observation
+├── lib/                           # Utility library
+│   ├── source-code-scanner.js
+│   ├── detection-pattern-loader.js
+│   ├── validation-patterns.js
+│   ├── hook-logger.js
+│   ├── hook-state-manager.js
+│   ├── trace-context.js
+│   ├── rollback-tracker.js
+│   ├── artifact-evaluator.js
+│   ├── execution-path.js
+│   └── metrics-analyzer.js
+└── README.md                      # This file
+```
+
+## Hook Trigger Timing
+
+| Hook | PreToolUse | PostToolUse | Stop |
+|------|------------|-------------|------|
+| trace-initialization | ✅ | | |
+| frozen-zone-guard | ✅ | | |
+| scope-sentinel | ✅ | | |
+| constitution-guard | ✅ | | |
+| layer1-validator | ✅ | ✅ | |
+| environment-manager | ✅ | | ✅ |
+| ai-project-guard | ✅ | ✅ | |
+| execution-tracker | | ✅ | |
+| artifact-evaluation-hook | | ✅ | |
+| pipeline-observer | | ✅ | ✅ |
+
+## Self-Contained Requirements
+
+Scripts in this directory must be self-contained, meeting the following requirements:
+
+1. **Only depend on Node.js built-in modules** (fs, path, etc.)
+2. **Only depend on `./lib/` local utility library**
+3. **Do not depend on any scaffolding code**
+
+This ensures they can run independently after being copied to `.autospec/plugins/hooks/`.