Golden paths

Golden paths are optional, maintained playbooks for common changes. They provide a tested route for builders and agents that want one, but they are not required file-by-file procedures. A different implementation approach is valid when it preserves the repository's architecture and security invariants and passes outcome-level verification.

AGENTS.md, executed code, migrations, configuration, and tests remain authoritative. A golden path supplements those sources; it does not override them or make a particular skill, MCP client, or coding agent mandatory.

Foundation runbooks

• Add a domain end to end
• Add a database migration
• Add an environment variable
• Diagnose or recover a failed migration
• Add a billing-gated feature
• Add a billing plan
• Diagnose a failed billing webhook
• Deploy a fresh application
• Add an authenticated route
• Add a transactional email
• Add an upload type
• Customize branding and design tokens
• Remove an optional subsystem
• Decide a background-work request

Each runbook defines when it is useful, the files and boundaries commonly involved, a recommended procedure, verification, security constraints, failure modes, rollback or diagnosis, acceptance criteria, and unsafe actions. A structural test in packages/create-app/src/golden-paths.test.ts prevents those sections from silently disappearing from buyer output.

Completion rule

A runbook is not verified because its Markdown exists. Rehearse it from a clean generated buyer application, record every incorrect assumption or intervention, and fix the architecture, instructions, or verification harness that caused the failure. A product change is accepted because its behavior and required checks pass, not because the author followed a runbook.