# AGENTS.md (DRAFT, owned by plan 10-workflow-example.md)

Normative agent workflow for MoloApp. Human quickstart lives in README.md;
this file is the single entry point for autonomous work. Status: draft until
the root Makefile and CLI land (09-cli-ops.md); per-part commands below are
live today via `example/example.mk`.

## Setup commands

```sh
g++ --version   # expect g++ 15.2 with -std=c++23
make --version  # GNU or BSD make
```

Expected: both print versions. Failure action: stop, page a human.

## Build

```sh
make            # whole repo (root Makefile includes per-part .mk files)
make -f example/example.mk example   # this part only, standalone
```

Expected: warning-free build, outputs only under `build/`. Failure action:
fix at root cause, never silence warnings.

## Test

```sh
make test                                 # whole repo
make -f example/example.mk example-test   # this part only, standalone
```

Expected: `example suite: 37 passed, 0 failed`. Failure action: reproduce
through the real stack first (failing route-level test), then fix; the
reproduction stays in the suite. Conventions: `tests/README.md`.

## Lint

```sh
make lint   # configured gate (falls back to -Wall -Wextra clean build)
```

Expected: zero findings. Failure action: fix, never skip the gate.

## Docs update

After behavior changes, in the same session: spec delta first, then code,
then example route, then tests, then changelog entry. Docs state what the
system does today; gaps list the owning file next to the code.

## Version bump

Never hand-chosen. From commits since the last tag: any `!` or
`BREAKING CHANGE` -> MAJOR; else any `feat` -> MINOR; else any `fix` ->
PATCH; else no release. `VERSION` plus annotated tag `vMAJOR.MINOR.PATCH`
update atomically with the changelog entry. Demo: `POST /workflow/release`.

## Commit

Format: `<type>[(scope)][!]: <description>`, subject max 100 chars.
Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci,
chore. Scope is the area slug: runtime, security, data, routing,
realtime, supervisor, clients, cli, workflow. Malformed commits are
rejected before version analysis.

## Tag

Tagging requires a green suite plus live verification after deploy, same
session. Failed verification blocks the tag. Max 1 release per green run.

## Deploy

```sh
make deploy   # defined by 09-cli-ops.md; loopback single binary for v1
```

## Verify live

After deploy: health probe, metrics scrape, example index load on a 360px
viewport, click the matrix top 10 routes. Any red step halts the pipeline;
report, never force-push past red.

## Floors and escalation

Never cross alone: `specs/`, `CHANGELOG.md`, `VERSION`, tags, retention
windows, destructive file deletes, history rewrite, force push, hard
reset. On a floor hit: dry-run, stop, page a human. Pipeline order is
lint -> suite -> bump -> changelog -> commit -> tag -> deploy -> verify;
timeout 30 min, then escalate. On code-vs-spec conflict the spec wins
until formally amended in the same change.