Production grade scaffold

Production-Grade Application Scaffold

Six layers by default - Presentation -> API -> Domain Logic -> Data Access -> Database -> Infrastructure, dependencies pointing inward only - bent per archetype (see step 1).

Read only what steps 1-3 point to. Never open all of references/ or templates/ up front - each file below is self-contained and loaded on demand, not as background reading.

0. Claim your scope before you write

Assume you are not the only agent scaffolding this repo. Scaffolding is write-heavy against fixed, predictable paths, and every collision here is silent - last writer wins, nothing errors, and the loss shows up later as a missing migration or a dependency that vanished.

State the paths you own before step 1 ("I own src/api/ and src/database/migrations/"), then:

• One root manifest, one owner. package.json, pyproject.toml, Cargo.toml, go.mod are single shared files. If you did not create it, do not read-modify-write it - append your dependencies through the package manager's own command (npm pkg set, cargo add, uv add), which is a single atomic operation, or hand the change to whoever owns the file.
• Migrations get timestamps, never sequential integers. 0003_add_orders.sql is a shared counter with no lock around it: two agents both pick 0003 and one silently disappears. 20260726T141233Z_add_orders.sql cannot collide. This applies to src/database/migrations/, app/database/migrations/, and migrations/ in the templates.
• Create, don't clobber. New files go through an exclusive-create (O_EXCL / wx / create_new). A failure there means someone got there first - read what they wrote and adapt, do not overwrite. Only touch an existing file if you own it.
• Per-agent paths for scratch and logs. No shared temp file, no single shared scratch dir.
• Shared SQLite gets busy_timeout. If anything you scaffold keeps state in one .db file reached by several processes, set busy_timeout (measured: recovers 100% of writes that would otherwise be lost; WAL alone recovers about 10%) and use single-statement upserts rather than SELECT-then-write.

If the scope you need is already claimed, say so and stop rather than writing anyway.

1. Detect archetype (read the matching section of references/architecture-archetypes.md only)

First match wins, top to bottom. Several signals co-occur in real repos; the order below is the tiebreak, not a suggestion.

#	Signal in repo	Archetype	Template
1	wrangler.toml and next.config.*/nuxt.config.*	SSR framework deployed to Cloudflare (OpenNext)	templates/nextjs-fullstack/ for app structure, templates/cloudflare-workers/ for deploy config only
2	next.config.*, nuxt.config.*, svelte.config.* without a static-export setting (output: 'export', nitro.preset: 'static', adapter-static)	Full-stack SSR framework	templates/nextjs-fullstack/
3	the same configs with static export configured	Plain website	templates/static-site/
4	wrangler.toml alone	Cloudflare Workers (edge)	templates/cloudflare-workers/
5	serverless.yml, template.yaml, host.json	Serverless API	templates/serverless-api/
6	Raw sockets/custom protocol, no HTTP framework	Networking/systems service	templates/networking-service/
7	A build that emits only static assets, no server entry point	Plain website	templates/static-site/
8	None of the above / persistent server + DB	Layered web app (default)	stack table below
9	Nothing exists yet	-	ask the user

Rows 2/3 and 7 turn on a file-visible condition, not a judgement call: open the framework config and look for the static-export setting before choosing.

2. Detect stack (layered web app only - other archetypes are language-fixed above)

package.json -> templates/nodejs-typescript/ - pyproject.toml/requirements.txt -> templates/python-fastapi/ - Cargo.toml -> templates/rust-axum/ - anything else -> templates/generic-layered/ (hand-adapt; boundaries matter more than folder names).

3. Detect cloud target, if any (read only the matching subsection of references/cloud-providers.md)

.aws/, SAM/CDK files -> AWS - *.bicep, azure-pipelines.yml -> Azure - wrangler.toml -> Cloudflare (already implies the archetype in step 1) - none -> self-hosted/no specific provider, skip this file.

4. Apply checklists - read only the ones relevant to what you're building/auditing

references/security.md - references/auth.md (skip for static-site) - references/database.md (skip for static-site; cloudflare-workers uses the D1 notes in cloud-providers.md instead) - references/api-layer.md (skip for static-site, networking-service) - references/domain-structure.md - references/infrastructure-delivery.md. Each ends in a "minimum bar" checklist - treat an empty-but-organized repo as incomplete until that bar is met.

The templates are built to pass these bars as shipped (real dependency and secret scanning, a signed tag-gated release with SBOM and SLSA provenance, hardened compose files). If you change a template's CI, do not weaken it into a placeholder that exits 0 - a green pipeline that tests nothing is worse than a red one.

4a. UI / Presentation layer - only when you are creating or changing components

Fires only if the archetype renders UI (layered web app, SSR nextjs-fullstack, static-site) and this task actually creates or changes Presentation-layer components. Auditing an existing UI, or scaffolding any non-Presentation layer, skips this step entirely - it is the single most expensive branch in this skill and it is off by default.

When it does fire: read references/ui-components.md (2 KB) first. Invoke the ui-standout skill only at the point of picking concrete components - it is a whole separate skill load, so do not pull it in to answer a structural question. Its 46-rule taste gate is part of the Presentation minimum bar: a UI that trips the slop detector is not production-grade.

SKIP entirely for serverless-api and networking-service (no Presentation layer). If charts or dashboards are in scope and a dataviz skill is available in this environment, defer to it; dataviz ships as a platform skill rather than a sibling here, so treat its absence as normal and fall back to ui-components.md.

Harness / init-harness integration. When init-harness runs its section 0.5 context-bootstrap on a greenfield UI app, it hands off to this scaffold to lay the app skeleton first, then wraps the control plane around it. The harness "Production-grade bar" MCQ (Solid small tool / Multi-user product / High-scale) selects which of these checklists apply and how strict the bars are - and, for UI archetypes, whether the ui-standout taste gate is advisory or enforced. Ownership stays clean: this scaffold writes src//CI/templates; init-harness owns .claude//harness//hooks.

5. Re-classify on change, don't patch

Archetype/stack/cloud change (e.g. Next.js -> Rust, monolith -> serverless) -> redo steps 1-3 for the new shape; don't carry old assumptions (connection pools, Dockerfiles, OAuth2 bearer tokens) into an archetype where they don't apply - architecture-archetypes.md and cloud-providers.md both flag where this bites.

Files in this skill

references/ (9): architecture-archetypes.md, cloud-providers.md, security.md, auth.md, database.md, api-layer.md, domain-structure.md, infrastructure-delivery.md, ui-components.md.

templates/ (9): nodejs-typescript, python-fastapi, rust-axum, generic-layered (layered web app) - nextjs-fullstack (SSR) - serverless-api (AWS/Azure serverless) - cloudflare-workers (edge) - static-site (no backend) - networking-service (protocol/systems).

Template READMEs cite reference files as skill:production-grade-scaffold/references/foo.md. That is a citation into this installed skill, not a path in the generated repo - the references do not travel with a copied template, and a plain relative path there would dangle by construction.

Interop

<!-- interop-contract: v1 -->

Edition: CLI (Claude Code). Precedence:

• Yields to init-harness on the control plane and parallel-agent writes (under a harness its terminal domains + worktrees supersede section 0's contract, which applies only with no harness).
• Yields to ui-standout on Presentation-layer component choice (gate + justification live there and are not restated here).
• Wins over init-harness on application structure (which layers and files exist).
• Wins over ponytail on structure (PGS picks the layers, ponytail the code inside them).
• Wins over ui-standout on layer structure and minimum bars (which layers exist, and the Presentation minimum bar).
• Disjoint from agent-reach, graphify, install-skill, playwright-tester, scrapling, skill-creator, token-efficiency.
• External, conditional: dataviz - platform skill outside this tree, owns chart internals. If present defer; if absent fall back to references/ui-components.md. Never a hard dependency. Owns: src/ (six layers), .github/workflows/, dependabot.yml, Dockerfile, docker-compose.yml, infra/, root manifests, migrations. Never writes: .claude/, harness/, .agents/, hooks (init-harness) * tests/, playwright.config.ts, .tests/** (playwright-tester) * components.json or a lockfile from >1 agent (ui-standout) Matchers claimed: none (no hooks). File triggers only: next.config.*, nuxt.config.*, svelte.config.*, wrangler.toml, serverless.yml, template.yaml, host.json, package.json, pyproject.toml, requirements.txt, Cargo.toml, .aws/, *.bicep, azure-pipelines.yml. Model policy: roles, not versions (session/thinker/workhorse/utility); zero IDs pinned. Shared-resource protocol: root manifests - creator owns; never read-modify-write one you did not create. Migrations - timestamped, never sequential. Under a harness init-harness's domains supersede.

Matrix and rulings: ../INTEROP.md.