Skip to content

docs: tell scaffold agents to use a unique design, not mimic the scaffold#816

Merged
vivek7405 merged 2 commits into
mainfrom
docs/unique-design-scaffold-guideline
Jul 7, 2026
Merged

docs: tell scaffold agents to use a unique design, not mimic the scaffold#816
vivek7405 merged 2 commits into
mainfrom
docs/unique-design-scaffold-guideline

Conversation

@vivek7405

Copy link
Copy Markdown
Collaborator

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.md
  • packages/cli/templates/CONVENTIONS.md (new numbered item 6)
  • packages/cli/templates/.cursorrules
  • packages/cli/templates/.github/copilot-instructions.md
  • packages/cli/templates/.agents/rules/workflow.md

Scoped to UI so it is a natural no-op for the api template (no UI), and it explicitly says to KEEP the design tokens / theme wiring (infrastructure) and restyle on top.

Doc surfaces

  • Scaffold templates (item 4): updated (the change IS the scaffold templates).
  • Every markdown (item 2): the five files above are the surfaces that carry these rules; CLAUDE.md @-includes AGENTS.md + CONVENTIONS.md so it inherits; .gemini / .opencode / .claude are hooks, not prose.
  • Docs site (item 3): N/A because this is scaffold-authoring guidance for the building agent, not framework API a docs reader consumes.
  • MCP (item 5): N/A because the guideline is prose in the scaffold rule files, not an introspection surface or a webjs check rule.
  • Editor plugins (item 6), marketing (item 7), version bump (item 9): N/A because no source, editor surface, landing claim, or published-package version changed.

Test plan

  • Scaffold tests still pass (packages/cli/test/, test/scaffolds/*).
  • A freshly scaffolded app still passes webjs check (the guideline is prose, not an enforced marker).
  • test/docs/doc-source-consistency.test.mjs still passes (it gates the scaffold agent files).
  • Invariant 11 (prose punctuation) respected in the added lines.

…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 vivek7405 self-assigned this Jul 7, 2026

@vivek7405 vivek7405 left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 vivek7405 left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread packages/cli/templates/.cursorrules
Comment thread packages/cli/templates/.github/copilot-instructions.md
Comment thread packages/cli/templates/.agents/rules/workflow.md

@vivek7405 vivek7405 left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@vivek7405 vivek7405 marked this pull request as ready for review July 7, 2026 05:52
@vivek7405 vivek7405 merged commit a579b14 into main Jul 7, 2026
10 checks passed
@vivek7405 vivek7405 deleted the docs/unique-design-scaffold-guideline branch July 7, 2026 05:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Tell scaffold agents to use a unique design, not mimic the scaffold

1 participant