feat: model overlays with explicit --model flag (no auto-detect)

Adds a per-model behavioral patch layer orthogonal to the host axis.
Different LLMs have different tendencies (GPT won't stop, Gemini
over-explains, o-series wants structured output). Overlays nudge each
model toward better defaults for gstack workflows.

Codex review caught three landmines the prior reviews missed:
1. Host != model — Claude Code can run any Claude model, Codex runs
   GPT/o-series, Cursor fronts multiple providers. Auto-detecting from
   host would lie. Dropped auto-detect. --model is explicit (default
   claude). Missing overlay file → empty string (graceful).
2. Import cycle — putting Model in resolvers/types.ts would cycle
   through hosts/index. Created neutral scripts/models.ts instead.
3. "Final say" is dangerous — overlay at the end of preamble could
   override STOP points, AskUserQuestion gates, /ship review gates.
   Placed overlay after spawned-session-check but before voice + tier
   sections. Wrapper heading adds explicit subordination language on
   every overlay: "subordinate to skill workflow, STOP points,
   AskUserQuestion gates, plan-mode safety, and /ship review gates."

Changes:
- scripts/models.ts: new neutral module. ALL_MODEL_NAMES, Model type,
  resolveModel() for family heuristics (gpt-5.4-mini → gpt-5.4, o3 →
  o-series, claude-opus-4-7 → claude), validateModel() helper.
- scripts/resolvers/types.ts: import Model, add ctx.model field.
- scripts/resolvers/model-overlay.ts: new resolver. Reads
  model-overlays/{model}.md. Supports {{INHERIT:base}} directive at
  top of file for concat (gpt-5.4 inherits gpt). Cycle guard.
- scripts/resolvers/index.ts: register MODEL_OVERLAY resolver.
- scripts/resolvers/preamble.ts: wire generateModelOverlay into
  composition before voice. Print MODEL_OVERLAY: {model} in preamble
  bash so users can see which overlay is active. Filter empty sections.
- scripts/gen-skill-docs.ts: parse --model CLI flag. Default claude.
  Unknown model → throw with list of valid options.
- model-overlays/{claude,gpt,gpt-5.4,gemini,o-series}.md: behavioral
  patches per model family. gpt-5.4.md uses {{INHERIT:gpt}} to extend
  gpt.md without duplication.
- test/gen-skill-docs.test.ts: fix qa-only guardrail regex scope.
  Was matching Edit/Glob/Grep anywhere after `allowed-tools:` in the
  whole file. Now scoped to frontmatter only. Body prose (Claude
  overlay references Edit as a tool) correctly no longer breaks it.

Verification:
- bun run gen:skill-docs --host all --dry-run → all fresh
- bun run gen:skill-docs --model gpt-5.4 → concat works, gpt.md +
  gpt-5.4.md content appears in order
- bun run gen:skill-docs --model unknown → errors with valid list
- All generated skills contain MODEL_OVERLAY: claude in preamble
- Golden ship fixtures regenerated

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-04-17 06:01:27 +08:00
parent 36ef6e9869
commit 6c8cf6774f
47 changed files with 890 additions and 6 deletions

10
model-overlays/claude.md Normal file
View File

@@ -0,0 +1,10 @@
**Todo-list discipline.** When working through a multi-step plan, mark each task
complete individually as you finish it. Do not batch-complete at the end. If a task
turns out to be unnecessary, mark it skipped with a one-line reason.
**Think before heavy actions.** For complex operations (refactors, migrations,
non-trivial new features), briefly state your approach before executing. This lets
the user course-correct cheaply instead of mid-flight.
**Dedicated tools over Bash.** Prefer Read, Edit, Write, Glob, Grep over shell
equivalents (cat, sed, find, grep). The dedicated tools are cheaper and clearer.

10
model-overlays/gemini.md Normal file
View File

@@ -0,0 +1,10 @@
**Conciseness constraint.** Keep non-code text output short. Aim for under 3 lines
for routine responses unless the user explicitly asks for detail. Code blocks and
command output do not count toward the limit.
**Bias toward action.** Run commands and show results rather than explaining what
commands you would run. The user sees the command and the output — they don't need
narration.
**Structured output when useful.** Tables, bullet points, and code blocks beat prose
for lists of things. Prose is for explaining; structure is for presenting.

15
model-overlays/gpt-5.4.md Normal file
View File

@@ -0,0 +1,15 @@
{{INHERIT:gpt}}
**Anti-verbosity protocol (additional).** Your default output mode is too verbose for
tools that value terse output. Constrain:
- Status updates: one line, not a paragraph.
- Code explanations: only when the user asked for one, or when the code is genuinely
surprising.
- Do not narrate what you are about to do. Just do it.
- Do not repeat the user's request back to them.
- When showing code changes, show the changed lines with minimal surrounding context.
- Markdown headings are not decoration. Use them only when structural.
**Cap answers at the shortest form that contains the answer.** If the answer is a
one-line command, reply with a one-line command.

14
model-overlays/gpt.md Normal file
View File

@@ -0,0 +1,14 @@
**Completion bias.** Do not end your turn with a partial solution when the full
solution is reachable. If you encounter an error, debug it. If a test fails, fix it.
If something is ambiguous, make your best judgment and proceed — don't stop and ask
unless you're genuinely blocked.
**Prefer doing over listing.** When you'd be tempted to write "you could also try X,
Y, or Z," try the best option yourself. Pick, execute, report results.
**No preamble.** Skip "Great question!", "Let me help with that", and restating the
user's request. Start with the work.
**Reminder: subordination applies.** When a skill workflow says STOP, stop. When the
skill asks via AskUserQuestion, that is the wait-for-user gate, not an ambiguity.
Completion bias does not override safety gates.

View File

@@ -0,0 +1,11 @@
**Reasoning model behavior.** You have strong internal reasoning. Use it, but do not
expose chain-of-thought in outputs unless the user asks to see your reasoning.
Surface the conclusion plus evidence, not the reasoning chain.
**Structured outputs preferred.** Tables or bullet points over prose paragraphs
when presenting analysis. Prose is for explanation and context; structure is for
findings, options, and comparisons.
**Completion bias (subordinate to safety gates).** Do not stop with partial
solutions when the full solution is reachable. But skill workflow STOP points,
AskUserQuestion gates, and /ship review gates always win over completion bias.