Comet Tweak

Comet Preset: Tweak

Before starting or resuming, read and follow comet-classic/reference/classic-layout.md. All OpenSpec CLI calls must use the adapter, and all paths must use the bound <classic-*> logical roots.

Tweak provides preset choices for Comet's five-phase workflow. It uses OpenSpec for requirements and implementation, reuses open/build/verify/archive, and skips Superpowers brainstorming and a full implementation plan. It does not create a separate workflow.

Use it for configuration, documentation, or prompt adjustments, and moderate changes that need spec-driven implementation, including delta spec, without the full /comet-classic deep-design flow. Delta spec is a normal Tweak artifact; needing it is not by itself a reason to escalate.

All applicability conditions must hold:

1. The work fits in one OpenSpec change.
2. The solution can be clarified without a Superpowers Design Doc and full implementation plan.
3. No cross-module or cross-layer architectural coordination is needed.
4. Task scope can be estimated. File/task counts are prompts only, not automatic escalation rules; see “Escalation decisions.”

When the preset may no longer fit: If implementation encounters a change listed under “Escalation decisions,” let the user decide whether to use the full /comet-classic flow.

Preset flow: 4 phases

0. Set the output language

Use Comet's configured artifact language for the reduced OpenSpec artifacts. Before .comet.yaml exists, read classic.language from project .comet/config.yaml, then global ~/.comet/config.yaml. After initialization, read it with comet state get <name> language.

Execution order: open → OpenSpec apply → verify → archive. Tweak presets each stage: prepare the necessary artifacts, build directly through OpenSpec apply, choose light/full verification from change size and delta spec, and request final archive confirmation after verification passes.

Use the supported Comet CLI described in comet-classic/reference/scripts.md. On recovery from any entry, check phase/workflow under comet-classic/reference/context-recovery.md first.

For an existing tweak, the first state operation must be comet state select <change-name>. For a new change, run it immediately after .comet.yaml initializes successfully and before source edits.

After entering the tweak workspace and reading current phase, run comet task <project-root> --task "<original-user-request>" --phase "<phase>" --session "<stable-task-session-id>" --json. Use the returned context as follows:

• Add only returned text to the current context. Context Manifest (manifest / <context_manifest>) contains only summaries, application reasons, and stable IDs. Add --expand-context "<id>" when source text, provenance, or validation details are needed. When path, operation, or phase changes, select applicable entries again using the same --session.
• Use comet memory remember ... --scope global|project when the user explicitly asks for long-term memory. Use comet memory observe only for implicit, reusable, stable collaboration patterns. Do not save task summaries, progress, command output, or test results.
• Before task completion, write project-validated and reusable experience to Project Memory with comet knowledge remember <project-root> --title "<concise title>" --text "<symptom, approach, verification>" --type <fact|decision|pattern|procedure|constraint|failure-resolution> --json. The same title updates the existing entry; skip the write when nothing is reusable, and never save task summaries, one-off command output, or unverified guesses in Project Memory.
• After actually using an entry and determining its outcome, take applications[].applicationId (application_id in Hook text) and run comet task <project-root> --task "<original-user-request>" --application "<application-id>" --outcome used-successfully|ignored|overridden|corrected|contributed-to-failure --json to record the result.
• Before task completion, complete one learning check: when a user correction, preference, or collaboration habit has a clear reuse condition, call comet memory observe and pass --learning-check submitted to the completion command; pass --learning-check no-observation when you checked and found none, or --learning-check not-run when no check occurred. Use observation JSON learning.result and status.learning.lastCheck to distinguish candidate, promotion, deduplication, and skip; do not submit task summaries or test results.
• At task completion, still run comet task with --complete --workflow <workflow> --change <change-id> --learning-check submitted|no-observation|not-run. Without Hooks, this Skill uses the same interface. comet memory context is a compatibility entry only. Plugin failures do not block this change.

1. Open a minimal change

Reuse Comet Open with tweak defaults. Skip the full openspec-explore exploration and create the artifacts needed for this change.

Required now: Load openspec-new-change using the Skill tool. Do not skip this step.

<!-- external-openspec-skill-override -->

Adapt external OpenSpec instructions: Do not directly invoke the official CLI, adopt a fixed cwd, or read/write fixed physical OpenSpec paths. Use comet classic openspec -- <args...> for every OpenSpec command and this invocation's <classic-*> logical roots for all change and artifact paths.

Follow the skill to create the reduced artifacts:

• proposal.md: motivation, goals, and scope.
• design.md: a brief implementation approach; no comparison required.
• tasks.md: a reasonably scoped task list. Count alone does not trigger escalation; see “Escalation decisions.”
• Optional delta spec: create it normally if the change affects existing spec acceptance scenarios, using only ## MODIFIED Requirements or ## ADDED Requirements. OpenSpec uses delta specs to describe incremental changes to existing systems. The need for this artifact does not itself require escalation.

Workspace isolation is a user choice made before state initialization; do not write current as an assumed default (choosing a worktree after initialization fails: the change directory only appears in the primary root, not in the worktree). Pause under comet-classic/reference/decision-point.md and present:

• A. Work on the current branch (--isolation current, binding the actual branch).
• B. Create a branch: create and switch to tweak/YYYYMMDD/<change-name> (--isolation branch).
• C. Create a worktree: first load Superpowers using-git-worktrees with the Skill tool and let it create the isolated workspace (--isolation worktree).

Then prepare the workspace and initialize plus select the change inside the returned projectRoot:

comet classic workspace prepare <name> --isolation <selected-isolation> --json
cd <returned projectRoot>
comet state init <name> tweak --isolation <selected-isolation>
comet state select <name>
comet state check <name> open

If select/check returns BLOCKED because bound_branch differs from the current branch, pause under comet-classic/reference/decision-point.md. Offer a single choice: return to the bound branch and rerun entry checks, or, after the user explicitly confirms that the current branch should take over this change, run comet state rebind <change-name> and rerun entry checks. Do not switch or rebind branches yourself.

Apply the guard to move from open to build:

comet guard <change-name> open --apply

2. Build with OpenSpec apply, for tweak only

Use tweak's build_mode: direct. Preserve the isolation confirmed in Step 1; do not change it back to current. Skip Superpowers brainstorming and writing-plans, and execute this change's tasks through OpenSpec's apply action.

<IMPORTANT>
This apply path belongs only to tweak. Full `/comet-classic` or `workflow: full` must not use tweak's `openspec-apply-change` Build path. Full still generates a Design Doc through `/comet-design`, then plans and implements through `/comet-build` using the confirmed strategy. Autonomous does not require `writing-plans`; other strategies use the planning and execution skills specified by `/comet-build`.
</IMPORTANT>

Before starting or resuming edits, handle uncommitted changes under comet-classic/reference/dirty-worktree.md. After establishing ownership, follow “Escalation decisions” if a listed condition appears or changed files exceed the prompt threshold.

Required now: Load openspec-apply-change using the Skill tool. Do not skip this step.

<!-- external-openspec-skill-override -->

Adapt external OpenSpec instructions: Use its apply method only. Replace direct official CLI calls, fixed cwd, and fixed physical OpenSpec paths with comet classic openspec -- <args...> and the <classic-*> logical roots.

Pass the current <change-name> and follow the skill's apply instructions:

1. Run comet classic openspec -- status --change "<name>" --json, or use its still-valid result, to identify the schema and task artifact.
2. Run comet classic openspec -- instructions apply --change "<name>" --json, or use its still-valid result, to read apply instructions, contextFiles, task progress, and the current instruction.
3. Read every listed context file. Do not implement from old conversation alone or simply invent a loop over tasks.
4. Complete unchecked tasks one by one under the apply instructions, keeping changes minimal and focused.
5. After each task:
   • Run the project's formatter, such as mvn spotless:apply or npm run format.
   • Run relevant tests and confirm they pass.
   • Mark the task complete under openspec-apply-change rules.
   • Commit with tweak: <change-summary>.
6. Explicitly run relevant project tests and build after all tasks finish.
7. Apply the phase guard to move from build to verify.

During tweak, a crash, unexpected behavior, failing test, or failing build encountered while running the program, tests, build, or manual verification requires loading Superpowers systematic-debugging through the Skill tool. Do not propose or implement source repairs before completing root-cause investigation.

Follow comet-classic/reference/debug-gate.md for investigation, the minimal failing test, verification after repair, and completing those steps within the current change.

Reassess whether tweak still fits: Throughout Build, and once more before build→verify, follow “Escalation decisions”:

• The Agent assesses the actual changes for conditions requiring reconsideration of the workflow.
• File counts only prompt the user to review scope; when the threshold is exceeded without valid authorization, the user decides whether to escalate.
• Scale only recommends light/full verification; it does not decide workflow escalation.

When an escalation condition applies, or the file-count threshold is exceeded without valid authorization, do not escalate or decide to continue on your own. Pause under comet-classic/reference/decision-point.md and ask the user to choose tweak or the full /comet-classic flow. With valid authorization, follow the reporting and continuation rules below without asking again.

Apply the phase guard:

comet guard <change-name> build --apply

State becomes phase: verify, verify_result: pending; continue to verification.

3. Verify

Reuse /comet-verify, whose size assessment selects light or full verification.

Required now: Load comet-verify using the Skill tool. Do not skip this step.

Verification with delta spec: Delta spec is a normal tweak artifact. If the change created one, explicitly set full verification before entering comet-verify. This uses OpenSpec verification (openspec-verify-change) to check delta-spec consistency:

comet state set <change-name> verify_mode full

A tweak without delta spec usually meets light conditions (≤ 3 tasks and changed files below the scale threshold). Follow comet-verify's light-verification checklist. If the user wants more review, they can run comet state set <name> review_mode standard or thorough before verification.

After verification and its report are complete, /comet-verify runs comet guard <change-name> verify --apply. Reuse its successful archive state and agent.continuation; do not manually set verify_result: pass or repeat Guard. If Guard fails, address its reasons without claiming acceptance passed. /comet-archive still requires final confirmation before archiving; never run archive automatically.

4. Archive

Reuse /comet-archive. Require .comet.yaml verify_result: pass and wait for its final archive confirmation.

Required now: Load comet-archive using the Skill tool. Do not skip this step.