From 97e5bd126b90c127ffc128e145df9e3f3be4664e Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 22 Jun 2026 17:37:52 +0000 Subject: [PATCH] docs: add CLAUDE.md + AGENTS.md doc-map chain CLAUDE.md (<=200 lines): working agreements (you're-the-dev, verify-then-commit, design-first), build/run via run-sica-fondt, S1/S2/S3 invariants; links to ONBOARDING.md and AGENTS.md. AGENTS.md (<=100 pref): signpost to every doc and which to read for which task. ONBOARDING.md now points at AGENTS.md. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_015hmgREHNsxYCuim33yUF2c --- AGENTS.md | 40 ++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++ ONBOARDING.md | 4 +++- 3 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..4ef9c00 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,40 @@ +# AGENTS.md + +How to use the documents in this repo. This is the map: read it first, then go +to the right doc for your task. Keep this file under **200 lines** (aim for +**100**) — it's a signpost, not a manual. The depth lives in the docs it points +to. + +## Read in this order + +1. **`README.md`** — what sica-fondt is. +2. **`SOUL.md`** — intent and principles; the "why." +3. **`docs/`** — the architecture in detail: + - `bus-topology.md` — the Ichor bus and organ wiring. + - `gen03_state_of_architecture.md` — current architectural state. + - `gen03_body.md`, `gen03_self.md` — body/self model. + - `plans/` — forward-looking plans. +4. **`CLAUDE.md`** — working agreements, build/run, invariants. Read before + making changes. +5. **`ONBOARDING.md`** — setup checklist and first-task walkthrough (for people). + +## Which doc for which task + +| If you want to… | Go to | +|---|---| +| Understand the system at a high level | `README.md`, `SOUL.md` | +| Understand the architecture / organ model | `docs/` (start: `bus-topology.md`) | +| Build, run, or smoke-test | `run-sica-fondt` skill → `smoke.sh` | +| Know the rules before editing | `CLAUDE.md` (working agreements + invariants) | +| Onboard a new teammate | `ONBOARDING.md` | +| Find which doc covers a topic | this file | + +## Rules of the road + +- **Design before code.** The design docs are the source of truth; code follows. +- **Honor the invariants** (S1/S2/S3 in `CLAUDE.md`) — the Ada border and the + COBOL vault are not optional. +- **Verify, then commit.** Run the smoke driver; commit + push before leaving + (the container is ephemeral). +- **Keep the docs honest.** If you change behavior, update the doc that + describes it — and keep `CLAUDE.md` ≤200 lines and this file ≤200 (≤100 pref). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..526623d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,53 @@ +# CLAUDE.md + +Guidance for Claude Code when working in this repository. Keep this file under +**200 lines**. For team setup and a newcomer walkthrough, see +[`ONBOARDING.md`](ONBOARDING.md); for how the docs fit together and which to +read when, see [`AGENTS.md`](AGENTS.md). + +## What this is + +sica-fondt is a **design-first, polyglot architecture**: an Ichor perfusion bus +(Pony) feeds an Ada/SPARK border (D1), which fronts the inner brain, with a +COBOL invariant-law vault as the constitution. The design docs are the source of +truth; the code follows them. + +## Working agreements + +- **You're the dev.** When details are missing or a decision is open, make the + reasonable call and fill in concrete details — don't leave placeholders or + stall to ask, unless something is genuinely ambiguous. +- **Verify, then commit.** After generating or editing, confirm it works (build + / run / `run-sica-fondt` smoke), then commit with a descriptive message. + Commit and push before ending a session — the container is ephemeral. +- **Design before code.** If something feels ambiguous, the answer is usually + already written in `docs/`. Sync the design first. + +## Build & run + +Use the `run-sica-fondt` skill (`.claude/skills/run-sica-fondt/`) — its +`smoke.sh` builds and runs every executable unit and asserts output: + +```bash +.claude/skills/run-sica-fondt/smoke.sh # want: smoke: ALL GREEN +``` + +Per-unit commands and gotchas live in that skill's `SKILL.md`. Toolchains +(ponyc/Alire/GnuCOBOL) are reinstalled each session by the SessionStart hook +`.claude/hooks/install-toolchains.sh`; if `ponyc` isn't found, +`export PATH=/root/.local/share/ponyup/bin:$PATH`. + +## Invariants — do not violate + +- **S1:** all external traffic crosses the Ada border (D1) first; never route + around it. +- **S2:** never reclassify a message's provenance. +- **S3 / vault:** the COBOL invariant-law vault (Invariant 0, the culpability + anchor; 01, minimize harm) is immutable at runtime — don't edit it casually. + +## Docs map + +- `README.md`, `SOUL.md` — the project and its intent. +- `docs/` — architecture (`bus-topology.md`, `gen03_state_of_architecture.md`, …). +- `ONBOARDING.md` — new-teammate setup and walkthrough. +- `AGENTS.md` — which document to read for what. diff --git a/ONBOARDING.md b/ONBOARDING.md index b9794f1..cafcd45 100644 --- a/ONBOARDING.md +++ b/ONBOARDING.md @@ -61,7 +61,9 @@ Top MCP Servers: ## Get Started -Your first task: get the project running end-to-end and read the map. +Your first task: get the project running end-to-end and read the map. Not sure +which doc to read for what? Start with [`AGENTS.md`](AGENTS.md) — it's the +signpost to every other document here. 1. Open the repo and let the SessionStart hook finish installing toolchains. 2. Run the smoke driver to confirm everything builds and runs: