mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-19 10:52:28 +08:00
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:
10
model-overlays/claude.md
Normal file
10
model-overlays/claude.md
Normal 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
10
model-overlays/gemini.md
Normal 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
15
model-overlays/gpt-5.4.md
Normal 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
14
model-overlays/gpt.md
Normal 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.
|
||||
11
model-overlays/o-series.md
Normal file
11
model-overlays/o-series.md
Normal 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.
|
||||
Reference in New Issue
Block a user