docs: tell scaffold agents to use a unique design, not mimic the scaffold#816
Conversation
…fold Every per-agent rule file already says to replace the example content but none said to give the app a DISTINCT look, so agents kept shipping the scaffold's palette/layout with new copy. Add a UI-scoped unique-design guideline alongside the scaffold-is-reference guidance in all five prose surfaces (AGENTS.md, CONVENTIONS.md, .cursorrules, copilot-instructions, .agents/rules/workflow.md) so every agent on every platform gets it. The api template has no UI, so the guideline is a natural no-op there.
vivek7405
left a comment
There was a problem hiding this comment.
Checked the lockstep and the accuracy. All five prose surfaces that carry the scaffold-is-reference guidance got the guideline in each agent's format; CLAUDE.md just @-includes AGENTS.md + CONVENTIONS.md so it inherits, and the .gemini/.opencode/.claude dirs are hooks, not prose. The CONVENTIONS list renumbers cleanly to 1..7 and nothing cross-references the old numbers. The look it tells agents NOT to copy (warm accent, 760px reading column, serif display) matches what the scaffold actually generates, and it keeps the design tokens as infrastructure. UI-scoped, so it is a no-op for api. Nothing to change.
AGENTS.md and CONVENTIONS.md scoped the unique-design guideline with an explicit 'the api template has no UI, so this does not apply there', but the three condensed rule files (.cursorrules, copilot-instructions, workflow.md) ended with an unconditional app/layout.ts reference. Add the same carve-out so an agent building an api app (no layout, no UI) is not misdirected, keeping all five surfaces consistent.
vivek7405
left a comment
There was a problem hiding this comment.
Zoomed in on cross-variant consistency, since the whole point of this is that all five surfaces say the same thing. The keep-the-tokens carve-out is solid everywhere and does not contradict the replace-the-placeholder marker rule. One real gap though: the two prose docs (AGENTS.md, CONVENTIONS.md) spell out the api carve-out but the three condensed rule files did not, and they end on an unconditional app/layout.ts reference, which an agent scaffolding an api app (no layout, no UI) could trip on. The 'when the app has a UI' opener scopes it, but the belt-and-suspenders line was missing. The cosmetic wording drift (warm colors vs warm accent, serif-display mention) is fine to leave since the rule files are deliberately terser.
vivek7405
left a comment
There was a problem hiding this comment.
Re-checked after the carve-out fix. All five surfaces now state the api carve-out equivalently, placed after the do-not-mimic clause and before keep-the-tokens; the CONVENTIONS list still renumbers cleanly to 1..7 and the rule-file bullet wrapping is intact. Reads consistent end to end now.
Closes #815
Summary
The scaffold's per-agent rule files already tell the building agent to REPLACE the example content ("the scaffold is reference, not the final product"), but none of them said to give the app a DISTINCT visual design. So agents kept shipping an app that still looked like the scaffold (the warm accent, the 760px reading column, the serif display, the example chrome), just with different copy. A platform embedding webjs (crisp) had to bolt this instruction onto its own build prompt; it belongs in the scaffold so every agent on every platform (Claude, Cursor, Copilot, Gemini, OpenCode, Aider) gets it for free.
Change
Added a UI-scoped "use a unique design, do not mimic the scaffold's example look" guideline alongside the existing scaffold-is-reference guidance, in all five prose surfaces in lockstep:
packages/cli/templates/AGENTS.mdpackages/cli/templates/CONVENTIONS.md(new numbered item 6)packages/cli/templates/.cursorrulespackages/cli/templates/.github/copilot-instructions.mdpackages/cli/templates/.agents/rules/workflow.mdScoped to UI so it is a natural no-op for the
apitemplate (no UI), and it explicitly says to KEEP the design tokens / theme wiring (infrastructure) and restyle on top.Doc surfaces
CLAUDE.md@-includes AGENTS.md + CONVENTIONS.md so it inherits;.gemini/.opencode/.claudeare hooks, not prose.webjs checkrule.Test plan
packages/cli/test/,test/scaffolds/*).webjs check(the guideline is prose, not an enforced marker).test/docs/doc-source-consistency.test.mjsstill passes (it gates the scaffold agent files).