production-full-stack

Production Full-Stack

Produce a deployable, observable, secure system—not a demo. Ponytail governs scope, not production quality: prefer a modular monolith until measured needs justify services, but never omit a required control to save code.

If this is an existing application and adoption is pending, stop and invoke Adopt Existing Project. Do not scaffold over, move or refactor existing code until its read-only assessment and user approval gate are complete.

1. Research and decisions

Before selecting a framework, queue, cache, database library, validation library, UI system, or observability package:

1. Search current official documentation, release notes, package registries, security advisories, maintenance policy, compatibility, and license.
2. Prefer stable, actively maintained, production-proven libraries with minimal dependency and operational cost. Do not select from memory alone.
3. Record considered options, versions, evidence links, tradeoffs, and the final decision in docs/architecture/dependencies.md.
4. Pin direct dependencies and commit the ecosystem lockfile.

Read references/architecture.md, then use Superpowers brainstorming and planning before implementation.

2. Scaffold the production contract

Create a stack-appropriate equivalent of:

apps/web        frontend
apps/api        HTTP/API process
apps/worker     background worker process
packages        shared contracts, UI, validation, config, observability
database        schema, migrations, seeds
infra           Docker and deployment configuration
tests           unit, integration, contract, E2E, load and security tests
docs            architecture, API, operations and security evidence

Also create and maintain:

• Dockerfile for each runnable service, compose.yaml for local development, and compose.prod.yaml as a hardened single-host production baseline.
• .env.example with documented names and safe placeholders.
• .env.local with cryptographically generated development secrets; never use secret, changeme, framework defaults, or copied production values.
• .gitignore covering .env.local, other environment files except examples, keys, certificates, logs, dumps, caches, coverage, builds and editor files.
• .production-baseline.json containing implementation and test evidence.
• README.md, DESIGN.md, API documentation, threat model, ASVS matrix, operational runbook and risk register.

Run Security Review and state STRIDE mitigations before implementation.

3. Mandatory architecture outcomes

• Keep API processes stateless and horizontally scalable.
• Include a queue/broker and a separately scalable worker service.
• Move slow, bursty, retryable, scheduled, CPU-heavy, file-processing, email, webhook, import/export and third-party work out of request handlers.
• Use a bounded configurable worker pool with concurrency greater than one. Select threads, async tasks, processes, or runtime workers according to the language and workload; never create an unbounded thread per request.
• Make queued jobs idempotent, traceable and tenant-aware. Use acknowledgements, bounded exponential-backoff retries with jitter, timeouts, a dead-letter path, cancellation where feasible, and observable queue depth/age/failure metrics.
• Use transactional outbox or equivalent when database state and message publication must succeed together.
• Provision and use a shared cache for rate limits, safe reusable reads, job status or other justified cross-instance state. Every cached value needs an owner, key namespace, tenant boundary, TTL, invalidation rule, stampede protection and sensitive-data decision.
• Use server-side pagination for every unbounded collection. Prefer cursor pagination for changing or high-volume data; allow page/offset pagination for stable administrative datasets where random access is required.
• Apply endpoint-specific rate limits and quotas by IP, identity, tenant and/or operation cost. Return 429, retry guidance and the standard API envelope.
• Emit structured operational logs, metrics and traces with correlation IDs.
• Emit append-oriented audit events for security-relevant actions, including the client IP derived only through a configured trusted-proxy chain.

Read references/concurrency-data.md and references/operations.md.

4. Backend contract

Use one documented response envelope for success and failure. Keep HTTP status semantics authoritative while including status_code for client consistency. Use stable machine-readable error codes and safe, specific messages a user can act on. Never expose stack traces, SQL, secrets, internal hosts or raw exceptions.

Validate at the boundary, authorize every resource/action server-side, use transactions and constraints for invariants, and generate an OpenAPI or equivalent contract from or alongside the implementation. Read references/api-contract.md.

5. Frontend contract

Invoke Impeccable for UI work. Research current layouts appropriate to the specific product and workflow using reputable design-system documentation and real products; record the rationale and sources in DESIGN.md without copying.

• Use shared shells, layouts, navigation, forms, tables, pagination, loading, empty, error and permission states instead of page-specific duplication.
• Use a consistent spacing scale. Default component and table-cell padding to the space-3 token (0.75rem; Tailwind p-3) while adapting compact/touch variants deliberately.
• Avoid generic AI aesthetics, decorative gradients, glass cards, excessive shadows, nested cards and random radii.
• Display backend field errors inline and action/system outcomes through an accessible shared toast system. Preserve the backend request ID for support.
• Implement keyboard behavior, focus management, semantic HTML, contrast, responsive layout and reduced-motion support.

Read references/frontend.md.

6. Completion gate

For every feature or behavior change:

1. Update README.md and affected API, architecture, operations, environment, security and design documentation in the same change.
2. Update .env.example, .env.local, .gitignore, Compose files and the production manifest when the change affects them. Never print secret values.
3. Run unit, integration, contract, E2E, negative/security and relevant load or concurrency tests.
4. Review the complete diff using Superpowers code review and Security Review.
5. Check for leaked tasks, threads, listeners, subscriptions, timers, streams, files, sockets, DB connections, response bodies and unbounded caches/queues.
6. Profile or soak-test long-running paths when memory/resource leakage is plausible; compare resource usage before and after repeated work.
7. Run scripts/validate_project.py --project <root> from this skill.
8. Do not claim production-ready while evidence is missing, checks fail, or residual critical/high risk lacks explicit acceptance.