🛠️ webdev — Web Engineering Department

One head skill for web engineering. The stack is whatever the project already uses — detect first, build second; never introduce a new dependency for what a few lines or an installed one covers. Every mode ends with the repo's verification gate (build, tests, lint) actually passing.

Modes

Every invocation resolves to exactly one mode. Match the request, then load only the matched reference:

| Mode | Trigger phrases | Behavior | Reference | | frontend | "build this page/component", "frontend work", "react/astro/vue work", "popular-web-design", "imagegen-frontend-mobile", "userinterface-wiki", "developer homepage", "developer landing page", "anti-fouc", "zero-cls" | Component/page implementation against design spec, including developer 7-block architecture, anti-FOUC hydrator, and zero-CLS font fallbacks | references/frontend.md & references/hydration-polish.md | | backend | "api design", "endpoint", "database schema", "auth flow", "cli-developer" | APIs, data models, integrations, auth, and CLI developer tooling | references/backend.md | | fullstack | "fullstack feature", "end-to-end build", "ship the feature", "fullstack-guardian" | Full-feature build with Three-Perspective Security Architecture (Frontend, Backend, Security): data → API → UI → verified | references/fullstack.md | | ecommerce | "ecommerce", "checkout", "product catalog", "cart", "payment gateway" | Catalog, cart, checkout, payments, post-purchase flows | references/ecommerce.md | | cms | "cms integration", "content model", "payload", "sanity", "headless cms" | Content modeling + CMS integration + preview/editor experience | references/cms.md | | performance | "site is slow", "core web vitals", "lighthouse", "lcp/cls/inp", "cache-component" | Measure-first optimization: profile → fix → verify in field data with component caching | references/performance.md | | accessibility | "accessibility", "wcag", "screen reader", "keyboard nav", "a11y" | WCAG 2.2 AA audit and fixes: keyboard, contrast, semantics, forms | references/accessibility.md | | migrations | "migrate the site", "platform migration", "react 18 to 19", "major version upgrade" | Planned migrations: audit → map → execute → verify with rollback | references/migrations.md | | prototype | "spike this", "is this approach feasible", "riskiest unknown first", "throwaway probe" | Riskiest-technical-unknown-first throwaway tracer → proven/disproven/needs-probe verdict; code never ships | references/prototype.md | | spec | "write the spec", "spec this feature", "ready-for-agent", "scope this build", "spec-miner", "reverse engineer" | Build-ready spec packet and legacy code reverse-engineering (EARS format, Arch Hat vs QA Hat, deep seams); human gate per phase | references/spec.md | | implement | "implement the spec", "build from spec", "tracer slices", "ship this story" | Spec-to-shipped tracer slices (one test → one impl); Simplicity-First; review chain before done | references/implement.md | | onboard | "onboard", "oinboard", "codebase onboarding", "orient", "explain this repo", "explore codebase" | Rapid codebase orientation, execution path tracing, mental models, and repository exploration without speculation | references/onboard.md | | funnel | "build funnel", "sales funnel", "checkout flow", "multi-step form", "upsell flow", "funnel engineering", "conversion tracking" | Full-stack funnel engineering: multi-step form state machines, 1-click upsells/downsells, Stripe checkout, server-side tracking pixels (CAPI), and CRM webhooks | references/funnel.md | | edge | "edge runtime", "cloudflare workers", "hono edge", "d1 sql", "sub-10ms cold start" | Serverless edge computing: Hono v4, Cloudflare D1 parameterized queries, edge KV caching, and sub-10ms cold starts | references/edge.md | | rate-limit | "rate limit", "sliding window", "ddos defense", "abuse mitigation", "api rate limiter", "honeypot" | Edge rate limiting & abuse defense: sliding-window counters, IETF RateLimit headers, and honeypot bot tarpits | references/rate-limit.md | | offline | "offline mode", "pwa", "service worker", "offline caching", "background sync", "offline form queue", "sw generator" | Progressive Web App architecture: CacheFirst static assets, NetworkFirst API routing, IndexedDB mutation queues, and background sync | references/offline.md | | realtime-bus | "realtime bus", "websockets", "pub sub", "durable objects websocket", "sse stream", "live presence" | Distributed WebSockets & Server-Sent Events engine: Cloudflare Durable Objects backplane, monotonic sequence IDs, 45s heartbeat pruning, and sub-50ms fanout | references/realtime-bus.md | | deploy | "ship the build", "static upload", "one-command deploy", "deploy the frontend" | App-side ship: one-command full-stack deploy, static-upload fallback, object-storage contract (pipelines live in devops) | references/deploy.md | | audit | "audit responsiveness", "responsiveness-check", "mobile responsiveness", "viewport audit", "touch targets", "overflow check" | Responsive design audits (responsiveness-check), mobile viewports (375px–1920px), touch targets, and code health | references/audit.md |

Only the resolved mode's reference is loaded — the rest stay on disk, saving tokens on every run.

Chain order

prototype → spec → implement → qa-launch gate. Prototype answers the riskiest technical unknown (throwaway); spec turns the verdict into a labeled packet; implement rebuilds slice by slice (prototype code never merges); qa-launch verifies the shipped result. Design-side (visual/clickable) prototyping lives in design prototype — referenced, never duplicated here.

Support references (load on topic)

Loadable by topic; also routable as /webdev-<file> commands (not separate routed modes):

• technical-resilience.md
• security-headers.md

When to Use

• Building or refactoring web features, pages, or full apps.
• Designing or implementing APIs, data models, and integrations.
• Implementing e-commerce functionality (catalog, cart, checkout).
• CMS integration and content modeling.
• Fixing web performance or accessibility issues.
• Migrating sites, platforms, or major versions.

Anti-Triggers

• Visual design of new interfaces → design (ui mode).
• Polishing/refactoring existing UI → refactor-ui; motion → animate.
• Scaffolding a brand-new project from scratch → new-project.
• Native mobile apps → mobile.

Quick Reference

Stack-detection ladder (run before any mode)

1. Read package.json / pyproject.toml / go.mod / composer.json — framework, scripts, deps.
2. Read the router and directory structure — conventions beat guesses.
3. Read 2–3 representative components/endpoints — match their patterns exactly.
4. Only then plan. The existing pattern wins over personal preference. Always.

Verification gate (every mode)

A change is not done until the gate is green. If no gate exists, say so and add the minimal one.

CLI Engine Commands (webdev.ts)

Sourcing rule

When the user provides reference URLs (docs, examples, prior art) — fetch, read, and follow them as the primary source; defaults here are fallbacks. Record which URLs were used.

Suite contracts

• New projects: scaffold with new-project first; webdev builds on top.
• PR-quality bar: route the diff through code-review before merge.
• Programmatic video delivery (note only — build lives elsewhere): route assembly/export to animate (other-libraries §9) and scripting/production families to content (video mode).

Procedure

1. Intake. detect the existing stack from the manifest and imports before proposing anything — the repo wins over preference every time.
2. Resolve the mode. Match the request against the mode table; exactly one mode. Ambiguous → ask one question, then proceed.
3. Execute the mode playbook. Load references/<mode>.md and follow its Intake → Deliverable → Procedure → Quality gate in order.
4. Gate and deliver. Pass this file's Verification checklist plus the mode's quality gate, then deliver the artifact where the client expects it.

Pitfalls

• Introducing a new dependency where an installed one or a few lines suffice.
• Ignoring the repo's existing patterns — inconsistency is technical debt at delivery speed.
• Skipping the verification gate because 'it's just a small change'.
• Optimizing performance before measuring — profile first.
• A11y as a final coat — build accessible markup from the start; retrofitting costs 5×.
• Migrations without a rollback plan and content freeze strategy.
• Checkout flows without handling failure states (payment declines, inventory races).

Verification

• Stack detected and confirmed before any code was written.
• No new dependencies added unless justified against installed alternatives.
• The project's own verification gate (build/test/lint) ran green.
• All changes follow existing repo patterns (imports, naming, structure).
• Anti-FOUC blocking head script present in <head> (zero theme flash on refresh).
• Zero-CLS @font-face metric overrides configured for web font system fallbacks.
• Clean @media print stylesheet active (interactive chrome stripped, ink-safe).
• scroll-padding-top declared on root <html> matching sticky/fixed navigation header.
• Dev ports probed and subprocess zombies cleared before starting server.
• Dependencies vetted against typosquats and hallucinated compound packages.
• SSR boundaries verified (no unquarantined top-level browser globals).
• Interactive elements keyboard-navigable and labeled (default, not afterthought).
• Mode-specific gate in the loaded reference passed.