artifact-chain-assistant 0.8.0 → 0.8.2

package/adapters/claude/skills/help/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: help
+description: 展示 artifact-chain-assistant 插件的标准 Family API、bundled legacy 方法和安装后采用步骤。安装后即使专业 family 实现未安装，用户也能看见标准能力。
+---
+
+# help
+
+## 目的
+
+轻量展示 artifact-chain 生态的可用标准能力，帮助用户了解安装后可以使用哪些技能族和服务。本技能只做安全渲染，不做项目生命周期判断。
+
+## 职责边界
+
+- **渲染静态 Family API Catalog**：从 `family-apis/catalog.json` 读取标准 family 和 service 定义，即使实现未安装也可见。
+- **展示 bundled legacy 方法**：从 `families-src/*/implementation.yaml` 读取已有的 bundled family 迁移样本，诚实标记 `targetApiStatus: pending`。
+- **动态 projection 当前 fail-closed**：Registry v2 verifier 尚未接入时，无论是否提供 projection 都只显示 `NOT_AVAILABLE / REGISTRY_V2_REQUIRED`。
+- **不读取第三方 `SKILL.md`**：不解析项目 sources/bindings，不自行计算 provider 状态。
+- **不猜测安装/启用/信任状态**：没有 projection 时不输出 `NOT_INSTALLED` 或 `ENABLED`。
+
+## 渲染内容
+
+### 1. Standard Family API
+
+从 Family API Catalog 渲染所有已发布的标准 family：
+
+```
+## Standard Family API
+
+| Family | Major | Services | Summary |
+|--------|-------|----------|---------|
+| artifact.e2e-test-family | 1 | default, help, author, review, repair | E2E Test Skill Family |
+
+### artifact.e2e-test-family@1
+
+Standard skill family for authoring, reviewing, and repairing E2E test specification artifacts.
+
+**Services:**
+- `default` (required, workflow) — Default route entry
+- `help` (required, operation) — Help and capability overview
+- `author` (required, workflow) — Author E2E test specs from feature/scenario artifacts
+- `review` (required, operation) — Review E2E test specifications
+- `repair` (required, workflow) — Repair E2E test specs based on review findings
+
+**Artifact Contracts:** artifact.e2e-test@1；feature/scenario 输入仍以版本化 protocol ref 表达
+**Side-effect ceiling:** write-authorized-artifacts (author/repair), write-review-result (review)
+**Mix-safe:** No (default whole-family atomic binding)
+```
+
+### 2. Bundled Legacy Methods
+
+从 `families-src/*/implementation.yaml` 渲染现有 bundled family：
+
+```
+## Bundled Legacy Methods
+
+These bundled families predate the standard Family API system.
+They are recorded as migration samples and will be migrated to formal Family API conformance.
+
+### prd-feature (bundled-stable)
+- Status: targetApiStatus: pending (no published Family API)
+- Services: default, author, review, repair
+- Note: Does NOT claim Family API conformance
+
+### scenario-script (bundled-stable)
+- Status: targetApiStatus: pending (no published Family API)
+- Services: default, author, review, repair
+- Note: Does NOT claim Family API conformance
+```
+
+### 3. Installation Status
+
+```
+## Installation Status
+
+Registry projection: NOT_AVAILABLE (REGISTRY_V2_REQUIRED)
+(Dynamic state is unavailable until the authoritative Registry v2 verifier is integrated.)
+```
+
+即使 projection 文件自称已校验，也不得由 assistant 直接渲染。后续只能消费 Registry v2 verifier 的权威结果。
+
+## 采用步骤
+
+```
+## Getting Started
+
+1. **Learn**: Review the Standard Family API above to understand available capabilities.
+2. **Bootstrap**: Run `artifact-chain-bootstrap` (with user authorization) to set up your project.
+3. **Orient**: Run `where-am-i` to get project-specific recommendations based on your current state.
+4. **Adopt**: Follow where-am-i recommendations to adopt specific families and services.
+```
+
+## 故障诊断
+
+- 如果 Family API Catalog 缺失或格式错误：检查 `family-apis/catalog.json` 是否存在于插件安装目录。
+- 如果 bundled 方法不显示：检查 `families-src/*/implementation.yaml` 是否存在。
+- 如果 registry 状态为 `NOT_AVAILABLE / REGISTRY_V2_REQUIRED`：等待或安装提供权威 projection verifier 的 Registry v2；不要信任手写状态文件。

package/adapters/claude/skills/prd-feature/author/references/compose.md

@@ -0,0 +1,43 @@
+# prd-feature compose
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+基于 inspect 结果编写 PRD 功能特性制品的 frontmatter 和正文。
+
+## 步骤
+
+### 1. 确定制品 ID
+
+- 从项目中 PRD 注册类型对应的 `idPatterns` 派生合法 ID；未配置时沿用项目同类制品约定
+- 检查与已有制品 ID 不冲突
+- ID 风格与同类制品保持一致
+
+### 2. 编写 frontmatter
+
+字段、状态初值和关联字段从项目模板、配置及同类制品派生。不要自行增加项目未采用的字段或状态。
+
+### 3. 编写正文结构
+
+优先遵循项目模板。模板未规定时，组织业务目标、可验证验收标准、关键约束和关联证据；章节名称不作固定要求。
+
+### 4. 验收标准编写规则
+
+每条验收标准必须：
+- 使用编号列表
+- 以动词开头（"支持""提供""确保""验证"）
+- 包含可验证的条件（不使用"足够""合理""尽快"等模糊词）
+- 可映射到至少一个测试场景或实现验证点
+
+### 5. 文件放置
+
+- 文件名：`<id>.md` 或 `<id>-<slug>.md`
+- 路径：按项目中 PRD 注册类型的 paths 配置
+- 文件名与 ID 保持可追溯对应
+
+## 输出
+
+compose 输出供 validate 和 review 消费：
+- 完整的制品文件内容
+- 制品 ID 和路径

package/adapters/claude/skills/prd-feature/author/references/inspect.md

@@ -0,0 +1,94 @@
+# prd-feature inspect
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在编写或审阅 PRD 功能特性制品前，收集项目配置、已有制品、关联关系和实现状态的证据。
+
+## 步骤
+
+### 1. 项目配置发现
+
+```bash
+# 确认项目根目录
+git rev-parse --show-toplevel
+
+# 读取 artifact-graph 配置
+cat artifact-graph.config.yaml
+
+# 确认 CLI 能力
+artifact-graph --help
+```
+
+提取：
+- PRD 对应的注册类型名、paths、target 与对应 `idPatterns`（如有）
+- 项目模板、`artifacts/README.md`、`AGENTS.md`/`CLAUDE.md` 中的本地规则
+- 项目注册的关联类型与同类制品实际使用的关联字段
+
+### 2. 已有制品扫描
+
+从步骤 1 提取的 PRD 注册类型 paths 扫描已有制品：
+
+```bash
+# 查询特定制品关系
+artifact-graph query --from <ID>
+```
+
+记录：
+- 已有制品 ID 列表（用于 ID 唯一性检查）
+- 已有制品 status 分布
+- 制品文件命名模式
+
+### 3. 关联制品可达性
+
+对项目配置、模板或同类制品声明的每个关联 ID：
+
+```bash
+artifact-graph query --from <RELATED_ID>
+```
+
+记录每个关联 ID 的存在状态；状态取值沿用目标项目的表达。
+
+### 4. 实现状态检查
+
+```bash
+artifact-graph context --target <type>:<ID> --mode implementation
+artifact-graph validate --root . --warning-only
+```
+
+记录：
+- 实现文件列表
+- validate 警告列表
+- 追溯注释存在性
+
+## 输出
+
+inspect 输出供 author、review、repair 流程消费：
+
+```yaml
+project:
+  root: <项目根目录>
+  config_loaded: true | false
+artifact_type:
+  name: <项目注册的 PRD 类型名>
+  registered: true | false
+  paths: [<制品路径列表>]
+  id_pattern: <ID pattern>
+existing_artifacts:
+  - id: <ID>
+    path: <文件路径>
+    status: <status>
+target_artifact:
+  id: <ID> | null
+  path: <文件路径> | null
+  exists: true | false
+related:
+  artifacts: [{ type, id, status }]
+validation:
+  warnings: [<警告列表>]
+  pass: true | false
+implementation:
+  files: [<实现文件列表>]
+  trace_comments: [<追溯注释列表>]
+```

package/adapters/claude/skills/prd-feature/author/references/validate.md

@@ -0,0 +1,65 @@
+# prd-feature validate
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在 author 或 repair 完成后，验证 PRD 功能特性制品的结构完整性和制品链一致性。
+
+## 步骤
+
+### 1. 制品链验证
+
+```bash
+artifact-graph validate --root . --warning-only
+```
+
+检查：
+- 无新增孤立制品警告
+- 无新增关联引用警告
+- 新制品已正确参与图遍历
+
+### 2. 项目规范完整性
+
+按项目配置、模板、`artifacts/README.md` 和同类制品检查 frontmatter、ID、状态与正文结构；不要假设固定字段或枚举。
+
+### 3. ID 唯一性
+
+从 `artifact-graph.config.yaml` 中 PRD 注册类型的 paths 派生扫描路径，确认新制品 ID 不与已有制品冲突。
+
+### 4. 关联可达性
+
+对项目规则声明的关联字段中的每个 ID：
+
+```bash
+artifact-graph query --from <ID>
+```
+
+确认关联制品在图中存在。
+
+### 5. 验收标准基本检查
+
+- 能定位非空的验收标准（章节名服从项目模板）
+- 标准有编号
+- 未决事项与项目状态规则不冲突
+
+## 输出
+
+validate 输出供 review 和 repair 消费：
+
+```yaml
+validation:
+  artifact_id: <ID>
+  artifact_path: <文件路径>
+  issues:
+    - code: <问题代码>
+      severity: error | warning | info
+      message: <问题描述>
+      location: <文件路径>:<行号>
+  pass: true | false
+  chain_check:
+    validate_output: <artifact-graph validate 关键输出>
+    related_check:
+      - id: <关联 ID>
+        exists: true | false
+```

package/adapters/claude/skills/prd-feature/review/references/compose.md

@@ -0,0 +1,43 @@
+# prd-feature compose
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+基于 inspect 结果编写 PRD 功能特性制品的 frontmatter 和正文。
+
+## 步骤
+
+### 1. 确定制品 ID
+
+- 从项目中 PRD 注册类型对应的 `idPatterns` 派生合法 ID；未配置时沿用项目同类制品约定
+- 检查与已有制品 ID 不冲突
+- ID 风格与同类制品保持一致
+
+### 2. 编写 frontmatter
+
+字段、状态初值和关联字段从项目模板、配置及同类制品派生。不要自行增加项目未采用的字段或状态。
+
+### 3. 编写正文结构
+
+优先遵循项目模板。模板未规定时，组织业务目标、可验证验收标准、关键约束和关联证据；章节名称不作固定要求。
+
+### 4. 验收标准编写规则
+
+每条验收标准必须：
+- 使用编号列表
+- 以动词开头（"支持""提供""确保""验证"）
+- 包含可验证的条件（不使用"足够""合理""尽快"等模糊词）
+- 可映射到至少一个测试场景或实现验证点
+
+### 5. 文件放置
+
+- 文件名：`<id>.md` 或 `<id>-<slug>.md`
+- 路径：按项目中 PRD 注册类型的 paths 配置
+- 文件名与 ID 保持可追溯对应
+
+## 输出
+
+compose 输出供 validate 和 review 消费：
+- 完整的制品文件内容
+- 制品 ID 和路径

package/adapters/claude/skills/prd-feature/review/references/inspect.md

@@ -0,0 +1,94 @@
+# prd-feature inspect
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在编写或审阅 PRD 功能特性制品前，收集项目配置、已有制品、关联关系和实现状态的证据。
+
+## 步骤
+
+### 1. 项目配置发现
+
+```bash
+# 确认项目根目录
+git rev-parse --show-toplevel
+
+# 读取 artifact-graph 配置
+cat artifact-graph.config.yaml
+
+# 确认 CLI 能力
+artifact-graph --help
+```
+
+提取：
+- PRD 对应的注册类型名、paths、target 与对应 `idPatterns`（如有）
+- 项目模板、`artifacts/README.md`、`AGENTS.md`/`CLAUDE.md` 中的本地规则
+- 项目注册的关联类型与同类制品实际使用的关联字段
+
+### 2. 已有制品扫描
+
+从步骤 1 提取的 PRD 注册类型 paths 扫描已有制品：
+
+```bash
+# 查询特定制品关系
+artifact-graph query --from <ID>
+```
+
+记录：
+- 已有制品 ID 列表（用于 ID 唯一性检查）
+- 已有制品 status 分布
+- 制品文件命名模式
+
+### 3. 关联制品可达性
+
+对项目配置、模板或同类制品声明的每个关联 ID：
+
+```bash
+artifact-graph query --from <RELATED_ID>
+```
+
+记录每个关联 ID 的存在状态；状态取值沿用目标项目的表达。
+
+### 4. 实现状态检查
+
+```bash
+artifact-graph context --target <type>:<ID> --mode implementation
+artifact-graph validate --root . --warning-only
+```
+
+记录：
+- 实现文件列表
+- validate 警告列表
+- 追溯注释存在性
+
+## 输出
+
+inspect 输出供 author、review、repair 流程消费：
+
+```yaml
+project:
+  root: <项目根目录>
+  config_loaded: true | false
+artifact_type:
+  name: <项目注册的 PRD 类型名>
+  registered: true | false
+  paths: [<制品路径列表>]
+  id_pattern: <ID pattern>
+existing_artifacts:
+  - id: <ID>
+    path: <文件路径>
+    status: <status>
+target_artifact:
+  id: <ID> | null
+  path: <文件路径> | null
+  exists: true | false
+related:
+  artifacts: [{ type, id, status }]
+validation:
+  warnings: [<警告列表>]
+  pass: true | false
+implementation:
+  files: [<实现文件列表>]
+  trace_comments: [<追溯注释列表>]
+```

package/adapters/claude/skills/prd-feature/review/references/validate.md

@@ -0,0 +1,65 @@
+# prd-feature validate
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在 author 或 repair 完成后，验证 PRD 功能特性制品的结构完整性和制品链一致性。
+
+## 步骤
+
+### 1. 制品链验证
+
+```bash
+artifact-graph validate --root . --warning-only
+```
+
+检查：
+- 无新增孤立制品警告
+- 无新增关联引用警告
+- 新制品已正确参与图遍历
+
+### 2. 项目规范完整性
+
+按项目配置、模板、`artifacts/README.md` 和同类制品检查 frontmatter、ID、状态与正文结构；不要假设固定字段或枚举。
+
+### 3. ID 唯一性
+
+从 `artifact-graph.config.yaml` 中 PRD 注册类型的 paths 派生扫描路径，确认新制品 ID 不与已有制品冲突。
+
+### 4. 关联可达性
+
+对项目规则声明的关联字段中的每个 ID：
+
+```bash
+artifact-graph query --from <ID>
+```
+
+确认关联制品在图中存在。
+
+### 5. 验收标准基本检查
+
+- 能定位非空的验收标准（章节名服从项目模板）
+- 标准有编号
+- 未决事项与项目状态规则不冲突
+
+## 输出
+
+validate 输出供 review 和 repair 消费：
+
+```yaml
+validation:
+  artifact_id: <ID>
+  artifact_path: <文件路径>
+  issues:
+    - code: <问题代码>
+      severity: error | warning | info
+      message: <问题描述>
+      location: <文件路径>:<行号>
+  pass: true | false
+  chain_check:
+    validate_output: <artifact-graph validate 关键输出>
+    related_check:
+      - id: <关联 ID>
+        exists: true | false
+```

package/adapters/claude/skills/quickstart/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: quickstart
+description: 按意图路由到正确的技能。根据用户描述的意图，推荐最合适的入口技能和最小调用提示词。
+---
+
+# quickstart
+
+## 目的
+
+为首次使用 artifact-chain-assistant 或不确定该用哪个技能的用户提供单一入口。根据用户描述的意图进行自然语言路由，输出目标技能名称、推荐理由和最小调用提示词。
+
+## 职责边界
+
+- **纯路由**：不执行任何写操作或项目分析。
+- **不复制技能逻辑**：quickstart 只做意图判断和路由推荐，不执行被路由技能的任何步骤。
+- **不猜测意图**：当用户意图不明确时，输出追问而非猜测路由。
+
+## 路由规则
+
+根据用户输入的意图，按以下规则路由：
+
+### 能力说明或功能查询
+
+**匹配关键词**：能做什么、功能、能力、what can、help、capabilities
+
+**路由目标**：`help`
+
+**理由**：help 技能展示标准 Family API Catalog、bundled legacy 方法和采用步骤。
+
+**最小提示词**：`请展示 artifact-chain-assistant 的标准能力和采用步骤。`
+
+### 环境检查或采用状态确认
+
+**匹配关键词**：环境、检查、准备好了吗、状态、setup、ready
+
+**路由目标**：`setup`
+
+**理由**：setup 技能执行只读环境检查并输出结构化状态报告。
+
+**最小提示词**：`请检查我的环境是否具备使用 artifact-chain-assistant 的条件。`
+
+### 首次初始化或结构修复
+
+**匹配关键词**：初始化、初始化项目、bootstrap、设置、configure、init、修复配置
+
+**路由目标**：先 `setup`，经用户授权后进入 `artifact-chain-bootstrap`
+
+**理由**：先通过 setup 了解当前状态，再由用户决定是否授权 bootstrap 执行写入操作。
+
+**最小提示词**：`请先检查我的环境状态，然后引导我完成项目初始化。`
+
+### 模糊的项目需求或制品定位
+
+**匹配关键词**：该做什么、下一步、当前状态、制品在哪、where、定位
+
+**路由目标**：`where-am-i`
+
+**理由**：where-am-i 搜索项目配置和制品图，输出结构化的项目事实和路由建议。
+
+**最小提示词**：`请分析我的项目当前状态并推荐下一步。`
+
+### 日常维护、版本锁刷新或 hook 管理
+
+**匹配关键词**：维护、刷新锁、version-lock、hook、maintain、update
+
+**路由目标**：`artifact-chain-maintainer`
+
+**理由**：maintainer 技能处理日常维护任务，包括版本锁刷新和 hook 管理。
+
+**最小提示词**：`请帮我执行日常维护任务。`
+
+### 明确的制品制作/审阅/修复任务
+
+**匹配关键词**：制作、审阅、修复、author、review、repair、PRD、scenario、design
+
+**路由目标**：对应的 family/service
+
+**理由**：用户已明确知道要执行的操作，直接路由到对应的专业入口。
+
+**最小提示词**：根据具体任务构造，例如 `请审阅这个 PRD feature 制品。`
+
+### 意图不明确
+
+**行为**：输出追问，不猜测路由。
+
+**追问示例**：
+```
+您的意图不太明确，请告诉我更多信息：
+- 您想了解这个插件能做什么？→ 我会路由到 help
+- 您想检查环境是否准备就绪？→ 我会路由到 setup
+- 您想初始化项目？→ 我会先检查环境，再引导 bootstrap
+- 您想知道下一步该做什么？→ 我会路由到 where-am-i
+- 您有明确的制品任务？→ 请描述具体操作（制作/审阅/修复）和制品类型
+```
+
+## 输出格式
+
+```
+## 路由建议
+
+**目标技能**：`help`
+**推荐理由**：您询问的是插件能力，help 技能展示标准 Family API 和采用步骤。
+**最小提示词**：`请展示 artifact-chain-assistant 的标准能力和采用步骤。`
+
+> 直接将最小提示词发送给助手即可启动目标技能。
+```
+
+## 安全边界
+
+- quickstart 本身不执行任何写操作或项目分析。
+- 路由推荐基于用户意图的自然语言匹配，不依赖项目状态。
+- 当意图匹配多个技能时，输出候选列表和区分标准，由用户选择。
+- 当意图超出插件能力范围时，明确说明并建议外部资源。

package/adapters/claude/skills/scenario-script/author/references/compose.md

@@ -0,0 +1,43 @@
+# scenario-script compose
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+基于 inspect 结果编写场景剧本制品的 frontmatter 和正文。
+
+## 步骤
+
+### 1. 确定制品 ID
+
+- 从项目 `idPatterns` 中场景类型对应的 pattern 派生合法 ID
+- 检查与已有制品 ID 不冲突
+- ID 应简短且具有业务语义
+
+### 2. 编写 frontmatter
+
+从 inspect 输出的项目模板、配置和同类制品派生 frontmatter。不得自行增加项目未采用的字段或状态。
+
+### 3. 编写正文结构
+
+正文应覆盖角色与目标、前置条件、主路径、异常路径、可观察结果和必要追溯等通用质量维度；具体章节名和布局从项目模板与已有制品派生。
+
+### 4. 场景步骤编写规则
+
+每个主路径和异常路径步骤必须：
+- 使用编号列表
+- 以动词开头
+- 包含可验证的条件（不使用"足够""合理""尽快"等模糊词）
+- 每个异常路径描述触发条件和预期处理方式
+
+### 5. 文件放置
+
+- 文件名按项目制品命名模式（从已有制品扫描结果派生）
+- 路径按项目中场景剧本注册类型的 paths 配置
+- 文件名与 ID 保持可追溯对应
+
+## 输出
+
+compose 输出供 validate 和 review 消费：
+- 完整的制品文件内容
+- 制品 ID 和路径