---
name: Starting an app
description: Use when asked to create, scaffold or start a new app or project, and when asked to run one. There is a template to begin from, and a specific way the owner expects a dev server to be started.
version: 1
---

**Do not scaffold a new app from scratch.** There is a template, it is the agreed starting point, and it
carries decisions that took a while to settle.

```bash
git clone git@gitea.officer.dev:templates/template-react.git <name>
```

Bun · Hono · React 19 · Tailwind v4 · shadcn/ui · Postgres with Drizzle. A JSON API at `/api` and a React
app at `/`, over one query layer.

**SSH, not HTTPS.** `https://gitea.officer.dev/…` prompts for a username and fails in a non-interactive
shell; the SSH remote is already authenticated. If SSH is being refused for a stretch — the public host is
behind a proxy that rate-limits it — `ssh://git@100.64.0.13:10023/templates/template-react.git` is the same
repository over the tailnet.

### Cloning into the folder you are already in

`git clone <url> .` works, **and only into a genuinely empty directory**. Verified: a single file makes it
fail, and so does a single HIDDEN one —

```
fatal: destination path '.' already exists and is not an empty directory.
```

That is not an edge case here. A commander's directory holds `CLAUDE.md` and `state/`; a plugin's chat
directory holds a `CLAUDE.md` the platform wrote. Cloning into either fails.

When the directory is not empty, fetch instead of cloning:

```bash
git init -q .
git remote add origin git@gitea.officer.dev:templates/template-react.git
git fetch -q --depth 1 origin HEAD
git checkout -q FETCH_HEAD -- .
git reset -q
```

**This overwrites a file that collides, without asking.** Also verified: doing it in a directory that
already had a `CLAUDE.md` replaced it with the template's. So look at what is there first, and if one of
those files is the platform's — a commander's brief, a plugin's chat brief — move it aside and put it back,
or clone somewhere else and copy in what you need.

## Then read its own documentation, and do step 1

The template documents itself. **`README.md` step 1 is a rename** — everything project-specific is called
`app`, and a case-sensitive search for `app`, `App` and `APP` finds all of it. Thirty seconds at the start,
a chore forever after. Do it before the first commit.

Its `CLAUDE.md` points at `CONVENTIONS.md` (React patterns, feature folders, manager hooks),
`docs/DATABASE.md` and `docs/SURFACES.md`. Read those rather than inferring house style from the code —
they exist so the same argument is not had twice.

Drop the template's git history and start your own unless told otherwise: it is a starting point, not an
upstream to track.

## Data to build against

There is mock data, so a dashboard has something real to show:

```bash
git clone git@gitea.officer.dev:templates/sample-data.git
```

`sales` — 6,402 daily orders over two years, with a Q4 lift, a summer dip, quiet weekends and one region
pulling ahead in year two. `subscriptions` — 480 accounts where "active" is a calculation over start and
cancel dates rather than a column, and small plans churn far more than large ones.

Both come as `.xlsx` and `.csv`, identical data. **The CSV needs no parser**, so prefer it unless reading
the spreadsheet is the point. Its `README.md` has every column.

Use this rather than inventing rows. Generated data with no shape in it produces a chart that proves
nothing, and that is what gets built when an agent makes numbers up.

## Running it — always as a background job

```bash
bun dev
```

**Start it in the BACKGROUND, never in the foreground.** Two reasons, and either one is sufficient:

- **A dev server does not exit.** Run in the foreground it blocks the turn until the tool times out, and
  the timeout is reported as a failure of a thing that was working perfectly.
- **The owner wants to watch it.** A background job gets Officer's live panel — the same one they would
  see running it themselves — so they can read the output, see the port, and stop it. Run any other way it
  is invisible, and stopping it means asking you.

`bun dev` prints steadily, so the panel fills immediately. `predev` regenerates the index first; that is
normal and takes a moment.

The general rule about background output still applies — see the background-jobs affordance. It matters
less here only because this particular command is already talkative.

**Say the URL when it comes up.** The port is in `.env` and the template's README, and the first thing
anybody wants after "it's running" is where to look.