Brief: project-knowledge rules ("agentic engineering manifesto")

Goal

Every project, repo or subproject, follows one set of rules that keeps its knowledge agent-usable and its "done" provable:

rule	lives in	purpose
QA	`QA.md` at the project root	how to run checks; how to tell the result makes sense
current architecture	`docs/architecture.md`	how the system is now
decisions	`docs/adr/NNNN-slug.md`	changes from the architecture baseline onward
papercuts	`docs/papercuts/slug.md`	friction hit by agent or human
writing style	`docs/style.md`	dense; diagrams and schemas over prose
small linked tagged docs	`docs/**` + `docs/tags.md`	one concept per file, controlled tag vocabulary
freshness	frontmatter `code:` refs	docs point at code; change code → update doc in the same commit

Premise: strong models follow short rules well. Text gets most of the way; a small checker covers the rest.

Deliverables

Manifesto repo/site (new, not part of aesop). A garden of small pages, not a blog. Published like aesop (GitHub Pages + llms.txt). Dogfoods its own rules: small tagged files, its own ADRs and papercuts. Holds: one principle page per rule, the catch-up prompt, the scaffold, a versioned rules text.
Python template: ships the AGENTS.md rules section + scaffold.
Existing repos: a hosted catch-up prompt, pasted into an agent session. It reads the version marker → full adoption or upgrade.
Checker tool (later): see Tooling.

Files in this bundle

AGENTS-section.md        rules text, inlined into each repo's AGENTS.md (version marker on line 1)
catch-up-prompt.md       adoption/upgrade prompt for existing repos
manifesto/
  qa-principles.md       principle page: QA (the only page written so far)
scaffold/                copied into target repos as-is
  QA.md                  template; tiers + expect live in frontmatter
  docs/README.md         index
  docs/architecture.md   template: diagram, component table, invariants
  docs/style.md          writing rules
  docs/tags.md           seed vocabulary
  docs/adr/0000-template.md
  docs/papercuts/_template.md

Moved since: manifesto/qa-principles.md → content/principles/qa.md, AGENTS-section.md → content/rules/v1.md, catch-up-prompt.md → content/catch-up.md, scaffold/ → scaffold/. Current layout: architecture.

<MANIFESTO_URL> was a placeholder; it is now https://mojzis.github.io/clauding (ADR 0010).

Decisions made

Separate repo from aesop. aesop = tools that enforce; manifesto = conventions agents read. aesop links to the manifesto. aesop's principle-style content may move over (undecided).
Rules are inlined in each repo (they're short) with a version marker and a link for the rationale. Copy plus marker beats fetching at runtime.
No backfilled ADRs. Missing architecture.md → write it from the code as the baseline; ADRs start from there. Accepting an ADR means updating architecture.md in the same change.
Docs → code links only, as path::Symbol in frontmatter code:. One direction, checkable.
Controlled tag vocabulary in docs/tags.md (the braindump idea: show existing tags when adding).
QA has three questions: did I run the right thing (tiers), did it actually run (expect: floors, skip lists, duration range), does it make sense (oracles). Oracles: reference cases, invariants, bounds with units, diff vs main (explain every diff), negative control. Agents propose oracles (proposed); only humans confirm. An explicit "not evidence" list. Every task ends with a QA report.
Catch-up never invents: it runs QA tiers and records only what it observed, writes architecture only from verifiable code, and logs failures as papercuts without fixing them.
QA.md sits at the project root, not in docs/. It's operational, like the README.

Tooling

Markdown is the only source of truth. The tool is a disposable view over it. - No stored index. Parse on every call; repo docs are small. Agents and humans edit files directly, so any index would go stale. - Zero-install CLI (uvx), with a guide subcommand, same pattern as aesop tools.

command	does	priority
`check`	`code:` refs resolve (path + symbol); relative links resolve; tags in vocabulary; frontmatter present; size limit; accepted ADR ⇒ architecture.md touched in the same commit	1
`qa run <tier>`	run the tier from `QA.md` frontmatter, parse the summary, compare to `expect`	1
`touching <paths>`	docs whose `code:` covers the given paths; for the staged diff in a commit hook	2
`tags`	vocabulary with usage counts	2
`links` / `orphans`	backlinks; unlinked files	3
search	don't build; agents use ripgrep	—

Open questions

Repo and site name. Whether the checker lives in aesop or next to the manifesto.
Large repos: architecture.md will exceed ~150 lines and should become an index plus per-component files. Write that as an ADR once it actually happens.
Data pipelines: reference cases need small, realistic, commit-safe fixtures. Do they exist, or is producing them part of adoption?
Exact QA.md frontmatter schema (keys, units) before the tool depends on it.
Papercuts: keep fixed ones (current default) or delete them.

Suggested build order

Manifesto repo: move manifesto/ + scaffold/ + rules + prompt in. Write the remaining principle pages in docs/style.md style (architecture, adr, papercuts, docs & tags, freshness). Add an llms.txt and publish.
Write the repo's own first ADRs for the decisions above. These are real ones, made now.
Put the scaffold + rules section into the Python template.
Pilot the catch-up prompt on one existing repo. Log what went wrong as papercuts on the manifesto and revise the prompt.
Checker: check + qa run, then touching in a commit hook.

raw markdown