artifact-chain-assistant 0.8.0

package/adapters/claude/templates/README.md

@@ -0,0 +1,159 @@
+# Artifact Chain Assistant 模板目录
+
+本目录提供 `artifact-chain-assistant` 插件的 starter 模板，为目标项目提供制品结构的入门指导。
+
+## 权威层级
+
+**关键原则：插件模板是入门指导，项目本地模板是权威。**
+
+| 层级 | 权威范围 | 对模板的职责 |
+|------|---------|-------------|
+| **插件（本目录）** | 通用助手指导 | 提供 starter 模板和通用审查清单。**模板是指导，不是权威。** |
+| **目标项目** | 最终工作法 | 维护项目本地模板，覆盖或补充插件建议。**项目本地模板是权威。** |
+
+当项目需要不同的章节结构、审查标准或命名规则时，项目本地模板覆盖插件模板。项目本地审查技能覆盖插件通用审查规则。
+
+## 目录结构
+
+```
+templates/
+├── core/                          # 核心制品模板
+│   ├── feature/                   # 功能特性
+│   │   ├── starter.md             # 起草指引模板
+│   │   └── review-checklist.md    # 通用审查清单
+│   ├── scenario/                  # 场景
+│   ├── decision/                  # 决策
+│   ├── design/                    # 设计文档
+│   ├── test/                      # 测试
+│   └── e2e_test/                  # 端到端测试
+│
+├── extended/                      # 扩展制品模板（按类别组织）
+│   ├── contracts/                 # 契约类制品
+│   │   ├── api_contract/          # API 契约
+│   │   ├── cli_contract/          # CLI 契约
+│   │   └── data_contract/         # 数据契约
+│   ├── domain/                    # 领域与数据制品
+│   │   └── domain_model/          # 领域模型
+│   ├── ops/                       # 部署与运维制品
+│   │   ├── runbook/               # 运维手册
+│   │   └── deployment_manifest/   # 部署清单
+│   └── agent/                     # Agent 与 Hook 制品
+│       ├── agent_skill/           # Agent 技能
+│       └── hook_policy/           # Hook 策略
+│
+├── git-hooks/                     # Git hook 脚本模板
+├── claude/                        # Claude Code 适配器模板
+└── codex/                         # Codex 适配器模板
+```
+
+## 模板使用方式
+
+### Bootstrap 阶段
+
+1. `artifact-chain-bootstrap` 技能根据项目形态选择最小可用 profile
+2. bootstrap 技能引用本目录的 starter 模板生成初始制品结构
+3. 在 `artifacts/README.md` 中记录模板来源
+
+### 采用阶段
+
+1. 项目团队审阅 starter 模板
+2. 决定哪些章节保留、哪些修改、哪些删除
+3. 修改后的模板成为项目本地权威
+
+### 成熟阶段
+
+1. 项目可能在本地维护完整的模板库
+2. 完全不再引用插件 starter
+3. 插件 starter 仅在新成员加入或新类型启用时被参考
+
+## 模板内容说明
+
+### starter.md
+
+每个类型的 `starter.md` 包含：
+- 制品 frontmatter 结构
+- 最小填写指引
+- 关键章节说明
+- 关联制品示例
+
+**使用建议**：
+- 复制到项目本地后修改
+- 根据项目需求调整章节
+- 删除不适用的章节
+- 添加项目特定的章节
+
+### review-checklist.md
+
+每个类型的 `review-checklist.md` 包含：
+- 结构完整性检查
+- 内容质量检查
+- 追溯性检查
+- 生命周期检查
+
+**使用建议**：
+- 作为审查基线参考
+- 根据项目标准调整检查项
+- 添加项目特定的检查项
+- 在审查技能中引用
+
+## 扩展制品类型说明
+
+### 契约类制品
+
+记录系统边界的接口约定。当需求从功能和场景流入实现时，契约是上下文组装的关键上游。
+
+- **api_contract**：REST/GraphQL/gRPC API 接口契约
+- **cli_contract**：命令行工具接口契约
+- **data_contract**：数据模型和数据质量契约
+
+### 领域与数据制品
+
+捕捉业务概念和技术数据模型。是企业 Java 和 DDD 项目的核心制品。
+
+- **domain_model**：聚合、实体、值对象、领域事件
+
+### 部署与运维制品
+
+覆盖生产环境的变更、安全、性能和操作流程。仅当项目有对应运维流程时启用。
+
+- **runbook**：运维操作手册
+- **deployment_manifest**：部署配置清单
+
+### Agent 与 Hook 制品
+
+覆盖 AI 辅助工作流和 CI/CD 门禁。仅当项目有对应文件或流程时启用。
+
+- **agent_skill**：Agent 技能定义
+- **hook_policy**：Hook 策略和门禁规则
+
+## Bootstrap 裁剪策略
+
+bootstrap 的职责是根据项目形态选择**最小可用 profile**，而非启用所有已知类型。
+
+裁剪规则：
+
+1. **基础集合始终启用**：`feature`、`scenario`、`decision`、`design`、`test`、`e2e_test`
+2. **契约类按证据加入**：仅当项目本地存在对应的接口文件时启用
+3. **领域与数据类按项目形态加入**：企业 Java/DDD 项目可启用 `domain_model`
+4. **运维类按运维流程加入**：仅有部署配置文件或运维手册的项目才启用对应类型
+5. **Agent/Hook 类按本地文件加入**：仅当项目存在 `skills/`、`policies/` 或 hook 配置文件时启用
+6. **渐进扩展**：项目随成熟度增长，可按需添加新类型
+
+## 扩展制品目录设计
+
+本目录的模板结构遵循扩展制品目录规范：
+
+- 模板按类别组织（contracts、domain、ops、agent），每类含 starter 模板和审查清单
+- 模板来源遵循权威层级：插件模板是入门指导，项目本地模板是权威
+- Bootstrap 按项目形态裁剪，仅启用有本地证据的类型
+- 模板生命周期：starter → 项目采用定制 → 本地权威
+
+详细的类型目录、推荐路径、ID 模式和生命周期规则，请参考
+[扩展制品目录](../EXTENDED-ARTIFACT-CATALOG.md)。
+
+## 相关文档
+
+- [扩展制品目录](../EXTENDED-ARTIFACT-CATALOG.md) - 类型分类、路径/ID 模式、生命周期规则
+- [ADOPTION-GUIDE](extended/ADOPTION-GUIDE.md) - 模板采用与升级评审指南
+- [INSTALL.md](../INSTALL.md) - 插件安装指南
+- [artifact-chain-bootstrap 技能](../skills/artifact-chain-bootstrap/SKILL.md) - Bootstrap 技能文档

package/adapters/claude/templates/core/decision/review-checklist.md

@@ -0,0 +1,35 @@
+# Decision 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] `id` 字段存在且符合项目 ID 模式（如 `D-{PREFIX}-{nn}`）
+- [ ] `title` 字段存在且清晰表达决策主题
+- [ ] `status` 字段存在且为有效值（proposed/accepted/deprecated/superseded）
+- [ ] `date` 字段记录决策日期
+
+## 决策质量
+
+- [ ] 背景清晰描述问题域
+- [ ] 至少考虑 2 个选项
+- [ ] 每个选项有优缺点分析
+- [ ] 决策理由与驱动因素一致
+
+## 追溯性
+
+- [ ] 关联相关功能特性或设计文档
+- [ ] 决策影响范围已识别
+- [ ] 相关方已通知或参与
+
+## 可验证性
+
+- [ ] 影响分析包含正面和负面
+- [ ] 验证方法可执行
+- [ ] 决策可追溯到实际实现
+
+## 生命周期
+
+- [ ] proposed 状态应有决策期限
+- [ ] accepted 状态应有实现计划
+- [ ] deprecated/superseded 应记录替代决策 ID

package/adapters/claude/templates/core/decision/starter.md

@@ -0,0 +1,66 @@
+---
+id: {DECISION_ID}
+title: {标题}
+status: proposed
+date: {YYYY-MM-DD}
+decision_makers: []
+related_features: []
+---
+
+# {DECISION_ID}: {标题}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+
+## 背景
+
+{描述需要做出决策的背景、问题或机遇}
+
+## 决策驱动因素
+
+{列出影响决策的关键因素}
+
+1. {驱动因素 1}
+2. {驱动因素 2}
+3. {驱动因素 3}
+
+## 考虑的选项
+
+### 选项 1：{选项名称}
+
+**描述**：{选项描述}
+
+**优点**：
+- {优点 1}
+- {优点 2}
+
+**缺点**：
+- {缺点 1}
+- {缺点 2}
+
+### 选项 2：{选项名称}
+
+**描述**：{选项描述}
+
+**优点**：
+- {优点 1}
+
+**缺点**：
+- {缺点 1}
+
+## 决策
+
+{选择的选项及理由}
+
+## 影响
+
+{决策带来的正面和负面影响}
+
+## 验证
+
+{如何验证这个决策是否正确}
+
+## 变更日志
+
+| 日期 | 状态变更 | 原因 |
+|------|---------|------|
+| {YYYY-MM-DD} | proposed | 初始提议 |

package/adapters/claude/templates/core/design/review-checklist.md

@@ -0,0 +1,41 @@
+# Design 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] 标题清晰表达设计范围
+- [ ] 概述包含目标、范围和约束
+- [ ] 至少包含架构视图和详细设计
+- [ ] 关联制品字段完整
+
+## 设计质量
+
+- [ ] 设计目标具体可验证
+- [ ] 组件职责单一明确
+- [ ] 接口定义完整（输入/输出/错误）
+- [ ] 数据流清晰可追溯
+
+## 非功能需求
+
+- [ ] 性能要求已识别
+- [ ] 安全考虑已记录
+- [ ] 可扩展性已设计
+
+## 风险管理
+
+- [ ] 风险已识别和评估
+- [ ] 缓解措施具体可行
+- [ ] 风险负责人已指定
+
+## 追溯性
+
+- [ ] 关联功能特性存在
+- [ ] 关联决策已做出
+- [ ] 设计可追溯到需求
+
+## 可实现性
+
+- [ ] 设计可在当前技术栈实现
+- [ ] 工作量估算合理
+- [ ] 依赖项已识别

package/adapters/claude/templates/core/design/starter.md

@@ -0,0 +1,84 @@
+---
+title: {设计文档标题}
+related_features: []
+related_decisions: []
+related_scenarios: []
+---
+
+# {设计文档标题}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+
+## 概述
+
+{用一段话描述设计目标、范围和主要约束}
+
+## 设计目标
+
+1. {设计目标 1}
+2. {设计目标 2}
+3. {设计目标 3}
+
+## 架构视图
+
+### 组件图
+
+{描述主要组件及其关系}
+
+### 数据流
+
+{描述关键数据流或处理流程}
+
+### 接口设计
+
+{列出主要接口及其契约}
+
+## 详细设计
+
+### 模块 1：{模块名称}
+
+**职责**：{模块职责}
+
+**接口**：
+- {接口 1}
+- {接口 2}
+
+**实现要点**：
+- {实现要点 1}
+- {实现要点 2}
+
+### 模块 2：{模块名称}
+
+{同上结构}
+
+## 非功能需求
+
+### 性能
+
+{性能要求和约束}
+
+### 安全
+
+{安全考虑}
+
+### 可扩展性
+
+{可扩展性设计}
+
+## 风险与缓解
+
+| 风险 | 影响 | 概率 | 缓解措施 |
+|------|------|------|---------|
+| {风险 1} | {影响} | {概率} | {措施} |
+
+## 关联制品
+
+- 功能特性：{related_features}
+- 决策：{related_decisions}
+- 场景：{related_scenarios}
+
+## 变更日志
+
+| 日期 | 变更 | 作者 |
+|------|------|------|
+| {YYYY-MM-DD} | 初始草稿 | {作者} |

package/adapters/claude/templates/core/e2e_test/review-checklist.md

@@ -0,0 +1,43 @@
+# E2E Test 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] `id` 字段存在且符合项目 ID 模式
+- [ ] `title` 清晰描述测试的端到端流程
+- [ ] `status` 字段存在且为有效值
+- [ ] 测试场景覆盖主流程
+
+## 测试质量
+
+- [ ] 前置条件具体可准备
+- [ ] 测试步骤可执行
+- [ ] 预期结果可验证
+- [ ] 覆盖关键用户流程
+
+## 覆盖范围
+
+- [ ] 主场景完整覆盖
+- [ ] 关键备选场景已覆盖
+- [ ] 错误路径已测试
+- [ ] 边界条件已考虑
+
+## 追溯性
+
+- [ ] 关联功能特性存在
+- [ ] 关联场景存在
+- [ ] 测试可追溯到用户需求
+
+## 可执行性
+
+- [ ] 测试环境要求明确
+- [ ] 测试数据可准备
+- [ ] 测试可自动化或手动执行
+- [ ] 测试结果可重现
+
+## 维护性
+
+- [ ] 测试易于理解
+- [ ] 测试数据与实现解耦
+- [ ] 测试可适应 UI/API 变更

package/adapters/claude/templates/core/e2e_test/starter.md

@@ -0,0 +1,70 @@
+---
+id: {E2E_TEST_ID}
+title: {标题}
+status: draft
+related_features: []
+related_scenarios: []
+---
+
+# {E2E_TEST_ID}: {标题}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+
+## 测试目标
+
+{描述这个端到端测试要验证的完整用户流程}
+
+## 测试场景
+
+### 主场景：{场景名称}
+
+**前置条件**：
+- {条件 1}
+- {条件 2}
+
+**测试步骤**：
+1. {步骤 1}
+2. {步骤 2}
+3. {步骤 3}
+
+**预期结果**：
+- {结果 1}
+- {结果 2}
+
+### 备选场景：{场景名称}
+
+{同上结构}
+
+## 测试数据
+
+{描述测试所需的数据准备}
+
+## 环境要求
+
+{列出测试环境的特殊要求}
+
+## 自动化脚本
+
+{如果适用，关联自动化测试脚本路径}
+
+```typescript
+// 示例：Playwright E2E 测试
+import { test, expect } from '@playwright/test';
+
+test('{测试名称}', async ({ page }) => {
+  await page.goto('{URL}');
+  await page.click('{选择器}');
+  await expect(page.locator('{选择器}')).toHaveText('{预期文本}');
+});
+```
+
+## 关联制品
+
+- 功能特性：{related_features}
+- 场景：{related_scenarios}
+
+## 变更日志
+
+| 日期 | 变更 | 作者 |
+|------|------|------|
+| {YYYY-MM-DD} | 初始草稿 | {作者} |

package/adapters/claude/templates/core/feature/review-checklist.md

@@ -0,0 +1,29 @@
+# Feature 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] `id` 字段存在且符合项目 ID 模式（如 `ACA{nn}`）
+- [ ] `title` 字段存在且简洁明确
+- [ ] `status` 字段存在且为有效值（draft/active/done/deprecated）
+- [ ] 验收标准至少 3 条，每条可独立验证
+
+## 内容质量
+
+- [ ] 概述清晰描述问题域和解决目标
+- [ ] 验收标准使用可测试的表述（避免"应该"、"可能"）
+- [ ] 关联的场景 ID 存在且有效
+- [ ] 设计约束已识别并记录
+
+## 追溯性
+
+- [ ] 至少关联一个场景或设计文档
+- [ ] 关联的制品 ID 在图中可查
+- [ ] 验收标准可追溯到场景测试
+
+## 生命周期
+
+- [ ] 草稿状态的 feature 可以缺少部分关联
+- [ ] active 状态的 feature 必须有完整关联
+- [ ] done/deprecated 状态的 feature 应记录完成原因

package/adapters/claude/templates/core/feature/starter.md

@@ -0,0 +1,43 @@
+---
+id: {FEATURE_ID}
+title: {标题}
+status: draft
+scenarios: []
+design_docs: []
+---
+
+# {FEATURE_ID}: {标题}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+
+## 概述
+
+{用一两句话描述这个功能特性要解决的核心问题}
+
+## 验收标准
+
+{列出可验证的验收标准，每条标准应可独立测试}
+
+1. {验收标准 1}
+2. {验收标准 2}
+3. {验收标准 3}
+
+## 用户场景
+
+{关联的场景 ID，或在此描述主要用户场景}
+
+## 设计约束
+
+{列出已知的技术、业务或时间约束}
+
+## 关联制品
+
+- 设计文档：{design_docs}
+- 场景：{scenarios}
+- 决策：{related_decisions}
+
+## 变更日志
+
+| 日期 | 变更 | 作者 |
+|------|------|------|
+| {YYYY-MM-DD} | 初始草稿 | {作者} |

package/adapters/claude/templates/core/scenario/review-checklist.md

@@ -0,0 +1,29 @@
+# Scenario 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] `id` 字段存在且符合项目 ID 模式（如 `S-{nn}`）
+- [ ] `title` 字段存在且描述场景本质
+- [ ] `status` 字段存在且为有效值
+- [ ] 角色与目标清晰定义
+
+## 流程质量
+
+- [ ] 主流程使用 Given/When/Then 格式
+- [ ] 至少覆盖一个备选流程
+- [ ] 前置条件可验证
+- [ ] 系统响应具体可测试
+
+## 追溯性
+
+- [ ] 关联至少一个功能特性
+- [ ] 关联的功能特性 ID 存在
+- [ ] 场景可追溯到功能需求
+
+## 可执行性
+
+- [ ] 场景可以手动或自动执行
+- [ ] 验收标准与流程步骤一致
+- [ ] 备选流程覆盖关键异常路径

package/adapters/claude/templates/core/scenario/starter.md

@@ -0,0 +1,57 @@
+---
+id: {SCENARIO_ID}
+title: {标题}
+status: draft
+related_features: []
+---
+
+# {SCENARIO_ID}: {标题}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+
+## 角色与目标
+
+**角色**：{用户角色}
+**目标**：{用户要完成的任务}
+
+## 前置条件
+
+{列出执行此场景前必须满足的条件}
+
+## 主流程
+
+```gherkin
+Given {前置状态}
+When {用户操作}
+Then {系统响应}
+```
+
+## 备选流程
+
+### 备选 1：{备选流程名称}
+
+```gherkin
+Given {前置状态}
+When {异常操作}
+Then {错误处理或备选路径}
+```
+
+## 验收标准
+
+1. {场景验收标准 1}
+2. {场景验收标准 2}
+
+## 关联制品
+
+- 功能特性：{related_features}
+- 设计文档：{related_designs}
+
+## 测试脚本
+
+{如果适用，关联自动化测试脚本路径}
+
+## 变更日志
+
+| 日期 | 变更 | 作者 |
+|------|------|------|
+| {YYYY-MM-DD} | 初始草稿 | {作者} |

package/adapters/claude/templates/core/test/review-checklist.md

@@ -0,0 +1,37 @@
+# Test 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 测试结构
+
+- [ ] 测试文件组织清晰（按模块或功能）
+- [ ] 测试命名描述预期行为
+- [ ] 使用 Arrange-Act-Assert 或 Given-When-Then 模式
+- [ ] 测试独立，不依赖执行顺序
+
+## 覆盖质量
+
+- [ ] 正常路径已覆盖
+- [ ] 边界条件已测试
+- [ ] 异常路径已覆盖
+- [ ] 关键业务逻辑测试充分
+
+## 代码质量
+
+- [ ] 测试代码可读性好
+- [ ] 避免测试实现细节
+- [ ] Mock 使用合理，不过度 mock
+- [ ] 断言明确具体
+
+## 追溯性
+
+- [ ] 测试关联功能特性（通过追溯注释）
+- [ ] 测试覆盖验收标准
+- [ ] 测试可追溯到需求
+
+## 可维护性
+
+- [ ] 测试易于理解和修改
+- [ ] 测试数据构造清晰
+- [ ] 测试环境隔离
+- [ ] 测试执行稳定（无随机失败）