jabber.developer2
22977846a3
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.
69 lines
2.7 KiB
Markdown
69 lines
2.7 KiB
Markdown
# cproof-context
|
|
|
|
Agent-oriented context documentation for the [cproof](https://git.jabber.space/devs/cproof)
|
|
project (a fork of Profanity, a terminal-based XMPP client written in C).
|
|
|
|
This repository is **not** human-onboarding documentation. It is structured for
|
|
consumption by AI/agent skills — tables over prose, concrete identifiers over
|
|
descriptions, layered files loaded on demand.
|
|
|
|
## Layout
|
|
|
|
| Path | Churn | Purpose |
|
|
|---|---|---|
|
|
| `SKILL.md` | low | Always-loaded entry hint. Points to `INDEX.md`. |
|
|
| `INDEX.md` | low | One-page map of every doc with churn label. |
|
|
| `architecture/` | low | Stable structural reference: source map, test map, data flow. |
|
|
| `patterns/` | medium | Codified conventions: memory, commands, autocomplete, events, etc. |
|
|
| `testing/` | medium | How tests are organised, written, and stubbed. |
|
|
| `build/` | medium | Local, Docker, and CI build flows. |
|
|
| `playbooks/` | medium | Step-by-step recipes for common tasks. |
|
|
| `gotchas.md` | append-only | Dated entries: one per known pitfall. |
|
|
| `wip/` | high | Branch-specific notes for in-flight features. Deleted on merge. |
|
|
|
|
See `INDEX.md` for the full file list.
|
|
|
|
## Consumer
|
|
|
|
Consumed by an agent skill that operates on the cproof codebase. The skill
|
|
should pin this repo to a specific SHA (not a branch) and treat the loaded
|
|
files as authoritative for their stated scope.
|
|
|
|
## Update flow
|
|
|
|
1. Edits land via PRs against `master`.
|
|
2. Drift checks (path / identifier existence in cproof HEAD) run in CI before
|
|
merge — see `architecture/test-map.md` and `build/ci.md` for details once
|
|
wired up.
|
|
3. After major cproof refactors, the skill consumer bumps the pinned SHA to a
|
|
commit known to pass drift checks.
|
|
|
|
## Out of scope
|
|
|
|
- User-specific agent preferences (language, commit-trailer policy, etc.) —
|
|
belong in agent memory, not here.
|
|
- Git history snapshots, changelogs, PR summaries — derivable from `git log` /
|
|
`gh pr`.
|
|
- Aspirational guidance — this repo describes cproof as it is, not as it
|
|
should be.
|
|
|
|
## Baseline and WIP
|
|
|
|
The stable layers (`architecture/`, `patterns/`, `testing/`, `build/`,
|
|
`playbooks/`, `gotchas.md`) describe **cproof on `master`**. They do not
|
|
mention symbols, files, or commits that exist only on a feature branch.
|
|
|
|
In-flight feature branches that materially change the surface (new module,
|
|
new commands, new stubs) get a single file under `wip/<branch-slug>.md`. On
|
|
merge to `master`, that file is deleted and any surviving content is folded
|
|
into the stable layers.
|
|
|
|
Current WIP: `wip/feat-ai.md` (cproof branch `feat/ai`).
|
|
|
|
## Status
|
|
|
|
Layout is being authored on `draft/split-context`. The single
|
|
`file-structure.md` (still present on `feat/add-context`) is being decomposed
|
|
into the structure above; once the split is complete, `file-structure.md` is
|
|
deleted.
|