production-product-builder skill

Production Product Builder

Turn a product prompt or repository into the fullest safe, working, measurable implementation the scope allows. Build end-to-end vertical slices, not disconnected screens. Optimize for durable user value and voluntary sharing rather than manipulative virality.

Start every run

1. Read repository instructions and inspect the actual stack, entry points, routes, data, auth, tests, CI, deployment, analytics, and uncommitted work.
2. Read references/execution-workflow.md and references/quality-gates.md.
3. Read only the task-relevant resources:

• brand, practitioner, studio, venue, launch, campaign, portfolio, or any content-led site with no application backend: references/premium-microsite-playbook.md
• new visual identity, substantial UI redesign, animated frontend, or reference-led design: references/frontend-art-direction.md
• choosing UI foundations or component galleries, including Material UI: references/ui-library-selection.md
• Motion/Framer Motion, GSAP, CSS, scroll or interaction animation: references/motion-engineering.md
• AI website prompts, MotionSites/Awwwards references, or design refinement: references/frontend-prompts.md
• tool and integration selection: references/tool-routing.md
• AI features, agents, RAG, voice, or model integrations: references/ai-product-playbook.md
• activation, retention, sharing, referrals, launch, SEO/AEO, or growth: references/growth-playbook.md
• third-party libraries, assets, hosting, or services: references/source-catalog.md
• documentation and handoff: references/deliverables.md

1. Run scripts/repo_audit.sh when shell access is available. Treat its report as discovery evidence, not proof that a feature works.
2. Before selecting or replacing a stack, resolve the user's frontend framework and backend language preferences using the intake below.
3. Translate the request into outcomes, users, jobs, journeys, conversion, requirements, exclusions, risks, assumptions, measurable acceptance criteria, and a dependency-ordered plan. Continue into implementation once relevant stack preferences are resolved, unless the user explicitly requests planning only.

Ask for stack preferences

For a new build, new frontend/backend, or stack replacement, ask for the missing choices before scaffolding or installing dependencies:

• Frontend: “Which frontend framework would you like, or would you like me to recommend one?” Offer a few relevant examples such as Next.js/React, Vue/Nuxt, Svelte/SvelteKit, Astro, or plain HTML/CSS. Accept another choice; this is not a fixed shortlist.
• Backend, when needed: “Which backend language would you prefer, or should I recommend one?” Examples include TypeScript/JavaScript, Python, PHP, Go, Java, or C#. A language, a runtime such as Node.js, and a framework are separate choices; record them accurately.
• Backend scope unclear: combine the question: “Do you want a backend? If yes, which language would you prefer, or should I recommend one?” Do not add a backend to a clearly frontend-only/static site or ask its language when none is needed.

Bundle the relevant questions into one short intake. Do not re-ask choices already supplied, including a named backend framework that clearly determines its language. For ordinary fixes or additions within an existing stack, preserve it; when a stack decision is actually needed, include keeping the detected stack as an option.

Wait for unanswered stack preferences before dependent implementation; continue independent inspection, content work, or reference research meanwhile. “No preference,” “recommend for me,” or “you choose” delegates the decision: select a suitable stack, briefly explain it, and proceed without another confirmation. Silence is not delegation. Record the chosen frontend framework, backend scope/language/framework, and whether each was supplied, retained, or delegated in the project brief. Reuse these choices throughout the task.

Catalog defaults and example CLI arguments are suggestions, not user choices. If the requested framework is absent from a helper's supported options, adapt the workflow manually instead of silently substituting another framework.

Operating contract

• Treat explicit user requirements as authoritative and preserve working architecture and unrelated changes.
• Ask for missing stack preferences as above. Resolve other ordinary ambiguity with documented assumptions; ask when a material decision cannot be inferred safely.
• Use the smallest architecture that satisfies the job. Extend a sound stack instead of replacing it for preference.
• Complete UI, domain logic, persistence, authorization, integrations, failure states, analytics, tests, and docs for each critical journey.
• Use real tools to inspect, edit, render, browse, test, and measure. Never substitute a plausible claim for executed evidence.
• Never expose secrets, access paid sources or external accounts without authorization, invent proof or metrics, bypass licenses, or run intrusive tests against production or third parties.
• Keep critical content usable without animation, WebGL, third-party scripts, or an ideal network.
• Do not commit, push, deploy, publish, purchase, message users, or mutate production unless explicitly authorized.

Product decision system

Prioritize work in this order:

1. Trust and correctness — data integrity, authorization, privacy, truthful claims, recoverability.
2. Core value — the shortest complete path from first visit to a meaningful outcome.
3. Activation and retention — onboarding, templates, sensible defaults, saved progress, reminders, collaboration, and recurring value.
4. Distribution — indexable content, shareable artifacts, invitations, embeds, referrals, integrations, and launch surfaces that are natural consequences of product use.
5. Polish — premium visual hierarchy, motion, 3D, delight, and secondary customization.

For every proposed feature, state the user problem, expected behavior, success signal, abuse/privacy risk, and cheapest valid implementation. Reject decorative or growth work that weakens the core journey.

Premium microsite track

When the job is to make a visitor understand, trust, and contact or buy — rather than to operate an application — run the specialist track instead of the full product workflow. Signals: brand site, landing page, portfolio, clinic or practice site, restaurant, venue, launch or campaign page, "make it feel premium", scroll animations, 3D product.

Read references/premium-microsite-playbook.md, then use the bundled knowledge base rather than reasoning from memory:

python3 scripts/microsite_search.py --list-domains
python3 scripts/microsite_search.py "<query>" --domain archetype|section|motion|webgl|schema|stack|brand|budget|content
python3 scripts/microsite_brief.py --list
python3 scripts/microsite_brief.py --archetype <name> --name "<client>" --out docs/MICROSITE_BRIEF.md
scripts/microsite_gate.sh <project-dir>

Track rules that override the generic defaults:

• Replace backend scope with an explicit exclusion list. Never invent auth, tenancy, migrations, or payments for a brochure site.
• Write the real content before the layout; keep it in one typed content module so copy is reviewable in a single diff.
• Ship a complete, accessible, motion-free static shell first. Motion and WebGL are added on top of something that already works.
• One WebGL centrepiece maximum, lazy-loaded behind a poster and a capability gate, with a static fallback that is a deliverable rather than a catch block.
• Every credential, number, testimonial, price, and affiliation comes from the client. Placeholders are marked TODO(client) and fail the gate.
• Pre-render the HTML. A client-rendered shell with an empty root element forfeits search, link previews, and no-JS visitors.

When ui-ux-pro-max is installed, use it to expand palette, font pairing, and style exploration when useful. Reconcile its suggestions with the actual brief and bundled checks; no specialist skill is required for this package to work.

Distinctive frontend track

For substantial visual work, read references/frontend-art-direction.md. Keep detailed guidance in the linked references instead of loading every catalog.

python3 scripts/microsite_search.py "professional react dashboard" --domain library
python3 scripts/microsite_search.py "editorial expressive" --domain typography
python3 scripts/microsite_search.py "scroll narrative" --domain pattern
python3 scripts/microsite_search.py "animated website prompts" --domain source
python3 scripts/frontend_brief.py --name "Project" --query "marine engineering precise blue" --framework react --kit marine-precision --engine motion
python3 scripts/design_validate.py

• Translate selected references into observed principles and original adaptations. Distinguish live motion observations from proposed timing and screenshot inference.
• Define a subject-specific composition, semantic palette, type roles, responsive behavior, and one useful signature interaction. Use real content and assets.
• Keep one coherent UI foundation and one primary animation owner. CSS, Motion, GSAP, Material UI, and component galleries have different jobs; choose by need and preserve a sound installed stack.
• Deliver the static layout and useful states before motion. Verify actual color pairs, focus/touch behavior, reduced-motion alternatives, lifecycle cleanup, and production cost.
• The brief generator creates local seeds and prompts, not a rendered design or verification evidence. A microsite still needs its content/SEO brief and release checks.

Tool orchestration

Select tools by capability and evidence needed; do not install a fashionable stack by default. Follow the decision matrix in references/tool-routing.md.

• Use repository search, language servers, type systems, tests, and build tools for code truth.
• Use a controlled browser for rendered behavior, breakpoints, keyboard flow, console/network errors, metadata, and screenshots.
• Use image generation only for original raster assets; use code-native SVG/CSS/canvas for interface primitives and established icon systems.
• Use document, PDF, spreadsheet, and presentation tooling when those formats are actual deliverables, then render and inspect them.
• Use official APIs/connectors for source-of-truth systems; request authorization before writes with external consequences.
• Use specialist security, SEO/AEO, UI/UX, accessibility, performance, and cloud tooling when installed and task-relevant. Fall back to standards-based local checks and document coverage gaps.
• Parallelize independent read-only discovery and verification when the environment explicitly permits agent delegation. Keep edits ownership-safe and integrate before broad tests.

Build an outcome contract

Before large edits, capture a compact contract in the plan or docs/PRODUCT_STRATEGY.md:

• audience, problem, promise, primary action, activation event, and return trigger;
• roles, permissions, core journeys, page/route map, data and integration boundaries;
• chosen frontend framework and backend scope/language/framework, with the user's choice or delegation recorded;
• functional and non-functional acceptance criteria;
• baseline and target metrics when supplied, plus instrumentation needed to measure them;
• privacy, accessibility, security, performance, reliability, SEO/AEO, and deployment constraints;
• assumptions, exclusions, dependencies, risks, and rollback path.

Never fabricate a baseline or forecast. Mark estimates as hypotheses and define how to validate them.

Implement in dependency order

1. Safe configuration, environment validation, secrets, and feature flags.
2. Schema, migrations, fixtures, and rollback/backup considerations.
3. Domain logic, API contracts, validation, authorization, idempotency, and error models.
4. Design tokens, accessible primitives, content hierarchy, and all interaction states.
5. Primary journey end to end; then secondary journeys and edge states.
6. External integrations with timeouts, retries, signatures, replay defense, fallbacks, and observability.
7. Ethical growth loop and instrumentation where the product benefits from it.
8. SEO/AEO, structured data, social cards, performance budgets, and offline/degraded behavior.
9. Tests, scans, browser verification, documentation, deployment, and rollback guidance.

After each coherent slice, run focused checks and fix causal failures before expanding scope.

Engineer growth without dark patterns

When growth is in scope, read references/growth-playbook.md and implement at most one primary loop first. A valid loop must connect value to a natural distribution action:

user receives value -> creates or shares useful artifact -> recipient experiences value -> recipient activates -> loop repeats

Instrument the funnel from acquisition through activation, retention, referral, and revenue where applicable. Include consent, attribution, abuse controls, unsubscribe/revocation, rate limits, and privacy minimization. Do not add forced invites, contact scraping, spam, fake scarcity, hidden consent, misleading social proof, or rewards that incentivize abuse.

Production engineering requirements

• Validate every trust boundary with schema-safe parsing and consistent nonsensitive errors.
• Enforce authentication and object-level authorization server-side with deny-by-default permissions.
• Use safe queries, transactions, indexes based on access patterns, bounded pagination, request limits, and upload controls.
• Protect sessions, cookies, webhooks, redirects, URL fetching, payments, CORS, CSRF, and secrets as applicable.
• Add health/readiness checks, structured logs, useful metrics/traces, error reporting hooks, audit events, backup, restore, migration, and rollback guidance.
• Make loading, empty, partial, error, unauthorized, offline, retry, success, and destructive-action states deliberate.
• Meet WCAG 2.2 AA: semantic structure, keyboard access, visible focus, contrast, labels, announcements, touch targets, zoom/reflow, and reduced motion.
• Set product-specific budgets for Core Web Vitals, route weight, images/fonts, third-party scripts, API latency, and expensive render loops. Record exceptions.
• Keep public copy specific and truthful. Never invent customers, reviews, usage numbers, prices, certifications, security guarantees, or outcomes.

Verify with evidence

Run the applicable subset and record exact commands, results, and gaps:

• format, lint, static analysis, typecheck, unit, integration, API, component, and end-to-end tests;
• production build plus migration and startup smoke checks;
• dependency, secret, SAST, container, and infrastructure scans;
• browser console/network, responsive viewport, keyboard, screen-reader spot check, automated accessibility, visual regression, and reduced-motion checks;
• production-mode performance, metadata, canonical, robots, sitemap, structured data, Open Graph, and broken-link checks;
• authorization, tenant isolation, validation, abuse, webhook, payment, data export/deletion, backup/restore, and rollback tests where relevant.

Run scripts/project_gate.sh near delivery and supplement it with project-specific commands. A skipped check is a coverage gap, not a pass. Never weaken a meaningful test or security control to obtain green output.

Finish the product

Create only relevant deliverables from references/deliverables.md. Ensure the repository contains enough information to set up, configure, migrate, seed, test, build, deploy, observe, troubleshoot, roll back, and report security issues.

Before declaring completion, verify that:

• critical journeys work end to end and acceptance criteria map to evidence;
• production build and critical tests ran successfully, or exact blockers are explicit;
• no known critical/high exploitable security issue, secret, unlicensed asset, fabricated claim, broken placeholder, dead control, or unexplained TODO remains;
• responsive, accessibility, performance, SEO/AEO, privacy, and browser coverage are recorded honestly;
• documentation matches the implementation and the working tree contains only intended changes.

Use the concise evidence-based final format in references/deliverables.md. Never call the result production-ready when a required release gate failed or was not run.