capabilities/affordances/officer/core/starting-an-app.md

name, description, version

name	description	version
Starting an app	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.	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.

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:

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:

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

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.