Introducing webapp-blueprint

webapp-blueprint is a project template that brings application scaffolding, development tooling, design principles, quality checks, and instructions for coding agents into one repository.

It is not a boilerplate that picks a finished stack for every project. It starts by clarifying what will be built, resolves the remaining technical choices, and then enforces the selected conventions mechanically.

What is included

The monorepo contains a React frontend, an API, BDD-style end-to-end tests, and a Terraform foundation. Its tooling includes pnpm workspaces, Turborepo, mise, Vitest, Playwright, oxlint, and oxfmt.

Checks cover dependency direction, feature boundaries, pinned versions, plaintext secrets, and GitHub Actions syntax. Local development and CI share mise run check as their entry point.

On a clean clone, install dependencies before running the checks.

mise install
mise run install
mise run check

The frontend and API also include a small vertical slice. It ensures architecture rules and tests exercise real code instead of passing over an empty repository.

Bootstrapping a clone

The first step is to ask a coding agent:

Initialize this project with the bootstrap-template skill.

bootstrap-template turns the product idea into a project brief, researches primary sources, and asks the unresolved technical questions in dependency order. Only after those answers are complete does it materialize the selected stack.

The contract layer illustrates this choice. It starts empty, with recipes for protobuf and ConnectRPC or TypeSpec-generated OpenAPI, but neither option is selected by default. Generated-contract drift checks become active after bootstrap selects and connects a generation path.

After bootstrap, the README points to a project-specific setup-project skill for new checkouts and worktrees.

Documentation with different lifetimes

The repository separates durable principles, replaceable recipes, and executable configuration.

Location	Purpose
docs/principles/	Tool-independent requirements
docs/recipes/	Current ways to satisfy those requirements
Root configuration and scripts	Checks and processes that actually run

For example, the principle says that the repository stores secret references rather than values. The current recipe uses 1Password CLI and keeps only op:// references in .env.example.

Documentation is searchable with mise run docs:dev, and the bundled docs MCP lets coding agents search the same decisions.

Agent tooling and Ramune

The repository includes skills for ADRs, documentation maintenance, commits, and pull requests. Claude and Codex review workflows are bundled but remain disabled until bootstrap selects a provider.

tools/ramune/ contains a task-graph runtime for coordinating multiple coding agents. It is introduced in a separate post.

When it fits

webapp-blueprint fits projects that want to keep early technical decisions and ongoing quality checks in the same repository.

It is probably too heavy for a demo meant to last only a few hours. The design favors keeping conventions and implementation aligned over minimizing the initial file count.

The public repository is github.com/NiraiHayakawa/webapp-blueprint.