pastilhasandClaude Opus 5
8a1bcb03f5
two things an agent cannot discover and gets wrong by default. FIRST: asked to create an app, it scaffolds one. there is a template — templates/template-react on gitea — and it is the agreed starting point. it documents itself, so this points at its README, CLAUDE.md and CONVENTIONS.md rather than restating them; the one thing worth lifting out is README step 1, the rename, because it costs thirty seconds at the start and is a chore forever after. SSH not HTTPS, verified both ways: the https remote prompts for a username and dies in a non-interactive shell. the tailnet address is noted as the fallback for when the public host's ssh is being rate-limited, which the deploy skill already records as a recurring thing. SECOND: asked to run it, it runs bun dev in the foreground, which blocks until the tool times out and reports a working server as a failure. backgrounding is both the only thing that works AND what the owner wants — a background job gets officer's live panel, the same one they would see running it themselves, so they can read the output and stop it without asking. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043
2.7 KiB
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.
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.
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.