Writing conventions for kb/agentic-systems/

Purpose and quality

This collection explains external agentic systems and harnesses, including memory and knowledge as whole-system lenses. Its contribution is an evidence-grounded account of source-native operation, bounded synthesis and explicit limitations. The quality goal is fidelity and economy. Explain native operation before using Commonplace concepts; qualify mappings and preserve evidence limits. A reader must be able to reject a mapping without losing the operational account.

Placement and maintenance

The root holds README.md, COLLECTION.md and instructions/, types/, reports/. reviews/ holds ordinary accounts and generated reviews; comparisons/ holds cross-system writing and tables. instructions/ owns the research method, shared analysis contracts, landscape synthesis and taxonomy maintenance. General procedures, including the Commonplace transfer scan, remain in kb/instructions/. Edit canonical instructions; projections provide checkout skill discovery. Research skills are not promoted to every initialized KB. No nested collections.

reports/state/ is ignored working state, excluded from ordinary validation; selected state/outputs receive explicit checks. Workers write only assigned outputs; code owns acceptance, copies and cleanup. Each run keeps its opening method commit; earlier runs finish there or remain recovery evidence.

reports/retained/ holds frozen accepted sets. Other research evidence uses names distinct from run IDs. Substantive corrections require a new run. reports/retained-archive/ preserves historical bytes/contracts and pins, excluded from current-schema sweeps and comparisons. Only an explicitly authorized layout migration may change paths, types, required links and derived hashes; preserve findings, sources, record/run identities and historical method/synthesis provenance, and retain a verified old/new hash map.

Complete runs publish workflow-owned generated reviews; publication is mandatory. Do not hand-edit them. Correct inputs/method and rerun. Unmarked authored accounts remain author-maintained. The generated-review, run-state and set types govern publication identity, membership, byte pins and recovery checks. Retain accepted members unchanged; the memory member's comparison profile is authoritative. Trials supply no separate semantic clearance. Comparison readers verify retained pins and keep code-grounded and doc-grounded populations separate.

Authoring

Open authored accounts with one line stating the evidence basis and capture date. Typed members use their type's evidence format. Descriptive titles name the system/feature; argumentative accounts use claim-shaped titles and title-as-claim. Member descriptions follow their type; ordinary descriptions identify subject and scope. Worker fragments keep the job's headings. Instructions use imperative titles and trigger descriptions; their quality goal is executability and precision.

Before assessing theory pathways, read the Theory account in the shared record contract. It supplies independently evidenced conditions and separate learning, persistence, addressability and reflection assessments; analytical jobs already receive it. Before editing instructions, shared contracts or local types, follow method maintenance.

Durable analyses exclude current Commonplace differences, adoption ideas and watch items: those belong in separately commissioned transfer state under kb/reports/state/agentic-system-transfer/, retained until disposition and then replaced/deleted by its workflow. Do not feed transfer state into stable analyses or public comparisons. Transferable theory belongs in kb/notes/, raw captures in source snapshots, Commonplace descriptions in kb/reference/, unfinished work in kb/work/.

Use global types under types/ or local types under agentic-systems/types/. Frontmatter-free Markdown is text.

  • Sources: tracked ingests, never snapshots; derived-from, evidenced-by, see-also.
  • External: evidence used, preferably version-pinned; do not prospect the open web; evidenced-by, see-also.
  • Notes: theory mappings; rests-on, defined-in, rare is-evidence-for, see-also.
  • Agent-memory systems: related subsystem accounts; contains, part-of, compares-with, see-also.
  • Local retained analyses: supporting overview/member/record; see-also.
  • Reports: separately retained evidence; evidenced-by, see-also.
  • Reference: direct Commonplace analogues; see-also.
  • Instructions: directly mapped procedures; procedure, see-also.
  • Method links: composition/conditions/targets; composition, precondition, invokes, applies-when, operates-on, rests-on, see-also. Reviews, archives and workshops are not method execution inputs.