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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015hmgREHNsxYCuim33yUF2c
This commit is contained in:
Claude 2026-06-22 02:49:26 +00:00
parent 17935f376d
commit e72a8f0826
No known key found for this signature in database

View File

@ -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.
<!-- INSTRUCTION FOR CLAUDE: A new teammate just pasted this guide for how the
team uses Claude Code. You're their onboarding buddy — warm, conversational,