Skip to content

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

Description

@vivek7405

Problem

The scaffold's per-agent rule files tell the building AI agent to REPLACE the example content ("the scaffold is reference, not the final product"), but they never tell it to use a DISTINCT visual design. So agents frequently ship an app that still looks like the scaffold (its warm-orange palette, the 760px reading column, the serif display, the example chrome), just with different copy. Platforms embedding webjs (e.g. crisp) had to bolt this instruction onto their own build prompt; it should live in the scaffold so EVERY agent on EVERY platform (Claude, Cursor, Copilot, Gemini, OpenCode, Aider) gets it for free.

Design / approach

Add a short "use a unique design, do not mimic the scaffold's example look" guideline alongside the existing "scaffold is reference" guidance, in every per-agent rule surface, in lockstep. Scope it to UI so it is a natural no-op for the api template (no UI): "when the app has a UI, use a design of your own (palette, layout, type, chrome), not the scaffold's example look." Keep the design TOKENS / theme infrastructure (that is not the example look, it is wiring).

Implementation notes (for the implementing agent)

The 3 templates (full-stack / api / saas) SHARE one set of agent-rule files copied for all of them by packages/cli/lib/create.js (see templateFiles ~L457 and the command-rewrite list ~L521), so editing the shared files covers all three. The prose lives in FIVE files under packages/cli/templates/ (edit all in lockstep; CLAUDE.md just @-includes AGENTS.md + CONVENTIONS.md, and .gemini / .opencode / .claude are hooks, not prose):

  • AGENTS.md around L20-30 (the scaffold-reference + layout-width paragraph).
  • CONVENTIONS.md ## The scaffold is reference, not the final product (L308), specifically item 5 about adapting app/layout.ts / add a new item.
  • .cursorrules, .github/copilot-instructions.md, .agents/rules/workflow.md: each has a - **The scaffold is reference, not the final product.** bullet (~L17-21) to extend.

Landmines:

  • The scaffold AGENTS.md / CONVENTIONS.md are DISTINCT from the framework-root ones; edit the packages/cli/templates/ copies.
  • Invariant 11 (prose punctuation, no em-dash / space-hyphen / space-semicolon pause) applies to these files.
  • Keep the wording UI-scoped so api apps are unaffected.

Tests + docs: packages/cli/test/ scaffold tests + test/scaffolds/*; run test/docs/doc-source-consistency.test.mjs if it covers scaffold agent files. No docs-site API change (this is scaffold-authoring guidance). Also mirror into the docs-site scaffold/getting-started page only if it restates these rules.

Acceptance criteria

  • The unique-design guideline appears in all 5 per-agent prose files in lockstep, UI-scoped so api is unaffected.
  • A freshly scaffolded app still passes webjs check (guideline is prose, not an enforced marker).
  • Wording respects invariant 11 (no banned pause punctuation).
  • Scaffold tests still pass.

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Fields

No fields configured for issues without a type.

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions