bootstrapping-code

Bootstrapping Code

Required inputs

Require the successful output from preparing-repositories before taking action:

LOCAL_REPOSITORY_PATH: <absolute path>
REPOSITORY_STATUS: existing-local | cloned | created-and-cloned

If those values are missing, stop before bootstrapping and prepare the repository first. Do not choose a fallback directory yourself.

Use the returned LOCAL_REPOSITORY_PATH as the working directory.

Hard rules

• Use pnpm for package initialization, package version checks, and package installation.
• Do not trust remembered package versions. Check latest versions with pnpm view <package> version before installing, then install with @latest.
• Load react-router-patterns before adding or changing React Router code. Any generated React Router code must follow those patterns.
• Stop before bootstrapping if preparing-repositories has not completed successfully.
• Stop before bootstrapping if the repository or local destination was missing from the user's request and preparing-repositories has not resolved it.
• Stop before bootstrapping if LOCAL_REPOSITORY_PATH already contains files other than repository metadata.
• After bootstrap starts, treat files created by the bootstrap as project source and reuse or update them in later steps.
• Never delete or overwrite user files to force a bootstrap.
• Never create a local-only Product Builder app in work/, ./work, a temporary directory, the current workspace, or any agent-chosen folder.
• Keep Cloudflare spelled correctly in generated files, package names, and user-facing output.

Gotchas

• pnpm wrangler types must be re-run after any change to wrangler.jsonc bindings. Skipping this causes TypeScript errors in workers/app.ts because the generated Env interface is stale.
• shadcn/ui init modifies tailwind.config.ts and app/styles/globals.css. If these files were already customized, the init may overwrite changes. Check the diff after running it.
• React Router in framework mode requires app/root.tsx to export a default component and a Layout. Missing either causes a blank page with no error in the browser console.
• Vite config must use cloudflareDevProxy() before reactRouter() in the plugins array. Wrong order causes the dev server to serve raw source instead of compiled output.

Workflow

1. Confirm preparing-repositories returned LOCAL_REPOSITORY_PATH and REPOSITORY_STATUS.
2. If LOCAL_REPOSITORY_PATH and REPOSITORY_STATUS are missing, stop before bootstrapping and prepare the repository first.
3. Validate LOCAL_REPOSITORY_PATH exists, is a git repository, and contains no pre-existing files other than repository metadata.
4. Initialize pnpm and base files using 01-initialize-pnpm-and-base-files.md.
5. Add TypeScript using 02-typescript.md.
6. Add Vite, linting, and formatting using 03-vite-linting-formatting.md.
7. Add Cloudflare using 04-cloudflare.md.
8. Load react-router-patterns, then add the React Router page using 05-react-router-page.md.
9. Add Tailwind and shadcn/ui using 06-tailwind-and-shadcn-ui.md.
10. Run final verification using 07-final-verification.md.
11. Create initial project documentation in docs/:
    • Create docs/architecture.md using the template in architecture-template.md. Fill in the Overview with the product description. The Stack section should list only the base stack: Cloudflare Workers, TypeScript; React Router v7 (framework mode, SSR); Tailwind CSS, shadcn/ui. The Structure section should reflect the bootstrapped directory layout. Add a single convention link for Routes: **[Routes](conventions/routes.md)** — loader/action structure, protected routes, navigation.
    • Create docs/conventions/routes.md using the template in convention-template.md. Seed it with key React Router patterns: route filenames describe role not URL syntax; use middleware only for cross-cutting request work; keep mutations in actions; ownership checks in the route/action that owns the resource param.
12. Update the project README.md with a very basic overview of the bootstrapped application, including the stack, local development command, verification commands, and Cloudflare deployment target.
13. Update the project AGENTS.md with basic agent instructions and the bootstrapped project structure. Include:
    • Repository purpose, common commands, and where the main application, routes, UI components, Cloudflare worker, and configuration files live.
    • A Project Documentation section that directs agents to read docs/architecture.md first for project context, then follow links to conventions and data model for detail. List the docs structure:
      • docs/architecture.md — stack, structure, conventions index, and implementation log.
      • docs/conventions/ — project-specific patterns and anti-patterns.
      • docs/features/ — feature specs (added during planning).
    • React Router guidance: route filenames describe role, not URL syntax; use middleware only for cross-cutting request work such as auth, logging, shared context, and headers; keep mutations in actions and ownership checks in the route/action that owns the resource param.
14. Commit the generated and updated files in the repository using the repository's Conventional Commits format.
15. Summarize what was created, include the commit hash, and list any command that failed.

Stop message

When stopping because repository preparation has not provided the required inputs, say this directly:

I need a prepared GitHub repository and explicit local destination before I can bootstrap the Product Builder project.

When stopping because the local repository has pre-existing files, say this directly:

The local repository <path> has pre-existing files, so I stopped before bootstrapping. Remove the existing files or provide a new empty repository.

Include the files found when available.

Validation checklist

• preparing-repositories completed successfully.
• LOCAL_REPOSITORY_PATH and REPOSITORY_STATUS are available.
• Local repository has no pre-existing files beyond repository metadata.
• pnpm view was used for latest package checks.
• react-router-patterns was loaded before React Router code was generated, and the generated code follows those patterns.
• Cloudflare types are generated with wrangler types.
• pnpm format, pnpm typecheck, pnpm lint, and pnpm build pass after fixing generated-file issues.
• Final file structure and git status --short were reviewed.
• docs/architecture.md was created with the base stack, bootstrapped structure, and a Routes convention link.
• docs/conventions/routes.md was created with seed React Router patterns.
• README.md gives a very basic overview of the bootstrapped app, commands, and Cloudflare target.
• AGENTS.md includes basic agent instructions, the bootstrapped project structure, a Project Documentation section referencing docs/, and React Router guidance.
• Generated and updated files were committed with a Conventional Commit message.