Skip to content

docs: CONVENTIONS.md per package [closes #232]#280

Merged
EmersonBraun merged 1 commit intomainfrom
foundation/conventions
Apr 15, 2026
Merged

docs: CONVENTIONS.md per package [closes #232]#280
EmersonBraun merged 1 commit intomainfrom
foundation/conventions

Conversation

@EmersonBraun
Copy link
Copy Markdown
Owner

Summary

One focused CONVENTIONS.md per package explaining:

  • Scope — what belongs here
  • 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.
  • Testing conventions specific to that package
  • Common pitfalls as a lookup table
  • Review checklist reviewers run when approving PRs

Closes #232.

Highlights per package

  • core — strictest rules. Zero deps, <10KB, no any, named exports only. Explicit list of what triggers an ADR.
  • adapters — step-by-step for a new chat adapter + embedder, naming rules, contract-test pointer (10 invariants).
  • react — headless components, data-ak-* attributes for styling hooks, accessibility requirements.
  • ink — documents the ink@7 / ink-testing-library@4 test harness workaround so new contributors don't rediscover it.
  • cli--help fits one screen, stdout vs stderr discipline, exit code conventions.
  • runtime — enforces RT1–RT14 as the review gate. Any PR touching the loop must argue why each invariant still holds.
  • tools — JSON Schema 7 (not Zod), requiresConfirmation: true for destructive ops, snake_case naming.
  • skills — how to write the system prompt, pure-declarative no-execute principle, onActivate only for dynamic per-user tools.
  • memory — separate sections for ChatMemory and VectorMemory backends, invariant lists.
  • rag — composition-first ("can this be done by wrapping Retriever?"), keep createRAG small.
  • observability — observers are read-only; mutation belongs in a wrapper runtime.
  • sandbox — deny-by-default network/filesystem, security posture non-negotiable.
  • eval — scores in [0, 1], every metric optional, replay-first design.
  • templates — helpers as pure functions, defaults in JSDoc.

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

  • 14 CONVENTIONS.md files created
  • Each links to the relevant ADRs and sibling packages
  • Each ends with a package-specific review checklist
  • Reviewer: spot-check the rules against real patterns in each src/
  • Reviewer: confirm the stability-tier notes match what was declared in feat: declare stability tier per package [closes #227] #279
  • Reviewer: any pitfall missing from your experience that should land now?

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

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
@EmersonBraun EmersonBraun merged commit 9ffa3c5 into main Apr 15, 2026
1 check failed
@EmersonBraun EmersonBraun deleted the foundation/conventions branch April 15, 2026 12:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[P0.21] Social proof on landing (stars, downloads, showcase)

1 participant