noname-shuying/.agents/skills/comet-any/reference/authoring-subagents.md

Authoring Subagents Overview

Core Principles

/comet-any authoring outputs are drafted by six responsibility-specific subagents, then assembled and recorded by the main session through the backend CLI. The main session dispatches a fresh subagent for every lane in the authoring DAG and supplies the matching reference/subagents/*.md file as that role's brief.

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.

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

Dispatch rules:

• Sequencing follows DAG dependencies; only the barrier truly waits for all prior lanes.
• 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 /comet-classic customization, the protected boundary is 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:

{
  "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.
• 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.