SHA256

Files

docs: split context into layered, agent-oriented files

Replace the single file-structure.md with a stratified layout designed
for AI/agent skill consumption: tables and concrete identifiers over
prose, files loaded on demand, content separated by churn rate.

Layers:
- architecture/  stable structural reference (overview, source-map,
                 test-map, data-flow)
- patterns/      memory, commands, autocomplete, events, xmpp,
                 encryption, ui, plugins
- testing/       unit-tests, stubs, functional-tests, bench
- build/         local, docker, ci
- playbooks/     add-command, add-test, add-autocomplete,
                 add-event-handler, add-encryption
- gotchas.md     append-only dated entries (seven seed entries)
- wip/           branch-specific notes; deleted on merge to master

Stable layers describe cproof on master only. In-flight feature
branches (currently feat/ai) get a single file under wip/.

INDEX.md is the entry map with churn labels; SKILL.md is the
always-loaded skill hint pointing to it.

2026-04-30 20:52:06 +03:00

2.9 KiB

Raw Permalink Blame History

INDEX

One-page map of every context file. Churn labels: low (years), med (months), high (weeks).

Top level

File	Churn	When to load
`README.md`	low	Never — repo metadata for humans.
`SKILL.md`	low	Always (entry hint).
`INDEX.md`	low	Always (this file).

architecture/ — structural reference

File	Churn	When to load
`overview.md`	low	First load on any cproof task.
`source-map.md`	low	When choosing where to put new code, or locating an unfamiliar module.
`test-map.md`	low	When writing or running tests.
`data-flow.md`	low	When reasoning about input → output paths (commands, events, UI updates).

patterns/ — conventions and idioms

File	Churn	When to load
`memory.md`	low	Any C edit that allocates / frees.
`commands.md`	med	Adding, changing, or understanding a `/command`.
`autocomplete.md`	med	Anything that touches `cmd_ac.c` or registers an `Autocomplete`.
`events.md`	med	Touching `src/event/`.
`xmpp.md`	med	Touching `src/xmpp/` or any XMPP-gated code path.
`encryption.md`	med	Touching `src/omemo/`, `src/otr/`, or `src/pgp/`.
`ui.md`	med	Touching `src/ui/`.
`plugins.md`	med	Touching `src/plugins/`, plugin C/Python API.

testing/ — how tests work

File	Churn	When to load
`unit-tests.md`	med	Writing or extending unit tests.
`stubs.md`	med	Adding a function whose callers are unit-tested, or wiring a new stub.
`functional-tests.md`	med	Touching `tests/functionaltests/`.
`bench.md`	low	Touching `tests/bench/` or interpreting bench output.

build/ — how to build

File	Churn	When to load
`local.md`	low	Reference for `autogen.sh` / `configure` / `make` flags.
`docker.md`	low	Always when building — canonical environment.
`ci.md`	med	Diagnosing CI failures, reading CI logs.

playbooks/ — step-by-step recipes

File	Churn	When to load
`add-command.md`	med	Adding a new `/command`.
`add-test.md`	med	Adding a new unit test file.
`add-autocomplete.md`	med	Adding autocomplete for an existing command.
`add-event-handler.md`	med	Adding a server- or client-event handler.
`add-encryption.md`	med	Touching encryption modules safely.

gotchas.md

File	Churn	When to load
`gotchas.md`	high (append-only)	Always scan before finishing a task.

wip/ — branch-specific notes

Files describing in-flight feature branches. Each file is deleted when its branch merges to master; the surviving content (if any) is folded into the stable layers above.

File	Churn	When to load
`wip/feat-ai.md`	high (deleted on merge)	Working on `feat/ai`, or trying to understand AI-related code that does not yet exist on `master`.

2.9 KiB Raw Permalink Blame History