This page documents the primary execution skills of the Comet state machine: comet-open, comet-design, and comet-build. These skills guide the AI agent through the first three phases of the Five-Phase Workflow ensuring rigorous artifact creation, user confirmation, and state-guarded transitions.
The Open phase focuses on problem exploration and structural initialization using the OpenSpec framework.
The skill begins by delegating to openspec-explore to define the change assets/skills/comet-open/SKILL.md18-28 It introduces a PRD Split Preflight blocking point: if the input is a large PRD or contains multiple independent capabilities, the agent must propose a split list and wait for user confirmation before proceeding assets/skills/comet-open/SKILL.md31-49
After split confirmation and requirements clarification, it uses openspec-new-change to create the structure assets/skills/comet-open/SKILL.md74-86 It enforces a "Naming and Scope Guard," preventing the agent from auto-generating change names without user confirmation assets/skills/comet-open/SKILL.md108
The phase is considered complete only when the following structure is present in openspec/changes/<name>/:
proposal.md: Why + What: problem, goals, scope assets/skills/comet-open/SKILL.md116design.md: How (high-level): architecture decisions assets/skills/comet-open/SKILL.md117tasks.md: Task checklist (checkboxes) assets/skills/comet-open/SKILL.md118.comet.yaml: Initialized via "$COMET_STATE" init <name> full assets/skills/comet-open/SKILL.md136Before exiting, the agent must use the platform's available user input mechanism to present a summary of the three artifacts and obtain explicit user approval assets/skills/comet-open/SKILL.md160-175
Phase 1 Workflow and Data Flow
Sources: assets/skills/comet-open/SKILL.md31-64 assets/skills/comet-open/SKILL.md90-118 assets/skills/comet-open/SKILL.md160-187
The Design phase transitions from high-level architecture to deep technical implementation details using the superpowers:brainstorming skill.
A critical step in this phase is the generation of a Handoff Package. The agent is prohibited from writing summaries manually assets/skills/comet-design/SKILL.md35 It must execute:
"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write assets/skills/comet-design/SKILL.md38
The handoff supports two modes:
off): Generates design-context.json and design-context.md (compact traceable excerpts) assets/skills/comet-design/SKILL.md43-48context_compression: beta): Generates spec-context.json and spec-context.md (structured spec projection) assets/skills/comet-design/SKILL.md50-55The agent loads superpowers:brainstorming with the handoff package as input assets/skills/comet-design/SKILL.md86-105 During brainstorming, it must incrementally update brainstorm-summary.md as a recovery checkpoint assets/skills/comet-design/SKILL.md134
Before creating the final design.md, an Active Context Compression Gate is enforced: the agent must trigger platform-native compression or prompt the user to clear the context window to preserve tokens for the Build phase assets/skills/comet-design/SKILL.md187-195
Upon confirmation, the design_doc path is recorded and the comet-guard.sh is invoked with --apply to transition to the build phase assets/skills/comet-design/SKILL.md215-228
Sources: assets/skills/comet-design/SKILL.md33-78 assets/skills/comet-design/SKILL.md134-146 assets/skills/comet-design/SKILL.md187-230
The Build phase is where implementation occurs. It introduces workspace isolation, specific execution modes, and a "Plan-Ready" pause point.
Implementation begins by creating a plan through a subagent to avoid polluting the main session context assets/skills/comet-build/SKILL.md33-35 The plan file (in docs/superpowers/plans/) must include a base-ref (the git HEAD before implementation) assets/skills/comet-build/SKILL.md46-63
After the plan is recorded, the agent provides a Plan-Ready Pause Point. The user can choose to continue in the current model or stop the invocation (build_pause: plan-ready) to switch to a more capable model for execution assets/skills/comet-build/SKILL.md83-104
Before implementation, the agent must ask the user to choose three parameters in a single interaction assets/skills/comet-build/SKILL.md116-141:
| Configuration Type | Options | Recommendation Rule |
|---|---|---|
| Workspace Isolation | branch or worktree | Use worktree for parallel development or uncommitted work assets/skills/comet-build/SKILL.md118-128 |
| Execution Method | subagent-driven-development or executing-plans | Use subagent for high complexity (tasks ≥ 3) assets/skills/comet-build/SKILL.md129-139 |
| TDD Mode | tdd or direct | Use tdd for logic changes; direct is for tweaks/hotfixes assets/skills/comet-build/SKILL.md153-160 |
subagent_dispatch: confirmed assets/skills/comet-build/SKILL.md150 assets/skills/comet-build/SKILL.md204executing-plans skill assets/skills/comet-build/SKILL.md203direct_override: true is set; default for hotfix and tweak assets/skills/comet-build/SKILL.md168-175Build Phase Configuration and Execution
Sources: assets/skills/comet-build/SKILL.md83-105 assets/skills/comet-build/SKILL.md116-160 assets/skills/comet-build/SKILL.md201-205
Since the build phase is often long-running, the skill supports recovery after context compaction. Running "$COMET_BASH" "$COMET_STATE" check <name> build allows the agent to read the phase, plan path, and use grep on tasks.md to find the first unchecked task and resume work seamlessly assets/skills/comet-build/SKILL.md31
Sources: assets/skills/comet-build/SKILL.md31 assets/skills/comet-build/SKILL.md108-114
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.