docs: CONVENTIONS.md per package [closes #232]#280
Merged
EmersonBraun merged 1 commit intomainfrom Apr 15, 2026
Merged
Conversation
Closes #232. One focused governance doc per package explaining: - Scope (what belongs in this package) - What does NOT belong here (routing to sibling packages) - How to add a new X (step-by-step for adapters, tools, skills, memory backends, components, observers, etc.) - Package-specific testing conventions - Common pitfalls as a lookup table - Review checklist per package Highlights: - core/CONVENTIONS.md — strictest rules (zero deps, <10KB, no any, named exports only); explicit list of what triggers an ADR - adapters — step-by-step for new chat adapter + new embedder, naming, contract-test pointer - react — headless components, data-ak-* attributes, accessibility - ink — documents the ink@7 / ink-testing-library@4 test harness workaround - cli — --help one screen, stdout vs stderr discipline, exit codes - runtime — enforces the 14 RT invariants as review gate - tools — JSON Schema 7 not Zod, requiresConfirmation for destructive ops - skills — how to write the prompt, pure declarative no-execute principle - memory — split into ChatMemory/VectorMemory adding guides - rag — composition-first, keep createRAG small - observability — observers are read-only (wrap runtime instead for mutation) - sandbox — deny-by-default network/filesystem - eval — scores in [0,1], metrics optional - templates — helpers as pure functions Every page ends with a package-specific review checklist that reviewers use when approving PRs for that package. Refs #232 #211
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
One focused CONVENTIONS.md per package explaining:
Closes #232.
Highlights per package
any, named exports only. Explicit list of what triggers an ADR.data-ak-*attributes for styling hooks, accessibility requirements.--helpfits one screen, stdout vs stderr discipline, exit code conventions.requiresConfirmation: truefor destructive ops, snake_case naming.onActivateonly for dynamic per-user tools.createRAGsmall.[0, 1], every metric optional, replay-first design.Why this matters for Fase 3 onboarding
Fase 3 adds ~10 new adapters, ~15 new tools, 8 memory backends, 4 UI frameworks. Without CONVENTIONS.md per package, every contributor relitigates the same design questions. These docs are the reference for 'how do I add X to Y?'.
Test plan
src/Follow-up
The linked 'contract test suites' (AdapterContractSuite, MemoryContractSuite) referenced in several CONVENTIONS don't exist yet — they're tracked for Phase 2 work.
Refs #232 #211