artifact-chain-assistant 0.8.0 → 0.8.2

package/adapters/codex/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/codex/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/codex/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/codex/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 和路径

package/adapters/codex/skills/scenario-script/author/references/inspect.md

@@ -0,0 +1,105 @@
+# scenario-script inspect
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在编写或审阅场景剧本制品前，收集项目配置、已有制品、关联关系和场景模板的证据。
+
+## 步骤
+
+### 1. 项目配置发现
+
+```bash
+# 确认项目根目录
+git rev-parse --show-toplevel
+
+# 读取 artifact-graph 配置
+cat artifact-graph.config.yaml
+
+# 确认场景类型注册和路径
+artifact-graph --help
+```
+
+提取：
+- 场景剧本对应的注册类型名、paths、target 与对应 `idPatterns`（如有）
+- 项目注册的关联类型与同类制品实际使用的关联字段
+
+### 2. 项目模板与治理文档
+
+读取以下文件以派生场景剧本的合法字段、status 枚举和章节结构：
+- `artifact-graph.config.yaml` 中场景类型的注册信息
+- `artifacts/README.md` 中的制品边界说明
+- `AGENTS.md` 或 `CLAUDE.md` 中的治理规则
+- 同类已有制品（从步骤 3 的扫描结果中选取典型样本）
+
+从以上来源派生：
+- frontmatter 必填字段（不得假设固定字段集）
+- status 合法枚举（不得假设固定枚举值）
+- 章节结构要求（不得假设固定章节名）
+
+### 3. 已有制品扫描
+
+从步骤 1 提取的制品路径扫描已有场景制品：
+
+```bash
+# 查询特定制品关系
+artifact-graph query --from <ID>
+```
+
+记录：
+- 已有制品 ID 列表（用于 ID 唯一性检查）
+- 已有制品 status 分布
+- 制品文件命名模式
+
+### 4. 关联制品可达性
+
+对目标制品的关联制品 ID：
+
+```bash
+artifact-graph query --from <RELATED_ID>
+```
+
+记录每个关联 ID 的存在状态；状态取值沿用目标项目的表达。
+
+### 5. 实现状态检查
+
+```bash
+artifact-graph validate --root . --warning-only
+```
+
+记录：
+- validate 警告列表
+- 制品链一致性状态
+
+## 输出
+
+inspect 输出供 author、review、repair 流程消费：
+
+```yaml
+project:
+  root: <项目根目录>
+  config_loaded: true | false
+artifact_type:
+  name: <项目注册的场景剧本类型名>
+  registered: true | false
+  paths: [<制品路径列表>]
+  id_pattern: <ID pattern>
+template:
+  required_fields: [<从项目模板派生的必填字段>]
+  status_enum: [<从项目模板派生的合法状态>]
+  sections: [<从项目模板派生的必要章节>]
+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
+```

package/adapters/codex/skills/scenario-script/author/references/validate.md

@@ -0,0 +1,72 @@
+# scenario-script validate
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在 author 或 repair 完成后，验证场景剧本制品的结构完整性和制品链一致性。
+
+## 步骤
+
+### 1. 制品链验证
+
+```bash
+artifact-graph validate --root . --warning-only
+```
+
+检查：
+- 无新增孤立制品警告
+- 无新增关联引用警告
+- 新制品已正确参与图遍历
+
+### 2. 项目规范完整性
+
+按项目配置、模板、治理文档和同类制品检查 frontmatter、ID、状态与正文结构；不要假设固定字段或枚举。
+
+### 3. ID 唯一性
+
+从项目配置中派生制品扫描路径，确认新制品的 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
+quality_dimensions:
+  role_and_goals: present | missing
+  preconditions: present | missing
+  main_path: present | missing
+  exception_paths: present | missing
+  observable_results: present | missing
+  traceability: present | missing
+```

package/adapters/codex/skills/scenario-script/review/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 和路径

package/adapters/codex/skills/scenario-script/review/references/inspect.md

@@ -0,0 +1,105 @@
+# scenario-script inspect
+
+内部工序，不作为 catalog 入口。
+
+## 目的
+
+在编写或审阅场景剧本制品前，收集项目配置、已有制品、关联关系和场景模板的证据。
+
+## 步骤
+
+### 1. 项目配置发现
+
+```bash
+# 确认项目根目录
+git rev-parse --show-toplevel
+
+# 读取 artifact-graph 配置
+cat artifact-graph.config.yaml
+
+# 确认场景类型注册和路径
+artifact-graph --help
+```
+
+提取：
+- 场景剧本对应的注册类型名、paths、target 与对应 `idPatterns`（如有）
+- 项目注册的关联类型与同类制品实际使用的关联字段
+
+### 2. 项目模板与治理文档
+
+读取以下文件以派生场景剧本的合法字段、status 枚举和章节结构：
+- `artifact-graph.config.yaml` 中场景类型的注册信息
+- `artifacts/README.md` 中的制品边界说明
+- `AGENTS.md` 或 `CLAUDE.md` 中的治理规则
+- 同类已有制品（从步骤 3 的扫描结果中选取典型样本）
+
+从以上来源派生：
+- frontmatter 必填字段（不得假设固定字段集）
+- status 合法枚举（不得假设固定枚举值）
+- 章节结构要求（不得假设固定章节名）
+
+### 3. 已有制品扫描
+
+从步骤 1 提取的制品路径扫描已有场景制品：
+
+```bash
+# 查询特定制品关系
+artifact-graph query --from <ID>
+```
+
+记录：
+- 已有制品 ID 列表（用于 ID 唯一性检查）
+- 已有制品 status 分布
+- 制品文件命名模式
+
+### 4. 关联制品可达性
+
+对目标制品的关联制品 ID：
+
+```bash
+artifact-graph query --from <RELATED_ID>
+```
+
+记录每个关联 ID 的存在状态；状态取值沿用目标项目的表达。
+
+### 5. 实现状态检查
+
+```bash
+artifact-graph validate --root . --warning-only
+```
+
+记录：
+- validate 警告列表
+- 制品链一致性状态
+
+## 输出
+
+inspect 输出供 author、review、repair 流程消费：
+
+```yaml
+project:
+  root: <项目根目录>
+  config_loaded: true | false
+artifact_type:
+  name: <项目注册的场景剧本类型名>
+  registered: true | false
+  paths: [<制品路径列表>]
+  id_pattern: <ID pattern>
+template:
+  required_fields: [<从项目模板派生的必填字段>]
+  status_enum: [<从项目模板派生的合法状态>]
+  sections: [<从项目模板派生的必要章节>]
+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
+```