@rpamis/comet 0.3.9 → 0.4.0-beta.1

package/assets/skills/comet/scripts/comet-state.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './comet-runtime.mjs';
+process.exitCode = await main(["state", ...process.argv.slice(2)]);

package/assets/skills/comet/scripts/comet-yaml-validate.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from './comet-runtime.mjs';
+process.exitCode = await main(["validate", ...process.argv.slice(2)]);

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

@@ -0,0 +1,118 @@
+---
+name: comet-any
+description: "Use when the user wants to customize Comet five-phase skills, create a workflow skill, organize an existing skill, or compose skills with Workflow Node / Skill Binding / Output Schema."
+---
+
+# Comet Any - Skill Creator
+
+`/comet-any` is the Comet Skill creation guide. The user describes the workflow they want; this Skill resolves real Skills, proposes a plan, waits for confirmation, generates a verifiable Comet-native Skill Bundle, and internally drives eval, review, publish readiness, and install preview.
+
+Ordinary users see three starting points:
+
+- `customize existing Comet Skills`: overlay the existing five phase Skills for `open / design / build / verify / archive` without modifying the `/comet` command itself.
+- `create a new workflow Skill`: generate a new `workflow-kernel` from the goal and candidate Skills.
+- `upgrade an existing Skill`: read existing Skills and add Workflow Nodes, Skill Bindings, Output Schemas, Guardrails, Handoffs, eval, and readiness.
+
+Bundle, Factory, and composition are backend audit terms, not the first-screen user model.
+
+## Core Model
+
+Every path compiles to one Workflow Contract:
+
+- `Workflow Node`: a resumable workflow node such as `open`, `design`, `plan`, `execute`, `subagent-execute`, `review`, `verify`, or `archive`.
+- `Node Responsibility`: the responsibility this Node owns in the Agent workflow, explaining why it exists, what it must produce, and whether it can be replaced.
+- `Skill Binding`: the implementation or helper Skill bound to a Node.
+- `Required Skill Call`: a Skill that must be called inside a Node without replacing the Node implementation. For example, `execute` and `subagent-execute` may require `elementui`, while `review` may require `whitebox-code-standard`.
+- `Output Schema`: the artifacts, state, or evidence a Node must produce. Output Schema must be attached to a concrete Workflow Node before it is effective; defining it only in `workflow.outputSchemas` does not trigger guard, eval, or readiness. Scripts, eval, and readiness depend on Node-attached Output Schemas, not Skill names.
+- `Guardrail`: a check that blocks or allows Node advancement.
+- `Handoff`: evidence returned by a subagent or cross-Node delegation.
+- `workflow-protocol.json`: the package's single runtime source of truth, with kind `comet-five-phase-overlay` or `workflow-kernel`.
+
+## Protected Boundary
+
+`comet-five-phase-overlay` preserves the Comet control flow and `.comet.yaml` state semantics. In ordinary mode:
+
+- `comet-five-phase-overlay` primary state comes only from `openspec/changes/<name>/.comet.yaml`; no active change or multiple active changes must block and ask the user to choose.
+- The overlay must not create `.comet/runs/<workflow>/state.json` as the Comet overlay primary state. Bundle drafts, eval evidence, and publish readiness may keep their own evidence files, but they cannot replace `.comet.yaml`.
+- `control` Nodes cannot be overridden: `open`, `execute`, `verify`, `archive`.
+- `producer` Nodes may be overridden: `design`, `plan`, but only when the replacement satisfies the matching Output Schema.
+- `handoff` and `guardrail` Nodes may require or augment Skills.
+- If the user insists on replacing a control Node, switch to advanced `workflow-kernel` and require a new state model, Output Schemas, and Guardrails.
+- Every Node must explain its responsibility; internal coordinates are not part of the user-facing workflow model.
+
+## Steps
+
+1. Resume state: run `comet creator guide --project . --json` and show a resume summary.
+2. Read preferences: load `.comet/skill-preferences.yaml`, then use `comet creator candidates --json` to discover real local Skills and `comet skill show <name> --json` to read each candidate's real content and hash. Do not guess capability from a Skill name.
+3. Build proposal: express the goal as Workflow Nodes, Skill Bindings, Output Schemas, Guardrails, Handoffs, and Evidence.
+4. Show confirmation: list each Node, bound Skill, Required Skill Call, Output Schema, executable disclosure, and readiness impact. The confirmation must show enforcement for each new binding or schema: `guarded`, `handoff-guarded`, `evidence-only`, or `advisory`.
+5. Wait for confirmation: do not write a Bundle draft before confirmation; pause for missing or ambiguous Skills.
+6. Initialize backend state: after confirmation, call `comet creator init <name> --file <plan.json> --confirmed-proposal --json`.
+7. Run the authoring pipeline and generate the Bundle: run `comet creator authoring-plan <name> --depth quick|full --json` for the lane DAG. Dispatch lanes by the DAG — wave1 (`script`, `reference`, `pause-points`) in parallel where the platform supports subagents (otherwise inline, in dependency order), wave2 (`workflow-entry`, `skill-core`) after the script contract, and `skill-review` as the barrier. Record each lane via `comet creator authoring-record <name> --lane <id> --file <out.json> --json` (schema-validated; BLOCKED/NEEDS_CONTEXT is rejected). Then run `comet creator generate <name> --json`; it merges recorded content-leaf drafts (entry/node SKILL.md, decision-points, recovery) into the package while the deterministic backbone (protocol/scripts/manifest) stays templated, and renders real review evidence. Outputs entry Skill, Node Skills, `reference/workflow-protocol.json`, the six scripts, rules, hooks, and `comet/eval.yaml`.
+8. Validate: show quick/full eval workload and run or record current draft hash eval evidence; failed eval, skipped eval, or stale-hash evidence cannot become ready.
+9. Review readiness: read `comet publish review <name> --platform <reference-platform> --json` and show `Readiness:`, `Blockers:`, `Warnings:`, and `Evidence:`.
+10. Publish and install preview: publish only after human approval; installation must start with preview and show `No files were written`.
+
+## Plan Example
+
+Component-library and whitebox-review requirements should produce a plan like:
+
+```json
+{
+  "goal": "Customize existing Comet Skills with component and whitebox review requirements.",
+  "skillCreatorIntent": "customize-comet",
+  "workflow": {
+    "kind": "comet-five-phase-overlay",
+    "name": "team-comet",
+    "goal": "Require component and whitebox review Skills.",
+    "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"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+## Hard Rules
+
+- Show the proposal confirmation page before generation.
+- The confirmation must show enforcement for each new binding or schema: `guarded`, `handoff-guarded`, `evidence-only`, or `advisory`.
+- A Required Skill Call does not replace Node implementation.
+- A producer override must declare the Output Schema it satisfies.
+- Output Schema must be attached to a concrete Workflow Node before it is effective; defining it only in `workflow.outputSchemas` does not trigger guard, eval, or readiness.
+- Ordinary mode must not override control Nodes.
+- Eval, review, and publish readiness must read the same `workflow-protocol.json`.
+- Readiness blockers must stop publish: missing current draft hash eval evidence, missing human approval, required capability gaps, or unconfirmed executable disclosures cannot become ready.
+- Handoff must require subagents to load Required Skill Calls and return evidence.
+- Scripts read protocol and state; they do not use Skill names as validation authority.
+- Ask before installation. Never install automatically.
+
+## References
+
+- `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/comet-any/reference/authored-zone-example.md

@@ -0,0 +1,100 @@
+# Authored Zone Quality Bar (example)
+
+This is a concrete quality bar for the **Authored zone** you write (`## Decision Core` for the entry, `## Guidance` for nodes). The generator composes your Authored zone onto a deterministic **Auto zone** (frontmatter, route table, Entry/Exit checks, evidence format, recovery). You write ONLY the Authored zone. Calibrate against this example, not against a one-line boilerplate node.
+
+## What "Auto" vs "Authored" means
+
+- **Auto zone (template, do not rewrite)**: the invariant control plane. For a node: `## Node Goal`, `## Entry Check`, `## Skill Implementation`, `## Required Skill Calls`, `## Output Schemas`, `## Evidence Record`, `## Guardrails`, `## Exit Check`, `## Recovery`. For the entry: `## Workflow Nodes`, `## Skill Bindings`, `## Guardrails And Evidence`, `## Runtime And Recovery`.
+- **Authored zone (you write)**: the domain decisions the Auto zone cannot know. This is what makes the Skill usable, not just runnable.
+
+## Example: a `substance` node Guidance zone (workflow-kernel)
+
+This is the `## Guidance` body for a "Research" producer node in a research-writer workflow. Notice it is **decision content**: prerequisites, ordered domain steps, completion judgment beyond the mechanical Exit Check, and red flags. It references the bound Skill by name without copying its body.
+
+```markdown
+## Prerequisites
+
+- The entry Decision Core has confirmed the research topic and scope.
+- `research-skill` is resolvable in the project Skill pool; if missing, stop and ask the user before improvising.
+
+## Steps
+
+1. Load `research-skill` and follow its discovery method for the confirmed topic. Do not substitute a generic web search when the project Skill defines a specific source order.
+2. Gather sources in priority order; for each source, capture origin, date, and the claim you will reuse. Reject sources that fail the project's credibility bar rather than noting them as "weak".
+3. Distill findings into note files under `notes/*.md` — one note per distinct claim, with a verbatim quote and the source pointer. Synthesis happens in the writer node, not here.
+4. Record the `research.notes.v1` `summary` evidence with a one-paragraph distillation and the count of notes produced.
+
+## Completion reasoning
+
+This node is complete ONLY when both hold: (a) the `summary` evidence is recorded, and (b) at least one artifact matches `notes/*.md`. Do not exit merely because the step list is exhausted — if notes are sparse relative to the topic scope, continue researching rather than declaring done. The Exit Check script enforces the artifact + evidence requirement mechanically; your job is to judge whether the research is genuinely sufficient.
+
+## Red flags
+
+- Exiting after recording `summary` but producing zero `notes/*.md` files (the guardrail will block this — do not attempt to bypass).
+- Copying source text into notes without a quote marker or source pointer.
+- Advancing to the Write node while a source is still "to be verified" — verification belongs in this node.
+- Treating a single source as sufficient for a multi-perspective topic.
+```
+
+Use `###` subsections so they nest under `## Guidance`. The four sections above (Prerequisites / Steps / Completion reasoning / Red flags) are the expected shape for a `substance` node.
+
+## Example: an entry Decision Core (workflow-entry)
+
+This is the `## Decision Core` body for the entry SKILL.md. The entry is the **most-loaded file** — every invocation reads it first. A thin Decision Core ("run next, load what it says") makes the entire Skill feel mechanical. A rich Decision Core is what makes comet-level Skills feel intelligent.
+
+The Decision Core should model three concerns that the Auto zone does NOT handle: (1) **semantic current-Node detection** (how to determine which Node the user is in, beyond script output), (2) **resume and drift rules** (what to do when context resumes or state conflicts with files), and (3) **decision points and red flags** (where to pause for the user, and what false progress looks like).
+
+```markdown
+### Automatic Node Detection
+
+**Step 0: Determine the current Node and intent**
+
+1. Check the workflow protocol for the ordered Node list. The first incomplete Node (no recorded Exit evidence) is the candidate current Node.
+2. If the user's message describes work that clearly belongs to a later Node (e.g., "verify the results" when research is not complete), pause and explain: the earlier Node must finish before the later one starts. Do not skip ahead.
+3. If the user's message describes work that belongs to an earlier Node that is already marked complete, treat this as a correction — reset that Node's completion and re-enter it.
+
+**Step 1: Read workflow state**
+
+Run `node "$WORKFLOW_STATE" status` to confirm the detected Node. If the script's `NEXT:` output conflicts with file evidence (e.g., script says DONE but no artifacts exist), trust file evidence and correct state before continuing.
+
+**Resume rules**:
+- On every context resume, rerun Step 0 and Step 1. Do not trust conversation history for Node detection.
+- If workflow state shows a Node as complete but its expected artifacts are missing, treat the Node as incomplete and re-enter it.
+- If the user resumes mid-Node with a different topic, confirm whether to continue the current Node or start a new one.
+
+### Decision Points (must pause)
+
+| Situation | Action |
+|-----------|--------|
+| First invocation, no workflow state exists | Initialize state, confirm the topic/scope with the user before starting the first Node |
+| User input is ambiguous between two Nodes | Ask the user which Node they mean; do not guess |
+| Node requires user approval of output before advancing | Stop after recording evidence; wait for explicit confirmation |
+| Node fails its guard and the cause is unclear | Present the guard output and ask the user how to proceed |
+
+### Red Flags
+
+| Agent Thought | Actual Risk |
+|--------------|-------------|
+| "The user mentioned the topic, so research is implicitly confirmed" | Mentioning ≠ confirming. Pause at the first Node boundary and confirm scope. |
+| "The script returned NEXT: auto, so I should immediately load the next Skill" | `NEXT: auto` means the Node is done, not that you should skip confirmation. Check if the next Node has a decision point. |
+| "This looks like the same topic as last time, resume from where we left off" | Always re-read state. Conversation memory is unreliable after context compaction. |
+| "The exit check passed, so the work is good enough" | Exit checks are mechanical. Your job is to judge quality beyond the check — sparse notes, shallow analysis, or missing perspectives are not caught by scripts. |
+```
+
+This example models comet's Decision Core in miniature: semantic detection (Step 0 reads Node order, not just script output), state-fidelity (trust files over stale state), resume rules (re-detect on every resume), blocking decision points (explicit table), and red flags (the "thought → risk" pattern that catches agent self-deception).
+
+## substance vs delegates
+
+- **substance** node (workflow-kernel): the example above is the bar. Rich Guidance is mandatory; without it the node renders `AUTHORING PENDING` and the Bundle cannot become ready.
+- **delegates** node (comet-five-phase-overlay, delegating to an installed rich Skill): the delegate carries the execution richness, so do NOT duplicate it. But if the node declares **Required Skill Calls** (e.g. require `elementui` at the execute node), author a focused integration note — when, during the delegate's flow, the required Skill must be loaded and what evidence it adds — rather than a generic "load X" line. Example for a delegates execute node requiring `elementui`:
+
+```markdown
+This node runs `comet-build` for execution. In addition to that flow, load `elementui` whenever a change touches the component library, and confirm the change uses project-approved components before recording the `required-skill:execute.elementui` check. Do not re-implement what `comet-build` already does.
+```
+
+## Anti-patterns (do not write)
+
+- A one-line Guidance like "Run this node and record evidence." — that is what the Auto zone already implies; it adds nothing.
+- Copying the bound Skill's body verbatim.
+- Restating the route table or the Output Schema list (already in the Auto zone).
+- No `### Red flags` section on a substance node — red flags are where most of the real-world value lives.

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

@@ -0,0 +1,91 @@
+{
+  "schemaVersion": 1,
+  "description": "Deterministic authoring contract for /comet-any. The main session interprets this protocol, symmetric to how runtime scripts interpret workflow-protocol.json. The backend (domains/bundle/authoring.ts) mirrors these constants.",
+  "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/comet-any/reference/authoring-subagents.md

@@ -0,0 +1,102 @@
+# Authoring Subagents Overview
+
+## Core Principles
+
+`/comet-any` authoring outputs should be drafted by platform-native subagents, then assembled and recorded by the main session through the backend CLI. Claude Code, Codex, Gemini, Copilot, and other platforms expose subagents differently; this reference defines responsibilities, inputs, and outputs, not a provider-specific dispatch API.
+
+`reference/subagents/*.md` are portable lane briefs; Claude Code custom agents must be generated separately as platform agent resources with `name`, `description`, `tools`, and `model` frontmatter. Do not install these portable lane briefs directly as platform-native custom agent resources.
+
+Read this overview first, then give only the matching role brief to each subagent. Do not merge the six role briefs into one large prompt. The main session keeps global context, aggregates outputs, and calls `comet bundle` and `comet publish`; subagents only produce reviewable drafts.
+
+When the platform supports subagents, dispatch is required. If no platform subagent capability exists, the main session may execute the same briefs inline, but must mark that path as fallback in the user-facing summary and `reference/authoring-lanes.json`.
+
+All subagents only return Markdown outputs and structured review findings. They must not write Bundle state directly, execute candidate Skill scripts, or run publish, install, or distribution commands. CLI state remains owned by the main session.
+
+## Role Briefs
+
+After the user confirms the Skill Creator proposal, and before `comet creator generate` or source generation, the main session reads and dispatches these briefs in order:
+
+1. Script author subagent: `comet-any/reference/subagents/script-author.md`
+2. Reference author subagent: `comet-any/reference/subagents/reference-author.md`
+3. Workflow entry author subagent: `comet-any/reference/subagents/workflow-entry-author.md`
+4. Skill core author subagent: `comet-any/reference/subagents/skill-core-author.md`
+5. Pause point author subagent: `comet-any/reference/subagents/pause-points-author.md`
+6. Skill review subagent: `comet-any/reference/subagents/skill-reviewer.md`
+
+The relative paths inside this Skill are:
+
+- `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 outputs first become reviewable drafts, then flow into `reference/authoring-lanes.json`, `reference/skill-review.md`, and the final Bundle draft. If any subagent reports a blocking finding, stop in draft repair and do not continue to ready.
+
+## Dispatch by DAG
+
+The Role Briefs order above is a linearization of the authoring DAG, not a mandate to run strictly sequential. The authoritative DAG lives in `reference/authoring-protocol.json` and `comet creator authoring-plan <name> --depth quick|full --json`:
+
+- **wave1** (`script`, `reference`, `pause-points`): no dependencies on each other. On platforms that expose subagents, dispatch these three concurrently. Each gets only its own role brief, common input, and the protocol/resolved-skills paths (file handoff, no shared history).
+- **wave2** (`workflow-entry`, `skill-core`): depend on the script contract (`NEXT:`/`SKILL:` outputs). Start only after the script lane is DONE. The two may run concurrently with each other.
+- **barrier** (`skill-review`): the single synchronization point. Run only after wave1 and wave2 are all DONE; the reviewer must read every artifact and claim.
+
+Regardless of platform:
+
+- Sequencing follows DAG dependencies; only the barrier truly waits for all prior lanes.
+- On platforms without subagent capability, the main session runs the same lanes inline in dependency order — semantics are identical, only latency changes. Record `dispatchMode: "subagent"` or `"inline"` per lane in `reference/authoring-lanes.json`.
+- Claude Code may delegate a wave's fan-out to its `Workflow` tool as an optional accelerator; this is an implementation choice, not part of the contract. The contract is the protocol + schemas + DAG, which every platform can interpret.
+- Every lane output is validated and recorded via `comet creator authoring-record <name> --lane <id> --file <out.json> --json` before the next dependent wave begins.
+
+## Common Inputs
+
+Every subagent must receive the same common context:
+
+- The user-confirmed goal, starting point, and language.
+- `goal`, `workflow.kind`, `workflow.nodes`, `engineMode`, and `runnerMode` from `plan.json`, plus
+  the derived internal `callChain` source inventory from Skill Creator metadata.
+- `reference/resolved-skills.json` or an equivalent real Skill source summary.
+- `reference/workflow-protocol.json` or the workflow protocol that will be written there.
+- For customize existing Comet Skills, the protected boundary: `open / design / build / verify / archive`, `.comet.yaml`, decision point, verify-result-transition, and archive-delta-sync.
+- Project preferences, missing or ambiguous candidate decisions, deviation reasons, and scripts/hooks executable disclosures.
+
+## Output Format
+
+Each subagent returns:
+
+```json
+{
+  "lane": "<lane-name>",
+  "artifacts": [
+    {
+      "path": "reference/example.md",
+      "kind": "reference",
+      "content": "..."
+    }
+  ],
+  "claims": [
+    {
+      "id": "reference:example",
+      "kind": "reference",
+      "paths": ["reference/example.md"],
+      "summary": "What this output guarantees"
+    }
+  ],
+  "findings": []
+}
+```
+
+`claims` are review evidence, not decoration. Missing critical claims must block in the Skill review subagent.
+
+## Dispatch Notes
+
+- Create a fresh subagent for every dispatch; do not inherit main-session history. The main session provides only the role brief, input paths, and necessary background for that role.
+- Explicitly specify a model. If the platform does not support model selection, record `platform-default` in `reference/authoring-lanes.json`.
+- Use file handoff: provide paths instead of pasting large bodies of text. Common input, resolved Skill summaries, draft artifacts, and reports should move by path.
+- Each subagent receives only its role brief, common input, and necessary artifacts, not every other role's full brief.
+- The Skill review subagent must run after the other five author roles and must read all artifacts and claims.
+- The main session may ask a role to rework its output, but the rework still returns to `reference/authoring-lanes.json` and `reference/skill-review.md`.
+- Subagents cannot call `comet bundle`, `comet publish`, or `comet skill`, and cannot execute candidate Skill scripts.
+- If a status is `BLOCKED` or `NEEDS_CONTEXT`, the main session must add context, split the task, switch to a stronger model, or ask the user; it must not continue assembly.
+- Without platform subagent capability, inline fallback must preserve the same lane, claim, and finding structure.

package/assets/skills/comet-any/reference/bundle-authoring.md

@@ -0,0 +1,166 @@
+# Bundle Authoring Reference
+
+`comet creator` is `/comet-any`'s ordinary CLI surface, backed by the deterministic `comet bundle` backend. Ordinary users should not memorize Bundle subcommands; Skill Creator turns the confirmed Workflow Contract into a plan and uses the CLI to maintain state.
+
+## Workflow Contract Input
+
+The new `plan.json` uses `workflow` as the primary input:
+
+```json
+{
+  "goal": "Customize existing Comet Skills with component and whitebox review requirements.",
+  "skillCreatorIntent": "customize-comet",
+  "workflow": {
+    "kind": "comet-five-phase-overlay",
+    "name": "team-comet",
+    "goal": "Require component and whitebox review Skills.",
+    "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"
+          }
+        ]
+      }
+    }
+  },
+  "engineMode": "deterministic",
+  "runnerMode": "standalone"
+}
+```
+
+Field rules:
+
+- `workflow.kind`: `comet-five-phase-overlay` or `workflow-kernel`.
+- `workflow.nodes`: per-Node patches for the workflow.
+- `implementation`: replace Node implementation. Only allowed on Nodes that support override.
+- `requiredSkillCalls`: Required Skill Calls inside the Node.
+- `augmentations`: helper Skills that do not replace the main implementation. Every new binding or schema must declare enforcement: `guarded`, `handoff-guarded`, `evidence-only`, or `advisory`.
+- `satisfies`: Output Schema ids satisfied by a producer override.
+- `outputSchemas`: advanced `workflow-kernel` definitions may add custom Output Schemas. Output Schema must be attached to a concrete Workflow Node before it is effective; defining it only in `workflow.outputSchemas` does not trigger guard, eval, or readiness.
+- `customNodes[].responsibility`: every custom Node must declare its Agent workflow responsibility.
+- `customNodes[].requiredSkillCalls`: custom Nodes may directly declare required Skill calls; generated scripts block progress until evidence is recorded.
+
+## Built-In Comet Nodes
+
+`comet-five-phase-overlay` includes these Workflow Nodes:
+
+- `comet-five-phase-overlay` primary state comes only from `openspec/changes/<name>/.comet.yaml`; no active change or multiple active changes must block and ask the user to choose.
+- The overlay must not create `.comet/runs/<workflow>/state.json` as the Comet overlay primary state; overlay scripts only read and advance `.comet.yaml`, while other files may be draft, eval, or publish evidence.
+- `open`: control, preserves Comet intake and `.comet.yaml` initialization.
+- `design`: producer, may be overridden only when it satisfies `comet.design.v1`.
+- `plan`: producer, may be overridden only when it satisfies `comet.plan.v1`.
+- `execute`: control, may require or augment Skills such as `elementui`.
+- `subagent-execute`: Handoff, may require subagents to use `elementui` and return evidence.
+- `review`: Guardrail, may require `whitebox-code-standard`.
+- `verify`: control, preserves verification and branch finishing.
+- `archive`: control, preserves OpenSpec archive and delta sync.
+
+Custom `workflow-kernel` Node example:
+
+```json
+{
+  "id": "delegate-notes",
+  "label": "Delegate Notes",
+  "kind": "handoff",
+  "responsibility": "Delegate release note drafting and require returned evidence.",
+  "implementation": {
+    "skill": "handoff-coordinator",
+    "scope": "handoff"
+  },
+  "requiredSkillCalls": [
+    {
+      "skill": "release-notes",
+      "scope": "handoff"
+    }
+  ],
+  "operations": ["require", "augment"],
+  "outputSchemas": ["release.notes.v1"],
+  "guardrails": [
+    {
+      "id": "handoff-returned",
+      "label": "Handoff returned evidence",
+      "validation": "semantic"
+    }
+  ]
+}
+```
+
+## Generated Package
+
+Factory must generate:
+
+- entry `SKILL.md`
+- one internal Skill per Workflow Node
+- `reference/workflow-protocol.json`
+- `reference/resolved-skills.json`
+- `reference/decision-points.md`
+- `reference/recovery.md`
+- `reference/authoring-lanes.json`
+- `reference/skill-review.md`
+- `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`
+- `comet/eval.yaml`
+
+The three `workflow-*.mjs` scripts are authored per workflow contract; the three `comet-*.mjs` scripts are deterministically generated by the factory (plan alias, required-files check, hook guard) and read the same `workflow-protocol.json`.
+
+`workflow-protocol.json` is the shared source of truth for runtime, eval, review, and publish readiness.
+
+## CLI Lifecycle
+
+Common Creator commands:
+
+```bash
+comet creator guide --project . --json
+comet creator candidates --json
+comet creator propose <name> --file <plan.json> --json
+comet creator init <name> --file <plan.json> --confirmed-proposal --json
+comet creator resolve <name> --candidate <query> --source <root-or-hash> --json
+comet creator generate <name> --json
+comet bundle compile <name> --platform <id> --json
+comet eval <generated-skill>/comet/eval.yaml --quick --html
+comet eval <generated-skill>/comet/eval.yaml --full --html
+comet publish review <name> --platform <reference-platform> --json
+comet publish approve <name> --reviewer <reviewer> --json
+comet publish run <name> --platform <reference-platform> --json
+comet publish distribute <name> --platform <id> --scope project --preview --json
+```
+
+`<generated-skill>` is the directory for the compiled Skill. Eval results must be recorded as current draft hash eval evidence; readiness reads only evidence for that hash. Stale eval evidence may remain for audit, but cannot advance ready.
+
+## Readiness
+
+Readiness must check:
+
+- resolved Skills have no missing or ambiguous entries.
+- the proposal has been confirmed.
+- `workflow-protocol.json` loads successfully.
+- no ordinary control Node override exists.
+- producer overrides satisfy Output Schemas.
+- every new binding or schema has `guarded`, `handoff-guarded`, `evidence-only`, or `advisory` enforcement.
+- current draft hash eval evidence exists and is not stale.
+- human review approved the current hash.
+- capability gaps and executable disclosures have been shown.
+
+Non-JSON output must still show `Readiness:`, `Blockers:`, `Warnings:`, and `Evidence:`.