@rpamis/comet 0.4.0-beta.3 → 0.4.0-beta.5

package/eval/local/skills/benchmarks/039-release/comet-classic-039-design/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: comet-design
+description: "Comet Phase 2: Deep Design. Invoke with /comet-design. Produce Design Doc and delta spec through brainstorming."
+---
+
+# Comet Phase 2: Deep Design (Design)
+
+## Prerequisites
+
+- Active change exists (proposal.md, design.md, tasks.md)
+- No Design Doc (no corresponding file under `docs/superpowers/specs/`)
+
+## Steps
+
+### 0. Entry State Verification (Entry Check)
+
+Execute entry verification:
+
+```bash
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
+"$COMET_BASH" "$COMET_STATE" check <name> design
+```
+
+Proceed to Step 1 after verification passes. The script outputs specific failure reasons when verification fails.
+
+**Idempotency**: All design phase operations can be safely re-executed. If `handoff_context` and `handoff_hash` already exist, confirm they match current artifacts before deciding whether to regenerate.
+
+### 1a. Generate OpenSpec → Superpowers Handoff Package
+
+**Must be generated by script. Agent writing summaries on the fly is not allowed.**
+
+```bash
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
+```
+
+The script reads the change `.comet.yaml` `context_compression` snapshot, then generates and records the matching handoff package.
+
+Default `context_compression: off` generates:
+
+```
+openspec/changes/<name>/.comet/handoff/design-context.json
+openspec/changes/<name>/.comet/handoff/design-context.md
+```
+
+Beta mode (`context_compression: beta` in project `.comet/config.yaml`, snapshotted into `.comet.yaml` when the change is created) generates:
+
+```
+openspec/changes/<name>/.comet/handoff/spec-context.json
+openspec/changes/<name>/.comet/handoff/spec-context.md
+```
+
+And writes to `.comet.yaml`:
+
+```yaml
+handoff_context: openspec/changes/<name>/.comet/handoff/design-context.json
+handoff_hash: <sha256>
+```
+
+The default handoff package is a **compact traceable excerpt**, not an agent summary:
+- `design-context.json`: machine index containing change, phase, canonical spec, source paths, hash
+- `design-context.md`: context for Superpowers to read, containing script markers, source path, line range, sha256, deterministic excerpts
+- When exceeding excerpt budget, marks `[TRUNCATED]` and retains Full source path
+
+The beta handoff package is a **structured spec projection** that reduces OpenSpec token load without replacing the canonical spec:
+- `spec-context.json`: machine index containing change, phase, canonical spec, source paths, hash, and file roles
+- `spec-context.md`: context for Superpowers to read, verbatim-projecting delta spec files and referencing supporting artifacts by hash
+- OpenSpec delta specs remain canonical; if the projection is missing, stale, or unclear, regenerate the handoff or read the source spec directly instead of writing an agent summary
+
+If full context is genuinely needed, explicitly run:
+
+```bash
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write --full
+```
+
+Handoff package sources come from OpenSpec open phase artifacts:
+- `proposal.md`: goals, motivation, scope, non-goals
+- `design.md`: high-level architecture decisions, approach constraints
+- `tasks.md`: initial task boundaries
+- `specs/*/spec.md`: delta capability specs
+
+### 1b. Execute Brainstorming (with Context)
+
+**Immediately execute:** Use the Skill tool to load the Superpowers `brainstorming` skill. Skipping this step is prohibited.
+
+When loading the skill, ARGUMENTS must include:
+
+```text
+Language: Use the language of the user request that triggered this workflow
+```
+
+After the skill loads, follow its guidance and use the following context:
+
+```
+Change: <change-name>
+OpenSpec Context Pack: openspec/changes/<name>/.comet/handoff/design-context.md
+Machine handoff: openspec/changes/<name>/.comet/handoff/design-context.json
+
+If context_compression is beta, use:
+OpenSpec Context Pack: openspec/changes/<name>/.comet/handoff/spec-context.md
+Machine handoff: openspec/changes/<name>/.comet/handoff/spec-context.json
+
+OpenSpec artifacts are the upstream source of truth, but you must not weaken the Superpowers `brainstorming` clarification flow by "skipping redundant context exploration".
+Your task is to perform deep technical design based on the handoff package: implementation approach, technical risks, testing strategy, boundary conditions.
+If goals, scope, non-goals, acceptance scenarios, or key constraints remain unclear, you must continue asking questions and form the design proposal first; must not create the Design Doc after only one Q&A turn.
+Do not rewrite proposal/spec; if you find OpenSpec delta spec missing acceptance scenarios, you may only propose Spec Patches and write them back to OpenSpec delta spec; do not create a second requirements spec in the Design Doc. Spec Patches are limited to supplementing acceptance scenarios, correcting ambiguous descriptions, or adding boundary conditions — they must not substantially rewrite the delta spec's structure or scope. If major changes are needed, flag them as design findings and return to brainstorming for confirmation.
+
+Design Doc frontmatter must be minimal, containing only:
+---
+comet_change: <change-name>
+role: technical-design
+canonical_spec: openspec
+---
+
+Proceed through the original `brainstorming` skill flow: clarifying questions, 2-3 approaches, and step-by-step design confirmation. Do not write the Design Doc early.
+```
+
+Proceeding without loading this skill is prohibited.
+
+If the Superpowers `brainstorming` skill is unavailable, stop the process and prompt to install or enable Superpowers skills. Do not substitute this step with normal conversation.
+
+After the skill loads, follow its guidance to produce design proposals (presented as conversation):
+- Technical approach: architecture, data flow, key technology choices and risks
+- Testing strategy
+- Requirement/scope gaps and Spec Patches to be written back
+- If acceptance scenarios need supplementing, indicate delta spec changes to be written back
+
+The brainstorming phase does not write to the Design Doc file; it only produces design proposals for Step 1c user confirmation. Only after confirmation should `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` be created and delta spec written back.
+
+For context compaction recovery, the agent must incrementally update `brainstorm-summary.md` during brainstorming. After each clarification round or proposal iteration, update the file whenever new confirmed facts, key constraints, candidate approaches, trade-offs/risks, testing strategy, or Spec Patch candidates emerge; mark unconfirmed items as "pending" or "candidate". This file is a recovery checkpoint, not the Design Doc, and must not replace the Step 1c user confirmation.
+
+### 1c. User Confirms Design Proposal (Blocking Point)
+
+After brainstorming produces a design proposal, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to explicitly confirm the design proposal**. Must not create the final Design Doc, write `design_doc`, run design guard, or enter `/comet-build` before user confirmation.
+
+When pausing, only present essential summary:
+- Technical approach adopted
+- Key trade-offs and risks
+- Testing strategy
+- If there are Spec Patches, list the delta spec changes to be written back
+
+Only after the user explicitly confirms, proceed to Step 2. If the user requests adjustments, continue brainstorming iteration until the user confirms.
+
+### 1d. Brainstorming Checkpoint Finalization
+
+After the user confirms the design proposal, before creating the Design Doc, create or update the incrementally maintained checkpoint file and finalize it as the confirmed design summary:
+
+```bash
+mkdir -p openspec/changes/<name>/.comet/handoff
+```
+
+`openspec/changes/<name>/.comet/handoff/brainstorm-summary.md` structure:
+
+```markdown
+# Brainstorm Summary
+
+- Change: <change-name>
+- Date: <YYYY-MM-DD>
+
+## Confirmed Technical Approach
+
+<summary of the user-confirmed approach>
+
+## Key Trade-offs and Risks
+
+<major trade-offs and risks>
+
+## Testing Strategy
+
+<testing method overview>
+
+## Spec Patches
+
+<delta spec changes to write back, or "None" if none>
+```
+
+**Context compaction note**: Each incremental update to `brainstorm-summary.md` is a relatively safe recovery point. After brainstorming completes, if the context window is tight, prefer compacting here. After compaction, reload the following files to continue Step 2:
+- `openspec/changes/<name>/.comet/handoff/brainstorm-summary.md`
+- `openspec/changes/<name>/.comet/handoff/design-context.md` (or `spec-context.md` in beta mode)
+- `openspec/changes/<name>/.comet/handoff/design-context.json` (or `spec-context.json` in beta mode)
+
+### 1e. Active Context Compaction Gate
+
+After Step 1d completes and `brainstorm-summary.md` is written, enter the active compaction gate before creating the Design Doc. At this point the OpenSpec handoff, brainstorming decisions, and pending items are durable, so the agent should proactively release the earlier Spec and brainstorming context to preserve window space for Step 2 and the later Build phase.
+
+Rules:
+- If the current platform provides a native context compaction/cleanup mechanism (for example, the host agent's compact/compaction command, tool, or UI action), trigger active compaction here once; do not try to fake compaction through a shell script.
+- The compaction resume prompt must include the change name, current step (Design Step 2), and the three handoff file categories listed above.
+- If the current platform cannot be compacted programmatically by the agent, pause and tell the user to run the host platform's manual compaction action; continue to Step 2 only after the user confirms compaction is unavailable or asks to continue.
+
+### 2. Create Design Doc
+
+Create the Design Doc based on the full brainstorming conversation context (still in the main session).
+
+Design Doc frontmatter must be minimal:
+
+```yaml
+---
+comet_change: <change-name>
+role: technical-design
+canonical_spec: openspec
+---
+```
+
+Write the Design Doc to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`.
+If Spec Patches need to be written back, also edit the corresponding `specs/*/spec.md`.
+
+**Context compaction recovery**: If context has been compacted, resume from `brainstorm-summary.md` + handoff context. If the user has not confirmed the design proposal yet, return to Step 1b/1c and continue brainstorming; if the user has confirmed it, continue creating the Design Doc. brainstorm-summary.md is the compaction checkpoint, not the sole input for the Design Doc — when creating, leverage the full recovered context as much as possible.
+
+### 3. Update Comet State
+
+First record the design_doc path. If Spec Patches wrote back delta spec (added or modified `specs/*/spec.md`), must regenerate handoff to update hash:
+
+```bash
+# Record design_doc path
+"$COMET_BASH" "$COMET_STATE" set <name> design_doc docs/superpowers/specs/YYYY-MM-DD-topic-design.md
+
+# If delta spec changes exist, regenerate handoff (update hash)
+"$COMET_BASH" "$COMET_HANDOFF" <change-name> design --write
+
+# Auto-transition to next phase
+"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
+```
+
+If there are no delta spec changes, skip the handoff regeneration step. The state file updates automatically; no manual editing of other fields needed.
+
+## Exit Conditions
+
+- Design Doc created and saved
+- Design Doc frontmatter contains `comet_change`, `role: technical-design`, `canonical_spec: openspec`
+- `handoff_context` and `handoff_hash` written to `.comet.yaml` (enforced by guard)
+- `handoff_hash` matches current OpenSpec open phase artifacts (enforced by guard)
+- `design-context.md` or beta `spec-context.md` must be script-generated and contain source path, mode, sha256 traceability markers (enforced by guard)
+- In beta mode, `spec-context.json` must be structurally valid and reference the current source files (enforced by guard)
+- If new capabilities or supplementary acceptance scenarios exist, OpenSpec delta spec has been created/updated
+- `design_doc` written to `.comet.yaml`
+- **Phase guard**: Run `"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply`; after all PASS, auto-transitions to `phase: build`
+
+Must use `--apply` before exit:
+
+```bash
+"$COMET_BASH" "$COMET_GUARD" <change-name> design --apply
+```
+
+## Context Compression Recovery
+
+Follow `comet/reference/context-recovery.md` with phase set to `design`.
+
+## Automatic Handoff to Next Phase
+
+Follow `comet/reference/auto-transition.md`. Key command:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <change-name>
+```
+
+- `NEXT: auto` → invoke the skill pointed to by `SKILL` to enter the next phase
+- `NEXT: manual` → do not invoke the next skill; prompt user to run `/<SKILL>` manually
+- `NEXT: done` → workflow is complete, no further action needed

package/eval/local/skills/benchmarks/039-release/comet-classic-039-hotfix/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: comet-hotfix
+description: "Comet preset path: Bug fix / hotfix. Skip brainstorming, directly open → build → verify → archive. Applicable for behavior fixes, scenarios not involving new capability design."
+---
+
+# Comet Preset Path: Hotfix
+
+Quick bug fix workflow: open → build → verify → archive. Skip brainstorming and full plan, applicable for behavior fixes not involving new capability design.
+
+**Applicable conditions** (all must be met):
+1. Fix bugs in existing functionality, no new capability
+2. No interface changes or architecture adjustments
+3. Change scope is predictable (usually ≤ 2 files)
+
+**Not applicable**: If fix process discovers need for architecture adjustments, should upgrade to full `/comet` workflow.
+
+---
+
+## Process (preset workflow, 6 steps)
+
+### 0. Output Language Constraint
+
+Streamlined OpenSpec artifacts must use the language of the user request that triggered this workflow.
+
+Execution chain: open → build → root cause check → verify → archive. Hotfix provides default decisions for each phase: streamlined open, direct build, root cause confirmation, scale-based verification, and final archive confirmation after verification passes.
+
+Locate Comet scripts before starting:
+
+```bash
+COMET_ENV="${COMET_ENV:-$(find . "$HOME"/.*/skills "$HOME/.config" "$HOME/.gemini" -path '*/comet/scripts/comet-env.sh' -type f -print -quit 2>/dev/null)}"
+if [ -z "$COMET_ENV" ]; then
+  echo "ERROR: comet-env.sh not found. Ensure the comet skill is installed." >&2
+  return 1
+fi
+. "$COMET_ENV"
+```
+
+### 1. Quick Open (preset open)
+
+Reuse Comet open capability to create change, but use hotfix defaults: do not execute `openspec-explore` long exploration, directly enter streamlined change creation.
+
+**Immediately execute:** Use the Skill tool to load the `openspec-new-change` skill. Skipping this step is prohibited.
+
+After the skill loads, follow its guidance to create streamlined artifacts:
+  - `proposal.md` — problem description + root cause analysis + fix goal (no solution comparison needed)
+  - `design.md` — fix solution (one is enough, no multi-solution comparison needed)
+  - `tasks.md` — fix task list
+- **No delta spec needed** (unless fix changes existing spec acceptance scenarios)
+
+Initialize Comet state file:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" init <name> hotfix
+```
+
+Verify initialized state:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" check <name> open
+```
+
+Run phase guard to transition open → build:
+
+```bash
+"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply
+```
+
+Check `auto_transition` to decide whether to continue:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <name>
+```
+
+- `NEXT: auto` → continue to Step 2
+- `NEXT: manual` → pause, follow `HINT` to prompt user to run `/<SKILL>` manually
+
+### 2. Direct Build (preset build)
+
+Use hotfix defaults: `build_mode: direct`. Skip Superpowers `brainstorming` and `writing-plans` (unless tasks > 3; if exceeds 3 tasks, transfer to `/comet-build`'s plan and execution method selection — note this does NOT trigger full workflow upgrade, only switches execution method).
+
+Before continuing or starting changes, handle uncommitted changes through `comet/reference/dirty-worktree.md`. If attribution shows the fix scope exceeds hotfix, handle it through this file's "Upgrade Conditions".
+
+**Immediately execute:** Execute tasks one by one according to tasks.md:
+
+1. Read `openspec/changes/<name>/tasks.md`, get incomplete task list
+2. For each incomplete task:
+   - Modify code according to task description
+   - Run project formatter (e.g., `mvn spotless:apply`, `npm run format`)
+   - Run related tests to confirm pass
+   - Check corresponding `- [ ]` to `- [x]` in tasks.md
+   - Commit code, commit message format: `fix: <brief fix description>`
+3. After all tasks complete, explicitly run relevant project tests and build commands
+
+**If fix affects existing spec acceptance scenarios**:
+- Create delta spec in `openspec/changes/<name>/specs/<capability>/spec.md`
+- Only include `## MODIFIED Requirements` section
+
+During hotfix execution, whenever a crash, unexpected behavior, test failure, or build failure appears while running the program, tests, build, or manual verification, must use the Skill tool to load the Superpowers `systematic-debugging` skill. Before root-cause investigation is complete, must not propose or implement source-code fixes.
+
+For specific investigation, minimal failing test, fix verification, and keeping the current change verification loop, follow `comet/reference/debug-gate.md`.
+
+### 3. Root Cause Elimination Check
+
+**Execute before running build guard**, ensuring the fix actually eliminates the root cause:
+
+1. Read bug description and root cause in proposal.md
+2. Search and verify problem code no longer exists
+3. If root cause not eliminated, return to Step 2 to continue fix (still in build phase, no state transition needed)
+
+**Upgrade conditions**:
+- Root cause check reveals deep architecture issues → Stop hotfix, handle per "Upgrade Conditions" section
+- Fix requires additional interface changes → Stop hotfix, handle per "Upgrade Conditions" section
+
+After root cause is confirmed eliminated, run phase guard to transition build → verify:
+
+```bash
+"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply
+```
+
+State automatically updates to `phase: verify`, `verify_result: pending`, then enter verification.
+
+### 4. Verification (preset verify)
+
+Reuse `/comet-verify`, with comet-verify's scale assessment deciding lightweight or full verification.
+
+**Immediately execute:** Use the Skill tool to load the `comet-verify` skill. Skipping this step is prohibited.
+
+Small-scale hotfixes without delta spec usually meet lightweight verification conditions (≤ 3 tasks, ≤ 2 files), comet-verify's scale assessment will select the lightweight verification path (6 quick checks, including lightweight code review). If hotfix created delta spec, enter full verification path according to comet-verify's scale assessment rules.
+
+After verification passes, record `.comet.yaml` `verify_result` as `pass` according to `/comet-verify` rules, must not skip this status before archiving. After verification passes, still enter `/comet-archive`'s final archive confirmation; do not automatically run the archive script.
+
+### 5. Archive (preset archive)
+
+Reuse `/comet-archive`. Must satisfy `verify_result: pass` in `.comet.yaml` before archiving, and wait for `/comet-archive`'s final archive confirmation.
+
+**Immediately execute:** Use the Skill tool to load the `comet-archive` skill to archive. Skipping this step is prohibited.
+If there is delta spec, sync to main spec according to comet-archive rules, and handle associated Design Doc and Plan archiving annotations.
+
+---
+
+## Continuous Execution Mode
+
+<IMPORTANT>
+Hotfix workflow is **one-time continuous execution**. After invoking `/comet-hotfix`, agent must automatically advance through hotfix steps, without pausing to wait for user input mid-way.
+
+Exception: when `.comet.yaml` has `auto_transition: false`, after each phase guard advances `phase`, do not auto-invoke the next skill. In this case, use `"$COMET_BASH" "$COMET_STATE" next <name>` output and pause for manual continuation as instructed.
+
+The following situations must also pause and wait for user confirmation:
+
+1. Encountering upgrade conditions (see "Upgrade Conditions" section). **Must use the current platform's available user input/confirmation mechanism to pause and wait for the user to explicitly confirm** upgrading to full workflow
+2. workspace isolation and execution-method selection when tasks exceed 3 and transfer to `/comet-build`
+3. verify phase (comet-verify) verification-failure and branch-handling decisions
+4. Final archive confirmation (before comet-archive runs the archive script)
+
+Execution order: quick open → direct build → root cause check → verification → archive → complete
+
+After each step completes, immediately enter next step. Within each phase, must still call corresponding Comet/OpenSpec/Superpowers skill according to above requirements; if the called skill has its own user decision points, follow that skill's rules.
+</IMPORTANT>
+
+---
+
+## Upgrade Conditions
+
+Upgrade to full `/comet` when **any** of the following conditions are met:
+
+| Condition | Explanation |
+|-----------|-------------|
+| Change involves **3+ files** | Exceeds single-point fix scope |
+| Architecture changes | New modules, new interfaces, new dependencies |
+| Database schema changes | Structural adjustments |
+| Introduces new public API | Fix creates new external interface |
+| Fix scope exceeds single function/module | Requires coordinated changes |
+
+When upgrade conditions are met, **must follow the `comet/reference/decision-point.md` protocol to pause and wait for the user to explicitly confirm** upgrading to the full `/comet` workflow. Do not directly enter `/comet-design`, and do not automatically supplement Design Doc.
+
+After user confirms upgrade, **must first update the workflow and phase fields** before entering full flow:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" set <name> workflow full
+"$COMET_BASH" "$COMET_STATE" set <name> phase design
+```
+
+Then on current change basis, supplement Design Doc: **Immediately use the Skill tool to load the `comet-design` skill**, proceed normally with full workflow. If user does not confirm upgrade, stop hotfix and report that current change has exceeded hotfix scope.
+
+---
+
+## Exit Conditions
+
+- Bug fixed, tests pass
+- Change archived
+- If spec changes, synced to main spec
+- **Phase guard**: Before build → verify run `"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply`; before verify → archive follow `/comet-verify` and run `"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply`
+
+## Automatic Handoff to Next Phase
+
+Follow `comet/reference/auto-transition.md`. Key command:
+
+```bash
+"$COMET_BASH" "$COMET_STATE" next <name>
+```
+
+- `NEXT: auto` → invoke the skill pointed to by `SKILL` to continue hotfix workflow (`phase: build` returns `comet-hotfix`, `verify` returns `comet-verify`, `archive` returns `comet-archive`)
+- `NEXT: manual` → do not invoke the next skill; prompt user to manually run `/<SKILL>` per `HINT`
+- `NEXT: done` → workflow is complete, no further action needed