# Working agreements for miniSCP

## Orientation

`docs/` is the source of truth — read the relevant file before touching adjacent code:
[architecture.md](docs/architecture.md) (process/window model, bun modules, UI services, theming),
[gotchas.md](docs/gotchas.md) (landmines already hit — read before changing nearby code),
[build-and-release.md](docs/build-and-release.md), [platform-notes.md](docs/platform-notes.md).

## Planning

In plan mode, use `AskUserQuestion` to resolve **every** ambiguity before finalizing a
plan. Never guess at intent or silently pick behavior the user didn't specify — keep asking
until the approach is unambiguous, then exit planning.

## After an approved plan is executed

1. **Verify first** — backend: `bun run ./node_modules/typescript/bin/tsc --noEmit -p tsconfig.json`;
   UI: `bun run build:ui`; plus any smoke test that fits the change. (`bun run build:ui` is the
   full AOT type-check for Angular — trust it over IDE squiggles.)
2. **Then commit + push automatically, no need to ask** — a descriptive message ending with:

   ```
   Co-Authored-By: Claude <noreply@anthropic.com>
   ```

   Push to the current branch (this repo works directly on `main`).
3. If verification fails, fix it or report back — do **not** commit broken work.

## Keep the live documentation current

`docs/` is living, not a one-time write. When a change alters the architecture/process model,
a module's or service's responsibility, the RPC surface, theming, or introduces a new landmine,
update the matching doc **in the same change, before the auto-commit**:

- `docs/architecture.md` — structure, bun modules, UI services, theming.
- `docs/gotchas.md` — anything that caused a real bug or debugging spiral.
- `docs/build-and-release.md` / `docs/platform-notes.md` — when build or platform behavior changes.

Match the existing dense, bulleted house style.