From e72a8f08266f2690b591b842b07a1f61bd95ffac Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 22 Jun 2026 02:49:26 +0000 Subject: [PATCH] docs: fill in onboarding Team Tips and Get Started Authored the Team Tips (design-first workflow, ephemeral toolchains, D1 border invariants S1/S2, immutable invariant vault, verify-by-running, commit-before-leaving) and a Get Started starter task (run smoke driver -> read the map -> pick up work). References point at real docs (README/SOUL/docs). Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_015hmgREHNsxYCuim33yUF2c --- ONBOARDING.md | 32 ++++++++++++++++++++++++++++++-- 1 file changed, 30 insertions(+), 2 deletions(-) diff --git a/ONBOARDING.md b/ONBOARDING.md index 13a3c1d..b9794f1 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -39,11 +39,39 @@ Top MCP Servers: ## Team Tips -_TODO_ +- **Design before code.** This is a design-first repo — the architecture docs are + the source of truth and the code follows them. When something feels ambiguous, + the answer is usually already written down; sync the design first (`/design-sync`). +- **The container is ephemeral; toolchains are reinstalled every session.** A + SessionStart hook (`.claude/hooks/install-toolchains.sh`) installs ponyc (via + ponyup), Alire/GNAT, and GnuCOBOL on each session. If a build can't find + `ponyc`, it's a `PATH` thing: `export PATH=/root/.local/share/ponyup/bin:$PATH`. +- **All external traffic crosses the Ada border (D1) first.** That's the S1 + structural invariant — never route around it, and **never reclassify a + message's provenance** (S2). The Ichor bus rejects unscreened external payloads + on purpose. +- **The invariant-law vault is immutable at runtime.** Invariant 0 (the + culpability anchor) and 01 (minimize harm) live in the COBOL vault and are not + to be edited casually — they're the constitution, not config. +- **Verify by running, not just reading.** Use `/run-sica-fondt` (or its + `smoke.sh`) to build + run the Pony/Ada/COBOL units and confirm all green + before you push. +- **Commit and push before you walk away.** The stop hook will nag about + untracked files for a reason — nothing survives the container otherwise. ## Get Started -_TODO_ +Your first task: get the project running end-to-end and read the map. + +1. Open the repo and let the SessionStart hook finish installing toolchains. +2. Run the smoke driver to confirm everything builds and runs: + `.claude/skills/run-sica-fondt/smoke.sh` — you want `smoke: ALL GREEN`. +3. Read `README.md`, `SOUL.md`, and `docs/` (start with + `docs/bus-topology.md` and `docs/gen03_state_of_architecture.md`) to + understand the organ/border model (Ichor bus → Ada D1 border → inner brain; + the COBOL invariant vault). +4. Pick up a small design-sync or build task from there. Ask Claude to walk you + through any unit — it has the `run-sica-fondt` skill loaded.