@rpamis/comet 0.3.8 → 0.4.0-beta.1

package/assets/skills-zh/comet/runtime/classic/skill.yaml

@@ -0,0 +1,122 @@
+apiVersion: comet/v1alpha1
+kind: Skill
+metadata:
+  name: comet-classic
+  version: "1"
+  description: Comet 经典 full、hotfix、tweak 工作流的内部兼容编排
+goal:
+  statement: 在不改变用户命令面的前提下稳定推进或恢复经典 Comet Run
+  inputs:
+    - name: classic-state
+      description: 已校验且与 Run 投影一致的 ClassicState
+      required: true
+    - name: evidence
+      description: Classic Evidence 收集器生成的结构化证据
+      required: true
+  outputs:
+    - name: run-state
+      description: 原子同步后的 Classic 与 Run 状态
+      required: true
+  success:
+    - 旧字段与 Run 字段保持一致
+    - 每个步骤只调用声明的公开 Comet Skill
+    - completed 状态通过 completion eval
+orchestration:
+  mode: deterministic
+  entry: full.open
+  steps:
+    - id: full.open
+      action: { type: invoke_skill, ref: comet-open }
+      next: full.design.handoff
+    - id: full.design.handoff
+      action: { type: invoke_skill, ref: comet-design }
+      next: full.design.document
+    - id: full.design.document
+      action: { type: invoke_skill, ref: comet-design }
+      next: full.build.plan
+    - id: full.build.plan
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.plan-ready
+    - id: full.build.plan-ready
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.configure
+    - id: full.build.configure
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.execute
+    - id: full.build.execute
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.complete
+    - id: full.build.complete
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.verify.run
+    - id: full.build.fix
+      action: { type: invoke_skill, ref: comet-build }
+      next: full.build.execute
+    - id: full.verify.run
+      action: { type: invoke_skill, ref: comet-verify }
+      next: full.verify.branch
+    - id: full.verify.branch
+      action: { type: invoke_skill, ref: comet-verify }
+      next: full.archive.confirm
+    - id: full.archive.confirm
+      action: { type: invoke_skill, ref: comet-archive }
+      next: full.archive.execute
+    - id: full.archive.execute
+      action: { type: invoke_skill, ref: comet-archive }
+      next: completed
+    - id: hotfix.open
+      action: { type: invoke_skill, ref: comet-hotfix }
+      next: hotfix.build.execute
+    - id: hotfix.build.execute
+      action: { type: invoke_skill, ref: comet-build }
+      next: hotfix.build.complete
+    - id: hotfix.build.complete
+      action: { type: invoke_skill, ref: comet-build }
+      next: hotfix.verify.run
+    - id: hotfix.verify.run
+      action: { type: invoke_skill, ref: comet-verify }
+      next: hotfix.verify.branch
+    - id: hotfix.verify.branch
+      action: { type: invoke_skill, ref: comet-verify }
+      next: hotfix.archive.confirm
+    - id: hotfix.archive.confirm
+      action: { type: invoke_skill, ref: comet-archive }
+      next: hotfix.archive.execute
+    - id: hotfix.archive.execute
+      action: { type: invoke_skill, ref: comet-archive }
+      next: completed
+    - id: tweak.open
+      action: { type: invoke_skill, ref: comet-tweak }
+      next: tweak.build.execute
+    - id: tweak.build.execute
+      action: { type: invoke_skill, ref: comet-build }
+      next: tweak.build.complete
+    - id: tweak.build.complete
+      action: { type: invoke_skill, ref: comet-build }
+      next: tweak.verify.run
+    - id: tweak.verify.run
+      action: { type: invoke_skill, ref: comet-verify }
+      next: tweak.verify.branch
+    - id: tweak.verify.branch
+      action: { type: invoke_skill, ref: comet-verify }
+      next: tweak.archive.confirm
+    - id: tweak.archive.confirm
+      action: { type: invoke_skill, ref: comet-archive }
+      next: tweak.archive.execute
+    - id: tweak.archive.execute
+      action: { type: invoke_skill, ref: comet-archive }
+      next: completed
+    - id: completed
+      action: { type: checkpoint }
+      completionEvals:
+        - classic-completed
+skills:
+  - id: comet-open
+  - id: comet-design
+  - id: comet-build
+  - id: comet-verify
+  - id: comet-archive
+  - id: comet-hotfix
+  - id: comet-tweak
+agents: []
+tools: []

package/assets/skills-zh/comet-any/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: comet-any
+description: "Use when 用户想定制 Comet 五阶段 Skill、创建 workflow Skill、整理已有 Skill，或用 Workflow Node / Skill Binding / Output Schema 编排 Skill。"
+---
+
+# Comet Any - Skill Creator
+
+`/comet-any` 是 Comet 的 Skill 创建向导。用户只需要描述想要的工作流；本 Skill 负责读取真实 Skill、提出方案、等待确认、生成可验证的 Comet-native Skill Bundle，并通过内部 CLI 完成 eval、review、publish readiness 和安装预览。
+
+普通用户第一层只看到三种起点：
+
+- `基于 Comet 现有 Skill 的五阶段定制`：覆盖 `open / design / build / verify / archive` 五阶段的 Skill 编排，但不修改 `/comet` 命令本身。
+- `创建全新 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 主流程和 `.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 现有 Skill 的五阶段定制，要求组件库和白盒审查。",
+  "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`

package/assets/skills-zh/comet-any/reference/authored-zone-example.md

@@ -0,0 +1,100 @@
+# 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 还是开始新的。
+
+### 决策点（必须暂停）
+
+| 情况 | 处理 |
+|------|------|
+| 首次调用，无 workflow 状态 | 初始化状态，在开始第一个 Node 前与用户确认主题/范围 |
+| 用户输入在两个 Node 间有歧义 | 询问用户指哪个 Node；不要猜测 |
+| Node 需要用户确认输出才能推进 | 记录 evidence 后停下；等待明确确认 |
+| Node guard 失败且原因不明 | 展示 guard 输出，询问用户如何继续 |
+
+### Red Flags
+
+| Agent 想法 | 实际风险 |
+|-----------|---------|
+| "用户提到了主题，所以研究隐式确认" | 提到 ≠ 确认。在第一个 Node 边界暂停并确认范围。 |
+| "脚本返回 NEXT: auto，应该立即加载下一个 Skill" | `NEXT: auto` 表示 Node 完成，不是跳过确认。检查下一个 Node 是否有决策点。 |
+| "看起来和上次一样的话题，从上次断点继续" | 始终重新读取状态。对话记忆在上下文压缩后不可靠。 |
+| "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 是大部分真实价值所在。

package/assets/skills-zh/comet-any/reference/authoring-protocol.json

@@ -0,0 +1,91 @@
+{
+  "schemaVersion": 1,
+  "description": "/comet-any 的确定性创作契约。主会话解释执行本协议，对称于运行时脚本解释 workflow-protocol.json。后端（domains/bundle/authoring.ts）以同构常量镜像本契约。",
+  "depth": {
+    "quick": { "voters": 1, "maxRounds": 1, "evidenceSource": "llm-single" },
+    "full": { "voters": 3, "maxRounds": 4, "evidenceSource": "llm-multivote" },
+    "dryThreshold": 2
+  },
+  "dag": {
+    "wave1": ["script", "reference", "pause-points"],
+    "wave2": ["workflow-entry", "skill-core"],
+    "barrier": ["skill-review"]
+  },
+  "lanes": {
+    "script": {
+      "brief": "reference/subagents/script-author.md",
+      "claims": [
+        "script:workflow-state",
+        "script:workflow-guard",
+        "script:workflow-handoff",
+        "script:comet-plan",
+        "script:comet-check",
+        "script:comet-hook-guard"
+      ],
+      "producesContentLeaves": []
+    },
+    "reference": {
+      "brief": "reference/subagents/reference-author.md",
+      "claims": [
+        "reference:workflow-protocol",
+        "reference:resolved-skills",
+        "reference:composition-report",
+        "reference:authoring-lanes"
+      ],
+      "producesContentLeaves": []
+    },
+    "pause-points": {
+      "brief": "reference/subagents/pause-points-author.md",
+      "claims": ["pause:decision-points", "pause:recovery"],
+      "producesContentLeaves": [
+        "reference/decision-points.md",
+        "reference/recovery.md"
+      ]
+    },
+    "workflow-entry": {
+      "brief": "reference/subagents/workflow-entry-author.md",
+      "claims": ["workflow-entry"],
+      "producesContentLeaves": ["SKILL.md"]
+    },
+    "skill-core": {
+      "brief": "reference/subagents/skill-core-author.md",
+      "claims": [],
+      "producesContentLeaves": ["../<node-skill>/SKILL.md"]
+    },
+    "skill-review": {
+      "brief": "reference/subagents/skill-reviewer.md",
+      "claims": ["review:skill-review"],
+      "producesContentLeaves": ["reference/skill-review.md"]
+    }
+  },
+  "verify": {
+    "lenses": ["contract-fit", "usability", "evidence-trace", "self-consistency"],
+    "loopUntilDry": true
+  },
+  "merge": {
+    "deterministicBackbone": [
+      "reference/workflow-protocol.json",
+      "scripts/workflow-state.mjs",
+      "scripts/workflow-guard.mjs",
+      "scripts/workflow-handoff.mjs",
+      "scripts/comet-plan.mjs",
+      "scripts/comet-check.mjs",
+      "scripts/comet-hook-guard.mjs",
+      "bundle.yaml",
+      "comet/skill.yaml",
+      "comet/guardrails.yaml",
+      "comet/checks.yaml",
+      "comet/eval.yaml",
+      "reference/resolved-skills.json",
+      "reference/composition-report.md",
+      "reference/authoring-lanes.json"
+    ],
+    "contentLeaves": [
+      "SKILL.md",
+      "../<node-skill>/SKILL.md",
+      "reference/decision-points.md",
+      "reference/recovery.md",
+      "reference/skill-review.md"
+    ]
+  }
+}

package/assets/skills-zh/comet-any/reference/authoring-subagents.md

@@ -0,0 +1,107 @@
+# Authoring Subagents 总览
+
+## 核心原则
+
+`/comet-any` 的创作成果应由平台原生 subagent 分工产出，再交给主会话组装和后端 CLI 记录状态。
+Claude Code、Codex、Gemini、Copilot 等平台的 subagent 调用方式不同，本参考只定义职责、输入和输出；
+具体派发方式使用当前平台提供的原生 subagent 机制。
+
+`reference/subagents/*.md` 是跨平台 lane brief；Claude Code custom agent 必须单独生成到平台 agent 资源，并带 `name`、`description`、`tools`、`model` frontmatter。不要把这些 portable lane brief 直接当作 platform-native custom agent 安装。
+
+先读取本总览，再只把对应角色 brief 交给对应 subagent。不要把六个角色 brief 合并成一个大 prompt；
+主会话负责保留全局上下文、汇总成果、调用 `comet bundle` 和 `comet publish`，subagent 只产出可审查草稿。
+
+平台支持 subagent 时必须调度。没有平台 subagent 能力时，主会话可以使用同一份 brief 以内联方式完成，
+但必须在用户可读摘要和 `reference/authoring-lanes.json` 中标记为 fallback。
+
+所有 subagent 只返回 Markdown 成果和结构化审查结论，不得直接写入 Bundle state，不得执行候选 Skill 的脚本，
+不得运行发布、安装或分发命令。CLI 状态仍由主会话维护。
+
+## 角色 brief
+
+在用户确认 Skill Creator 方案后、运行 `comet creator generate` 或生成源码前，主会话按以下顺序读取并派发：
+
+1. 脚本作者 subagent：`comet-any/reference/subagents/script-author.md`
+2. reference 作者 subagent：`comet-any/reference/subagents/reference-author.md`
+3. workflow entry 作者 subagent：`comet-any/reference/subagents/workflow-entry-author.md`
+4. Skill 核心作者 subagent：`comet-any/reference/subagents/skill-core-author.md`
+5. 停顿点作者 subagent：`comet-any/reference/subagents/pause-points-author.md`
+6. Skill 审查 subagent：`comet-any/reference/subagents/skill-reviewer.md`
+
+角色文件在本 Skill 内的相对路径是：
+
+- `reference/subagents/script-author.md`
+- `reference/subagents/reference-author.md`
+- `reference/subagents/workflow-entry-author.md`
+- `reference/subagents/skill-core-author.md`
+- `reference/subagents/pause-points-author.md`
+- `reference/subagents/skill-reviewer.md`
+
+这些 subagent 的成果先落为可审查草稿，再进入 `reference/authoring-lanes.json`、`reference/skill-review.md`
+和最终 Bundle draft。若任一 subagent 报告 blocking finding，必须停在草稿修复，不得继续 ready。
+
+## 按 DAG 派发
+
+上面的角色 brief 顺序只是创作 DAG 的线性展开，并非要求严格串行。权威 DAG 在 `reference/authoring-protocol.json` 与 `comet creator authoring-plan <name> --depth quick|full --json`：
+
+- **wave1**（`script`、`reference`、`pause-points`）：彼此无依赖。在支持子代理的平台上并发派发这三个。每个只拿到自己的角色 brief、通用输入和 protocol/resolved-skills 路径（文件交接，不共享历史）。
+- **wave2**（`workflow-entry`、`skill-core`）：依赖 script 契约（`NEXT:`/`SKILL:` 输出）。仅在 script lane DONE 后开始。两者之间可并发。
+- **barrier**（`skill-review`）：唯一同步点。仅在 wave1 与 wave2 全部 DONE 后运行；审查者必须读取所有 artifact 与 claim。
+
+无论平台如何：
+
+- 编排遵循 DAG 依赖；只有 barrier 真正等待此前所有 lane。
+- 不支持子代理的平台，主会话按依赖顺序内联执行同样的 lane——语义完全一致，仅延迟不同。在 `reference/authoring-lanes.json` 中按 lane 记录 `dispatchMode: "subagent"` 或 `"inline"`。
+- Claude Code 可把某个 wave 的扇出委托给其 `Workflow` 工具作为可选加速器；这是实现选择，不是契约的一部分。契约是 protocol + schemas + DAG，任何平台都能解释。
+- 每个 lane 产出在下一个依赖 wave 开始前，必须经 `comet creator authoring-record <name> --lane <id> --file <out.json> --json` 校验并记录。
+
+## 通用输入
+
+每个 subagent 都必须拿到同一组上下文：
+
+- 用户确认的目标、起点和语言。
+- `plan.json` 中的 `goal`、`workflow.kind`、`workflow.nodes`、`engineMode`、`runnerMode`，以及规范化后的 `workflow-protocol.json`。
+- `reference/resolved-skills.json` 或等价的真实 Skill 来源摘要。
+- `reference/workflow-protocol.json` 或即将写入该文件的 workflow protocol。
+- `/comet` 定制场景下的受保护边界：`open / design / build / verify / archive`、`.comet.yaml`、decision point、verify-result-transition、archive-delta-sync。
+- 项目级偏好、缺失/歧义候选处理结果、偏离原因、scripts/hooks 可执行披露。
+
+## 输出格式
+
+每个 subagent 返回：
+
+```json
+{
+  "lane": "<lane-name>",
+  "artifacts": [
+    {
+      "path": "reference/example.md",
+      "kind": "reference",
+      "content": "..."
+    }
+  ],
+  "claims": [
+    {
+      "id": "reference:example",
+      "kind": "reference",
+      "paths": ["reference/example.md"],
+      "summary": "说明该成果保证了什么"
+    }
+  ],
+  "findings": []
+}
+```
+
+`claims` 是审查依据，不是装饰字段。缺少关键 claim 时，Skill 审查 subagent 必须阻塞。
+
+## 派发注意事项
+
+- 每次派发必须创建新的 subagent，不得继承主会话历史。主会话只提供该角色需要的 brief、输入路径和必要背景。
+- 必须显式指定 model；平台不支持 model 选择时，在 `reference/authoring-lanes.json` 记录为 platform-default。
+- 使用文件交接：主会话提供路径，不粘贴大段全文。通用输入、来源 Skill 摘要、草稿 artifact 和报告都应以路径交接。
+- 每个 subagent 只接收自己的角色 brief、通用输入和必要 artifact，不接收其他角色的完整 brief。
+- Skill 审查 subagent 必须在其他五个作者角色产出后运行，并读取所有 artifacts 与 claims。
+- 主会话可以要求某个角色返工，但返工结果仍必须回到 `reference/authoring-lanes.json` 和 `reference/skill-review.md`。
+- subagent 不能调用 `comet bundle`、`comet publish`、`comet skill`，也不能执行候选 Skill 的脚本。
+- 如果状态是 `BLOCKED` 或 `NEEDS_CONTEXT`，主会话必须补上下文、拆小任务、换更强模型或询问用户；不得继续组装。
+- 没有平台 subagent 能力时，内联 fallback 必须保留相同的 lane、claim 和 finding 结构。