---
name: bootstrap-react-project
description: Creates a new Humand React sandbox project with the production stack. Runs humand-create-app, installs dependencies, asks for the project type, and auto-chains the matching auth/connection skill. Use when the user wants to start a new project or mockup.
metadata:
  category: Project Creation
---

# Skill: Bootstrap React Project

Creates a new Humand frontend sandbox project ready to run locally. Uses `humand-create-app` under the hood — the CLI handles all mechanical work (token resolution, dependency installation, validation, git init). After scaffolding, **it is mandatory** to know what the project connects to: the skill asks for the project type and auto-chains the corresponding skill.

## When to use

- User wants to start a new sandbox or mockup
- User says "nuevo proyecto", "crear proyecto", "quiero hacer un mockup de X", "quiero explorar una idea"
- After `/setup-sandbox` completes successfully

## Prerequisites

**MANDATORY: Before writing any code, complete the pre-flight rules check** defined in `rules/workflows/preflight-rules-check.md`. Read ALL listed rules from `humand-react` and `sandbox.md` before generating project files. Do not skip this.

## Steps

### 1. Ask for project name

Ask the user:
> What would you like to name the project? (e.g. `checkout-redesign`, `onboarding-v2`)

Validate the name:
- Lowercase only
- No spaces (suggest using `-` instead)
- No special characters except `-`

If the project folder already exists in the current directory, warn the user and ask if they want a different name.

### 2. Ask for project type (MANDATORY)

Knowing what the project will connect to is required — the flow cannot continue without this answer. Ask the user and present the three options in English (these descriptions are user-facing):

> **What type of project is this?**
>
> 1. **Internal improvement project** — Will connect to tools we use internally at Humand.
> 2. **Revenue project** — Will connect only to data from one specific community.
> 3. **Test project** — Does not connect to anything; uses test data only.

Record the answer as one of: `internal`, `revenue`, `test`. Do not proceed without it.

### 3. Confirm before proceeding

Show a summary and ask for confirmation:
> I'm going to create the project `<name>` as a `<type>` project. Shall we start?

### 4. Run humand-create-app

First, verify the token file exists:

```bash
test -f ~/.humand/github-token && test -s ~/.humand/github-token
```

If missing or empty, stop and tell the user to run `/setup-sandbox` (or save a token manually to `~/.humand/github-token`). Do NOT proceed — the CLI would otherwise fall back to `gh auth token`, which returns the user's personal token (usually without access to `@humanddev` packages) and fails with 401/403.

Then run the CLI, forcing `GITHUB_TOKEN` from the file so the `gh` fallback is never used.

- For **`revenue`** projects, pass `--humand-api` so the CLI scaffolds the PostgREST proxy and service:
  ```bash
  GITHUB_TOKEN="$(cat ~/.humand/github-token)" bunx @humanddev/humand-create-app@latest <name> --humand-api
  ```
- For **`internal`** and **`test`** projects:
  ```bash
  GITHUB_TOKEN="$(cat ~/.humand/github-token)" bunx @humanddev/humand-create-app@latest <name>
  ```

**Do NOT ask the user to run this command.** Run it directly. **Do NOT run the CLI without the explicit `GITHUB_TOKEN=...` prefix** — the file is the single source of truth for this skill.

### 5. If the CLI fails — STOP

**This is critical.** When the CLI exits with a non-zero code:

1. **Do NOT try to fix the problem yourself.** No manual `bun install`, no `npm install`, no editing package.json, no deleting node_modules, no creative workarounds. Every "fix" you attempt will make things worse.
2. **Read the error output** from the CLI.
3. **Translate the error to plain English** and tell the user what happened.
4. **Only these actions are allowed:**
   - If the error mentions **token/authentication/401/403**: ask the user for a fresh GitHub token, save it, and re-run the exact same CLI command.
     ```bash
     mkdir -p ~/.humand
     echo "<token>" > ~/.humand/github-token
     chmod 600 ~/.humand/github-token
     ```
   - If the error mentions **port/network/timeout**: re-run the exact same CLI command (it has internal retries, but the network may have been temporarily down).
   - **For any other error**: tell the user what the error says and ask them how they want to proceed. Do NOT attempt to diagnose or fix it.

**Forbidden actions after a failure:**
- `npm install`, `yarn install`, `pnpm install` — only bun is supported
- `bun install` or `bun add` outside of the CLI — the CLI manages its own dependencies
- Editing `package.json`, `.npmrc`, `tsconfig.json`, or any generated file
- Deleting `node_modules/`, `bun.lockb`, or the project folder to "start fresh"
- Running `tsc`, `lint`, or `git init` manually — the CLI does all of this

**The CLI cleans up automatically on failure.** If any step fails, the CLI deletes the partial project folder before exiting. There is nothing to clean up — the next run starts completely fresh.

**The CLI is the single source of truth.** If it fails, the answer is to fix the root cause (usually a bad token) and re-run the exact same command. Never replicate its steps by hand.

### 6. Set up vercel.prod.json

Check if `vercel.prod.json` already exists in the project root. If not, create it:

```json
{
  "installCommand": "echo '//npm.pkg.github.com/:_authToken='$GITHUB_TOKEN >> .npmrc && rm -f bun.lockb && bun install",
  "rewrites": [
    { "source": "/((?!api/).*)", "destination": "/index.html" }
  ]
}
```

This ensures Vercel can install private `@humanddev` packages at build time. `GITHUB_TOKEN` must be set in the Vercel project's environment variables before deploying.

### 7. Auto-chain the matching skill

`cd` into the new project folder and invoke the corresponding skill(s) based on the type chosen in step 2. Do **not** ask the user — chain directly.

- **`internal`** → invoke `/add-super-admin-login`.
- **`revenue`** → invoke `/add-login`, wait until it completes, then invoke `/connect-to-humand-api`. Note: the CLI already scaffolded the PostgREST proxy and service files; `/connect-to-humand-api` only needs to wire up the credentials and env vars.
- **`test`** → no auth skill. Tell the user to run `/start-project` — the start/stop skills handle both the Vite server and the mock json-server.

### 8. Communicate the result and start a new conversation

Get the absolute path:

```bash
echo "$(cd <name> && pwd)"
```

Tell the user the project is ready and that they should **start a new conversation from the project folder**. This is important because:
- The new conversation starts with clean context (no bootstrap noise)
- The `.claude/` directory in the project contains rules and skills that only load when the conversation starts from that folder

> Project created successfully at `<absolute_path>`.
>
> **Next step:** Open a new conversation from the project folder.
>
> **From the terminal (Claude Code CLI):**
> ```
> cd <absolute_path>
> claude
> ```
>
> **From Claude Desktop:**
> Open a new conversation and switch the working folder to `<absolute_path>` (click the folder name at the bottom of the window).
>
> In that new conversation you can:
> - Run `/start-project` to start the server and view the project at http://localhost:3000
> - Run `/plan-project` to plan the screens before you start building

**Do NOT continue building in this conversation.** Do NOT invoke `/plan-project` or `/build-feature` here. The bootstrap conversation ends after step 6.