Project Architecture Guardrails
Activation Contract
Load this skill before changing UI, layout, component structure, state flow, theming, data display, or the server/client boundary of a Next.js or Astro app.
Hard Rules
- Detect the framework from the project before acting; never assume it.
- Keep rendering server-first. Add client-side code only when the interaction cannot work without it, and keep that surface as small as possible.
- Read the installed framework's own docs before changing framework APIs or project structure.
- Follow
DESIGN.mdfor visual and UX decisions when it exists. - Build from existing shadcn primitives and semantic tokens before writing custom markup or styles; load
shadcn-component-boundarieswhen it is installed. - Make loading, empty, and error states explicit for every data display.
- Add tests proportional to risk, using the test tooling the project already has.
Decision Gates
Execution Steps
- Read
package.jsonand list the root config files to detect the framework. - Load the matching reference and apply its boundary rules.
- Search existing components, routes, and styles before creating new ones.
- Implement the change with the smallest client-side surface that works.
- Answer the pre-close checklist, then load
project-min-evaluationwhen it is installed, or run the project's quality scripts.
Pre-close checklist:
- Did the change add unnecessary client-side surface?
- Does it follow
DESIGN.md? - Are loading, empty, and error states explicit?
Output Contract
Report the detected framework, every server/client boundary added or moved (with its reason), and the checklist answers.
References
- references/next.md [blocked] — Next.js server/client boundary rules.
- references/astro.md [blocked] — Astro island boundary rules.
