obto-build-loop

OBTO App Build Loop

Before anything else

1. Call obto_whoami first in every new conversation and follow its startHere.rules. Read domain and availableResources.
2. The server is stateless: pass appName AND domain on every app-scoped call. Never assume a "current app" — if the user hasn't named one, ask, or find it with obto_list_all_apps / obto_find_app_by_name.
3. Read obto://guide/quickstart from the server's resources before the first deployment. The server-served guides are the source of truth — prefer them over assumptions. Scan the availableResources directory whoami returns and load the ones whose whenToRead fits the task — e.g. obto://guide/blueprints before writing code for a collection type, and obto://guide/public-app-baseline before claiming an app is done.

Organize first. One thread = one item; its train id is the work item id (e.g. WT-28) or the team's train number. Title the thread <train id> <emoji> <short name>: ⚪ queued, 🟡 in progress, 🟠 blocked (name the blocker), 🟢 done. Retitle when the state changes; with no rename tool, ask the person once. Finish or hand off the item, mark it 🟢, then take the next, one at a time. New work found mid-thread is its own item (sdlc_create_item), not a detour.

The build loop

Work in this order; do not skip steps:

1. Contract first. Write the build contract: (1) what the app does, (2) the FIRST vertical slice, (3) what "done" means for it. Show it as a numbered plan and get the client's yes before any save, scaffold included; never invent scope. obto_scaffold_app requires it as buildContract.
2. Scaffold. Use obto_scaffold_app for new apps (creates record + working skeleton in one call), passing buildContract and kind: 'public' for a browser web app (index page + App.tsx + App.css, ESM imports + relative ./ paths) or 'native' for an OBTO shell component (ui_template + policy_client + script_client, window-global libs + return ComponentName;). The skeleton passes obto_validate_app immediately and writes each artifact to its correct collection. The response includes structured nextSteps — follow them in order.
3. One vertical slice. Ship a single end-to-end path (one page, one route, one script) and verify it works before expanding. Anything beyond the contract's slice is a NEW slice only after a yes — not a silent addition.
4. Verify after every write. After each obto_upsert_record / route change, read the artifact back (fetch by id <collection>::<app>::<domain>::<name>, or obto_grep_artifact for a slice of a large one) and confirm the content landed. Never claim a write succeeded without reading it back. For a code-bearing script, obto_validate_script also runs by reference — omit script and name the stored artifact — so you can validate exactly what the platform stored, not what you meant to send.
5. Review, test, gate — after every save. This is the same loop as obto://guide/quickstart Rule 5.
   • Review what you saved: obto_review_change with targets = every record you changed in this step. Fix every error finding, save, and review those records again. Repeat until there are no errors. Fix warnings, or suppress one with a comment // obto-review-ignore <rule> -- <reason> on or above the line (warn/info only; an error can never be suppressed).
   • Test. If obto_run_tests is in your tool list, run every plan and add a test for new behaviour (obto_save_test). Otherwise say "tests not run" (obto_test_results shows earlier runs). Never call untested verified.
   • Gate. obto_review_change mode gate must return gateOk: true before you say done or ask to go live. obto_validate_app shows the same verdict in doneGate. Going live (obto_build_app) needs the client's yes to that, and it refuses a failing gate (done_gate_failed).
   • Never rename or split a record to dodge a finding, suppress an error, or ask for a gate override. gateOverride is an operator tool with an audited reason, not part of the loop.
6. Smoke gate before "done" — verify semantically, on the surface a real visitor uses. A preview URL proves only that the preview infra responded, and HTTP 200 proves nothing at all: OBTO's own "Site Missing" / "domain was not found" shells are served with status 200, so a status-only check certifies broken apps as working. "Done" means all of:
   • The done gate passes: obto_review_change mode gate returns gateOk: true (step 5).
   • obto_validate_app returns no errors.
   • Every public API route called via obto_invoke_route returns the expected status, content type, and JSON shape. An HTML 200 on an /api/... route is a failure, never a response; so is a non-200, a 524/timeout, or a degraded-mode UI fallback.
   • The receipt says WHICH surface answered. connectVia:'canonical' means the real canonical host served it; a tenant_ingress_semantic_fallback (with canonicalAttempt + layerVerdict) means the canonical host served a platform shell and the tool fell back — that is a finding to report, not a pass. Fallback success is not canonical success.
   • For a published app, obto_get_build_status shows publish.status: 'published' with its per-surface verify evidence, and you have READ any caveats (a publish can be genuinely published and still carry a known platform degradation).
   • pltf_log (via obto_db_query) shows no runtime errors.
   • obto_capture_preview each page; read visibleText (sign-in or loading = not seen) and check console / pageErrors / failedRequests.
   • Best proof: one real user action end to end, read back through the app's API — with test data the client agreed to (preview data is real), then remove it.
   • Report the evidence: the gate verdict, the review ids or "no errors" per record, test run ids (or "tests not run"), and the smoke results above.