fix(core): ask before optional tweak work

Author: hqhq1025

packages/core/src/generate.test.ts

@@ -181,7 +181,7 @@ describe('composeSystemPrompt()', () => {
     const prompt = composeSystemPrompt({ mode: 'create' });
     for (const guardrail of [
       'Section/content beats needed to avoid sparse output',
-      'Palette, type ladder, and tweakable tokens',
+      'Palette, type ladder, candidate tweakable tokens',
       'No hotlinked stock or placeholder images',
       'Content must be domain-specific',
       '#0E0E10',
@@ -236,6 +236,18 @@ describe('composeSystemPrompt()', () => {
     expect(prompt).toContain('TWEAK_DEFAULTS');
   });
 
+  it('create mode asks before high-impact ambiguity and treats tweaks as optional', () => {
+    const prompt = composeSystemPrompt({ mode: 'create' });
+    expect(prompt).toContain('ask before editing instead of guessing');
+    expect(prompt).toContain('optional feature would add meaningful work');
+    expect(prompt).toContain('Tweak controls would require extra design-token work');
+    expect(prompt).toContain('Expose tweaks selectively');
+    expect(prompt).toContain('Skip tweak work for narrow edits');
+    expect(prompt).toContain('they can ask for controls in a later turn');
+    expect(prompt).toContain('Empty `{}` is valid');
+    expect(prompt).toContain('user did not want tweak controls');
+  });
+
   it('create mode defines concrete DESIGN.md promotion triggers', () => {
     const prompt = composeSystemPrompt({ mode: 'create' });
     expect(prompt).toContain('Before a second screen');
@@ -317,13 +329,13 @@ describe('composeSystemPrompt()', () => {
     expect(p).toContain('not a standalone HTML export');
   });
 
-  it('requires staged file generation instead of one huge initial artifact write', () => {
+  it('allows a coherent first file pass before preview', () => {
     const p = composeSystemPrompt({ mode: 'create' });
-    expect(p).toContain('First file scaffold');
-    expect(p).toContain('Do not put the whole finished page into the first write');
+    expect(p).toContain('First file pass');
+    expect(p).toContain('create `App.jsx` when you have a coherent first pass');
     expect(p).toContain('Preview the complete pass');
-    expect(p).toContain('Implement the first complete pass');
-    expect(p).toContain('do not call `preview` while the file is still only a scaffold');
+    expect(p).toContain('Implement and polish');
+    expect(p).toContain('Do not call `preview` while the file is still only a scaffold');
   });
 
   it('asks the agent to interleave concise progress notes with tool phases', () => {

packages/core/src/prompts/sections/editmode-protocol.md

@@ -1,6 +1,6 @@
 # EDITMODE protocol
 
-Declare user-tweakable visual parameters near the top of the design source:
+When useful, declare user-tweakable visual parameters near the top of the design source:
 
 ```js
 const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
@@ -18,6 +18,6 @@ Rules:
 - The preview runtime exposes each key as `--ocd-tweak-<kebab-key>` on `:root` before the design renders, for example `accentColor` becomes `--ocd-tweak-accent-color`.
 - Consume tweakable visual values through those CSS custom properties in styles, such as `background: "var(--ocd-tweak-accent-color)"` or `padding: "calc(var(--ocd-tweak-density) * 1rem)"`, so the tweak panel can update the rendered design instantly without re-running React or Babel.
 - Do not wire tweakable colors, spacing, radius, opacity, or typography directly from `TWEAK_DEFAULTS` into one-time rendered inline values when a CSS custom property can represent the same value.
-- Pick 2-6 values that materially change the design.
-- Empty `{}` is valid when no useful controls exist yet.
+- Pick 2-5 values that materially change the design.
+- Do not invent controls just to fill the panel. Empty `{}` is valid when no useful controls exist yet or when the user did not want tweak controls for this turn.
 - In revise mode, preserve an existing EDITMODE block unless the user explicitly asks to change it.

packages/core/src/prompts/sections/pre-flight.md

@@ -7,7 +7,7 @@ Before writing, silently decide:
 3. Section/content beats needed to avoid sparse output.
 4. Any metrics, comparisons, charts, empty states, forms, device frames, or brand references implied by the brief.
 5. Which manifest resources to load with `skill()` or `scaffold()`.
-6. Palette, type ladder, and tweakable tokens.
-7. The first file action sequence: for a fresh workspace, `set_todos`, compact scaffold `create App.jsx`, incremental edits to a complete first pass, then `preview(App.jsx)`; for existing source, `set_todos`, `view`, then edit.
+6. Palette, type ladder, candidate tweakable tokens, and whether tweak controls are worth doing now.
+7. The first file action sequence: for a fresh workspace, optional `set_todos` when the work has multiple steps, `create App.jsx`, focused edits to a complete first pass, then `preview(App.jsx)`; for existing source, optional `set_todos`, `view`, then edit.
 
-If a decision is still materially unclear, call `ask()` instead of guessing.
+If a decision is still materially unclear, or if optional tweak/control work may not be valuable for this user, call `ask()` instead of guessing.

packages/core/src/prompts/sections/workflow.md

@@ -2,14 +2,14 @@
 
 Work in a visible loop:
 
-1. **Understand** — infer the artifact, audience, tone, and density target from the brief.
-2. **Plan** — for a fresh design, call `set_title` once; for continuation or existing-source turns, do not call `set_title` unless the user explicitly asks to rename or pivot to a new artifact. Call `set_todos` before any `create`, `str_replace`, or `insert` file edit. This is required for fresh single-file designs too.
+1. **Understand** — infer the artifact, audience, tone, and density target from the brief. If the brief leaves a high-impact direction open, ask before editing instead of guessing.
+2. **Plan** — for a fresh design, call `set_title` once; for continuation or existing-source turns, do not call `set_title` unless the user explicitly asks to rename or pivot to a new artifact. Use `set_todos` for multi-step or ambiguous work, but do not delay a ready file edit solely to add todos.
 3. **Load resources** — use the resource manifest. Call `skill(name)` for matching method guidance, call `skill("brand:<slug>")` for reference-only brand DESIGN.md, and call `scaffold({kind, destPath})` for concrete starter/source files. If you need copyable JSX component patterns, view virtual `skills/*.jsx` snippets and adapt them; do not confuse those snippets with markdown `skill(name)` rules.
-4. **First file scaffold** — for a fresh artifact, create a compact `App.jsx` shell first: tokens, layout frame, representative content, and a valid `ReactDOM.createRoot(...)` end line. Do not put the whole finished page into the first write, and do not call `preview` while the file is still only a scaffold, loading state, skeleton, or placeholder.
-5. **Implement the first complete pass** — add the main sections, real mock data, visual hierarchy, interactions, responsive polish, and accessibility in smaller `str_replace` or `insert` edits. Do not paste source code in chat.
+4. **First file pass** — for a fresh artifact, create `App.jsx` when you have a coherent first pass: tokens, layout frame, representative content, and a valid `ReactDOM.createRoot(...)` end line. Do not call `preview` while the file is still only a scaffold, loading state, skeleton, or placeholder.
+5. **Implement and polish** — add or refine the main sections, real mock data, visual hierarchy, interactions, responsive polish, and accessibility with focused `str_replace` or `insert` edits. Do not paste source code in chat.
 6. **Preview the complete pass** — call `preview(App.jsx)` only after the artifact can stand on its own without "Loading", "Generating", gray skeleton blocks, placeholder cards, or empty lower sections, unless the user explicitly asked for a loading-state design.
 7. **Design baton** — create, repair, or update the workspace `DESIGN.md` for substantive artifacts, multi-screen work, adopted brand refs, or stable reusable tokens.
-8. **Expose tweaks** — call `tweaks()` after the first pass and keep 2-5 meaningful EDITMODE values, not every pixel.
+8. **Expose tweaks selectively** — call `tweaks()` only when the user asked for controls, answered that controls would help, or the artifact has 2-5 obvious high-leverage values. Skip tweak work for narrow edits, throwaway sketches, or when the user declines; they can ask for controls in a later turn.
 9. **Finish** — call `done(path)`. After it succeeds, answer with 1-2 concise sentences and no code.
 
 ## Visible progress
@@ -18,8 +18,15 @@ Interleave tool groups with short assistant text so the user understands the wor
 
 ## Ask
 
-If the brief is genuinely ambiguous, call `ask({questions:[...]})` before writing. Prefer visual/options questions over prose, keep the set small, and continue once the answer lands.
+If the brief is genuinely ambiguous or an optional feature would add meaningful work, call `ask({questions:[...]})` before writing. Prefer visual/options questions over prose, keep the set small, and continue once the answer lands.
+
+Good ask moments:
+- The user has not chosen a visual direction, artifact type, content source, or target audience.
+- Tweak controls would require extra design-token work and the brief does not imply the user wants them.
+- You are choosing between a quick one-off artifact and a reusable design system surface.
+
+Ask at most 1-3 questions. Do not ask about details you can infer safely or revise cheaply later.
 
 ## Revision workflow
 
-For revise-mode, continuation, or inline-comment work, call `set_todos`, re-read the current artifact with `view`, make the minimum coherent change, preserve the existing visual system unless asked, then call `done`.
+For revise-mode, continuation, or inline-comment work, re-read the current artifact with `view`, use `set_todos` only when the change has multiple steps, make the minimum coherent change, preserve the existing visual system unless asked, then call `done`.

packages/core/src/tools/ask.test.ts

@@ -56,6 +56,11 @@ describe('validateAskInput', () => {
 });
 
 describe('makeAskTool', () => {
+  it('describes optional tweak controls as a valid reason to ask', () => {
+    const tool = makeAskTool(async () => ({ status: 'answered', answers: [] }));
+    expect(tool.description).toContain('optional work such as tweak controls');
+  });
+
   it('routes valid input through the bridge and surfaces the answers', async () => {
     const canned: AskResult = {
       status: 'answered',

packages/core/src/tools/ask.ts

@@ -281,7 +281,8 @@ export function makeAskTool(askBridge: AskBridge): AgentTool<typeof AskInput, As
       'Render a structured questionnaire (1–25 questions, 5 types: text-options / ' +
       'svg-options / slider / file / freeform) to the user and wait for answers. ' +
       'Use BEFORE implementing when the request is ambiguous or when aesthetic / ' +
-      "content direction is unclear. Returns `{status: 'answered', answers}` or " +
+      'content direction is unclear, including optional work such as tweak controls. ' +
+      "Returns `{status: 'answered', answers}` or " +
       "`{status: 'cancelled', answers: []}`.",
     parameters: AskInput,
     async execute(_toolCallId, params): Promise<AgentToolResult<AskResult>> {