devs/cproof-context
SHA256
2
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
draft/split-context
cproof-context/README.md
jabber.developer2 22977846a3 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.7 KiB
Raw Permalink Blame History

cproof-context

Agent-oriented context documentation for the 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.