retoor
3c4334cec9
Full C++23 framework tree: runtime, observability, security, data, app, realtime, supervisor, clients, CLI, example plus enterprise tenancy, audit, operability, governance, supplychain. Postgres via docker compose for tests.
3.0 KiB
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
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
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
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
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
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.