angel1-mvp-toolkit

Why I built it

Every engagement starts the same way. New repository, Next.js 16 with App Router, TypeScript strict, Tailwind 4, Supabase or NextAuth depending on the auth model, Anthropic or OpenAI SDK depending on the model choice, Vitest and Playwright preconfigured because tests are not optional, a CLAUDE.md at the root because I work with Claude Code daily and that file is the difference between Claude understanding the project and Claude guessing.

The first three or four engagements, I copied the previous project. The fifth, I realized I was copying my own bugs forward. The sixth, I extracted the scaffolding into a CLI. That's angel1-mvp-toolkit.

It's published on npm at @massiangelone/angel1-mvp-toolkit, currently v1.0.0. One command:

npx @massiangelone/angel1-mvp-toolkit init my-app

Ninety seconds later you have a working repository with the stack chosen, dependencies installed, environment files stubbed, git initialized, and a first commit ready.

What it does

The CLI is one command, init <project-name>, with an optional --yes flag for non-interactive runs. The interactive path asks five questions:

• AI provider (Anthropic, OpenAI, both)
• Auth (Supabase Auth, NextAuth, none)
• Payments (Stripe, none)
• Email (Resend, none)
• RAG (pgvector + retrieval scaffold, none)

Each answer toggles which dependencies get installed and which template files get included. The template lives at packages/templates/base — roughly thirty-three files of Next.js 16 App Router boilerplate that has earned its place by surviving real projects. Conditional dependency injection happens in init.ts based on the answer set.

How it's structured

It's a pnpm monorepo with two packages:

• packages/cli — the interactive scaffolder. Reads the user's answers, copies and templates the base, modifies package.json with the right deps, runs pnpm install, initializes git, makes the first commit. Roughly a hundred and seventy lines of TypeScript that does one thing and doesn't try to grow into a framework.
• packages/templates/base — the actual project template. The thirty-three files that get copied. This is where the engineering opinions live: how the database client is structured, how the API routes are organized, how environment variables are validated at boot, what CLAUDE.md says.

The CLI is small on purpose. The interesting part of a scaffolder is never the scaffolder itself — it's the template, because that's what determines whether the projects you build on top of it succeed or rot.

What's actually opinionated about the template

A few decisions that aren't obvious until you've built ten of these:

Environment validation at boot, not at first use. The template includes a Zod schema for process.env that runs at startup. Misconfigured deployments fail at deploy time, not three hours later when a user hits the auth endpoint.

A project-specific CLAUDE.md ships by default. The template includes a CLAUDE.md at the root that describes the file structure, conventions, and the kinds of questions an AI coding assistant should ask before changing things. It's primarily tuned for Claude Code — the tool I run on every engagement — but the same file works as a baseline for Cursor, Aider, or any AI assistant that reads project context files. If you scaffold an OpenAI-only project, the file is still useful; rename or delete if it doesn't fit your workflow.

Tests are scaffolded, not promised. Vitest config, Playwright config, and example tests in both — committed to the first commit. Empty test directories age into "we'll add tests later." Tests with one example aging into ten.

No state management library by default. React state and URL state get you further than people expect. If you need Zustand or Jotai later, install them later. Today they're not in the template, on purpose.

What I'd do differently

Three honest limits at v1.0:

No template versioning. The CLI installs the template bundled with that CLI version. That's fine for now, but a tool that scaffolds production projects should let users pin a template version while still getting CLI bug fixes. Right now they're coupled.

No update path for existing projects. If I improve the template, projects scaffolded last month don't see the improvement without manually diffing. An angel1-mvp-toolkit upgrade command that applies non-conflicting changes is on the list of things real users would justify building.

Test coverage is thin on the OpenAI variant. The Anthropic path is exercised by real engagements every week. The OpenAI variant is tested structurally but doesn't have the same depth of production runs behind it. End-to-end smoke tests on both variants are the missing safety net.

What's next

v1.0 ships the foundation: init command, multi-provider AI (Claude / OpenAI / Both), Supabase or NextAuth, optional Stripe / Resend / RAG. The roadmap is deliberately empty — no "Planned" features promised in public. The next version of this tool will be whatever real engagements show needs to be there.

The eval harness that earlier drafts of this case study promised? It's been extracted into a separate tool: angel1-rag-eval. Two tools, one workflow: scaffold with the toolkit, measure with the eval CLI.

Install via npx @massiangelone/angel1-mvp-toolkit init my-app · npm · GitHub