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:

{
  "goal": "Customize /comet-classic five-phase 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 <classic-change-dir>/.comet.yaml bound by the Classic layout resolver; 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:

{
  "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:

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:.

6.5 KiB Raw Blame History