Why I built Critical Boiler, a stack-aware CLI that generates agent instructions, AI docs, implementation skills, styling foundations, and safer starter files before the real product work begins.
Every new AI-assisted project begins with a strange tax.
Before the agent can build the product, it needs to understand the repository. Which package manager should it use? Where do components live? What commands are real? What does “done” mean here? Is the project using Tailwind or SCSS? Which files may it overwrite? How should it plan multi-step work? Which framework conventions matter?
You can answer those questions in a prompt. The problem is that you pay for that answer again in every new repository—and sometimes again in every new conversation.
That is why I built Critical Boiler, a CLI for generating the predictable project context and starter files that coding agents otherwise spend tokens reconstructing from scratch.
Version 1.0.0 is now available as @twmw/critical-boiler on npm.
Critical Boiler is not another full framework generator. It does not try to replace create-next-app, create-vite, the Astro CLI, Angular CLI, or Flutter tooling. Its job is different: it gives a new or existing repository a deterministic, stack-aware operating layer for humans and coding agents.
The problem is repeated context, not repeated keystrokes
Traditional boilerplates are usually sold as typing shortcuts. They save you from manually creating a config file, a folder tree, or a CSS reset.
That still matters, but AI-assisted development changes the economics.
When a coding agent creates AGENTS.md, an architecture note, command documentation, a definition of done, framework rules, and styling guidance during a conversation, the cost is not just a few minutes. Those files consume context. The agent has to reason about decisions that are mostly predictable, generate the text, inspect the result, and often correct inconsistencies.
Then the same work happens again in the next project.
Critical Boiler moves that work out of the conversation and into a versioned tool. The agent can start with explicit project knowledge already on disk and spend its reasoning budget on the feature that makes the product unique.
Based on the current generated output, one Critical Boiler setup produces roughly 5.5k to 12.4k tokens of reusable instructions and configuration, depending on the chosen stack. Across all 15 supported variants, the tool contains about 143k tokens of repeatable setup material.
Those are estimates, not billing claims. Tokenization varies by model and content. The useful point is the order of magnitude: deterministic setup can be generated once instead of improvised inside an expensive working context.
What Critical Boiler generates
The core output is a small repository contract:
AGENTS.mdwith project-specific instructions for coding agentsai-docs/README.mdas the entry point for AI-facing project contextai-docs/architecture.mdwith stack-aware locations for entrypoints, routes, features, state, data, styles, and testsai-docs/commands.mdwith canonical commands so agents do not guess how to install, run, test, or buildai-docs/definition-of-done.mdwith scope, quality, documentation, verification, and handoff expectations.editorconfig,.gitignore, and.env.example- starter package metadata or a minimal Flutter scaffold
- framework and styling skills selected for the project
The exact file plan changes with the project type and technology choices. A React project receives React and TypeScript guidance. Next.js adds its own rules on top of React. Astro, Angular, Vue, Svelte, Nuxt, Flutter, Tailwind, and SCSS each add focused documentation or configuration where it belongs.
This distinction matters. A generic “frontend best practices” document is rarely specific enough to be useful. React rendering guidance is not Angular architecture guidance. Nuxt performance rules are not Astro island rules. Critical Boiler generates the context that matches the selected stack instead of dropping the same vague README into every repository.
The guided setup is deliberately simple
Install the package globally with pnpm:
pnpm add -g @twmw/critical-boilerThen move into a project and run:
critical-boilerDuring local development, the same experience starts with node ./src/cli.js.
The guided flow asks for a target folder, project type, technology, styling approach, and whether Beads task planning should be included. Single-choice questions use keyboard selectors: arrow keys move and Enter confirms.
The three project families are intentionally constrained:
- web application: React, Angular, Vue, or Svelte
- static website: Astro, Next.js, or Nuxt
- mobile application: Flutter
TypeScript is included automatically for web applications and static websites. Mobile projects skip the web-specific questions and generate a minimal runnable Flutter foundation instead of pretending that a Dart project needs package.json.
The constraints are a feature. A setup tool should make supported paths obvious, not present an infinite combination matrix it cannot maintain confidently.
Preview before writing
Any tool that writes a dozen files into a repository should make its plan inspectable.
Critical Boiler supports --dry-run, so you can see the exact file operations without changing the target:
critical-boiler --dry-run --project-type webApplication --tech react,tailwind --no-beads
In this React and Tailwind example, the plan contains 12 files: the root agent contract, four AI docs, editor and environment defaults, Vite and CSS setup, plus TypeScript, React, and Tailwind implementation skills.
Existing files are skipped by default. --force is available when replacement is intentional. Beads-managed sections are handled differently: marked guidance and missing package entries are merged additively so existing instructions, dependencies, and scripts remain authoritative.
That behavior is important for existing repositories. “Scaffold” must not mean “erase the project’s current decisions.”
Exact dependency versions instead of model guesses
One of the more practical design decisions happens when Critical Boiler generates package.json.
The CLI does not ask a model which package versions sound current. It queries the npm registry with:
npm view <package-name> versions --jsonIt then selects the latest stable published version and writes the exact version into dependencies or devDependencies.
This removes a subtle source of failure from AI-generated starters. Models can remember an old version, invent a plausible version, or use latest and make the result non-reproducible. Package versions are structured external state, so a deterministic registry lookup is the correct tool.
The generated dependency set also understands the stack. React includes React, React DOM, Vite, and the React Vite plugin. Tailwind selects the appropriate Vite or PostCSS integration. SCSS adds Sass. Web stacks receive TypeScript without requiring the user to remember it as an extra technology flag.
Critical Boiler creates a useful seed, but it stays honest about the boundary. It does not invent framework entrypoints that should come from the real framework scaffold. Angular src/main.ts, Next.js app/, Astro pages, and Nuxt application files remain the framework’s responsibility. Flutter is the deliberate exception because the mobile path generates a small runnable application.
Agent skills should be project-specific
Coding-agent instructions tend to fail in two opposite ways.
They are either too thin—“use best practices”—or so large and generic that the agent cannot tell which rules matter for the current change.
Critical Boiler generates focused skill documents based on the selected stack. Examples include:
- React performance, accessibility, data fetching, and render behavior
- Next.js Server Component, client-boundary, and composition guidance
- Angular strict TypeScript, RxJS, templates, services, and state patterns
- Vue component naming, props, emits, computed state, and communication rules
- Svelte runes, derived state, effects, snippets, and modern API guidance
- Nuxt links, rendering, lazy hydration, data fetching, and performance patterns
- Astro imports, components, islands, slots, and image guidance
- Flutter architecture, responsive layout, routing, networking, serialization, localization, and tests
- TypeScript domain types, runtime validation, generics, error handling, and migration rules
- Tailwind or SCSS implementation guidance matching the chosen styling system
These files are not a replacement for repository inspection. They are a baseline that makes the repository easier to inspect correctly.
An agent still needs to read the code, follow existing patterns, and verify its work. But it starts with fewer unknowns and less incentive to fill gaps with assumptions.
Styling foundations without pretending utilities are design
When SCSS is selected, Critical Boiler can generate a deliberately small styling foundation:
src/styles/reset.scss
src/styles/tokens.scss
src/styles/utilities.scss
src/styles/index.scssThe utility layer is limited to layout concerns such as display, alignment, spacing, sizing, stacks, clusters, sections, and containers. Branding, colors, typography, shadows, borders, and component visuals stay in semantic component classes.
That boundary reflects how I prefer to build interfaces. A starter should remove repetitive setup without flattening every design into utility soup.
Tailwind projects take a different path. They receive the integration file appropriate to the framework, a CSS entrypoint, a Tailwind implementation skill, and prompt guidance for refactors. The tool adapts to the selected architecture instead of forcing SCSS conventions into a Tailwind codebase or vice versa.
Beads planning is part of the repository layer
Multi-step agent work needs more than a checklist hidden in chat history. Critical Boiler can include Beads task planning by default, with an opt-out through --no-beads.
The generated integration includes a project-local planning skill, lifecycle documentation, setup and Markdown-import scripts, and package commands for setup, priming, ready work, and status. The intent is to make the dependency graph—not a stale prose plan—the source of truth for agent execution.
This is also why the integration is additive. Existing AGENTS.md content is preserved. Existing package scripts win on name collisions. The generated setup is idempotent, and large Markdown backlogs can be previewed before they are applied.
Critical Boiler does not install dependencies or initialize the Beads database behind your back. It writes the contract and the setup path; the developer remains in control of the side effects.
Reusable prompts without copying prompt files everywhere
Project instructions belong in the repository. Reusable prompt templates do not always need to.
Critical Boiler packages a prompt kit inside the CLI:
critical-boiler prompt --list
critical-boiler prompt feature-implementation
critical-boiler prompt frontend-component
critical-boiler prompt code-reviewThe current kit includes project kickoff, feature implementation, bug investigation, frontend component, Tailwind refactor, SCSS refactor, code review, and test creation flows.
The CLI asks for the template variables, renders the final prompt, prints it, and copies it to the clipboard. Framework-aware prompts can point the agent to the relevant skill already generated in the repository.
This keeps repeated working prompts available without filling every project with eight more template files.
How this fits with my other developer tools
Critical Boiler sits at the beginning of an AI-assisted development loop.
Critical Templates encodes repeatable file shapes inside an established repository. It helps humans and agents generate components, routes, services, or documents according to project-owned conventions.
Critical Gate sits near the end of the loop. It checks whether an AI-generated diff stayed inside the task and repository contract.
Critical Boiler prepares the repository itself:
Critical Boiler -> establish project context and starter rules
Critical Templates -> generate repeated artifacts from project conventions
Critical Gate -> inspect whether the final diff respects the contractThe common idea is that better models are only part of better AI development. Repositories also need deterministic interfaces. The environment should explain what belongs, provide tools for repeated operations, and verify the result.
Start with a dry run
Critical Boiler 1.0.0 requires Node.js 20 or newer and is published under the MIT license.
Install it:
pnpm add -g @twmw/critical-boilerPreview a setup:
critical-boiler --dry-run --tech react,tailwindOr launch the guided flow:
critical-boilerYou can find the package, complete option reference, supported technologies, generated-file catalog, prompt kit, and setup documentation on npm:
The goal is not to automate the interesting decisions. It is to stop paying models to remake the boring ones.
Give the agent a repository that already knows how it wants to be built. Then spend the context on the product.