Skip to main content
The tweak preset handles small, low-risk changes like copy edits, configuration tweaks, documentation updates, and prompt adjustments. It reuses Comet’s open, build, verify, and archive capabilities — but skips brainstorming and the full implementation plan, keeping the process lean and fast.

​
When to Use Tweak

Use /comet-tweak only when all of the following conditions are met:
  • The change is a local, non-capability adjustment: copy, configuration, documentation, or prompt edits
  • Fewer than 5 files are affected (typically no more than 4)
  • No cross-module coordination is required
  • Fewer than 5 new test cases are needed
  • Configuration changes involve only value modifications — no new config items are added or deleted
  • No new capability, architecture changes, or interface changes are introduced
  • No delta spec is needed (if an existing spec acceptance scenario is affected, upgrade to full)
When all conditions hold, tweak gives you the most lightweight path through the Comet workflow.

​
Tweak Workflow

/comet-tweak
  open → lightweight build → light verify → archive
  (brainstorming and full plan skipped)
PhaseWhat Happens
OpenStreamlined artifacts — proposal.md (motivation + goals + scope), design.md (brief description, no solution comparison), tasks.md (no more than 3 tasks)
Lightweight BuildDirect build (build_mode: direct) — tasks executed one by one, formatter and tests run per task, commits use tweak: prefix
Light Verifycomet-verify scale assessment confirms lightweight path (≤ 3 tasks, ≤ 4 files, no delta spec, no new capability)
ArchiveReuses /comet-archive after verify_result: pass is confirmed

​
Starting a Tweak

In your AI coding tool, describe the small change you want to make. Comet evaluates your description automatically:
  • If it meets tweak conditions, /comet auto-routes to /comet-tweak — you don’t need to invoke it directly.
  • You can also invoke /comet-tweak directly to explicitly use the preset.
Once invoked, the tweak workflow runs continuously without pausing for input — except at defined decision points (upgrade conditions and verification failures).

​
Upgrade Conditions

If any of the following conditions emerge during a tweak, Comet will pause and ask you to confirm an upgrade to the full workflow. Your explicit confirmation is required before the agent can continue.
ConditionWhy It Triggers an Upgrade
Change involves 5 or more filesExceeds small change scope
Cross-module coordination requiredRequires cross-component coordination
5 or more new test cases neededChange complexity is rising
Config item additions or deletions (not value changes)Beyond local optimization
New capability neededExceeds local optimization
Delta spec needed (existing spec acceptance scenarios affected)Must enter full workflow
Upgrade is confirmed interactively. If you decline, the tweak stops and Comet reports that the change has exceeded tweak scope.

​
Preset Comparison

AspectTweakHotfixFull
BrainstormingSkippedSkippedRequired
Full Implementation PlanSkippedSkipped (transfers to /comet-build if tasks > 3)Included
Verify ModeLight (5 quick checks)Scale-assessed (light or full)Full
Build Modedirect (default)direct (default)Chosen by user
Delta SpecNot allowed (triggers upgrade)Optional (triggers full verify)Supported
Typical UseDocs / copy / config / promptBug fixesFeatures / new capabilities
Max Files< 5< 3Unrestricted
Max Tasks≤ 3≤ 3 (else transfers to /comet-build)Unrestricted

​
Upgrading to Full Workflow

When a tweak is confirmed to need upgrading, Comet follows this path:
  1. Updates the workflow field in .comet.yaml to full
  2. Loads the comet-design skill to supplement a full Design Doc on top of the existing tweak artifacts
  3. Proceeds normally through the full workflow from the design phase onward
Your existing proposal.md, design.md, and tasks.md are preserved — you don’t start over.

​
Phase Guards

Tweak enforces the same guard transitions as the full workflow: 
# Transition open → build
"$COMET_BASH" "$COMET_GUARD" <change-name> open --apply

# Transition build → verify
"$COMET_BASH" "$COMET_GUARD" <change-name> build --apply

# Transition verify → archive (handled by /comet-verify)
"$COMET_BASH" "$COMET_GUARD" <change-name> verify --apply
Guards validate exit conditions before advancing — a tweak cannot enter verify without isolation and build_mode set, and cannot archive without verify_result: pass.