Skip to content
Closed
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified apps/web/public/favicon/apple-touch-icon.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified apps/web/public/favicon/favicon-96x96.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
46 changes: 4 additions & 42 deletions apps/web/public/favicon/favicon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified apps/web/public/favicon/web-app-manifest-192x192.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified apps/web/public/favicon/web-app-manifest-512x512.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
20 changes: 7 additions & 13 deletions apps/web/public/logo-dark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
20 changes: 7 additions & 13 deletions apps/web/public/logo-light.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
47 changes: 15 additions & 32 deletions apps/web/public/logo.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified apps/web/src/favicon.ico
Binary file not shown.
4 changes: 3 additions & 1 deletion plugin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Make your AI assistant scaffold and extend projects with [Better-T-Stack](https:
The plugin bundles:

- **MCP server** — the official `create-better-t-stack mcp` server (stdio, no auth/key). Exposes `bts_get_stack_guidance`, `bts_get_schema`, `bts_plan_project`, `bts_create_project`, `bts_plan_addons`, `bts_add_addons`.
- **Skills** — `scaffold-project` (start a new project) and `add-to-project` (add addons). These steer the assistant to plan a valid stack and generate it through the MCP rather than writing config by hand.
- **Skills** — `scaffold-project` (start a new project) and `add-to-project` (add addons or a workspace package to a project with a `bts.jsonc`). These steer the assistant to plan a valid stack and generate it through the MCP rather than writing config by hand.
- **Commands** — `/better-t-stack:new` and `/better-t-stack:add`.
- **Agent** — `stack-architect`, which designs a coherent stack from a product description and generates it.

Expand Down Expand Up @@ -58,3 +58,5 @@ args = ["-y", "create-better-t-stack@latest", "mcp"]
5. Report the stack and the exact `install` / `dev` commands.

Plan always precedes create; configs are always sent in full (explicit `"none"`, `[]`, booleans).

Without the MCP server, the skills fall back to the CLI's JSON commands (`create-json` / `add-json` with `"dryRun": true` first), and to a prefilled Stack Builder link (`https://better-t-stack.dev/new?...`) when no tools can run.
8 changes: 5 additions & 3 deletions plugin/agents/stack-architect.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,14 @@ You are a Better-T-Stack architect. You turn a product idea into a concrete, val
- `nx`, `turborepo`, and `vite-plus` cannot be combined.
- `convex` brings its own data layer — don't bolt on a conflicting database/orm/api unless the schema permits it.
- `mongodb` pairs with `mongoose` or Prisma, not Drizzle.
4. **Plan, don't write blindly.** Call `bts_plan_project` (dry run). Present the resolved stack with a one-line rationale per major choice. Confirm with the user.
5. **Generate.** On confirmation call `bts_create_project` with `install: false` (avoids MCP timeouts), then report the stack and the exact `install` / `dev` / DB-setup commands.
- A database needs an ORM, and an ORM needs a database.
- `runtime: workers` requires `backend: hono` and can't use `mongodb` or `dbSetup: docker`.
4. **Plan, don't write blindly.** Call `bts_plan_project` (dry run) — or, if the MCP isn't connected, `npx create-better-t-stack@latest create-json --input '<config with "dryRun": true>'`. Present the resolved stack with a one-line rationale per major choice. Confirm with the user.
5. **Generate.** On confirmation call `bts_create_project` (or `create-json` without `dryRun`) with `install: false` (avoids MCP timeouts), then report the stack and the exact `install` / `dev` / DB-setup commands.

## Defaults to lean on when the user is undecided

- Fullstack TypeScript web app: `next` or `tanstack-start` frontend, `hono` backend, `node` or `bun` runtime, `trpc` API, `postgres` + `drizzle`, `better-auth`, `turborepo`, `pnpm`.
- Prefer the smallest stack that satisfies the request; add addons only when justified.

Always plan before create. Never send a partial config. Report honestly if the plan surfaces a conflict.
Always plan before create. Never send a partial config. Never use `--yolo`. Report honestly if the plan surfaces a conflict.
20 changes: 7 additions & 13 deletions plugin/assets/icon.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 9 additions & 9 deletions plugin/commands/add.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
---
description: Add addons/features (PWA, Tauri, docs, linters, task runners, MCP, …) to an existing Better-T-Stack project via the Better-T-Stack MCP server.
argument-hint: "<addons to add, e.g. pwa biome turborepo>"
description: Add addons/features (PWA, Tauri, docs, linters, task runners, MCP, …) or a workspace package to an existing Better-T-Stack project via the Better-T-Stack MCP server (or the CLI's add-json).
argument-hint: "<addons to add, e.g. pwa biome turborepo, or a package name>"
---

# Add addons to a Better-T-Stack project
# Add to a Better-T-Stack project

User request: $ARGUMENTS

Add tooling/features to the current Better-T-Stack project using the Better-T-Stack MCP server instead of wiring it by hand.
Add tooling/features or a workspace package to the current Better-T-Stack project instead of wiring it by hand. Follow the **add-to-project** skill.

## Steps

1. **Confirm** the working directory is a Better-T-Stack project (look for `bts.jsonc`).
2. **Determine the addon set** from the arguments above. Use `bts_get_schema` for nested addon options when needed.
3. **Plan with `bts_plan_addons`** (dry run) and review the changes. Surface any conflicts (e.g. `nx`/`turborepo`/`vite-plus` are mutually exclusive).
4. **Apply with `bts_add_addons`** once confirmed.
1. **Confirm** the working directory is a Better-T-Stack project and read its `bts.jsonc` to learn the current stack. If it's missing, stop and tell the user — don't recreate it.
2. **Determine the addon set** (or `package` name) from the arguments above. Use `bts_get_schema` (or `schema --name addonOptions`) for nested addon options when needed.
3. **Plan with `bts_plan_addons`** — or, without the MCP, `create-better-t-stack add-json --input '<payload with "dryRun": true>'` — and review the changes. Surface any conflicts (e.g. `nx`/`turborepo`/`vite-plus` are mutually exclusive).
4. **Apply with `bts_add_addons`** (or `add-json` without `dryRun`) once confirmed.
5. **Report** what changed and any follow-up commands.

Always plan before applying. Don't add addons the user didn't ask for.
Always plan before applying. Don't add addons the user didn't ask for. Never hand-edit `bts.jsonc`.
12 changes: 6 additions & 6 deletions plugin/commands/new.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
---
description: Scaffold a new Better-T-Stack project. Plans a full, validated stack with the Better-T-Stack MCP server, confirms it, then generates the project.
description: Scaffold a new Better-T-Stack project. Plans a full, validated stack with the Better-T-Stack MCP server (or the CLI's create-json), confirms it, then generates the project.
argument-hint: "<project name and/or stack description>"
---

# Create a Better-T-Stack project

User request: $ARGUMENTS

Scaffold a new project using the Better-T-Stack MCP server. Do not hand-roll the project structure, tooling, auth, or database wiring.
Scaffold a new project with Better-T-Stack. Do not hand-roll the project structure, tooling, auth, or database wiring. Follow the **scaffold-project** skill.

## Steps

1. **Parse the request.** Extract the project name and any stack preferences from the arguments above. If nothing was provided, ask what kind of project they want.
2. **Resolve unknowns.** For any major choice not specified, either ask a brief question or pick a sensible default and state it. Call `bts_get_stack_guidance` and `bts_get_schema` when you need the authoritative option list or rules.
2. **Resolve unknowns.** For any major choice not specified, either ask a brief question or pick a sensible default and state it. Call `bts_get_stack_guidance` and `bts_get_schema` (or `npx create-better-t-stack@latest schema --name createInput`) for the authoritative option list and rules.
3. **Build a full explicit config.** Every field must be set explicitly (use `"none"`, `[]`, `true`/`false`). Required: `projectName`, `frontend`, `backend`, `runtime`, `database`, `orm`, `api`, `auth`, `payments`, `addons`, `examples`, `git`, `packageManager`, `install`, `dbSetup`, `webDeploy`, `serverDeploy`.
4. **Plan with `bts_plan_project`** (dry run). Show the resolved stack and confirm it matches intent.
5. **Create with `bts_create_project`** once confirmed. Use `install: false` to avoid MCP timeouts.
4. **Plan** with `bts_plan_project` — or, without the MCP, `create-better-t-stack create-json --input '<config with "dryRun": true>'`. Show the resolved stack and confirm it matches intent.
5. **Create** with `bts_create_project` (or `create-json` without `dryRun`) once confirmed. Use `install: false` to avoid timeouts.
6. **Report** the stack and the exact next commands (`<packageManager> install`, `dev`, any DB setup).

Always plan before create. Never send a partial config.
Always plan before create. Never send a partial config. Never use `--yolo`.
50 changes: 38 additions & 12 deletions plugin/skills/add-to-project/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: add-to-project
description: Add addons or features (PWA, Tauri, Starlight/Fumadocs docs, Biome/Oxlint, Husky/Lefthook, Turborepo/Nx, the MCP addon, etc.) to an existing Better-T-Stack project. Use when the user wants to extend, enhance, or add tooling to a project that was created with Better-T-Stack.
description: Add addons, features, or a workspace package (PWA, Tauri, Starlight/Fumadocs docs, Biome/Oxlint/Ultracite, Husky/Lefthook, Turborepo/Nx, the MCP or Skills addon, `packages/<name>`, etc.) to an existing Better-T-Stack project. Use when the user wants to extend, enhance, or add tooling to a project that has a `bts.jsonc` file.
metadata:
priority: 7
docs:
Expand All @@ -9,31 +9,57 @@ metadata:
- "bts.jsonc"
---

# Add addons to an existing Better-T-Stack project
# Add to an existing Better-T-Stack project

Use the Better-T-Stack MCP server to install addons into an existing project rather than wiring the tooling by hand.
Use Better-T-Stack to install addons or scaffold workspace packages into an existing project rather than wiring the tooling by hand.

## When this applies

The user already has a Better-T-Stack project (look for a `bts.jsonc` config) and wants to add tooling or features — e.g. "add PWA support", "add a docs site", "switch to Biome", "add Turborepo", "wire up the MCP addon".
The project has a `bts.jsonc` at its root and the user wants to add tooling, features, or a shared package — e.g. "add PWA support", "add a docs site", "switch to Biome", "add Turborepo", "wire up the MCP addon", "add a shared package".

For brand-new projects, use the **scaffold-project** skill instead.

## `bts.jsonc`

`bts.jsonc` records the stack chosen at creation (frontend, backend, database, addons, `addonOptions`, …) plus a `reproducibleCommand` that recreates the project. The add flow reads it to detect the stack.

- **Read it first** to understand the current stack before planning.
- **Never edit it by hand** to "enable" something — the add flow updates it.
- If it's missing, the add flow can't run. Tell the user rather than recreating it by guesswork.

## Workflow

1. **Confirm the target project** is a Better-T-Stack project and identify its directory.
2. **Plan.** Call `bts_plan_addons` with the desired addon set (and any nested `addonOptions`). This is a dry run — review the planned changes with the user.
3. **Apply.** Only after the plan succeeds and matches intent, call `bts_add_addons`.
4. **Report** what changed and the follow-up commands to run.
1. **Confirm the target project** and its directory (where `bts.jsonc` lives).
2. **Check valid values** for any nested options: MCP `bts_get_schema`, or CLI `npx create-better-t-stack@latest schema --name addonOptions` (also `addInput`).
3. **Plan (dry run).**
- MCP: `bts_plan_addons` with `projectDir` and `addons` (plus `addonOptions`) and/or `package`.
- CLI (no MCP):
```bash
npx create-better-t-stack@latest add-json --input '{
"projectDir": "./my-app",
"addons": ["pwa", "biome"],
"dryRun": true
}'
```
Review the planned changes with the user.
4. **Apply** only after the plan succeeds and matches intent: MCP `bts_add_addons`, or re-run `add-json` without `dryRun`.
5. **Report** what changed and the follow-up commands (e.g. `<packageManager> install`).

For a command the user can run themselves: `bunx create-better-t-stack@latest add --addons pwa biome` (use the project's package manager runner).

## Workspace packages

`package: "<name>"` (CLI: `add --package <name>`) scaffolds `packages/<name>` with a package manifest, the shared TypeScript config, and `src/index.ts`. Both the MCP add tools and `add-json` accept it.

## Available addons

`pwa`, `tauri`, `electrobun`, `starlight`, `biome`, `lefthook`, `husky`, `mcp`, `turborepo`, `nx`, `vite-plus`, `fumadocs`, `ultracite`, `oxlint`, `opentui`, `wxt`, `skills`, `evlog`.
`pwa`, `tauri`, `electrobun`, `starlight`, `biome`, `lefthook`, `husky`, `mcp`, `turborepo`, `nx`, `vite-plus`, `fumadocs`, `ultracite`, `oxlint`, `opentui`, `wxt`, `skills`, `evlog`, `axiom`.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Exclude Axiom from the addable-addon list

When an agent uses this skill to add axiom to an existing project, the plan always fails because addHandlerInternal explicitly rejects it as creation-only (apps/cli/src/helpers/core/add-handler.ts:456-461). Remove it from this add-flow list or clearly direct users to select it only during project creation.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 2d537a0. axiom is removed from the addable list, with a note that it can only be chosen at creation because add rejects it (add-handler.ts). The standalone skill's add section says the same.


Note: `nx`, `turborepo`, and `vite-plus` are mutually exclusive task runners. Use `bts_get_schema` for nested addon options (e.g. Fumadocs templates/search/AI chat, WXT templates, OpenTUI templates).
Nested options live in `addonOptions` (Fumadocs template/search/AI chat, WXT template, OpenTUI template, MCP servers/agents, Skills sources). `nx`, `turborepo`, and `vite-plus` are mutually exclusive task runners.

## Rules

- Always `bts_plan_addons` before `bts_add_addons`.
- Always plan/dry-run before applying.
- Don't add addons the user didn't ask for.
- Surface any conflicts (e.g. two task runners) from the plan before applying.
- Surface conflicts from the plan (e.g. two task runners, an addon already installed) before applying.
- Never hand-edit `bts.jsonc`.
Loading
Loading