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 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.
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 |
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.
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).
| 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) |
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
goodopinion's framing) β a judgment stance, not a gate-backed convention, so it stays there.
-
testing (delivered) + releasing (delivered) β the two existing plugins, folded in (Migrations). Consumed by
/work+/releaseandcode-review'stesting-strategy. -
ci (amended β per-plan CI) β
check-all.shremains 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 aggregateci-all.ymlcouples to the three OS workflows by filename (a rename trips the test). The gate inventory is areference/doc. The full 3-OS matrix +ci-allnow fire onpull_request, not on push tomain. A push directly tomain(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 thecheck-all.sh-backed PR check green before merge is even offered. The docs/wiki-only diet does not carry forward onto thepull_requesttrigger as-is β a trigger-levelpaths-ignorewould 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 insideci-all(diff-aware, not trigger-aware) underPLAN-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:/workwaits 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.ymlis unaffected β it was never part of the test matrix and stays push-triggered. Nightly main-HEAD backstop (lands withPLAN-per-plan-ci): a scheduled workflow reruns the full matrix againstmainHEAD independent of any PR, advisory-only β the drift-between-merges catch that push-triggered CI used to provide for free;agentm's existinghealth-nightly.yml(a different, heavier functional-quality tier) gets this wired into its scorecard render,cricketsgets the workflow fresh. Consumed by every pre-commit and bymaintenance'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/reviewand 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.
-
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:
-
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
goodopinion. -
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
/worksession. -
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.ymldeclaration; 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-designsuffix (check-wikirule (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.pyis the gate (mode Β· length Β· vendor Β· structure), its templates anddiataxis-authorskill author against it, and a per-repo.diataxis-conventions.mdcan override. The prose voice is a separate agentm opinion (subjective, learned), not a convention.
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.)
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.
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
rulenames ascripts/check-*.shgate, and the gate runs in thecheck-all.shbattery at every commit β independent of whether any plugin remembered to consult it. A violation fails the commit, not a code review. (Theciconvention "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 (
/workreads coding + testing,/releasereads 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.
-
requires development-lifecycle β
/work,/review,/releaserun the rules + skills. -
consumed by the phase loop, code-review (the
testing-strategyaudit draws on the testing standard), wiki (enforces thedocumentationconvention viacheck-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.
Two structural lifts at the Phase-3 / v6.0 pass:
-
Merge β
testing-conventions+releasing-conventionsconsolidate to onesrc/conventions/, thegroup.yamlmerges, andcapabilities: [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. -
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 standalonerules/+skills/;AGENTS.mdkeeps a pointer,conventionsowns the standard. The cite-don't-duplicate boundary keeps it from re-owning whatdeveloper-safety/privacy/maintenance/code-reviewalready hold.
- 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 β
conventionscites, 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-loopis 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 itscheck-*.shgate; shipcheck-no-skip-tests.sh+ acheck-conventions-cite-not-duplicateportfolio 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.
- 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)
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 aversion:in itssrc/<slug>/group.yaml(parsed bysrc_model.Group, written by both emitters intoplugin.json+ the Claude marketplace entry), replacing the frozenPLUGIN_VERSION="0.1.0"constant that madeclaude plugin updatea permanent no-op. Anti-recurrence gatecheck-version-bump.pyfails whensrc/<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 intocheck-all.sh+ CI. This is the decision record behind theversion-bump-requiredrule. 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 offdist/-on-main, or Antigravity shipping a version-drivenagy 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'sDEFAULT_SECTIONS, allow-listed bycheck-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 (awiki/architecture.ymlmanifest ofcomponents:{slug,title,summary,overview}+ optionalpillars:toggles; the generator scaffoldsarchitecture/<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.