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.

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.

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.

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 passes, record .comet.yaml verify_result: pass under /comet-verify rules. Do not omit that state before archive. Passing verification still leads to /comet-archive for final confirmation; never run archive automatically without it.

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.

Continue through the preset

1. An escalation condition appears: pause, present choices, and wait for an explicit decision to continue tweak or move to the full /comet-classic flow.
2. Verify needs acceptance of a WARNING/SUGGESTION deviation, a spec-divergence decision, or a strategy after the automatic repair limit. The first 3 clearly repairable failures are repaired and reverified automatically.
3. The final pre-archive choice of whether to archive and how to deliver the archive commit.

Order: quick Open → Build with escalation checks → Verify → Archive → done.

Continue to the next phase as soon as the current one finishes, subject to the rules above. Still invoke the required Comet/OpenSpec/Superpowers skills within each phase. If a called skill has a user decision, follow its rules. </IMPORTANT>

Escalation decisions

Escalation decides only whether to replace the lightweight preset with full. Neither the need for delta spec nor file count automatically upgrades the workflow. comet state scale recommends light/full verification without writing configuration; Verify chooses based on actual risk.

If /comet-classic passes an intent frame, before Build recheck only risk_signal and whether work adds a feature or public API, changes a structured-data schema, needs cross-module coordination, or exposes a deeper architecture issue. Follow this section when these arise. Delta spec remains a normal tweak artifact and does not automatically cause escalation. Do not repeat entry intent classification.

During implementation, watch for:

• Coordinated edits across modules.
• A new feature.
• Database schema changes.
• A new public API.
• A deeper architecture issue.
• The need to split this tweak into multiple OpenSpec changes.

For any of these, the Agent must neither escalate nor decide to stay on tweak without the user.

File count prompts a scope review only; it is not a substantive escalation signal. When delivery files exceed the prompt threshold, such as > 6 files, first count the current change's delivery files and check for valid authorization below. More files do not necessarily require the full flow. Tweak often includes delta spec or configuration edits and usually touches more files than defect repair, so its threshold is higher than hotfix's.

Delivery files include only implementation/source, tests, user documentation, configuration, and generated output. Count committed changes after the confirmed baseline together with staged, unstaged, and untracked files, deduplicated by path. Exclude OpenSpec artifacts in the current change directory, .comet metadata, and unrelated dirty files. Do not count OpenSpec artifacts or unrelated dirty files toward the threshold, and do not skip substantive-signal checks because the file count is small.

Reusing explicit authorization for a file-count-only prompt

Only an explicit authorization from the user of the current change to continue when the scope and risk are unchanged and file count is the only trigger can create or reuse authorization. Ordinary “start repairing” instructions, Skill invocation, historical preferences, and Personal Memory are not authorization. Store it only in <classic-change-dir>/.comet/rulings.md using this stable structure; if the change directory does not exist yet, keep the record pending and do not assume authorization exists:

### Preset file-count authorization
- status: active|invalidated
- workflow: tweak
- decision: continue-on-file-count-only
- scope: <confirmed scope of the current change>
- allowed-file-categories: implementation, tests, user-docs, config, generated
- authorization-basis: user-explicit
- reason: <basis and reason supplied by the user>

When the file-count threshold is first exceeded without a valid ruling, pause under comet-classic/reference/decision-point.md and ask the user to choose continue tweak (A) or escalate to full (B). Write the ruling only after the user explicitly chooses A and confirms that scope and risk are unchanged and file count is the only trigger; later growth within the same scope can reuse status: active without asking again. With valid authorization, do not ask, but first report the total file count, category breakdown, mapping to the confirmed scope, the ruling location, and the evidence that no substantive escalation signal was found, then continue tweak. Verification depth still follows actual risk and the comet state scale recommendation.

When resuming a task, read the current change's ruling first. A valid status: active record is reused under the same conditions; status: invalidated, missing, unreadable, ambiguous, or scope-mismatched records require pausing and offering continue tweak or escalate to full again.

status: active is valid only when workflow matches tweak, scope, acceptance, and risk assumptions are unchanged, all new delivery files remain within allowed-file-categories, and file count is the only trigger. If the user revokes authorization, the workflow changes, scope or acceptance changes, a new module/API/schema/capability/architecture issue appears (for example, a new public API or structured-data schema change), or a file falls outside the authorized categories, mark the record status: invalidated and return to the pause. If rulings.md is missing, unreadable, ambiguous, or invalid, there is no valid authorization and the Agent must pause; when escalating to full, also mark it status: invalidated and do not reuse it.

Therefore, any substantive escalation signal, or a file-count threshold exceeded without valid authorization, requires pausing under comet-classic/reference/decision-point.md and waiting for an explicit choice. Do not enter /comet-design or create a Design Doc automatically.

After the user chooses escalation (B), run the supported state-machine transition to full and return to design:

comet state transition <name> preset-escalate

It atomically sets workflow/classic_profile to full, moves phase to design, clears design_doc, and clears preset-specific build_mode, tdd_mode, review_mode, isolation, and verify_mode. Immediately load comet-design using the Skill tool to complete the design within the existing change. On entering Build, jointly reconfirm the complete working configuration.

If the user chooses to continue (A), continue tweak only after they explicitly confirm that scope and risk are unchanged and file count is the only trigger, and record the authorization basis and reason in the structure above. A bare “start repairing” or “continue” without that authorization meaning is not sufficient; pause for clarification.

Exit conditions

• The change is implemented and tests pass.
• The change is archived.
• Any spec changes are synced to main spec.
• Phase guards: use comet guard <change-name> build --apply before build → verify, and follow /comet-verify to run comet guard <change-name> verify --apply before verify → archive.

Continue to the next phase

Follow comet-classic/reference/auto-transition.md and agent.continuation from the successful result. Do not repeat next, select, or check while valid state information is available. Run this only after context loss, external state changes, or when an older result lacks that information:

comet state next <name>

• NEXT: auto: invoke the skill named by SKILL: build returns comet-tweak, verify returns comet-verify, and archive returns comet-archive.
• NEXT: manual: do not invoke the next skill. Follow HINT, return control, and end this invocation without another confirmation question.
• NEXT: done: the workflow is complete.