feat(project-boilerplate): add infra-coverage quiz, integrations template, design/incident/research pages

[paulund]

Summary

Quizzes a 21-category infrastructure pick-list during pre-flight and generates one docs/architecture/integrations/<provider>.md per active service. Adds gated-infra branch (Step 3a) so users opt in per-category, plus dedicated templates for email, queues, cron, style-guide, incident postmortems, feature flags, and "we tried X" research notes.

## Stack integrations and ## Gotchas sections added to AGENTS.md regen step. Validation gains three new checks: integration coverage, stack integrations sync, binding documentation.

Patterns captured from real projects

These were documented in socialqueue and bullion-api but had no quiz surface in the skill:

• Build-vs-runtime env var split — Neon DATABASE_URL (Worker secret, pooled) vs DATABASE_URL_DIRECT (build only, direct endpoint for DDL).
• OpenNext + Cloudflare cron-handler patch — the silent-drop-every-tick bug when worker.ts re-exports fetch but not scheduled.
• __Secure- cookie name — middleware must read both idp.session_token (HTTP) and __Secure-idp.session_token (HTTPS).
• Custom migration runner + --mark-applied drift recovery for live DBs that were created via drizzle-kit push.
• IdP endpoint surface — Better Auth plugin endpoints not on the typed auth.api.*; CLI/CORS quirks.
• Service-interface + Null fallback — Null impl used in production when binding / env var isn't configured (e.g. email when sender domain isn't wired).

Diff

• skills/project-boilerplate/SKILL.md — 175 → 214 lines (+39, well under 300 budget). Added Pre-flight step 5/6, quiz-loop Step 3a, AGENTS.md ## Stack integrations / ## Gotchas, three new validation checks, Skipped infra reporting.
• skills/project-boilerplate/references/page-templates.md — 1246 → 2241 lines (loaded on demand). Added 21-category pick-list, universal integrations/<provider>.md template, email.md, queues.md, style-guide.md, incident-YYYY-MM-DD-<slug>.md, feature-flags.md, research/<topic>.md, competitors.md. Extended overview.md Stack table to enumerate all 21 categories; extended auth.md, data-model.md, deploy/<platform>.md, env-vars.md, cron-jobs.md, observability.md, testing/strategy.md, mocking-services.md with infra-aware quiz questions and slots.

Verification

• bin/sync --dry-run clean; project-boilerplate still distributed to bullion-api, socialqueue, paulund, monlife.
• Code fences balanced (43 paired).
• wc -l: SKILL.md 214 / page-templates.md 2241.
• git status after commit: only the two intended files changed.

Test plan

• Run the skill against a greenfield repo (pnpm init, Next.js) — confirm Skipped infra list is rendered.
• Run against a repo with wrangler.toml + Stripe + Resend bindings — confirm three integrations/*.md pages are scaffolded with the universal template, plus email.md.
• Run against a repo with [[send_email]] and [[queues.producers]] bindings — confirm wiring section of each integration page carries the verbatim binding snippet.
• Confirm AGENTS.md ## Stack integrations table is generated from on-disk integration files and ## Gotchas is omitted when the per-platform Gotcha quiz is empty.

[paulund]

Automated review

Findings

• [medium | skills/project-boilerplate/references/page-templates.md:1696 | template email.md See-also → render in downstream email.md → broken relative path ../integrations/<provider>.md resolves to docs/integrations/<provider>.md which does not exist] — fixed in commit a8b243b
• [medium | skills/project-boilerplate/SKILL.md:140 | validation step 7 referenced docs/architecture/integrations/README.md "no doc needed" carve-out, but no template for that file exists in references/ → agent had no guidance on how to write the carve-out, every scaffolded project would fail step 7] — fixed in commit a8b243b
• [medium | skills/project-boilerplate/SKILL.md:142 | validation step 9 only checked wrangler.toml/wrangler.jsonc, but pre-flight (SKILL.md:34) detects across Vercel/Fly/Railway/docker-compose too → Vercel-hosted projects pass step 9 with undocumented bindings] — fixed in commit a8b243b
• [medium | skills/project-boilerplate/SKILL.md:74 | Step 3a referenced only neither state; declared-but-no-doc (binding present, no doc) had no rule — agent had to infer whether to re-ask the user] — fixed in commit a8b243b
• [low | skills/project-boilerplate/SKILL.md:78 | "continue to Step 3" anchor referenced a step textually before Step 3a — agent following the doc literally could re-run Step 3 instead of running a new quiz instance] — fixed in commit a8b243b
• [low | skills/project-boilerplate/SKILL.md:72 | misnumbered step ("Step 3a" between 3 and 4) breaks numeric sequence; Step 3a is a one-shot pre-quiz, not a per-page step] — fixed in commit a8b243b
• [low | skills/project-boilerplate/SKILL.md:34 + references/page-templates.md:778 | cron provider picked in Step 4 generates cron-jobs.md only — no per-provider integrations/<cron-provider>.md was generated; rule didn't say so, leaving the agent to wonder whether one was missing] — fixed in commit a8b243b
• [low | skills/project-boilerplate/references/page-templates.md:746 | typo "DRizzle" in observability.md metrics template bullet] — fixed in commit a8b243b
• [low | skills/project-boilerplate/references/page-templates.md:499 | broken sentence in deploy.md quiz: "What breaks if the patch is removed (be specific? Example types:" — question mark mid-parenthetical] — fixed in commit a8b243b
• [low | skills/project-boilerplate/references/page-templates.md:733 | unclosed <accountId> placeholder in observability.md logs template — partial HTML tag rendering] — fixed in commit a8b243b
• [low | skills/project-boilerplate/references/page-templates.md:254 | TODO marker <!-- TODO: not yet adopted --> inconsistent with the canonical <!-- TODO: fill --> used elsewhere] — fixed in commit a8b243b

Acceptance criteria coverage

Omitted — no linked issues on this PR.

Security

• [low | skills/project-boilerplate/SKILL.md:202 | gating-question paths (<slug>, <topic>, <title>) are free-text user answers substituted into file paths with no sanitization rule → defense-in-depth gap; in practice the LLM refuses path traversal and the agent has no execution sink downstream (writes only to docs/, no git add/commit)] — fixed in commit a8b243b
• (No other security-relevant changes. No command injection, no secret sinks — all secret references in templates are placeholders or RFC 2606 reserved domains. The agent is deliberately write-only and never runs shell.)

Risk

low — pure additive doc change to a skill file; no production module touched, no schema/authz/env/signature invariants affected, fully reversible by reverting one commit.