mirror of
https://github.com/Shu-Ying/noname-shuying.git
synced 2026-10-24 08:39:58 +08:00
fixed # 归档
This commit is contained in:
@@ -0,0 +1,105 @@
|
||||
# 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 Classification And Decision Points
|
||||
|
||||
Classify before acting: a user decision has two or more valid options that change scope, behavior, accepted risk, or an irreversible outcome; a sole safe next action is automatic handling; a missing dependency, corrupt state, or guard failure with no valid continuation is a stop condition; `NEXT: manual` only returns control. Only the first category must pause.
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| First invocation with an unambiguous topic and scope | Initialize state automatically and enter the first Node; do not pause to approve known information |
|
||||
| Topic, scope, or target Node has two or more mutually exclusive valid interpretations | Merge them into one question and let the user choose; do not guess |
|
||||
| Node requires user approval of output before advancing | Stop after recording evidence; wait for explicit confirmation |
|
||||
| Accepting a WARNING/deviation or performing an irreversible publish has a real tradeoff | Show only currently executable options and persist the choice |
|
||||
|
||||
When a Node guard fails, inspect evidence and perform the sole safe repair first. If a missing dependency or corrupt state prevents progress, report the stop condition and recovery requirement. Escalate to the decision table only when multiple valid recovery options would change scope or risk.
|
||||
|
||||
### Red Flags
|
||||
|
||||
| Agent Thought | Actual Risk |
|
||||
|--------------|-------------|
|
||||
| "Every first invocation needs another confirmation" | Clear input does not need duplicate approval; ask only when mutually exclusive interpretations still change 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. |
|
||||
| "The guard failed, so ask the user what to do" | Diagnose automatically and apply the sole safe repair first; if no valid action exists, report a stop condition instead of inventing options. |
|
||||
| "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.
|
||||
@@ -0,0 +1,94 @@
|
||||
# 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:
|
||||
|
||||
```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.
|
||||
- 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.
|
||||
@@ -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 /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:
|
||||
|
||||
```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:`.
|
||||
@@ -0,0 +1,83 @@
|
||||
# Eval Evidence Reference
|
||||
|
||||
## Eval choices
|
||||
|
||||
Before any verification action, show:
|
||||
|
||||
- `quick` estimated runs, covered components, and token workload.
|
||||
- `full` estimated runs, covered components, and token workload.
|
||||
- the three choices: `skip / quick / full eval`.
|
||||
|
||||
If eval is skipped, fails, or records stale-hash evidence, do not enter ready; do not publish or distribute.
|
||||
|
||||
For ordinary users, the verification path remains single-purpose: daily evaluation goes through
|
||||
`comet eval`. `/comet-any` may internally record eval evidence, but must not present the internal
|
||||
recording step as a replacement user-facing command.
|
||||
For ordinary users, prefer the word "verify" when explaining; do not surface `Publish readiness:`
|
||||
as a first-class concept.
|
||||
|
||||
## Result recording
|
||||
|
||||
Eval evidence must produce structured JSON with at least:
|
||||
|
||||
- the current draft hash.
|
||||
- covered entry Skill and internal Node Skills.
|
||||
- `workflow-protocol.json` hash.
|
||||
- quick or full choice, token workload, and result summary.
|
||||
- Bundle compile, safety check, and capability evidence.
|
||||
|
||||
Only current draft hash eval evidence can advance state. Stale eval evidence may remain on disk for
|
||||
audit, but cannot make the current draft ready.
|
||||
|
||||
## Human review
|
||||
|
||||
Passing eval still requires human approval. The review summary must include at least:
|
||||
|
||||
First run `comet publish review <name> --platform <reference-platform> --json`, then use its
|
||||
output to show:
|
||||
|
||||
- Bundle name, version, and hash.
|
||||
- Multiple entry and internal Skill lists.
|
||||
- `planHash`, `preferenceHash`, and `reference/resolved-skills.json` real Skill evidence,
|
||||
including project-level preference mode, required Skills, `sourceSummaries`, and the composed
|
||||
workflow summary.
|
||||
- Recommended call order and `preferenceIndex`.
|
||||
- Every item that deviates from the preferred order, plus the reason.
|
||||
- Whether `.comet/skill-preferences.yaml` drifted after Factory initialization; `advisory` mode
|
||||
warns, while `strict` mode blocks.
|
||||
- Whether the stable composed Skill Bundle required capability set
|
||||
`skills/scripts/rules/hooks/references` is complete, and whether `scripts/rules/hooks` remain
|
||||
the required control plane.
|
||||
- Whether `comet/skill.yaml`, `comet/guardrails.yaml`, `comet/checks.yaml`, and `comet/eval.yaml`
|
||||
were generated.
|
||||
- Whether `hooks/*.yaml` are treated only as portable hook descriptors until
|
||||
`comet publish distribute` compiles them for the target platform.
|
||||
- Capability gaps and executable disclosures.
|
||||
- eval choice, token workload, and result summary.
|
||||
- `Validate this Skill` and the next action so the user knows why the candidate can become ready
|
||||
or is blocked.
|
||||
|
||||
Readiness blockers stop publishing. If missing current draft hash eval evidence, missing human
|
||||
approval, required capability gaps, or unconfirmed executable disclosures remain, the flow must stop
|
||||
in review and cannot continue to publish.
|
||||
|
||||
Only after explicit user approval may the agent run `comet publish approve` and publish.
|
||||
|
||||
## Install preview
|
||||
|
||||
Before real distribution, preview is mandatory:
|
||||
|
||||
```bash
|
||||
comet publish distribute <name> --platform <id> --scope project --preview --json
|
||||
```
|
||||
|
||||
Preview is a required check, not an optional extra. It should show:
|
||||
|
||||
- `Install preview`
|
||||
- planned files
|
||||
- unsupported capability
|
||||
- executable disclosures
|
||||
- `No files were written`
|
||||
|
||||
Only after the user confirms the preview result may the Skill remove `--preview` and execute real
|
||||
distribution.
|
||||
@@ -0,0 +1,75 @@
|
||||
# Pause Point Author Subagent
|
||||
|
||||
## Responsibilities
|
||||
|
||||
Design only the places where the user genuinely must choose, plus cross-device recovery. First distinguish four categories: user decision, automatic handling, stop condition, and manual handoff. Create a user pause only when two or more valid options change scope, behavior, accepted risk, or an irreversible outcome. Execute a sole safe action directly, report a missing dependency or corrupt state as a stop condition, and return control for a manual handoff. Genuine user decisions cannot be bypassed by defaults, historical preferences, or automatic advancement.
|
||||
|
||||
Must cover:
|
||||
|
||||
- `reference/decision-points.md`
|
||||
- `reference/recovery.md`
|
||||
|
||||
## Inputs
|
||||
|
||||
Read the common input from the main session, especially:
|
||||
|
||||
- `confirm-generate`, `revise-proposal`, and `cancel` from the Skill Creator confirmation page: these are user decisions that change the generated result.
|
||||
- Eval workload (`skip / quick / full eval`) and human approval before installation: treat them as decisions only when multiple valid options actually remain.
|
||||
- Missing or stale eval evidence, unresolved candidates, ambiguity, capability gaps, and executable disclosures: classify each as automatically repairable, a no-path stop condition, or a real decision with multiple recovery choices. Do not turn all blockers into pause points.
|
||||
- Runner recovery state and cross-device recovery entry: reuse persisted choices that remain valid instead of asking again on resume.
|
||||
|
||||
Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not inherit main-session history; use only this brief, common input, workflow protocol, and existing drafts.
|
||||
|
||||
## Dispatch Template
|
||||
|
||||
Dispatch a fresh subagent for this role with:
|
||||
|
||||
```text
|
||||
description: "Design user pause points and recovery for <bundle-name>"
|
||||
prompt:
|
||||
You are the pause point author subagent.
|
||||
First read this brief, the common input path, workflow protocol path, Skill draft path, and report file path.
|
||||
First classify each candidate as a user decision, automatic handling, stop condition, or manual handoff. If facts needed for classification are missing, return NEEDS_CONTEXT.
|
||||
Do not guess missing choices, and do not disguise automatic repair, guard failure, capability gaps, a sole valid action, or manual handoff as a user pause.
|
||||
Only produce decision-points and recovery drafts; do not write Bundle state and do not execute candidate scripts.
|
||||
Write the full pause point draft to the report file path and return only a status summary of 15 lines or fewer.
|
||||
```
|
||||
|
||||
## Output Requirements
|
||||
|
||||
Return a classification table first, then describe genuine user pause points:
|
||||
|
||||
- Which category each candidate belongs to and the evidence for that classification.
|
||||
- The trigger condition for every pause point.
|
||||
- The choices available to the user.
|
||||
- Which Node each choice enters.
|
||||
- Where pause point evidence is written.
|
||||
- How automatic handling advances directly, and how stop conditions report recovery requirements without inventing options.
|
||||
- During recovery, how to show the current Node, blocking reason, suggested next step, and real options while reusing persisted choices.
|
||||
|
||||
Pause points must fit the current workflow protocol, not merely list original Comet pause points.
|
||||
|
||||
## Self-Check
|
||||
|
||||
Before returning, check:
|
||||
|
||||
- Every user pause point has trigger condition, options, next Node, and evidence location.
|
||||
- Every pause has at least two currently executable valid options; adjacent choices that can be answered together are merged, and a sole valid value creates no pause.
|
||||
- Guard failures, deterministic retries, state reconciliation, capability gaps, and `NEXT: manual` are classified according to their actual semantics instead of defaulting to user questions.
|
||||
- Default recommendations, historical preferences, and automatic advancement cannot bypass required pause points.
|
||||
- The recovery summary can show the current Node, blocking reason, suggested next step, and real options without re-asking choices that remain valid.
|
||||
- Cross-device recovery does not rely on current-session memory.
|
||||
- Pause points fit the current composed Skill instead of copying original Comet pause points.
|
||||
|
||||
## Required Claims
|
||||
|
||||
- `pause:decision-points`
|
||||
- `pause:recovery`
|
||||
|
||||
Missing any claim must block Skill review.
|
||||
|
||||
## Status Return
|
||||
|
||||
Status must be one of `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.
|
||||
|
||||
Write the full report to the report file path. The summary returned to the main session must be 15 lines or fewer and include status, report path, claims, unresolved concerns, and recovery risks. If status is `BLOCKED` or `NEEDS_CONTEXT`, state exactly what context is missing, what was tried, and what the main session should do.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Reference Author Subagent
|
||||
|
||||
## Responsibilities
|
||||
|
||||
Write and organize the generated Skill's reference layer so audit, recovery, review, and future maintenance have real evidence. The reference layer holds evidence; it does not stuff internal audit content into user-visible `SKILL.md`.
|
||||
|
||||
Must cover:
|
||||
|
||||
- `reference/workflow-protocol.json`
|
||||
- `reference/resolved-skills.json`
|
||||
- `reference/composition-report.md`
|
||||
- `reference/authoring-lanes.json`
|
||||
|
||||
## Inputs
|
||||
|
||||
Read the common input from the main session, especially:
|
||||
|
||||
- Resolved Skill name, source, description, hash, references, rules, scripts, and hooks.
|
||||
- `sourceSummaries`, which must come from real `SKILL.md` bodies and direct references.
|
||||
- Project preferences, missing or ambiguous candidate handling, deviation reasons, and executable disclosures.
|
||||
- The five-phase Comet semantics preserved when users customize `/comet-classic`.
|
||||
|
||||
Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not read main-session history, and do not copy entire source Skills into reference.
|
||||
|
||||
## Dispatch Template
|
||||
|
||||
Dispatch a fresh subagent for this role with:
|
||||
|
||||
```text
|
||||
description: "Organize reference evidence for <bundle-name>"
|
||||
prompt:
|
||||
You are the reference author subagent.
|
||||
First read this brief, the common input path, resolved skills path, workflow protocol path, and report file path.
|
||||
Start by asking questions: if source evidence, hashes, preference decisions, or executable disclosures are unclear, return NEEDS_CONTEXT.
|
||||
Do not guess or fill in missing sources.
|
||||
Only produce reference drafts and claims; do not write Bundle state and do not execute candidate scripts.
|
||||
Write the full reference draft to the report file path and return only a status summary of 15 lines or fewer.
|
||||
```
|
||||
|
||||
## Output Requirements
|
||||
|
||||
Return a reference draft that explains:
|
||||
|
||||
- Each workflow protocol Node's goal, guard, next-Node condition, and recovery point.
|
||||
- How resolved Skill evidence supports the composed flow.
|
||||
- Where composition matches user preferences, where it deviates, and why.
|
||||
- Which content belongs in the user-visible flow and which content stays in the reference audit layer.
|
||||
|
||||
Do not turn reference into copied source Skill prose. Distill it into evidence and protocol that the composed Skill can use.
|
||||
|
||||
## Self-Check
|
||||
|
||||
Before returning, check:
|
||||
|
||||
- Every source summary traces back to a real `SKILL.md` or direct reference.
|
||||
- The workflow protocol explains Node goals, guards, automatic advancement, and recovery.
|
||||
- Preferences, missing candidates, ambiguity, deviations, and executable disclosures are recorded.
|
||||
- User-visible flow and internal audit content have a clear boundary.
|
||||
- No source Skill body was copied wholesale into reference.
|
||||
|
||||
## Required Claims
|
||||
|
||||
- `reference:workflow-protocol`
|
||||
- `reference:resolved-skills`
|
||||
- `reference:composition-report`
|
||||
- `reference:authoring-lanes`
|
||||
|
||||
Missing any claim must block Skill review.
|
||||
|
||||
## Status Return
|
||||
|
||||
Status must be one of `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.
|
||||
|
||||
Write the full report to the report file path. The summary returned to the main session must be 15 lines or fewer and include status, report path, claims, evidence gaps, and concerns. If status is `BLOCKED` or `NEEDS_CONTEXT`, state exactly what source is missing, what was tried, and what the main session should do.
|
||||
@@ -0,0 +1,78 @@
|
||||
# Script Author Subagent
|
||||
|
||||
## Responsibilities
|
||||
|
||||
Design the generated Skill's script contract instead of copying Comet Classic scripts. Scripts must use the current workflow protocol, user-selected Node labels, and real composed Skill outputs to define automatic advancement, exit checks, recovery, and evidence recording.
|
||||
|
||||
Must cover:
|
||||
|
||||
- `scripts/workflow-state.mjs`
|
||||
- `scripts/workflow-guard.mjs`
|
||||
- `scripts/workflow-handoff.mjs`
|
||||
|
||||
The factory also deterministically generates `scripts/comet-plan.mjs`, `scripts/comet-check.mjs`, and `scripts/comet-hook-guard.mjs` from the same `workflow-protocol.json`. Do not duplicate or redesign those three; your contract is for the `workflow-*.mjs` scripts that the Skill core author and entry author reference.
|
||||
|
||||
## Inputs
|
||||
|
||||
Read the common input from the main session, especially:
|
||||
|
||||
- `reference/workflow-protocol.json`
|
||||
- `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`
|
||||
- Protected `.comet.yaml` semantics when users customize `/comet-classic`; `comet-five-phase-overlay` primary state comes only from `<classic-change-dir>/.comet.yaml` bound by the Classic layout resolver and must not create `.comet/runs/<workflow>/state.json` as the Comet overlay primary state.
|
||||
|
||||
Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not read main-session history or ask the user to restate content already written to artifacts.
|
||||
|
||||
## Dispatch Template
|
||||
|
||||
Dispatch a fresh subagent for this role with:
|
||||
|
||||
```text
|
||||
description: "Write the script contract for <bundle-name>"
|
||||
prompt:
|
||||
You are the script author subagent.
|
||||
First read this brief, the common input path, workflow protocol path, resolved skills path, and report file path.
|
||||
Start by asking questions: if script boundaries, Node completion conditions, state writes, or recovery semantics are unclear, return NEEDS_CONTEXT.
|
||||
Do not guess or fill in missing protocol details.
|
||||
Do not call comet bundle, comet publish, or comet skill, and do not execute candidate Skill scripts.
|
||||
Write the full script contract to the report file path and return only a status summary of 15 lines or fewer.
|
||||
```
|
||||
|
||||
## Output Requirements
|
||||
|
||||
Return a script contract draft that explains, for each script:
|
||||
|
||||
- Which state it reads.
|
||||
- Which state and evidence it writes.
|
||||
- How it decides whether the current Node goal is complete.
|
||||
- How it outputs `NEXT:`, `SKILL:`, and blocking reasons.
|
||||
- How it stays in the current Node when the Node is incomplete instead of forcing an exit.
|
||||
- How it supports cross-device recovery.
|
||||
- For `comet-five-phase-overlay`, how it blocks when there is no active change or multiple active changes and asks the user to choose.
|
||||
|
||||
Exit checks must come from the current workflow protocol and composed Skill goal, not copied Comet Classic scripts.
|
||||
|
||||
## Self-Check
|
||||
|
||||
Before returning, check:
|
||||
|
||||
- Every script has inputs, outputs, state reads/writes, evidence writes, and failure behavior.
|
||||
- Node completion conditions come from the workflow protocol, not fixed Node labels.
|
||||
- `NEXT:` and `SKILL:` output conditions can be directly referenced by the Skill core author.
|
||||
- Cross-device recovery does not rely on current-session memory.
|
||||
- No candidate script was executed and no Bundle state was written.
|
||||
|
||||
## Required Claims
|
||||
|
||||
- `script:workflow-state`
|
||||
- `script:workflow-guard`
|
||||
- `script:workflow-handoff`
|
||||
|
||||
Missing any claim must block Skill review.
|
||||
|
||||
## Status Return
|
||||
|
||||
Status must be one of `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.
|
||||
|
||||
Write the full report to the report file path. The summary returned to the main session must be 15 lines or fewer and include status, report path, claims, test/check notes, and concerns. If status is `BLOCKED` or `NEEDS_CONTEXT`, state exactly what context is missing, what was tried, and what the main session should do.
|
||||
@@ -0,0 +1,126 @@
|
||||
# Skill Core Author Subagent
|
||||
|
||||
## Responsibilities
|
||||
|
||||
Write the user-visible core content for internal Node Skills. The entry Skill is owned separately by the workflow entry author. The goal is a Comet-like multi-Node workflow, not a simple chain of source Skills or a copied source Skill body.
|
||||
|
||||
Must cover:
|
||||
|
||||
- Every internal Node Skill
|
||||
- Node invocation semantics in `comet/skill.yaml`
|
||||
- Every `node-skill:<skill-name>` claim
|
||||
|
||||
## Authored Zone (what you write)
|
||||
|
||||
The generator composes each Node SKILL.md from a deterministic **Auto zone** (frontmatter, Node Goal, Entry Check, Skill Implementation, Required Skill Calls, Output Schemas, Evidence Record, Guardrails, Exit Check, Recovery) plus an **Authored zone** (`## Guidance`) that YOU write. You do NOT write the whole file — only the Guidance body. The main session records your output via `comet creator authoring-record <name> --lane skill-core --file <out.json>`; the artifact `content` for `../<node-skill>/SKILL.md` is the Guidance body.
|
||||
|
||||
Quality bar: a real Comet phase skill (e.g. `comet-build/SKILL.md`); see `reference/authored-zone-example.md` for a full sample at the expected level. Author decision content, not boilerplate. Use `###` subsections within Guidance so they nest under `## Guidance`:
|
||||
|
||||
- `### Prerequisites` — what must be true before this Node starts.
|
||||
- `### Steps` — the ordered, domain-specific steps; reference the bound Skill by name and say when to call it (do not copy its body).
|
||||
- `### Completion reasoning` — when the Node is genuinely done (beyond the mechanical Exit Check), and the judgment calls involved.
|
||||
- `### Red flags` — the failure modes that look like progress but are not.
|
||||
|
||||
Here is a concrete excerpt showing the expected depth for a "Research" substance node. Notice: it is **decision content** (when to stop, what counts as enough, what to reject), not a restatement of the route table or output schema.
|
||||
|
||||
```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.
|
||||
```
|
||||
|
||||
Node mode (from the protocol):
|
||||
|
||||
- **substance** Node (workflow-kernel default): rich Guidance is mandatory. Without it the Node renders as `AUTHORING PENDING` and the Bundle cannot become ready.
|
||||
- **delegates** Node (comet-five-phase-overlay, delegating to an installed rich Skill): a short Guidance note is acceptable — the delegate carries the richness; do not duplicate it.
|
||||
|
||||
## Inputs
|
||||
|
||||
Read the common input from the main session, especially:
|
||||
|
||||
- User-confirmed Node labels and editable name fields.
|
||||
- Node goals, `requiredSkillCalls`, and automatic advancement conditions from
|
||||
`reference/workflow-protocol.json`.
|
||||
- Real Skill summaries from `reference/resolved-skills.json`.
|
||||
- The script author's `NEXT:`, `SKILL:`, guard, and recovery contracts.
|
||||
|
||||
Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not inherit main-session history; use only this brief, common input, script contracts, and reference evidence.
|
||||
|
||||
## Dispatch Template
|
||||
|
||||
Dispatch a fresh subagent for this role with:
|
||||
|
||||
```text
|
||||
description: "Write Skill core content for <bundle-name>"
|
||||
prompt:
|
||||
You are the Skill core author subagent.
|
||||
First read this brief, the common input path, script contract path, reference evidence path, and report file path.
|
||||
Start by asking questions: if Node labels, required Skill calls, automatic advancement, or user pause points are unclear, return NEEDS_CONTEXT.
|
||||
Do not guess or fill in missing flow details.
|
||||
Only write internal Node Skill drafts; do not write entry Skill, Bundle state, or execute candidate scripts.
|
||||
Write the full Skill draft to the report file path and return only a status summary of 15 lines or fewer.
|
||||
```
|
||||
|
||||
## Output Requirements
|
||||
|
||||
Return internal Node Skill drafts that show:
|
||||
|
||||
- Internal Node Skills own a single-Node goal, required Skill calls, completion evidence, and script guards.
|
||||
- If the protocol declares `requiredSkillCalls`, the matching Node must state the target Node,
|
||||
required Skill, applies-to scope, and evidence requirement. Subagent cases must also tell the
|
||||
implementation subagent prompt to load that Skill.
|
||||
- If the Node goal is not complete, continue working instead of exiting because a checklist is exhausted.
|
||||
- Automatic advancement must come from script outputs `NEXT:` and `SKILL:`, not agent guesses.
|
||||
- Nested Skill calls use only Skill names, not provider prefixes.
|
||||
- When users customize `/comet-classic`, preserve `open / design / build / verify / archive` and `.comet.yaml` semantics.
|
||||
- For arbitrary Skill composition, organize the result as a Comet-like multi-Node workflow.
|
||||
|
||||
Forbidden:
|
||||
|
||||
- Copying full source Skill bodies.
|
||||
- Provider prefixes such as `Superpowers writing-plans` or `OpenSpec openspec-propose`.
|
||||
- Mixing Chinese process sentences into English Skills.
|
||||
- Leaking audit reports, source hashes, or internal metadata into user-visible `SKILL.md`.
|
||||
|
||||
## Self-Check
|
||||
|
||||
Before returning, check:
|
||||
|
||||
- Every Node explains required Skill calls, completion evidence, script guards, and recovery entry.
|
||||
- Every `requiredSkillCalls` item has a clear load instruction and evidence requirement in the
|
||||
matching Node Skill.
|
||||
- Automatic advancement references script outputs `NEXT:` and `SKILL:`.
|
||||
- Skill calls use only Skill names, not provider prefixes.
|
||||
- User-visible English prose does not mix in Chinese process sentences.
|
||||
- No source Skill body was copied wholesale.
|
||||
|
||||
## Required Claims
|
||||
|
||||
- One `node-skill:<skill-name>` for every internal Node Skill
|
||||
|
||||
Missing any claim must block Skill review.
|
||||
|
||||
## Status Return
|
||||
|
||||
Status must be one of `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.
|
||||
|
||||
Write the full report to the report file path. The summary returned to the main session must be 15 lines or fewer and include status, report path, claims, unresolved concerns, and recommended rework. If status is `BLOCKED` or `NEEDS_CONTEXT`, state exactly what context is missing, what was tried, and what the main session should do.
|
||||
@@ -0,0 +1,123 @@
|
||||
# Skill Review Subagent
|
||||
|
||||
## Responsibilities
|
||||
|
||||
Review the other subagents' artifacts and claims, then decide whether the candidate Skill is usable like Comet. The review must give a clear conclusion: `Review passed` or blocking findings.
|
||||
|
||||
Must cover:
|
||||
|
||||
- `reference/skill-review.md`
|
||||
- `reference/authoring-lanes.json`
|
||||
|
||||
## Inputs
|
||||
|
||||
Read the common input from the main session, plus all artifacts, claims, and findings returned by the other five author roles.
|
||||
|
||||
Use file handoff: the main session provides paths instead of pasting large bodies of text. Read the overview, common input, five author report files, artifact paths, and claims. Do not use main-session history as a substitute for artifact evidence.
|
||||
|
||||
## Dispatch Template
|
||||
|
||||
Dispatch a fresh subagent for this role with:
|
||||
|
||||
```text
|
||||
description: "Review the Comet-like Skill outputs for <bundle-name>"
|
||||
prompt:
|
||||
You are the Skill review subagent.
|
||||
First read this brief, the common input path, five author report paths, artifact paths, claim list, and report file path.
|
||||
Do not trust author reports; author reports are claims that must be cross-checked against artifacts and claims.
|
||||
Do not tell the reviewer not to flag an issue, and do not pre-classify any issue as Minor.
|
||||
Review is read-only. Do not modify the working tree, index, HEAD, or branch state.
|
||||
Write the full review to the report file path and return both verdicts.
|
||||
```
|
||||
|
||||
## Review Method
|
||||
|
||||
Do not trust author reports. Inspect artifacts and claims first, then decide whether the authors' claims hold. Do not downgrade severity because "the author says this is intentional."
|
||||
|
||||
The review must provide two verdicts:
|
||||
|
||||
- Skill contract fit: whether the output satisfies the user-confirmed goal, workflow protocol,
|
||||
`requiredSkillCalls`, claims, Node advancement, script guards, pause points, and recovery
|
||||
requirements.
|
||||
- Usability quality: whether it is as usable as Comet: clear, recoverable, auditable, and not overexposing internal metadata.
|
||||
|
||||
Evidence must cite artifact paths and claims. Do not write only "looks fine."
|
||||
|
||||
## Blocking Conditions
|
||||
|
||||
Any of these must produce blocking findings:
|
||||
|
||||
- Missing `reference/skill-review.md`.
|
||||
- Missing `reference/authoring-lanes.json`.
|
||||
- Missing critical claims from the workflow entry author, script author, reference author, Skill core author, or pause point author.
|
||||
- Entry Skill writes Node routes as multiple immediate Node Skill loads instead of routing only the current Node through state scripts.
|
||||
- Missing `workflow-state.mjs`, `workflow-guard.mjs`, or `workflow-handoff.mjs` contract.
|
||||
- Missing any of the six generated scripts (`workflow-state`, `workflow-guard`, `workflow-handoff`, `comet-plan`, `comet-check`, `comet-hook-guard`) in the package.
|
||||
- Missing workflow entry, or Skill core has no internal Node Skill.
|
||||
- Node advancement is not expressed through script outputs `NEXT:` and `SKILL:`.
|
||||
- `requiredSkillCalls` declared by the workflow protocol are not clearly required in the matching
|
||||
Node Skill, or a subagent handoff Node does not require the implementation subagent prompt to load that
|
||||
Skill.
|
||||
- User pause points are missing, or can be bypassed by defaults.
|
||||
- Deterministic repair, guard failure, state reconciliation, a capability gap, a sole valid action, or `NEXT: manual` is treated as a user pause by default; or adjacent choices that can be answered together are split into serial confirmations.
|
||||
- The entry Skill frontmatter description does not identify it as the managed workflow entry/resume router, or an internal Node Skill description allows ordinary tasks to trigger it without explicit invocation or entry/runtime routing.
|
||||
- English Skills mix in Chinese process sentences.
|
||||
- Nested Skill calls use provider prefixes.
|
||||
- User-visible `SKILL.md` leaks generated audit sections, source hashes, or internal metadata.
|
||||
- Customizing `/comet-classic` replaces or removes `open / design / build / verify / archive`, `.comet.yaml`, decision point, verify-result-transition, or archive-delta-sync.
|
||||
- Arbitrary Skill composition is missing automatic advancement, script guards, user pause points, recovery, or current draft hash eval evidence.
|
||||
|
||||
## Severity
|
||||
|
||||
- Critical: makes the generated Skill unusable, unrecoverable, unauditable, or breaks protected `/comet-classic` semantics.
|
||||
- Important: makes the Node flow, script guards, pause points, Skill calls, or evidence chain untrustworthy; must be fixed before ready.
|
||||
- Minor: clarity, naming, or maintainability improvements that do not block ready.
|
||||
|
||||
## Output Requirements
|
||||
|
||||
Return:
|
||||
|
||||
- `reference/skill-review.md`
|
||||
- `reference/authoring-lanes.json`
|
||||
- `review:skill-review`
|
||||
- Final `Review passed` or blocking findings.
|
||||
|
||||
Output must include:
|
||||
|
||||
- Two verdicts: Skill contract fit and usability quality.
|
||||
- Strengths: concrete artifacts that work well.
|
||||
- Issues grouped by Critical, Important, and Minor.
|
||||
- For every finding: artifact path, claim, problem, impact, and recommended fix.
|
||||
- `Review passed` or blocking findings.
|
||||
|
||||
If any Critical or Important issue exists, do not return `Review passed`. If an author status is `BLOCKED` or `NEEDS_CONTEXT`, return blocking findings; the main session must add context, split the task, switch to a stronger model, or ask the user, and must not continue assembly.
|
||||
|
||||
## Multi-vote Review (depth-aware)
|
||||
|
||||
The skill-review lane is the DAG barrier and runs after every author lane. Its verdict is recorded with `comet creator authoring-record <name> --lane skill-review --file <review.json>` and becomes the real `skill-review.md` / `authoring-lanes.json` evidence — it is NOT a hardcoded approval.
|
||||
|
||||
- `depth: full` → dispatch N=3 independent reviewers, each holding exactly one lens (`contract-fit`, `usability`, `evidence-trace`, `self-consistency`), none seeing the others' conclusions. Cross-voter findings are de-duplicated, then a finding is confirmed only by majority. Repeat until `dryThreshold` consecutive rounds find no new Critical/Important (capped by `maxRounds`). `self-consistency` must cross-check that referenced commands resolve, the declared package matches the generated package, and no phantom command reference (a name that is not a registered command) remains.
|
||||
- `depth: quick` → a single reviewer, single round.
|
||||
- `passed` is `true` only when zero Critical/Important findings remain. Minor findings are recorded but do not block.
|
||||
|
||||
The recorded review object must match this shape (validated by `authoring-record`):
|
||||
|
||||
```json
|
||||
{
|
||||
"lane": "skill-review",
|
||||
"status": "DONE",
|
||||
"review": {
|
||||
"passed": true,
|
||||
"evidenceSource": "llm-multivote",
|
||||
"voters": 3,
|
||||
"lenses": ["contract-fit", "usability", "evidence-trace", "self-consistency"],
|
||||
"rounds": 2,
|
||||
"findings": [
|
||||
{ "severity": "minor", "path": "SKILL.md", "problem": "Wording nit.", "fix": "Rephrase." }
|
||||
],
|
||||
"reviewedAt": "2026-06-28T00:00:00.000Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
A `passed: false` review is a readiness blocker (publish cannot proceed); a missing review is a warning (the package still carries an honest `deterministic-check-only` placeholder, never a fabricated approval).
|
||||
@@ -0,0 +1,98 @@
|
||||
# Workflow Entry Author Subagent
|
||||
|
||||
## Responsibilities
|
||||
|
||||
Write the generated Skill's entry `SKILL.md`. The entry owns the entry point, recovery, main router explanation, and user pause points; it must not turn the Node route table into an execution checklist that immediately triggers multiple Skills.
|
||||
|
||||
Must cover:
|
||||
|
||||
- entry Skill
|
||||
- Entry guidance for workflow-state / workflow-guard / workflow-handoff
|
||||
- `workflow-entry` claim
|
||||
|
||||
## Authored Zone (what you write)
|
||||
|
||||
The generator composes the entry SKILL.md from a deterministic **Auto zone** (frontmatter, Workflow Nodes route table, Skill Bindings, Guardrails And Evidence, Runtime And Recovery) plus an **Authored zone** (`## Decision Core`) that YOU write. You do NOT write the whole file — only the Decision Core body. The main session records your output via `comet creator authoring-record <name> --lane workflow-entry --file <out.json>`; the artifact `content` for `SKILL.md` is the Decision Core body.
|
||||
|
||||
Quality bar: the `comet/SKILL.md` Decision Core (see `reference/authored-zone-example.md` for a full entry Decision Core example at the expected level). Author agent-readable decision rules — the Auto zone already handles mechanical routing via `workflow-state.mjs next`, so focus on judgment:
|
||||
|
||||
- **Semantic current-Node detection** — how to determine which Node the user is in, beyond just running the script. Model comet's Step 0 (detect intent from user message, check Node order, handle "belongs to earlier/later Node" conflicts) + Step 1 (read state, trust files over stale state).
|
||||
- **Resume and drift rules** — what to do when context resumes (re-detect from scratch, never trust conversation history), when state says DONE but artifacts are missing, when the user's topic shifts mid-Node.
|
||||
- **Decision classification and decision points** — first distinguish user decisions, automatic handling, stop conditions, and manual handoffs, then tabulate only genuine user choices. A clear first invocation, an objectively repairable guard failure, a sole valid next action, and `NEXT: manual` must not manufacture confirmation.
|
||||
- **Red flags** — the "agent thought → actual risk" pattern that catches self-deception (e.g., "user mentioned the topic so research is confirmed" → mentioning ≠ confirming).
|
||||
|
||||
A Decision Core without these four sections is a stub, not a Decision Core. The entry is the most-loaded file — it is what makes the Skill feel intelligent or mechanical.
|
||||
|
||||
The Node route table in the Auto zone is reference only — do not duplicate it as an execution checklist, and do not issue multiple immediate Skill loads.
|
||||
|
||||
## Inputs
|
||||
|
||||
Read the common input from the main session, especially:
|
||||
|
||||
- The user-confirmed goal, language, and Node labels.
|
||||
- Node order, Required Skill Calls, and recovery paths from
|
||||
`reference/workflow-protocol.json`.
|
||||
- The script author's `status`, `init`, `next`, `NEXT:`, `SKILL:`, and guard contracts.
|
||||
- The open / design / build / verify / archive boundary that must be preserved when users customize `/comet-classic`.
|
||||
|
||||
Use file handoff: the main session provides paths instead of pasting large bodies of text. Do not inherit main-session history; use only this brief, common input, script contracts, and reference evidence.
|
||||
|
||||
## Dispatch Template
|
||||
|
||||
Dispatch a fresh subagent for this role with:
|
||||
|
||||
```text
|
||||
description: "Write the workflow entry for <bundle-name>"
|
||||
prompt:
|
||||
You are the workflow entry author subagent.
|
||||
First read this brief, the common input path, script contract path, workflow protocol path, and report file path.
|
||||
First classify user decisions, automatic handling, stop conditions, and manual handoffs. If startup routing, recovery paths, current-Node detection, or genuine user choices are unclear, return NEEDS_CONTEXT.
|
||||
Do not guess or fill in missing flow details.
|
||||
Only write the entry SKILL.md draft; do not write internal Node Skills, Bundle state, or execute candidate scripts.
|
||||
The Decision Core MUST include four subsections: ### Automatic Node Detection (Step 0 intent detection + Step 1 state read + resume rules), ### Decision Classification And Decision Points (genuine user choices only), ### Red Flags (agent thought → actual risk table). Do not list guard failures, deterministic repair, a sole valid action, or manual handoff as a user decision. A Decision Core without these is a stub.
|
||||
Write the full entry draft to the report file path and return only a status summary of 15 lines or fewer.
|
||||
```
|
||||
|
||||
## Output Requirements
|
||||
|
||||
The entry draft must show:
|
||||
|
||||
- On entry, first read workflow state instead of directly loading a Node Skill.
|
||||
- If not started, initialize state before querying `next`.
|
||||
- Only after scripts output `NEXT: auto` and `SKILL: <node-skill>` should the agent load that single Node Skill.
|
||||
- The Node route table is reference only; it must not use "immediately execute" or "must load" execution directives.
|
||||
- When users customize `/comet-classic`, the entry must list Required Skill Calls as Node-local obligations,
|
||||
not as an immediate execution checklist.
|
||||
- User decisions, automatic handling, stop conditions, manual handoffs, recovery paths, and reference files are visible. Pause only when at least two real valid options remain, and merge adjacent choices.
|
||||
- When users customize `/comet-classic`, preserve the open / design / build / verify / archive main path and Guardrails.
|
||||
|
||||
Forbidden:
|
||||
|
||||
- Multiple `**Immediate:**` or `**Execute now:**` generated Node Skill loads in entry `SKILL.md`.
|
||||
- Copying full source Skill bodies.
|
||||
- Provider prefixes.
|
||||
- Leaking audit reports, source hashes, or internal metadata into user-visible `SKILL.md`.
|
||||
|
||||
## Self-Check
|
||||
|
||||
Before returning, check:
|
||||
|
||||
- The Decision Core has all four required subsections: Automatic Node Detection, Decision Points, Red Flags, and either Error Handling or Resume Rules.
|
||||
- The entry has exactly one main router startup protocol.
|
||||
- The entry has no immediate-load checklist for Node Skills.
|
||||
- The Node route is reference, not execution steps.
|
||||
- Automatic advancement references script outputs `NEXT:` and `SKILL:`.
|
||||
- A clear first invocation initializes directly, guard failures are diagnosed automatically or reported as stop conditions, and `NEXT: manual` only returns control; none is presented as a fabricated user decision.
|
||||
- User-visible English prose is consistent and does not mix in Chinese process sentences.
|
||||
|
||||
## Required Claim
|
||||
|
||||
- `workflow-entry`
|
||||
|
||||
Missing this claim must block Skill review.
|
||||
|
||||
## Status Return
|
||||
|
||||
Status must be one of `DONE`, `DONE_WITH_CONCERNS`, `NEEDS_CONTEXT`, or `BLOCKED`.
|
||||
|
||||
Write the full report to the report file path. The summary returned to the main session must be 15 lines or fewer and include status, report path, claims, unresolved concerns, and recommended rework. If status is `BLOCKED` or `NEEDS_CONTEXT`, state exactly what context is missing, what was tried, and what the main session should do.
|
||||
Reference in New Issue
Block a user