Basic principles
Treat this document as themandatory delivery processfor all Web work. First understand the current project and the user's goals, then form a plan, then implement, verify, conduct isolated review, and deliver. Do not migrate a stable architecture just for the sake of "new technology", do not expand the task when not asked, and do not substitute a UI that looks complete for work that is actually complete underneath.
Prioritize reusing the current project's mature tools, upstream patterns, and implementations that have been fully verified. Do not rewrite standard chat UI, Canvas behavior, streaming assistance capabilities, or provider integrations just to own the code. Do not add abstractions for nonexistent providers, protocols, research subjects, or future product patterns. Keep explicit state transitions, isolate third-party implementation differences, and keep Canvas and high-frequency interactions responsive during long tasks.
Required workflow
Work in the following order; except for pure copy, configuration, or very small verified fixes, do not skip the planning, acceptance, and isolated review steps.
- Identify the task and current state. Read the current repository's conventions, scripts, lockfile, existing components, dependencies, and deployment configuration. Determine whether the task is new creation, modification, repair, performance/experience optimization, review, release preparation, or deployment.
- Confirm current technical facts. Before creating a new project, upgrading dependencies, or using unfamiliar APIs, consult the official documentation of the relevant frameworks and tools; do not write implementations based on remembered versions, commands, or APIs.
- Output the plan first. Before implementation, provide a concise main-context summary of the plan. When needed, use the platform's available planning workflow to expand details. The plan should describe, according to the task's scale: goals and non-goals, user flows/information architecture, selection rationale, pages/components, state and data/API, dependency changes, risks, acceptance items, and deployment status.
- Implement the smallest correct change. Implement according to the current project's structure, naming, formatting, scripts, and existing design language. If adjacent issues are found, record them rather than expanding the current task.
- Perform quality acceptance. Run existing type checks, builds, and relevant tests; verify success, failure, empty, loading, and exception paths; complete screenshot, mobile, interaction, performance, SEO, and accessibility checks. Read
references/quality-gates.md。 - Perform strict isolated adversarial review. After each round of implementation or repair, must comply with
references/review-protocol.md. Fix only issues verified as true by source code or runtime facts, and re-verify after fixing. - Deliver according to evidence. Report what has been completed, verification evidence, real review issues fixed, remaining limitations, and optional follow-up work. Do not present checks that were not performed as passed.
Technology selection and toolchain
First preserve the current project's reasonable architecture. Only for new projects or when selection/migration is genuinely necessary, follow the table below and read references/stack-selection.md. Before choosing, verify the current official documentation, current stable versions, project compatibility, and existing scripts.
| Requirement characteristics | Default preferred choice | Decision points |
|---|---|---|
| Content sites, SEO, SSR, server components, or a mature React full-stack ecosystem | Next.js | Prioritize evaluating rendering, caching, routing, and the server-side boundary. |
| Highly interactive SPAs, marketing pages, pure front-end tools | Vite | Prioritize simplicity, rapid development, and client-side experience. |
| Full-stack React, Server Functions, end-to-end type safety, or deep TanStack workflows | TanStack Start | Prioritize evaluating existing TanStack integrations and server-side requirements. |
| Routing, querying/caching, data tables | TanStack Router、Query、Table | Do not create unjustified migrations for established, mature implementations. |
| 3D scenes, spatial interaction, WebGL experiences | React Three Fiber | Design in conjunction with performance budgets, fallback strategies, and accessible alternatives. |
| TypeScript asynchronous flows, error modeling, validation, server-side/domain workflows | Effect ecosystem | Evaluate and prioritize adoption by default; only refrain when complexity, compatibility, or project constraints prove it unsuitable. |
Vite+ priority rules: For applicable web projects, prioritize using Vite+ (vp) as the unified toolchain entry point. Before actually starting, consult the official Vite+ documentation and the current project's compatibility; do not harden any particular vp command, plugin, or compatibility assumption into a permanent rule. When using Next.js or another existing scaffold, first verify whether Vite+ is applicable, then decide whether to keep the project's existing tooling or introduce vp。
Implementation standards
Follow the non-negotiable standards below; for extended rules on UI, motion, and common issues, read the corresponding reference files as needed.
- Types and input: Leverage TypeScript inference as much as possible; avoid
any; validate the structure, semantics, and error paths of unknown external input when it enters the system. Whether or not Effect is adopted does not change this requirement. - State honesty: A spinner only indicates that real work has not yet completed; success is shown only after the underlying task completes; drafts must not masquerade as applied; disconnected agents or services must not masquerade as active.
- Comments and maintainability: Comments explain only intent, constraints, or non-obvious behavior, and do not restate obvious code. Provider and drawing/Canvas specifics must not leak into general product state.
- Usability and responsiveness: Maintain visible focus, keyboard reachability, sufficient contrast against the actual background, clear page escape paths, and mobile-first layouts. Read
references/design-motion.md。 - Evidence of user-visible changes: For UI changes, provide before-and-after screenshots when feasible. When motion, timing, drag-and-drop, or multi-step interactions are the focus, provide a short screen recording or equivalent runnable evidence.
- Media assets: Do not cram large images, videos, or other media directly into the build directory; use the project's existing or confirmed asset storage solution, and keep source files outside the build directory. Do not write any particular storage path, upload command, or map service as a cross-project hard rule.
Git, PRs, and automated review
Follow the repository's existing commit, branch, code formatting, and Pull Request conventions. Local commits may be created for completed, verifiable changes;do not create a Pull Request unless the user explicitly requests it. When the user requests a PR, keep a single PR focused on one primary concern.
Treat automated review results as claims to be verified. Fix only when the conclusion is consistent with the source code, runtime artifacts, or established facts; do not change correct code to please a bot. Fixes for all real issues must go through the same round of acceptance and strict isolated adversarial review.
Deployment and Release Gates
Deployment, production release, pushing to the production environment, purchasing resources, creating paid services, or other external irreversible operations all require obtaining the user'sexplicit confirmationfor this task before the operation. You may complete deployment preparation, environment checks, builds, previews, and release plans on your own, but must not interpret "the user previously authorized autonomous development" as release authorization.
The specific deployment platform, domain, environment variables, preview strategy, rollback, and permissions must be determined in the respective project based on the actual environment; do not guess or hardcode them in this general skill.
Reference File Navigation
| File | When to Read |
|---|---|
references/stack-selection.md |
For new projects, framework/tool selection, dependency upgrades, and when evaluating Vite+, TanStack, Effect, or React Three Fiber. |
references/design-motion.md |
When creating or reworking user-visible interfaces, design systems, themes, motion, or accessible experiences. |
references/quality-gates.md |
After each implementation, fix, performance optimization, delivery, or release preparation is completed. |
references/common-pitfalls.md |
When encountering issues with visual seams, contrast, themes, navigation, routing, state references, links, or selectors. |
references/review-protocol.md |
After each round of implementation or fixes is completed; mandatory. |
Prohibitions
- Do not skip planning and start medium-to-large Web implementations directly.
- Do not treat old memories of frameworks, versions, routing, or deployment commands as current facts.
- Do not create a Pull Request without authorization, or deploy/release without explicit confirmation for this task.
- Do not fabricate tests, screenshots, performance, SEO, accessibility, or review-pass conclusions.
- Do not let the adversarial reviewer read user requirements, plans, the main context, implementation notes, Git history, existing tests, or prior review conclusions.
- Do not rewrite mature capabilities without reason, introduce unnecessary dependencies, or expand the task scope when fixing.
- Do not deliver products with uncertain text contrast on transparent/image/scrolling backgrounds, unreachable navigation, or "fake success" UI.
This skill defines "fast completion" as: delivering a genuinely running, verifiable, maintainable Web experience with no fake states, using the minimal necessary changes.