mirror of
https://github.com/SHOGGOTH-SECTOR/sica-fondt.git
synced 2026-07-31 08:06:26 +00:00
docs: extract directory/doc index into docmap.yaml
AGENTS.md was carrying the read-order + routing table inline; moved that to an independent machine-readable docmap.yaml (read_order, routing, design_docs, organs with build cmds, invariants, smoke). AGENTS.md slims to a prose signpost (54->28 lines) pointing at it; CLAUDE.md docs-map lists it. YAML validated. 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
parent
0a5c88bb02
commit
d784a92f75
54
AGENTS.md
54
AGENTS.md
@ -1,54 +1,28 @@
|
||||
# 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 |
|
||||
How to use the documents in this repo — the prose signpost. The full
|
||||
directory/document index lives in [`docmap.yaml`](docmap.yaml) (machine-readable;
|
||||
start there to find which file covers what, the newcomer read-order, and the
|
||||
organ list). Working agreements and invariant text: [`CLAUDE.md`](CLAUDE.md).
|
||||
Keep this file lean (≤100 lines) — depth lives in the docs it points to.
|
||||
|
||||
## 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:
|
||||
scoped `AGENTS.md` with its *local* build/run/invariants (see `docmap.yaml` →
|
||||
`organs` for the list and paths).
|
||||
|
||||
- `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.
|
||||
Keep scopes **non-overlapping**: the root signposts, 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).
|
||||
- **Verify, then commit.** Run the smoke driver (`docmap.yaml` → `smoke`); commit
|
||||
+ push before leaving (the container is ephemeral).
|
||||
- **Keep the docs honest.** If you change behavior, update the doc — and the
|
||||
`docmap.yaml` entry — that describes it. Keep `CLAUDE.md` ≤200 lines and this
|
||||
file ≤100.
|
||||
|
||||
@ -50,4 +50,5 @@ Per-unit commands and gotchas live in that skill's `SKILL.md`. Toolchains
|
||||
- `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.
|
||||
- `AGENTS.md` — prose signpost for how the docs fit together.
|
||||
- `docmap.yaml` — machine-readable index: read-order, doc routing, organ list.
|
||||
|
||||
56
docmap.yaml
Normal file
56
docmap.yaml
Normal file
@ -0,0 +1,56 @@
|
||||
# docmap.yaml — directory & document index for sica-fondt.
|
||||
#
|
||||
# The independent, machine-readable map referenced by AGENTS.md. AGENTS.md stays
|
||||
# prose (scope + rules); this stays data (where things are). Keep in sync with
|
||||
# the tree. Invariant text is authoritative in CLAUDE.md — mirrored here as a
|
||||
# pointer only.
|
||||
|
||||
docs:
|
||||
read_order: # newcomer reading path
|
||||
- README.md # what sica-fondt is
|
||||
- SOUL.md # intent and principles — the "why"
|
||||
- docs/ # architecture in detail
|
||||
- CLAUDE.md # working agreements, build/run, invariants
|
||||
- ONBOARDING.md # newcomer setup + first task
|
||||
|
||||
routing: # which doc for which task
|
||||
high_level_overview: [README.md, SOUL.md]
|
||||
architecture: [docs/bus-topology.md, docs/gen03_state_of_architecture.md]
|
||||
build_run_test: .claude/skills/run-sica-fondt/ # smoke.sh
|
||||
rules_before_editing: CLAUDE.md
|
||||
onboard_teammate: ONBOARDING.md
|
||||
find_which_doc: AGENTS.md # the prose signpost; this file is its index
|
||||
|
||||
design_docs:
|
||||
docs/bus-topology.md: Ichor bus and organ wiring
|
||||
docs/gen03_state_of_architecture.md: current architectural state
|
||||
docs/gen03_body.md: body model
|
||||
docs/gen03_self.md: self model
|
||||
docs/plans/: forward-looking plans
|
||||
|
||||
# Organs — deployable units, each with its own scoped AGENTS.md (nearest-wins).
|
||||
organs:
|
||||
- path: src/ichor
|
||||
agents_md: src/ichor/AGENTS.md
|
||||
lang: pony
|
||||
role: Ichor perfusion bus (outer transport); S1 membrane screens external traffic
|
||||
build: "ponyc src/ichor -o build && ./build/ichor" # from repo root
|
||||
- path: src/endocrine
|
||||
agents_md: src/endocrine/AGENTS.md
|
||||
lang: [r, octave]
|
||||
role: endocrine array — R Drive-Box + Octave ETR
|
||||
build: "src/endocrine/run_tests.sh ; src/endocrine/etr/run_etr_tests.sh"
|
||||
- path: mafiabot_core
|
||||
agents_md: mafiabot_core/AGENTS.md
|
||||
lang: [ada, cobol]
|
||||
role: Ada border (D1) — all traffic crosses here first; COBOL invariant vault in src/trust
|
||||
build: "cd mafiabot_core && alr -n build" # not bare gprbuild
|
||||
|
||||
# Repo-wide invariants — authoritative text in CLAUDE.md.
|
||||
invariants:
|
||||
S1: all external traffic crosses the Ada border (D1) first
|
||||
S2: never reclassify a message's provenance
|
||||
S3: the COBOL invariant-law vault is immutable at runtime
|
||||
|
||||
# One harness builds and runs every executable unit; want "smoke: ALL GREEN".
|
||||
smoke: .claude/skills/run-sica-fondt/smoke.sh
|
||||
Loading…
x
Reference in New Issue
Block a user