release/v0.1.0

.agents/skills/comet-any/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: comet-any
+description: "仅在用户明确调用 /comet-any，或明确要求定制 /comet-classic 五阶段流程、创建或升级由 Comet Creator 管理的 workflow Skill 时使用；不要用于一般 Skill 的编写、整理或评审。"
+---
+
+# Comet Any - Skill Creator
+
+`/comet-any` 是 Comet 的 Skill 创建向导。用户只需要描述想要的工作流；本 Skill 负责读取真实 Skill、提出方案、等待确认、生成可验证的 Comet-native Skill Bundle，并通过内部 CLI 完成 eval、review、publish readiness 和安装预览。
+
+普通用户第一层只看到三种起点：
+
+- `基于 /comet-classic 的五阶段定制`：覆盖 `open / design / build / verify / archive` 五阶段的 Skill 编排，但不修改 `/comet-classic` 永久入口本身。
+- `创建全新 workflow Skill`：从目标和候选 Skills 生成新的 `workflow-kernel`。
+- `整理已有 Skill`：读取已有 Skill，补齐 Workflow Node、Skill Binding、Output Schema、Guardrail、Handoff、eval 和 readiness。
+
+后端 Bundle、Factory、composition 仍是内部审计词；不要把它们作为普通用户的第一屏概念。
+
+## 核心模型
+
+所有路径都必须编译到同一种 Workflow Contract：
+
+- `Workflow Node`：流程中的可恢复节点，例如 `open`、`design`、`plan`、`execute`、`subagent-execute`、`review`、`verify`、`archive`。
+- `Node Responsibility`：该 Node 在 Agent workflow 中承担的职责，用来解释它为什么存在、需要产出什么、能否替换。
+- `Skill Binding`：某个 Node 的实现 Skill 或辅助 Skill。
+- `Required Skill Call`：要求 Node 内必须调用某个 Skill，不替换 Node implementation。例如 `execute` 和 `subagent-execute` 必须调用 `elementui`，`review` 必须调用 `whitebox-code-standard`。
+- `Output Schema`：Node 必须产出的文件、状态或 evidence。Output Schema 必须挂到具体 Workflow Node 才算生效；只定义在 `workflow.outputSchemas` 里不会触发 guard、eval 或 readiness。脚本、eval、readiness 只依赖挂到 Node 的 Output Schema，不依赖 Skill 名称。
+- `Guardrail`：阻断或放行 Node 推进的检查。
+- `Handoff`：子代理或跨 Node 交接时必须带回的 evidence。
+- `workflow-protocol.json`：生成包的唯一运行事实源，kind 为 `comet-five-phase-overlay` 或 `workflow-kernel`。
+
+## 受保护边界
+
+`comet-five-phase-overlay` 保留 Comet Classic 五阶段主流程和 `.comet.yaml` 状态语义。普通模式下：
+
+- `comet-five-phase-overlay` 的主状态只来自 `openspec/changes/<name>/.comet.yaml`；没有 active change 或多个 active changes 时必须阻塞并请用户选择。
+- 不得创建 `.comet/runs/<workflow>/state.json` 作为 Comet overlay 主状态。Bundle 草稿、eval evidence 和 publish readiness 可以有自己的证据文件，但不能替代 `.comet.yaml`。
+- `control` Node 不允许 override：`open`、`execute`、`verify`、`archive`。
+- `producer` Node 可以 override：`design`、`plan`，但必须满足对应 Output Schema。
+- `handoff` 和 `guardrail` Node 可以 require / augment。
+- 用户坚持替换 control Node 时，改走高级 `workflow-kernel`，并要求重新声明 state、Output Schema 和 Guardrail。
+- 所有 Node 都必须用 responsibility 说明职责，不使用内部坐标作为用户理解流程的方式。
+
+## 工作步骤
+
+1. 恢复现有状态：先运行 `comet creator guide --project . --json`，展示恢复摘要和下一步。
+2. 读取项目偏好：读取 `.comet/skill-preferences.yaml`，用 `comet creator candidates --json` 发现真实本地 Skill，再用 `comet skill show <name> --json` 读取候选的真实内容与 hash。不得只按名字推测能力。
+3. 生成方案：把用户目标表达为 Workflow Nodes、Skill Bindings、Output Schemas、Guardrails、Handoffs 和 Evidence。
+4. 展示确认页：说明每个 Node 的职责、绑定 Skill、Required Skill Call、Output Schema、可执行披露和 readiness 影响。确认页必须为每个新增 binding 或 schema 显示 enforcement：`guarded`、`handoff-guarded`、`evidence-only` 或 `advisory`。
+5. 等待用户确认：未确认前不得写 Bundle draft；存在 missing / ambiguous Skill 时必须暂停。
+6. 初始化后端状态：确认后调用 `comet creator init <name> --file <plan.json> --confirmed-proposal --json`。
+7. 运行创作管线并生成 Bundle：先运行 `comet creator authoring-plan <name> --depth quick|full --json` 取得 lane DAG。按 DAG 派发 lane——wave1（`script`、`reference`、`pause-points`）在支持子代理的平台可并发（否则按依赖顺序内联），wave2（`workflow-entry`、`skill-core`）在 script 契约之后，`skill-review` 作为汇聚 barrier。每个 lane 的产出用 `comet creator authoring-record <name> --lane <id> --file <out.json> --json` 记录（经 schema 校验；BLOCKED/NEEDS_CONTEXT 会被拒绝）。随后运行 `comet creator generate <name> --json`：把记录的内容叶子草稿（entry/node SKILL.md、decision-points、recovery）合并进包，而确定性脊梁（protocol/scripts/manifest）保持模板化，并渲染真实审查证据。产出 entry Skill、Node Skills、`reference/workflow-protocol.json`、六个 scripts、rules、hooks 与 `comet/eval.yaml`。
+8. 验证：展示 quick/full eval 工作量，运行或记录当前 draft hash 的 eval evidence；失败、skip 或证据 hash 过期时不得进入 ready。
+9. Review / readiness：读取 `comet publish review <name> --platform <reference-platform> --json`，展示 `Readiness:`、`Blockers:`、`Warnings:`、`Evidence:`。
+10. Publish / install preview：人工批准后才能 publish；安装前必须先运行 preview，并展示 `No files were written`。
+
+## 方案示例
+
+组件库和白盒审查场景应生成类似 plan：
+
+```json
+{
+  "goal": "基于 /comet-classic 的五阶段定制，要求组件库和白盒审查。",
+  "skillCreatorIntent": "customize-comet",
+  "workflow": {
+    "kind": "comet-five-phase-overlay",
+    "name": "team-comet",
+    "goal": "要求组件库和白盒审查。",
+    "nodes": {
+      "execute": {
+        "requiredSkillCalls": [
+          {
+            "skill": "elementui",
+            "reason": "Use project component library during direct implementation."
+          }
+        ]
+      },
+      "subagent-execute": {
+        "requiredSkillCalls": [
+          {
+            "skill": "elementui",
+            "scope": "handoff"
+          }
+        ]
+      },
+      "review": {
+        "requiredSkillCalls": [
+          {
+            "skill": "whitebox-code-standard",
+            "scope": "review"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## 硬性规则
+
+- 必须先展示方案确认页，再生成。
+- 确认页必须为每个新增 binding 或 schema 显示 enforcement：`guarded`、`handoff-guarded`、`evidence-only` 或 `advisory`。
+- Required Skill Call 不替换 Node implementation。
+- producer override 必须声明 `satisfies` 的 Output Schema。
+- Output Schema 必须挂到具体 Workflow Node 才算生效；只定义在 `workflow.outputSchemas` 里不会触发 guard、eval 或 readiness。
+- control Node 普通模式不得 override。
+- eval、review、publish readiness 必须读取同一份 `workflow-protocol.json`。
+- readiness blockers 必须阻止 publish：缺少当前 draft hash 的 eval evidence、人工 approval、required capability 或 executable disclosure 任一项都不能进入 ready。
+- 子代理 Handoff 必须要求子代理加载 Required Skill Call 并回传 evidence。
+- 脚本只读取 protocol 和 state，不把 Skill 名称当成校验依据。
+- 安装前必须询问用户，不得自动安装。
+
+## 参考资料
+
+- `comet-any/reference/authoring-protocol.json`
+- `comet-any/reference/authored-zone-example.md`
+- `comet-any/reference/bundle-authoring.md`
+- `comet-any/reference/authoring-subagents.md`
+- `comet-any/reference/eval-provider.md`

.agents/skills/comet-any/reference/authored-zone-example.md

@@ -0,0 +1,105 @@
+# Authored 区质量标尺（样例）
+
+这是你编写的 **Authored 区**（entry 的 `## Decision Core`、node 的 `## Guidance`）的具体质量标尺。生成器把你的 Authored 区组装到确定性 **Auto 区**（frontmatter、路由表、Entry/Exit Check、证据格式、Recovery）之上。**你只写 Authored 区**。请按本样例校准，而不是写一行套话。
+
+## "Auto" 与 "Authored" 的含义
+
+- **Auto 区（模板，不要重写）**：不变的控制面。node 的 Auto 区包括 `## Node Goal`、`## Entry Check`、`## Skill Implementation`、`## Required Skill Calls`、`## Output Schemas`、`## Evidence Record`、`## Guardrails`、`## Exit Check`、`## Recovery`。entry 的 Auto 区包括 `## Workflow Nodes`、`## Skill Bindings`、`## Guardrails And Evidence`、`## Runtime And Recovery`。
+- **Authored 区（你写）**：Auto 区无法得知的领域决策。这是让 Skill "好用"而非"只是能跑"的关键。
+
+## 样例：`substance` 节点的 Guidance 区（workflow-kernel）
+
+下面是 research-writer workflow 中"Research"生产者节点的 `## Guidance` 正文。注意它是**决策内容**：前提、有序的领域步骤、超出机械 Exit Check 的完成判断、Red flags。它按名引用绑定的 Skill，但不复制其正文。
+
+```markdown
+## Prerequisites
+
+- entry 的 Decision Core 已确认研究主题与范围。
+- `research-skill` 在项目 Skill 池中可解析；若缺失，先停下询问用户，不要临时替代。
+
+## Steps
+
+1. 加载 `research-skill` 并按其发现方法处理已确认主题。当项目 Skill 定义了特定来源顺序时，不要用通用网络搜索替代。
+2. 按优先级收集来源；为每个来源记录来源、日期和你要复用的论点。不通过项目可信度门槛的来源应直接剔除，而不是标注为"偏弱"。
+3. 把发现提炼到 `notes/*.md` 笔记文件——每条独立论点一份，含逐字引用与来源指针。综合写在 writer 节点，不在这里。
+4. 记录 `research.notes.v1` 的 `summary` evidence：一段提炼 + 产出的笔记数量。
+
+## Completion reasoning
+
+本节点完成当且仅当两条同时成立：(a) 已记录 `summary` evidence；(b) 至少一个 artifact 匹配 `notes/*.md`。不要仅仅因为步骤清单走完就退出——如果相对主题范围笔记仍偏稀疏，应继续研究而非宣布完成。Exit Check 脚本会机械地强制 artifact + evidence 要求；你的职责是判断研究是否真正充分。
+
+## Red flags
+
+- 记录了 `summary` 却没有产出任何 `notes/*.md` 就退出（guardrail 会阻塞——不要试图绕过）。
+- 把来源原文复制进笔记却不加引用标记或来源指针。
+- 某来源仍"待核实"就推进到 Write 节点——核实属于本节点。
+- 对需要多视角的主题，仅凭单一来源就认为充分。
+```
+
+用 `###` 子标题，使其嵌套在 `## Guidance` 之下。上述四段（Prerequisites / Steps / Completion reasoning / Red flags）是 `substance` 节点的预期形态。
+
+## 样例：entry Decision Core（workflow-entry）
+
+下面是 entry SKILL.md 的 `## Decision Core` 正文。entry 是**每次调用最先读取的文件**——一个薄 Decision Core（"跑 next，照做"）会让整个 Skill 感觉机械。一个富 Decision Core 是 comet 级 Skill "好用"的核心。
+
+Decision Core 应建模 Auto 区不处理的三件事：(1) **语义化当前节点检测**（如何判断用户在哪个 Node，而非只看脚本输出），(2) **resume 与 drift 规则**（上下文恢复或状态与文件冲突时怎么办），(3) **决策点与 Red flags**（何时暂停等用户，以及什么是假进展）。
+
+```markdown
+### 自动节点检测
+
+**Step 0：确定当前节点与意图**
+
+1. 检查 workflow protocol 的有序 Node 列表。第一个未完成（无 Exit evidence 记录）的 Node 是候选当前节点。
+2. 若用户描述的工作明显属于更后面的 Node（如"验证结果"但研究尚未完成），暂停并说明：前序 Node 必须先完成。不要跳过。
+3. 若用户描述的工作属于已标记完成的更早 Node，视为纠正——重置该 Node 的完成状态并重新进入。
+
+**Step 1：读取 workflow 状态**
+
+运行 `node "$WORKFLOW_STATE" status` 确认检测到的节点。若脚本的 `NEXT:` 输出与文件证据冲突（如脚本说 DONE 但无 artifact），以文件为准，先纠正状态再继续。
+
+**Resume 规则**：
+- 每次上下文恢复，重新执行 Step 0 和 Step 1。不要信任对话历史做节点检测。
+- 若状态显示某 Node 已完成但预期 artifact 缺失，视为未完成并重新进入。
+- 若用户在某个 Node 中途恢复但话题变了，确认是继续当前 Node 还是开始新的。
+
+### 决策分类与决策点
+
+先分类再行动：有两个或以上会改变范围、行为、风险接受或不可逆结果的合法选项才是用户决策；唯一安全下一步直接执行；缺少依赖、状态损坏或无法继续的 guard 失败是停止条件；`NEXT: manual` 只是交还控制权。只有第一类必须暂停。
+
+| 情况 | 处理 |
+|------|------|
+| 首次调用且主题/范围明确 | 自动初始化状态并进入第一个 Node；不得为了确认已知信息而停顿 |
+| 主题、范围或目标 Node 存在两个以上互斥且合法的解释 | 合并为一个问题，让用户选择；不要猜测 |
+| Node 需要用户确认输出才能推进 | 记录 evidence 后停下；等待明确确认 |
+| WARNING/偏差接受或不可逆发布存在真实取舍 | 只展示当前可执行选项，并记录用户选择 |
+
+Node guard 失败时先自动读取证据并执行唯一安全修复；若缺少依赖或状态损坏导致无法继续，报告停止条件和恢复要求。只有恢复方式存在多个会改变范围或风险的合法选项时，才升级为上表中的用户决策。
+
+### Red Flags
+
+| Agent 想法 | 实际风险 |
+|-----------|---------|
+| "首次调用都应该再确认一次" | 清晰输入不需要重复批准；只有互斥解释仍会改变范围时才询问。 |
+| "脚本返回 NEXT: auto，应该立即加载下一个 Skill" | `NEXT: auto` 表示 Node 完成，不是跳过确认。检查下一个 Node 是否有决策点。 |
+| "guard 失败，所以让用户决定怎么办" | 先自动诊断并执行唯一安全修复；无合法动作时报告停止条件，不要发明选项。 |
+| "看起来和上次一样的话题，从上次断点继续" | 始终重新读取状态。对话记忆在上下文压缩后不可靠。 |
+| "Exit Check 通过了，所以工作够好了" | Exit Check 是机械的。你的职责是判断检查之外的质量——稀疏笔记、浅层分析、缺失视角，脚本抓不到。 |
+```
+
+此样例以精简形式建模了 comet 的 Decision Core：语义检测（Step 0 读 Node 顺序，非只看脚本输出）、状态忠实（文件优先于过期状态）、resume 规则（每次恢复重新检测）、阻塞决策点（显式表格）、Red flags（"想法 → 风险"模式，抓 agent 自欺）。
+
+## substance 与 delegates
+
+- **substance** 节点（workflow-kernel）：上面的样例就是标尺。必须有富 Guidance；缺失时该节点渲染为 `AUTHORING PENDING`，Bundle 不得 ready。
+- **delegates** 节点（comet-five-phase-overlay，委托给已安装的富 Skill）：富执行内容由被委托 Skill 承载，**不要复制**。但如果该节点声明了 **Required Skill Calls**（如 execute 节点要求 `elementui`），请写一段聚焦的整合说明——在被委托流程的什么时机必须加载该 Skill、它补充什么 evidence——而不是泛泛一句"加载 X"。例如要求 `elementui` 的 delegates execute 节点：
+
+```markdown
+本节点用 `comet-build` 执行。在其流程之外，每当改动涉及组件库时加载 `elementui`，并在记录 `required-skill:execute.elementui` 检查前确认改动使用了项目认可的组件。不要重复实现 `comet-build` 已做的事。
+```
+
+## 反模式（不要写）
+
+- 一行式 Guidance，如"运行本节点并记录 evidence。"——Auto 区已隐含此意，毫无增量。
+- 整段复制被绑定 Skill 的正文。
+- 重述路由表或 Output Schema 列表（Auto 区已有）。
+- substance 节点没有 `### Red flags`——Red flags 是大部分真实价值所在。