mirror of
https://github.com/SHOGGOTH-SECTOR/sica-fondt.git
synced 2026-07-31 16:16:26 +00:00
0a5c88bb02
AGENTS.md is hierarchical (nearest-file-wins), so the root is the map and each organ owns a scoped AGENTS.md with local build/run/invariants: src/ichor (Pony bus, S1 membrane), src/endocrine (R/Octave organ tests), mafiabot_core (Ada border + COBOL vault, alr-not-gprbuild, S3). Scopes kept non-overlapping to avoid the divergence trap rather than sprinkling sync notes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015hmgREHNsxYCuim33yUF2c
55 lines
2.3 KiB
Markdown
55 lines
2.3 KiB
Markdown
# 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 |
|
|
|
|
## Scope & nesting
|
|
|
|
`AGENTS.md` is **hierarchical** — an agent reads the *nearest* one walking up
|
|
from the file it's editing. So this root file is the **map**; each organ owns a
|
|
scoped `AGENTS.md` with its *local* build/run/invariants:
|
|
|
|
- `src/ichor/AGENTS.md` — the Ichor bus (Pony).
|
|
- `src/endocrine/AGENTS.md` — the endocrine organs (R / Octave).
|
|
- `mafiabot_core/AGENTS.md` — the Ada border (D1) + the COBOL vault under
|
|
`src/trust`.
|
|
|
|
Keep scopes **non-overlapping**: the root maps, the organs detail. Don't restate
|
|
the root in an organ file (that's how the two drift) — link up instead.
|
|
|
|
## 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).
|