Writing conventions for kb/agentic-systems/
Text contract
This collection covers external agentic systems and harnesses as whole systems — execution loops, orchestration APIs, sub-agent surfaces, scheduling, permissioning, and control — what each is built from and does. Analyses use Commonplace ontology to name comparable mechanisms while preserving the external system's native operation and evidence.
The quality goal is fidelity + economy: faithful to what the system actually does, in the minimum shared vocabulary needed to explain it. An analysis that misrepresents the analysed system or forces a mechanism into an ill-fitting Commonplace term is worse than none.
Memory and knowledge are lenses of the whole-system analysis. The separate
kb/agent-memory-systems/ collection is the legacy review corpus; new comparison
procedures consume the main analysis and its memory/context findings directly.
The analyse-agent-memory sub-agent returns a typed specialist report within
the parent run. The parent resolves its findings into the main result; the
specialist report does not supply comparison inputs or independent semantic
clearance.
Structure
The collection root is reserved for collection-level operating material:
README.md, COLLECTION.md, and meta-document directories such as types/.
Per-system and per-feature analyses live under reviews/ so the growing
analysis corpus does not obscure those operating documents. Generated cross-system
matrices and tables live under comparisons/.
Generated reviews
Every complete analyse-agentic-system run publishes one compact review in the
reviews/ directory. Each file records generated-by: analyse-agentic-system,
the producing analysis-run, a stable source-identity, and the
reviewed-revision, and the retained analysis-result path and
analysis-result-sha256. They are workflow-owned projections of a frozen analysis,
not hand-authored notes. Do not substantively hand-edit them. Correct the source
boundary or the shared review method, then rerun the skill and replace the
review from those inputs. Git history preserves earlier generated versions.
Publication cannot be waived per complete analysis. The workflow validates a
private candidate as its intended destination before replacing the review. A
correctable pre-publication failure leaves the incumbent unchanged and the run
open. The complete run state is the sole declaration that publication
succeeded.
This regeneration rule keeps system-specific judgment inside one declared method. A human may change the method and request a new run, but may not tune one published review independently and still present it as a generated review. Unmarked per-system and per-feature analyses remain ordinary authored artifacts.
Publication retains the exact result bytes under
kb/reports/retained/agentic-system-analysis/<run-id>/result.md. The public
review pins this immutable copy; comparison readers need neither ignored run
state nor the legacy corpus to reproduce its fields. Correct or enrich the
analysis through a new run, never by hand-editing its retained copy.
Evidence basis
Open each analysis with a one-line evidence basis: what it is grounded in — docs, source code, papers, or first-hand operation of the system — and when that evidence was captured. Comparison readers use the exact result's evidence-tier: code-grounded or doc-grounded. Keep those populations separate, and preserve each field's evidence basis within its tier.
Ontology and local transfer
State the external mechanism in its own operational terms before applying a Commonplace concept. Explain why the concept fits and qualify partial or unresolved mappings. Commonplace chooses the analytical distinctions; it is not the comparison target, and a reader must be able to reject a mapping without losing the external-system account.
Describe a theory pathway through the conditions of a
theory builder: localized content,
consumption, criticism of that content, and iteration, where the result of
criticism shapes the next round. Each condition holds only at the
strength supported by its own evidence. Improved capacity for future action
attributable to that criticism is a separate learning claim. Persistence
(within an episode, a run, across runs, or across problems) is a separate
graded finding above condition 4's minimum. Addressability is a separate
graded finding above condition 1's minimum. Record its degree and boundary; whole
replacement, or reconstruction from retained criticisms, can qualify, while
stored rules or parameters alone do not classify the process. Missing
historical rationale does not establish absent criticism; inaccessible model
processing remains unestablished. Reflection additionally requires a
causally connected self-representation of selected aspects inside the
declared system boundary: changes in those aspects can update the
representation, and operations mediated through it can affect later
behavior. Link the defining notes with rests-on or defined-in.
Current differences from Commonplace, borrowable ideas, and watch items are not part of the durable analysis. They depend on a current Commonplace baseline and interest brief. Produce them, when separately requested, as living transfer state under kb/reports/state/agentic-system-transfer/; never feed that scan back into the stable analysis or a public corpus comparison. Keep unresolved candidate judgments until disposition, then replace or delete the state report under its owning workflow.
Title conventions
- Descriptive coverage of one system or feature — name the system (
claude-code-dynamic-workflows.md). - Argumentative analyses — analyses asserting a specific claim — use a claim-shaped title and the
title-as-claimtrait, followingkb/notes/COLLECTION.mdconventions.
Outbound linking conventions
Organised per destination; label semantics in link-vocabulary.md.
- →
kb/sources/— link the tracked ingests an analysis is grounded in, never the local snapshots. Labels:derived-from,evidenced-by,see-also. - →
external— cite the source code, documents, papers, or first-hand records already used for the evidence basis; prefer version-pinned targets when available and do not prospect the open web. Labels:evidenced-by,see-also. - →
kb/notes/— search when an analysis maps a system onto theory. Userests-onwhen the theory explains the analysed design; use rareis-evidence-forwhen the observed system instead bears on the target claim. Promote a novel transferable claim tokb/notes/rather than author theory here. Labels:rests-on,is-evidence-for(rare),defined-in,see-also. - →
kb/agent-memory-systems/— when the analysed whole system has a memory, knowledge, or context-engineering subsystem reviewed there. Usecontainsfrom the whole-system analysis to the subsystem review; usepart-ofonly from a subsystem-focused analysis back to the whole system. Labels:part-of/contains,compares-with,see-also. - →
kb/reports/retained/— cite the exact main-analysis result when a comparison needs its full records, evidence, or normalized fields. Labels:see-also. - →
kb/reference/— scan when a design element has a direct Commonplace analogue. Labels:see-also. - →
kb/instructions/— link a Commonplace procedure when the external system analysis directly maps onto an operating rule or workflow. Labels:procedure,see-also.
Type eligibility
A typed artifact in this collection may use a global type, named by its path under the library root such as type: types/note.md, or a local type spec under this collection's types/ directory, named by its path under the KB root such as type: agentic-systems/types/<name>.md. Frontmatter-free Markdown is implicit text.
What does NOT belong here
- Transferable claims about KB methodology or orchestration theory →
kb/notes/ - Raw captures of external sources →
kb/sources/.snapshots/, each analysed by a tracked ingest inkb/sources/ - Descriptions of the Commonplace system itself →
kb/reference/ - Current Commonplace differences, borrowable ideas, and watch items → a selective transfer scan under
kb/reports/state/agentic-system-transfer/ - Procedures and how-to guidance →
kb/instructions/ - Work in progress →
kb/work/