feat: recommend lightweight Comet workflow paths

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to @rpamis/comet will be documented in this file.
 
+## What's Changed [0.4.0-beta.12] - 2026-07-30
+
+### Added
+
+- **Lightweight workflow recommendations**: Classic Comet now exposes `classic.recommend_lightweight_workflows` and typed route recommendation metadata so evidence-backed tweak or hotfix candidates can present confirmed lightweight workflow options before continuing full open, while risk signals keep the conservative full workflow path.
+
 ## What's Changed [0.4.0-beta.11] - 2026-07-29
 
 ### Changed

README-zh.md

@@ -143,6 +143,7 @@ classic:
   artifact_layout: docs
   language: zh-CN
   context_compression: off
+  recommend_lightweight_workflows: true
   review_mode: standard
   auto_transition: true
 ```

README.md

@@ -160,6 +160,7 @@ classic:
   artifact_layout: docs
   language: en
   context_compression: off
+  recommend_lightweight_workflows: true
   review_mode: standard
   auto_transition: true
 ```

assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.0-beta.11",
+  "version": "0.4.0-beta.12",
   "skills": [
     "comet/SKILL.md",
     "comet-classic/SKILL.md",

assets/skills-zh/comet-open/SKILL.md

@@ -57,7 +57,18 @@ comet classic openspec -- --version
 
 澄清摘要必须包含：目标、非目标、范围边界、关键未知项、验收场景草案。
 
-### 1a. PRD 拆分预检（阻塞点）
+### 1a. 轻量路径推荐确认（阻塞点）
+
+当 Comet intent runtime 返回轻量路径推荐 metadata 时，必须在创建 OpenSpec artifacts 前展示推荐理由，并按用户决策点协议暂停等待用户选择。
+
+选项必须直接来自 runtime 返回的 `recommendation.options`，不得自行推断或硬编码 tweak/hotfix 可用性。每个选项必须互斥：
+- `tweak` → 「切换到 `/comet-tweak`」，由 tweak workflow 创建并拥有 change
+- `hotfix` → 「切换到 `/comet-hotfix`」，仅当 runtime recommendation options 包含 `hotfix` 时展示
+- `full` → 「继续 full `/comet-open`」，保持完整 OpenSpec + Design 流程
+
+不得在轻量路径推荐确认前运行 `comet classic openspec -- new change`，不得创建 proposal/design/tasks，也不得自动把 full 请求降级为 tweak/hotfix。
+
+### 1b. PRD 拆分预检（阻塞点）
 
 当用户输入是大型 PRD、路线图、完整产品方案，或澄清摘要显示包含多个独立能力、模块、用户路径或里程碑时，必须在创建 OpenSpec artifacts 前评估是否需要拆分为多个 change。
 
@@ -112,7 +123,7 @@ comet state check <name> design
 
 断点恢复时先读取 `.comet/batches/<batch-id>.json`，再对清单中已创建的 active changes 运行上述 CLI 检查；已完整通过的拆分项不得重复创建，未通过的拆分项从 OpenSpec 返回的第一个 `ready` artifact 继续。未创建项按持久清单继续创建。清单缺失或损坏时停止并请求用户重建/确认，不能从目录列表猜测原始批次边界。
 
-### 1b. 需求与 Change 名称解析（默认不阻塞）
+### 1c. 需求与 Change 名称解析（默认不阻塞）
 
 创建 OpenSpec artifacts 前，把 Step 1 的澄清结果整理为 resolved brief：目标、非目标、范围边界、关键未知项和验收场景草案，并基于它派生一个能准确表达范围的 kebab-case 英文 change 名称。
 
@@ -137,9 +148,9 @@ resolved brief 或 change 名称仍不明确时不得运行 `comet classic opens
 <!-- external-openspec-skill-override -->
 **外部 OpenSpec Skill 覆写：** 对 `openspec-propose` 同样不得采用其直接官方 CLI、固定 cwd 或固定物理 OpenSpec 路径；命令必须通过 adapter，产物必须写入 resolver 返回的 `<classic-*>` 逻辑根。
 
-技能加载后，按其指引创建 change 骨架；当 Step 1b 已形成范围明确的 resolved brief 时，覆盖其"STOP and wait for user direction"行为，避免重复询问。
+技能加载后，按其指引创建 change 骨架；当 Step 1c 已形成范围明确的 resolved brief 时，覆盖其"STOP and wait for user direction"行为，避免重复询问。
 
-直接使用 Step 1b 的 resolved brief 填充产物内容。只有 brief 仍有会改变范围的歧义时，才回退到技能的提问流程。
+直接使用 Step 1c 的 resolved brief 填充产物内容。只有 brief 仍有会改变范围的歧义时，才回退到技能的提问流程。
 
 change 骨架创建后立即初始化可恢复状态，不能等 artifacts 全部生成后再写 `.comet.yaml`：
 
@@ -180,7 +191,7 @@ comet state check <name> open
 
 **阻塞与失败处理**：`applyRequires` 尚未全部完成但没有任何可推进其依赖闭包的 ready artifact 时，必须报告相关 `blocked` artifact 的 `missingDeps` 并停止，不得猜测顺序或跳过依赖。如果 adapter 的 `status` / `instructions` 调用失败、返回无效 JSON、路径逃逸仓库、或未提供可用的 `resolvedOutputPath`，也必须立即停止并报告 OpenSpec 错误。不得回退为硬编码文档结构。
 
-**命名与范围守卫**：change name 必须使用 Step 1b 解析出的 kebab-case 英文名，不得使用非 kebab-case（如中文）名称。变更范围必须与 resolved brief 和用户描述一致，不得自行扩大或缩小。
+**命名与范围守卫**：change name 必须使用 Step 1c 解析出的 kebab-case 英文名，不得使用非 kebab-case（如中文）名称。变更范围必须与 resolved brief 和用户描述一致，不得自行扩大或缩小。
 
 确认以下产物已创建：
 
@@ -224,7 +235,7 @@ comet state check <name> open
 
 全部 OpenSpec artifacts 完成且内容完整性检查通过后，**必须按 `comet/reference/decision-point.md` 的协议暂停并等待用户确认**。不得在用户确认前执行阶段守卫或自动流转。
 
-最终审视同时确认 change 名称、范围和产物内容；不得因 Step 1b 已完成解析而省略，也不得在此之前再增加一次常规摘要/命名确认。
+最终审视同时确认 change 名称、范围和产物内容；不得因 Step 1c 已完成解析而省略，也不得在此之前再增加一次常规摘要/命名确认。
 
 用户确认问题必须以单选题形式呈现，包含以下摘要和选项：
 

assets/skills/comet-native/scripts/comet-native-runtime.mjs

@@ -8049,6 +8049,7 @@ var COMMENTS = {
     "classic.artifact_layout": "# Selects the Classic artifact layout. The default is docs; update preserves detected root-level legacy artifacts.\n# artifact_layout: legacy | docs",
     "classic.language": "# Artifact language used by Classic workflow documents.\n# language: en | zh-CN",
     "classic.context_compression": "# Controls beta context compression for new Classic changes.\n# context_compression: off | beta",
+    "classic.recommend_lightweight_workflows": "# Controls whether Classic can recommend tweak or hotfix before continuing full open.\n# recommend_lightweight_workflows: true | false",
     "classic.review_mode": "# Sets the default review depth for new Classic changes.\n# review_mode: off | standard | thorough",
     "classic.auto_transition": "# Automatically enters the next Classic phase after a phase passes.\n# auto_transition: true | false"
   },
@@ -8073,6 +8074,7 @@ var COMMENTS = {
     "classic.artifact_layout": "# Classic 产物布局；默认使用 docs，update 检测到根目录 legacy 产物时予以保留。\n# 可选值：legacy | docs",
     "classic.language": "# Classic 工作流文档使用的产物语言。\n# 可选值：en | zh-CN",
     "classic.context_compression": "# 新建 Classic change 是否启用 beta 上下文压缩。\n# 可选值：off | beta",
+    "classic.recommend_lightweight_workflows": "# 是否允许 Classic 在进入完整 open 前推荐 tweak 或 hotfix。\n# 可选值：true | false",
     "classic.review_mode": "# 新建 Classic change 默认使用的审查深度。\n# 可选值：off | standard | thorough",
     "classic.auto_transition": "# Classic 阶段通过后是否自动进入下一阶段。\n# 可选值：true | false"
   }
@@ -8332,6 +8334,10 @@ function normalizeWorkflowClassicProjectConfig(value) {
   if (reviewMode !== "off" && reviewMode !== "standard" && reviewMode !== "thorough") {
     throw new Error("classic.review_mode must be off, standard, or thorough");
   }
+  const recommendLightweightWorkflows = classic.recommend_lightweight_workflows ?? true;
+  if (typeof recommendLightweightWorkflows !== "boolean") {
+    throw new Error("classic.recommend_lightweight_workflows must be true or false");
+  }
   const autoTransition = classic.auto_transition ?? true;
   if (typeof autoTransition !== "boolean") {
     throw new Error("classic.auto_transition must be true or false");
@@ -8340,6 +8346,7 @@ function normalizeWorkflowClassicProjectConfig(value) {
     artifact_layout: normalizeClassicArtifactLayout(classic.artifact_layout),
     language: projectConfigLanguage(classic.language, "zh-CN", "classic.language"),
     context_compression: contextCompression,
+    recommend_lightweight_workflows: recommendLightweightWorkflows,
     review_mode: reviewMode,
     auto_transition: autoTransition
   };
@@ -8448,6 +8455,7 @@ function workflowProjectConfigManagedValue(config) {
         artifact_layout: config.classic.artifact_layout,
         language: config.classic.language,
         context_compression: config.classic.context_compression,
+        recommend_lightweight_workflows: config.classic.recommend_lightweight_workflows,
         review_mode: config.classic.review_mode,
         auto_transition: config.classic.auto_transition
       }
@@ -8504,6 +8512,7 @@ function mergeWorkflowProjectConfigDocument(existing, config) {
       artifact_layout: validated.classic.artifact_layout,
       language: validated.classic.language,
       context_compression: validated.classic.context_compression,
+      recommend_lightweight_workflows: validated.classic.recommend_lightweight_workflows,
       review_mode: validated.classic.review_mode,
       auto_transition: validated.classic.auto_transition
     };

assets/skills/comet-open/SKILL.md

@@ -57,7 +57,18 @@ After the skill loads, explore the problem space following its guidance, but do
 
 The clarification summary must include: goals, non-goals, scope boundaries, key unknowns, and draft acceptance scenarios.
 
-### 1a. PRD Split Preflight (Blocking Point)
+### 1a. Lightweight Path Recommendation Confirmation (Blocking Point)
+
+When the Comet intent runtime returns lightweight path recommendation metadata, present the recommendation reasons before creating OpenSpec artifacts, then pause under the user decision-point protocol.
+
+Options must be built directly from the runtime's `recommendation.options`; do not infer or hardcode tweak/hotfix availability independently. Each option must be mutually exclusive:
+- `tweak` -> "Switch to `/comet-tweak`" — the tweak workflow creates and owns the change
+- `hotfix` -> "Switch to `/comet-hotfix`" — shown only when runtime recommendation options include `hotfix`
+- `full` -> "Continue full `/comet-open`" — keep the full OpenSpec + Design workflow
+
+The agent must not run `comet classic openspec -- new change` before lightweight path recommendation confirmation, must not create proposal/design/tasks, and must not automatically downgrade a full request to tweak/hotfix.
+
+### 1b. PRD Split Preflight (Blocking Point)
 
 When the user input is a large PRD, roadmap, complete product plan, or the clarification summary shows multiple independent capabilities, modules, user journeys, or milestones, must evaluate whether it should be split into multiple changes before creating OpenSpec artifacts.
 
@@ -112,7 +123,7 @@ Only after every split item passes both CLI checks may you pause and ask which c
 
 On resume, read `.comet/batches/<batch-id>.json` first, then run the CLI checks above for already-created active changes. Do not recreate items that fully pass; resume incomplete items from the first `ready` artifact returned by OpenSpec. Create missing items from the persisted manifest. If the manifest is missing or damaged, stop and ask the user to rebuild/confirm it instead of inferring the original batch boundary from directory names.
 
-### 1b. Resolve Requirements and Change Name (Non-blocking by Default)
+### 1c. Resolve Requirements and Change Name (Non-blocking by Default)
 
 Before creating OpenSpec artifacts, turn Step 1 clarification into a resolved brief containing the goal, non-goals, scope boundaries, key unknowns, and draft acceptance scenarios. Derive one kebab-case English change name that accurately represents that scope.
 
@@ -137,9 +148,9 @@ Full `/comet-classic` workflow must not use the Skill tool to load the `openspec
 <!-- external-openspec-skill-override -->
 **External OpenSpec Skill override:** Apply the same rule to `openspec-propose`: ignore direct official CLI, fixed-cwd, and fixed physical OpenSpec path instructions; use the adapter and resolver-returned `<classic-*>` logical roots.
 
-After the skill loads, follow its guidance to create the change skeleton. When Step 1b has produced an unambiguous resolved brief, override its "STOP and wait for user direction" behavior to avoid a duplicate question.
+After the skill loads, follow its guidance to create the change skeleton. When Step 1c has produced an unambiguous resolved brief, override its "STOP and wait for user direction" behavior to avoid a duplicate question.
 
-Use the Step 1b resolved brief directly to populate artifact content. Fall back to the skill's question flow only when ambiguity remains that would change scope.
+Use the Step 1c resolved brief directly to populate artifact content. Fall back to the skill's question flow only when ambiguity remains that would change scope.
 
 Immediately after creating the change skeleton, initialize recoverable state instead of waiting until every artifact is generated:
 
@@ -180,7 +191,7 @@ After preflight, generate the implementation-required artifacts from the OpenSpe
 
 **Blocking and failure handling**: if `applyRequires` is incomplete and no ready artifact can advance its dependency closure, report `missingDeps` for the relevant `blocked` artifacts and stop. Do not guess order or skip dependencies. Also stop if status/instructions fails, returns invalid JSON, escapes the repository, or provides no usable `resolvedOutputPath`. Must not fall back to hard-coded artifact prose.
 
-**Naming and scope guard**: Use the kebab-case English name resolved in Step 1b; never use a non-kebab-case name. Change scope must match the resolved brief and user request; do not expand or narrow it independently.
+**Naming and scope guard**: Use the kebab-case English name resolved in Step 1c; never use a non-kebab-case name. Change scope must match the resolved brief and user request; do not expand or narrow it independently.
 
 Confirm the following artifacts have been created:
 
@@ -224,7 +235,7 @@ Then check key artifact content: proposal covers problem, goals, scope, and non-
 
 After all OpenSpec artifacts are complete and the content check passes, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for user confirmation**. Must not execute the phase guard or auto-transition before user confirmation.
 
-The final review confirms the change name, scope, and artifact content together. Do not skip it because Step 1b resolved the brief, and do not add another routine summary/name confirmation before it.
+The final review confirms the change name, scope, and artifact content together. Do not skip it because Step 1c resolved the brief, and do not add another routine summary/name confirmation before it.
 
 The user confirmation question must be presented as a single-select question with the following summary and options:
 

assets/skills/comet/scripts/comet-entry-runtime.mjs

@@ -7597,6 +7597,10 @@ function normalizeWorkflowClassicProjectConfig(value) {
   if (reviewMode !== "off" && reviewMode !== "standard" && reviewMode !== "thorough") {
     throw new Error("classic.review_mode must be off, standard, or thorough");
   }
+  const recommendLightweightWorkflows = classic.recommend_lightweight_workflows ?? true;
+  if (typeof recommendLightweightWorkflows !== "boolean") {
+    throw new Error("classic.recommend_lightweight_workflows must be true or false");
+  }
   const autoTransition = classic.auto_transition ?? true;
   if (typeof autoTransition !== "boolean") {
     throw new Error("classic.auto_transition must be true or false");
@@ -7605,6 +7609,7 @@ function normalizeWorkflowClassicProjectConfig(value) {
     artifact_layout: normalizeClassicArtifactLayout(classic.artifact_layout),
     language: projectConfigLanguage(classic.language, "zh-CN", "classic.language"),
     context_compression: contextCompression,
+    recommend_lightweight_workflows: recommendLightweightWorkflows,
     review_mode: reviewMode,
     auto_transition: autoTransition
   };

assets/skills/comet/scripts/comet-hook-router.mjs

@@ -7589,6 +7589,10 @@ function normalizeWorkflowClassicProjectConfig(value) {
   if (reviewMode !== "off" && reviewMode !== "standard" && reviewMode !== "thorough") {
     throw new Error("classic.review_mode must be off, standard, or thorough");
   }
+  const recommendLightweightWorkflows = classic.recommend_lightweight_workflows ?? true;
+  if (typeof recommendLightweightWorkflows !== "boolean") {
+    throw new Error("classic.recommend_lightweight_workflows must be true or false");
+  }
   const autoTransition = classic.auto_transition ?? true;
   if (typeof autoTransition !== "boolean") {
     throw new Error("classic.auto_transition must be true or false");
@@ -7597,6 +7601,7 @@ function normalizeWorkflowClassicProjectConfig(value) {
     artifact_layout: normalizeClassicArtifactLayout(classic.artifact_layout),
     language: projectConfigLanguage(classic.language, "zh-CN", "classic.language"),
     context_compression: contextCompression,
+    recommend_lightweight_workflows: recommendLightweightWorkflows,
     review_mode: reviewMode,
     auto_transition: autoTransition
   };