crickets conventions - alexherrero/crickets GitHub Wiki

Note

LAUNCHED (lifted 2026-06-24, AG Phase 3; originally approved 2026-06-23) Β· locked 2026-06-28 (final AG design sweep). child-design β€” the conventions capability (the base set of standards a plugin consumes before opinions weigh in). status: launched (lifted into tracked wiki/designs/ 2026-06-24, AG Phase 3). Points up at the crickets HLD.

conventions

Objective

conventions is the base set of standards a plugin consumes directly β€” before any opinion weighs in. They are objective, house-standard facts a tool reads and acts on with no judgment call:

  • bump the version when a primitive changes;
  • set up CI on a new project;
  • run the gate battery before every commit;
  • a skip needs a named blocker;
  • keep state on disk.

Each enforceable convention is backed by a deterministic gate (scripts/check-*.sh) β€” shipped, or gate-targeted ([PENDING-IMPL]) when a newly-folded rule's gate isn't built yet. That gate, present or pledged, is what makes it a convention and not an opinion. Conventions are the substrate the agentm opinions cite, and the arrow runs one way: opinions, personas, and workflows read conventions; conventions never ask an opinion.

Overview

conventions is an extensible shell holding base-standard domains in three shapes β€” rules (enforceable, gate-backed), skills (practice), and reference (objective house facts) β€” detailed under Design. The domains:

Domain Holds Status
testing tests-are-sacred Β· verification-first Β· the 3-layer pyramid Β· no-skip-tests (rule shipped; check-no-skip-tests.sh gate [PENDING-IMPL]) delivered
releasing ship-release Β· version-bump-required Β· changelog + paired-release discipline delivered
ci always set up CI Β· check-all.sh is the source of truth Β· run-the-battery-before-commit Β· add-new-checks partial
code-quality evidence-to-flip-a-task Β· no-change-detector tests Β· design-conformance (the seam invariants) Β· BeyoncΓ©-rule Β· simplicity-first Β· skill-quality + check-slop (the skill-shape gate, [PENDING-IMPL]) partial
agentic-engineering phase-gated sessions Β· state-on-disk Β· single-threaded + read-only fan-out Β· the PLAN.md shape Β· wake-on-CI Β· no-parallel-implementers Β· the single-cycle shape (cooldown-gated Β· cursor-backed Β· idempotent Β· opt-in Β· surface-don't-adopt) partial (mostly homeless today)
reliability deterministic-checks-gate-LLM-judgment Β· prefer-deterministic-over-agentic verification Β· resolve-don't-cache-paths partial
coding the day-to-day base (naming Β· error-handling Β· structure) under testing + quality β€” no home today new
documentation the DiΓ‘taxis structure (four modes Β· single-mode-per-page Β· intent-group layout Β· length ceilings Β· naming) β€” enforced by wiki's check-wiki.py partial

The conventions hub: phase workflows probe it by name through the resolver and personas lean on it, while opinions cite it one-way; its rules are enforced by the check-all.sh gate battery, and it cites β€” never re-owns β€” the standards held by developer-safety, privacy, maintenance, and code-review

Consumers (workflows, personas) read conventions by name through the resolver; opinions cite it one-way (it is their substrate); its rules are enforced by the check-all.sh gate battery β€” the can't-forget floor; and it cites, never re-owns, the standards held by developer-safety / privacy / maintenance / code-review.

Design

The line β€” conventions vs opinions

A convention is an objective, house-standard fact a plugin reads and acts on with no judgment ("bump the version on any primitive change"; "a skip needs a named blocker"; "tests are a 3-layer pyramid"). An opinion is an agentm stance asked for by name that requires judgment (done / good / efficient / how-we-engineer).

Conventions are what an opinion cites: the done opinion is literally "the check battery + the written conventions for shape." So an opinion is the named question ("is this done?"); conventions are part of the deterministic answer it cites. One convention can be cited by several opinions; an opinion cites conventions across domains. The arrow is one-way: conventions stay dumb and objective, consumed directly (crickets-side); opinions are the judgment surface on top (the agentm pillar).

The three shapes

Shape Path What it is How it holds
rule rules/<name>.md an enforceable standard β€” trigger condition Β· "what is NOT a bypass" table Β· enforcement checklist (the no-skip-tests / version-bump-required template) names its scripts/check-*.sh gate (shipped or [PENDING-IMPL]) β€” the gate is what makes it objective and un-forgettable
skill skills/<name>/SKILL.md standing day-to-day practice prose consulted by the workflow; owns the practice, not the audit (that's code-review's testing-strategy)
reference reference/<name>.md objective house facts (the gate-battery inventory, the features.json schema) the rules cite objective facts only β€” cited, not gated; subjective tradeoff knowledge is excluded (below)

Cite, don't duplicate

conventions holds the objective, gate-backed, house-standard conventions and migrates in the homeless ones (the agentic-engineering harness discipline, the ci-battery rules, the no-change-detector quality rule, the coding base). It does not re-own a standard another capability already owns β€” it cites it:

  • the recoverability gate is developer-safety's.
  • the deterministic PII / secret scan is privacy's.
  • dependency repair is maintenance's.
  • the adversarial-review contract is code-review's (the good opinion's framing) β€” a judgment stance, not a gate-backed convention, so it stays there.

The domains

  • testing (delivered) + releasing (delivered) β€” the two existing plugins, folded in (Migrations). Consumed by /work + /release and code-review's testing-strategy.
  • ci (amended β€” per-plan CI) β€” check-all.sh remains the single source of truth for "green"; the rules: always set up CI on a new project Β· run the battery before every commit Β· add a new check to the battery as the project grows. The both-places consistency is mechanically enforced β€” scripts/test_ci_consistency.py (itself a battery test) fails if a battery gate is missing from the Linux workflow or a toolchain gate from any of the three OS workflows, and the aggregate ci-all.yml couples to the three OS workflows by filename (a rename trips the test). The gate inventory is a reference/ doc. The full 3-OS matrix + ci-all now fire on pull_request, not on push to main. A push directly to main (a merge landing) runs, at most, a light lint/typecheck smoke job β€” not the full matrix; the PR that produced the merge already ran the full matrix as a required check before GitHub allowed the merge, so re-running it post-merge is redundant work, not redundant safety. Branch protection (ADR 0029, unchanged) requires the check-all.sh-backed PR check green before merge is even offered. The docs/wiki-only diet does not carry forward onto the pull_request trigger as-is β€” a trigger-level paths-ignore would mean a docs-only PR's required check never fires, and a required check that never reports blocks that merge forever (demoting it to non-required would let code PRs skip it instead). Every PR gets the full matrix for now; the diet's docs-only fast path re-lands as a job-level no-op inside ci-all (diff-aware, not trigger-aware) under PLAN-per-plan-ci β€” filtering moves from "does this trigger fire" to "does this job actually run once it has." development-lifecycle's wake-on-CI cadence becomes wake-on-PR-checks: /work waits on the PR's check-suite instead of a bare push's; the pipelined one-task-lag cadence (2026-07-05 amendment) still governs when it's consulted, unchanged in shape. wiki-sync.yml is unaffected β€” it was never part of the test matrix and stays push-triggered. Nightly main-HEAD backstop (lands with PLAN-per-plan-ci): a scheduled workflow reruns the full matrix against main HEAD independent of any PR, advisory-only β€” the drift-between-merges catch that push-triggered CI used to provide for free; agentm's existing health-nightly.yml (a different, heavier functional-quality tier) gets this wired into its scorecard render, crickets gets the workflow fresh. Consumed by every pre-commit and by maintenance's CI-repair.
  • code-quality (partial) β€” evidence-required-to-flip-a-task, no-change-detector tests, design-conformance to the seam invariants (import-direction, no-Path-leak, one-port), the BeyoncΓ©-rule, simplicity-first. Each is gate-backed (check-*.sh) or a skill. Consumed by /review and the Tech-Lead persona.
  • agentic-engineering (partial β€” mostly homeless) β€” the harness discipline: phase-gated sessions, state-on-disk-not-conversation, single-threaded implementation with read-only sub-agent fan-out, the PLAN.md shape (locked design calls + narrative Status), wake-on-CI, no parallel implementers. Today these live only in AGENTS.md / principles.md / CLAUDE.md; they migrate in. Consumed by every phase workflow and every persona.
    • The single-cycle shape (named 2026-07-06). A background primitive built to run often and cheaply when there's nothing to do: cooldown-gated (a cursor + a per-item marker decide what's due, so a repeat call this soon is a cheap no-op); cursor-backed (progress lives in a local, non-synced marker β€” never in memory, never re-derived); idempotent (a crashed or re-fired cycle re-runs whole safely, because the cursor and the dispatched-set make repetition harmless); opt-in (nothing runs until an operator or a job manifest turns it on); surface, don't adopt (the primitive reports what it did; a caller decides what to do with the report, the primitive never acts unilaterally beyond its own scope). Two independent implementations share this shape: wiki-watch's one-cycle drift-detection pass (crickets), and the agentm runner's job-manifest cycle (agentm, built 2026-07-06) β€” named here so the two read as one documented pattern, not two coincidentally-similar mechanisms invented twice.
  • reliability (partial) β€” deterministic-checks-gate-LLM-judgment, prefer-deterministic-over-agentic verification when both achieve the same thing, resolve-don't-cache vault paths. Consumed by the gate battery and the good opinion.
  • coding (new) β€” the general day-to-day base (naming, error-handling, structure) that sits under testing + quality and has no dedicated home; the umbrella skill for the expanded shell. Consumed by every /work session.
  • documentation (partial) β€” the DiΓ‘taxis structure: every page is exactly one of four modes (tutorials Β· how-to Β· reference Β· explanation), single-mode-per-page, with length ceilings and a naming style. The tree is the fixed six-section frame in fixed order β€” How-to Β· Reference Β· Architecture Β· Designs Β· Explanation Β· Operational β€” with two conditional sections (Architecture on a wiki/architecture.yml declaration; Operational on audience/visibility). The naming rule: every page basename is unique across the tree case-insensitively; when a user-facing page and a design page collide, the user-facing page owns the clean name and the design page takes a -design suffix (check-wiki rule (g)). Index/landing pages (<!-- mode: index -->) are shape-exempt from the single-mode rule. The objective structure standard lives here; wiki consumes and enforces it β€” check-wiki.py is the gate (mode Β· length Β· vendor Β· structure), its templates and diataxis-author skill author against it, and a per-repo .diataxis-conventions.md can override. The prose voice is a separate agentm opinion (subjective, learned), not a convention.

Opinions β€” conventions are the substrate they cite

conventions consumes no opinion; it is the inverse β€” the deterministic substrate the opinions point at. done = the check battery + these written shape conventions; good cites testing + code-quality; how-we-engineer cites agentic-engineering + ci; efficient cites the objective performance gates. The arrow is one-way β€” opinions read conventions; conventions never ask an opinion. (The subjective tradeoff knowledge an opinion adds β€” language choice, platform tradeoffs, per-language performance tuning β€” lives in the Opinions pillar or learned memory, not here: it is contextual judgment that decays, not a house standard.)

The extensible shell

One conventions plugin, domains as sub-folders:

src/conventions/
β”œβ”€β”€ group.yaml          # requires: [development-lifecycle] Β· capabilities: [conventions]
β”‚                       #   (resolver-aliases the old testing-conventions + releasing-conventions)
β”œβ”€β”€ rules/              # enforceable β€” each names a check-*.sh gate
β”‚   β”œβ”€β”€ no-skip-tests.md
β”‚   β”œβ”€β”€ version-bump-required.md
β”‚   β”œβ”€β”€ always-setup-ci.md
β”‚   └── …
β”œβ”€β”€ skills/             # standing practice
β”‚   β”œβ”€β”€ testing-conventions/
β”‚   β”œβ”€β”€ ship-release/
β”‚   └── coding/
└── reference/          # objective house facts the rules cite
    β”œβ”€β”€ gate-inventory.md
    └── …

Adding a domain = drop a rules/ file (+ its check-*.sh gate), a skills/ folder, or a reference/ doc, then bump the version β€” no new plugin, no new wiring.

How others call it in

A consumer β€” a command, skill, persona, or opinion β€” reaches conventions the one-way way everything reaches a capability: by name through the resolver (find_capability β†’ capability_resolver.py, version-matched, graceful-skip), then reads the relevant domain's rules / skills / reference. The harder problem is making sure a consumer doesn't forget β€” handled in two tiers:

  • Gate-backed conventions can't be forgotten. Every rule names a scripts/check-*.sh gate, and the gate runs in the check-all.sh battery at every commit β€” independent of whether any plugin remembered to consult it. A violation fails the commit, not a code review. (The ci convention "run the battery before every commit" is what closes this loop.) This is the strong floor.
  • Practice + reference conventions are surfaced, not just available. A skill / reference standard has no gate, so a consumer must read it β€” and a standard nobody reads is dead. So the applicable conventions are surfaced at the point of work: each phase workflow consults its domain (/work reads coding + testing, /release reads releasing). The set a project is governed by is surfaced at session start β€” the pattern the always-load memory already uses. A consumer declares the conventions it depends on, and the Phase-2 conformance gate can check that a plugin which should consult one actually declares it β€” so "forgot to call conventions" becomes a gate finding, not a silent gap.

The principle: prefer the gate. A convention that can be made gate-backed should be β€” the battery is the only mechanism that survives forgetfulness; surfacing is the fallback for the genuinely judgment-shaped ones.

Dependencies

  • requires development-lifecycle β€” /work, /review, /release run the rules + skills.
  • consumed by the phase loop, code-review (the testing-strategy audit draws on the testing standard), wiki (enforces the documentation convention via check-wiki.py), the personas (Engineer / Reviewer / Maintainer / Tech-Lead lean on it), and the opinions (which cite it β€” the inverse clause above).
  • cites, does not own β€” developer-safety (recoverability) Β· privacy (the PII scan) Β· maintenance (dependency repair) Β· code-review (the adversarial contract).
  • Points up at the crickets HLD; the requires/enhances mechanics are in crickets-composition.

Migrations

Two structural lifts at the Phase-3 / v6.0 pass:

  1. Merge β€” testing-conventions + releasing-conventions consolidate to one src/conventions/, the group.yaml merges, and capabilities: [conventions] replaces the two transitional declarations (the merged group declares both the old and new capability names, so the old ones keep resolving β€” the composition rename mechanism). The four existing primitives don't change.
  2. Migrate the homeless conventions in β€” the objective base standards that live only in AGENTS.md / principles.md / ~/.claude/CLAUDE.md (the agentic-engineering discipline, the ci-battery rules, the no-change-detector quality rule, the coding base) become standalone rules/ + skills/; AGENTS.md keeps a pointer, conventions owns the standard. The cite-don't-duplicate boundary keeps it from re-owning what developer-safety / privacy / maintenance / code-review already hold.

Risks & open questions

  • The line is the standing risk β€” a convention must be objective and (ideally) gate-backed; a judgment stance is an opinion. Grey-zone principles (simplicity-first, adversarial-review-assumes-bugs) resolve by the rule: gate-backed β†’ conventions; pure judgment-framing β†’ the opinion.
  • Subjective knowledge-refs are explicitly OUT β€” language-selection, platform-selection, per-language performance tuning belong in the Opinions pillar or learned memory (contextual, decaying); putting them behind a gate would be a category error.
  • The de-dup must hold β€” conventions cites, never duplicates, a standard another capability owns; a re-owned convention drifts from its source.
  • The reference/ shape is new β€” objective house facts only; the rules cite it, no gate enforces a reference doc.
  • self-correction-loop is not a conventions concern β€” the evaluateβ†’gradeβ†’re-run improvement loop is the agentm Experience β†’ Opinions loop (agentm Opinions), not a gate-backed standard; conventions only folds in the skill-shape gate (skill-quality + check-slop).
  • Re-audit triggers: land the merge + the homeless-migration at the Phase-3 lift; add the reference/ shape; confirm each new rule names its check-*.sh gate; ship check-no-skip-tests.sh + a check-conventions-cite-not-duplicate portfolio lint (fails on a standard duplicated rather than cited β€” the structural boundary the residual bucket rests on); keep the subjective knowledge-refs routed to opinions/memory.

References

  • crickets src/testing-conventions/ + src/releasing-conventions/ (live; β†’ src/conventions/) β€” rules (no-skip-tests, version-bump-required) Β· skills (testing-conventions, ship-release)
  • Homeless conventions to migrate in: agentm AGENTS.md (the non-negotiables) Β· harness/principles.md (the seven principles) Β· ~/.claude/CLAUDE.md (the dev-flow conventions); the gate inventory = scripts/check-all.sh + wiki/reference/CI-Gates.md
  • Standards it cites (not owns): developer-safety Β· privacy Β· maintenance Β· code-review
  • Up: crickets HLD Β· composition Β· agentm Opinions (which cite conventions)

Amendment log

2026-07-23 β€” releasing domain: ship-release gains an HLD-update close-out check (Loose Ends arc, "Release and generator polish" task 1); this doc's own governs: glob corrected. Standing gap named by a FOLLOWUPS entry filed at Plan #18 (2026-05-26, still open as of 2026-07-14): a release could change architecture β€” new/removed primitive kind, a generator-behavior change, anything a living design should reflect β€” and ship without that design ever being checked, and nothing caught it. ship-release/SKILL.md gains pre-release checklist item 9; development-lifecycle's /release command gains the matching constraint 10 + Process step 4c (Hook 7 in that design's own hook-numbering sequence). Both key off the plan's existing touches_architecture: self-report (already wired since Hook 3's /plan-time grounding gate) rather than inventing a new architecture-changed heuristic β€” the new step fires on the flag alone, catching what the existing parent_design_doc divergence check (Hook 5, constraint 4b) structurally can't: architecture changed and no design was ever cited at all β€” 4b only ever catches a design that was cited and then drifted from a locked call. Why not fold this into coalescence-gate's seven-item checklist as an eighth item: that checklist is deliberately arc-closing-conditional (its own "What is NOT an acceptable shortcut" table treats the set as fixed, and it only fires when a release closes an arc); this check needs to fire on every touches_architecture: true release, not just arc-closing ones, so it lives in release.md's unconditional Process instead β€” coalescence-gate.md gets a one-line See-also cross-reference, not a member of the seven. Why not CONTRIBUTING.md (the FOLLOWUPS entry's third checked-and-found-absent location): that file is contributor-onboarding scoped (authoring a plugin, testing locally, commit messages) with no release section today β€” the mechanism belongs in the files that actually drive a release. Aside, same landing: this design's own governs: frontmatter glob was found stale mid-plan β€” still naming the pre-merge src/releasing-conventions//src/testing-conventions/ directories from before the AG Wave A merge into src/conventions/ (2026-06-23, this log's own bottom entry), so find_governing_design.py was silently falling through to the parent HLD's broad src/** fallback for anything under src/conventions/. Corrected to governs: [src/conventions/]. Re-audit trigger: if a mechanical "did this release change architecture" detector is ever built (replacing the plan-author's touches_architecture: self-report with something that inspects the diff directly), revisit whether the self-report step here is still needed or can retire in its favor.

2026-07-06 β€” ci domain: per-plan CI, the matrix moves from push to pull_request (operator-ratified 2026-07-06; ROADMAP-MASTER Β§ Ratified 2026-07-06; adjudicated via the W1 verdict memo + Fable judgment pass; PLAN-worktree-native-flow / PLAN-per-plan-ci). The full 3-OS matrix + ci-all now trigger on pull_request; a push to main runs at most a light lint job. Branch protection requires the PR-triggered ci-all check green before merge. The docs/wiki-only paths-ignore diet is intentionally not carried onto the pull_request trigger in this wave β€” a trigger-level skip on a required check means a docs-only PR's check never reports, which blocks that merge forever (a bug the Fable judgment pass caught before it shipped). Every PR runs the full matrix for now; the diet returns as a job-level, diff-aware no-op inside ci-all under the follow-on PLAN-per-plan-ci. Wake-on-CI becomes wake-on-PR-checks. wiki-sync.yml is unaffected (rider 4, Fable pass) β€” it was never the test matrix. A nightly main-HEAD full-matrix backstop (advisory-only) lands with PLAN-per-plan-ci, closing the gap that push-triggered CI used to cover for free. Why not carry the paths-ignore diet forward unchanged (the original draft's assumption): GitHub can't express a required check that sometimes doesn't run β€” the trigger-level filter and the required-check contract are mutually exclusive until the filter moves to job level. Re-audit triggers: the job-level diet ships in PLAN-per-plan-ci (this bullet's "every PR runs the full matrix for now" language should then be corrected); GitHub ships a native way to make a trigger-filtered check merge-transparent.

2026-07-06 β€” named the single-cycle shape in agentic-engineering (AG Wave B leader 1/5, the agentm runner's own Migrations bullet). wiki-watch's one-cycle drift-detection pass and the newly-built agentm runner's job-manifest cycle independently converged on the same shape (cooldown-gated Β· cursor-backed Β· idempotent Β· opt-in Β· surface-don't-adopt) without either citing the other. Named it here so future background primitives have one documented pattern to point at instead of re-deriving it. Why not leave it un-named: two coincidentally-similar mechanisms invented twice is exactly the homelessness this domain exists to fix. Re-audit trigger: a third independent implementation surfacing a shape variant this description doesn't cover.

2026-07-05 β€” ci-battery path-filter: docs/wiki-only diffs skip the 3-OS matrix + ci-all (PLAN-ci-walltime-diet task 3). Generalizes the existing wiki-sync.yml paths: [wiki/**] precedent (previously scoped only to that one workflow) into a named rule for tests-{linux,mac,windows}.yml + ci-all.yml: a push confined to wiki/** + *.md is docs-only and self-skips the matrix. Evidence (2026-07-03..05, agentm+crickets): 9-32% of pushes in-window touched zero code paths yet still ran the full matrix β€” 60 wasted workflow runs across both repos in a single 2-day window. The guard is deliberately conservative: any file outside wiki/**/*.md counts as code, full stop β€” a diff mixing one code file with 500 doc files still runs the full matrix. Cites development-lifecycle's 2026-07-05 pipelined wake-on-CI cadence amendment for when /work consults this gate; this entry only owns the gate rule itself, per the cite-don't-duplicate boundary this domain already states about itself.

Why not a broader doc-extension allowlist: the conservative two-pattern rule already covers the evidence window's docs-only share; a broader allowlist (e.g. other markup/config formats) raises the guard's surface for a fixture to prove exhaustively, for a savings the evidence doesn't currently justify.

Re-audit triggers: a future language/format is added under wiki/** that isn't itself documentation (e.g. a generated script checked into wiki/) β€” revisit the glob; or the docs-only share of pushes grows enough that a broader allowlist's savings would clearly outweigh its guard-surface cost.

2026-06-30 β€” Decisions section retired: six-section taxonomy (the ADR-0020 re-audit trigger fired). With the ADR model retired and decisions living in design amendment logs, the decisions/ section is universally empty β€” the exact "drop it" case ADR-0020 (below) named as its re-audit trigger. The documentation domain body now reads a fixed six-section frame (How-to Β· Reference Β· Architecture Β· Designs Β· Explanation Β· Operational; Architecture + Operational conditional, the other four always present). wiki_init.py's DEFAULT_SECTIONS, check-wiki's _FOLDER_MODE + the accepted-ADR rule (f), the documenter / migrate.py ADR-routing, and the project templates drop decisions/ in the same pass; agentm + crickets delete their (already-empty) wiki/decisions/ tombstones. Why not keep the slot: a permanently-empty always-present section is drift that re-scaffolds itself. Re-audit trigger: a durable decision-artifact class with no living-design home (re-add a section); a host that reintroduces the ADR model as the default.

2026-06-28 β€” lock-down sweep + voice pass (operator review). Converted the relationship mermaid to a house-style hand-SVG (diagrams/crickets-conventions.svg); and did a voice pass to the current design-doc standard β€” fixed the one LLM-tell (first-classβ†’standalone) and split the longest run-on sentences into one-claim sentences (the doc was otherwise on-standard: active voice, colon-led lists, no peacock words). No change to the conventions contract. Locked as a v5–v8 guidepost.

2026-06-28 — AG critique revisions (W6 · R4 · R10). Demoted the gate thesis to gate-backed OR gate-targeted and marked no-skip-tests's check-no-skip-tests.sh gate [PENDING-IMPL] (W6); named the residual-bucket's structural boundary — a check-conventions-cite-not-duplicate portfolio lint (fails on a standard duplicated rather than cited) — in the re-audit triggers (R4); folded skill-quality + check-slop into the code-quality domain as the gate-targeted skill-shape gate, and scoped self-correction-loop out as the agentm Experience→Opinions loop, not a convention (R10). Re-audit: ship check-no-skip-tests.sh + the cite-not-duplicate lint.

2026-06-24 β€” subsumed continuous-integration.md + wiki-section-taxonomy.md (AG Wave 2, move-and-retire). Two superseded designs whose still-live convention substance lands here; both deleted (git history retains the full PRD text + part files). The two C4-folded ADRs they had absorbed (AG Phase-2) are preserved below with decision + why-not + re-audit; the seven-section frame is also reflected in the documentation domain body, and the ci-consistency mechanism is noted in the ci domain.

  • ADR 0021 β€” per-plugin marketplace versioning sourced from group.yaml (2026-06-11). Each plugin owns a version: in its src/<slug>/group.yaml (parsed by src_model.Group, written by both emitters into plugin.json + the Claude marketplace entry), replacing the frozen PLUGIN_VERSION="0.1.0" constant that made claude plugin update a permanent no-op. Anti-recurrence gate check-version-bump.py fails when src/<slug>/** changed vs the base ref without a strict SemVer increase (content diffed from merge-base, version vs base tip, graceful-skip when the base is unresolvable); wired into check-all.sh + CI. This is the decision record behind the version-bump-required rule. Why not the repo-level pin / one global version / a side registry / trust-the-author / mere-inequality: the pin is the bug; a global version couples unrelated plugins into spurious churn; a registry is a second source to drift; author vigilance isn't a gate; inequality admits downgrades + garbage. Re-audit trigger: Claude changing the update trigger (content-hash), the publish model moving off dist/-on-main, or Antigravity shipping a version-driven agy plugin update.
  • ADR 0020 β€” seven-section wiki taxonomy: fixed frame + per-project Architecture manifest + conditional gates (2026-06-11). A fixed seven-section frame in fixed order β€” How-to Β· Reference Β· Architecture Β· Designs Β· Explanation Β· Decisions Β· Operational β€” scaffolded by wiki_init.py's DEFAULT_SECTIONS, allow-listed by check-wiki's _FOLDER_MODE; supersedes-in-spirit the intent-folder IA (ADR 0018) while keeping its nearest-_Sidebar.md + two-level reachability. Two conditional sections: Architecture renders on declaration (a wiki/architecture.yml manifest of components: {slug,title,summary,overview} + optional pillars: toggles; the generator scaffolds architecture/<slug>/ + a landing and renders a third sidebar nesting level, validated + fail-closed), and Operational renders on audience/visibility (public wikis suppress it), not per-page sensitivity. Why not per-repo improvised folders / DiΓ‘taxis-type-only / hard-coded architecture / always-present sections / sensitivity-gated Operational: improvisation drifts with no source of truth; DiΓ‘taxis modes don't cover Architecture/Designs/Decisions/Operational; a hard-coded architecture list is wrong for every repo but one; stub sections are noise; sensitivity is the per-page PII gate's job. Re-audit trigger: a recurring doc type with no home (add a section) or a universally-empty section (drop it); the {slug,title,summary,overview} shape proving too thin/thick.

2026-06-23 β€” added the documentation domain (operator review of wiki). The DiΓ‘taxis structure (four modes Β· single-mode-per-page Β· intent-group layout Β· length ceilings Β· naming) is a base standard, so it lands as the documentation convention domain β€” the canonical home for "how we structure docs," alongside testing/ci. wiki consumes + enforces it (check-wiki.py is its gate; the templates + diataxis-author skill author against it) β€” one-way: wiki tools the standard, conventions owns it. The prose voice stays a separate agentm opinion (subjective, learned), not a convention. partial (the standard + gate ship in wiki; the convention home here is new).

2026-06-23 β€” authored from the seeded stub, then expanded on operator review from "testing + releasing" to the base-standards shell. A conventions-scope-investigation workflow (mining the HLDs + every sub-design + AGENTS.md / principles.md) found ~23 conventions homeless in the harness prose. Reframed conventions as the objective base standards a plugin consumes before opinions weigh in β€” the clean line: a convention is an objective house fact (gate-backed, no judgment, consumed directly, crickets-side); an opinion is a judgment stance asked by name (agentm-side). They relate by implementation β€” the done opinion is the check battery + the written conventions; opinions cite conventions, the arrow one-way. Expanded the domains to testing Β· releasing Β· ci Β· code-quality Β· agentic-engineering Β· reliability Β· coding, added a reference/ shape for objective house facts, and locked the cite-don't-duplicate rule (conventions cites developer-safety / privacy / maintenance / code-review, never re-owns). Operator decisions (2026-06-23): the boundary as above; the 7 domains + reference/ shape; subjective knowledge-refs (language / platform / per-language perf) are OUT β†’ the Opinions pillar / memory; cite-don't-duplicate for the standards other capabilities own; one aliased conventions plugin (testing + releasing fold in, domains as sub-folders). Built-vs-designed: testing + releasing delivered; ci / code-quality / reliability partial (gate-backed pieces exist, the convention home does not); agentic-engineering + coding mostly to-migrate. Re-audit: land the merge + homeless-migration; add the reference shape; each rule names its gate.

⚠️ **GitHub.com Fallback** ⚠️