Infrastructure questions belong before the first line of code

Most project scaffolds ask what framework you want and then start generating files. That is a useful beginning, but it is not enough to describe a project that will run anywhere real.

The important questions are usually about the things around the application: where it will run, which database it uses, how it sends email, what handles scheduled work, and which services need special configuration. I have started putting those questions before scaffolding in the project-boilerplate update, because infrastructure decisions become much harder to document after the project has already been created around incomplete assumptions.

A framework is not a project shape

A framework tells you how to start writing application code. It does not tell you what the application needs in production.

Two Next.js projects can share the same framework and have completely different operational shapes. One can be a static site deployed to Cloudflare Pages. Another might use OpenNext, a managed Postgres database, Better Auth, an email provider, scheduled jobs, and a migration process. The first needs a build and a deploy configuration. The second needs a collection of decisions that affect authentication, database access, runtime bindings, and recovery procedures.

If a template treats both projects as the same kind of application, it will generate a plausible directory structure while leaving the important parts implicit. That is how a project can look well organised and still be difficult to operate.

This is why I am less interested in a scaffold that produces the most files. I want one that asks enough questions to avoid making the wrong project shape look like a default.

The question comes before generation

The project-boilerplate skill now has an infrastructure pre-flight. It asks which categories a project actually uses before it generates the documentation and supporting templates. The list covers things such as hosting, databases, authentication, payments, email, queues, cron, storage, observability, feature flags, secrets, and AI services.

The point is not to force every project to adopt every service. The skill lets the person creating the project say that a category is not relevant. That decision is useful too. A generated project can record that queues or browser rendering were considered and skipped, instead of leaving the next engineer to guess whether the omission was deliberate.

This is a small change to the order of operations, but order matters. Once a generic project has been generated, people tend to accept its structure as a fact. They fill in the obvious pages and move on. Asking about infrastructure first makes the template respond to the project instead of making the project conform to the template.

Documentation should follow declared reality

The update generates one integration page for each active provider and adds stack integrations to the generated AGENTS.md. It also records gotchas when the pre-flight questions uncover a platform-specific constraint.

That gives project documentation two useful qualities. It tells you what the project uses, and it explains the parts that are easy to get wrong. A generic architecture document can describe the system, but it cannot know that a particular database has separate pooled and direct connection requirements. A tech-stack document can record that a service exists, but it will not automatically explain the deployment trap attached to it.

The template can create the place for that information. The person running it still has to provide the project-specific answer. That is a better division of responsibility than asking a template to invent an architecture from a framework name.

The useful detail is usually a gotcha

The best examples in this work came from production problems and awkward integrations that had already been documented elsewhere. They were not abstract infrastructure categories. They were details that only become visible when a real system meets a real platform.

For example, a Neon-backed application may need one database URL for the Worker at runtime and another direct endpoint during the build for schema operations. An OpenNext deployment on Cloudflare can appear to run scheduled work while silently dropping every tick if the worker re-exports fetch but not scheduled. Authentication can depend on reading both the ordinary and __Secure- cookie names. A custom migration runner may need a deliberate drift-recovery path when the live database was created through a different tool.

The same pattern appears outside hosting and databases. Better Auth plugin endpoints may not appear on the typed auth.api.* surface. An email service may need a null implementation when its binding or sender configuration is absent. These are exactly the details that disappear from a generic scaffold because they are not properties of the framework. They are properties of the chosen infrastructure.

I do not want a template to pretend it knows every gotcha in advance. I do want it to ask where those gotchas belong, capture the answer, and make the result visible to the next person working in the repository.

A project template should expose its assumptions

This changes what I think a useful project template is for. It is not just a fast way to create folders. It is a way to make early assumptions visible while they are still cheap to challenge.

That also explains why the update adds validation for integration coverage, synchronisation between integration pages and the stack table, and documentation for hosting bindings. The checks are not there to make the generated output look complete. They catch the more important failure where the project declares a service but its documentation never explains how the code connects to it.

There is a limit, of course. Asking infrastructure questions does not make the answers correct. It cannot replace design work, deployment testing, or an engineer who understands the platform. It does make omissions easier to spot. That is a good trade for a project-starting tool.

I would rather spend a few minutes deciding whether a project has queues, scheduled work, or a separate migration path than spend an afternoon discovering that the generated documentation assumed none of them existed. The first line of code is not the real beginning of a project. The real beginning is deciding what has to keep that code running.