---
name: dev-conventions
description: >
  Eristack development conventions: GitHub Flow, Changesets for user-facing
  package changes, core vs adapter boundaries, examples-first wiring, package
  docs as source of truth, HARD RULE docs+ai-knowledge every iteration,
  _ai-docs promote-then-delete. Use when contributing to business-libs or
  aligning an app with Eristack norms.
metadata:
  type: core
  library: '@eristack/ai-knowledge'
  library_version: '0.1.1'
sources:
  - 'eristack/business-libs:packages/ai/ai-knowledge/knowledge/dev-conventions.md'
  - 'eristack/business-libs:packages/ai/ai-knowledge/knowledge/upgrading.md'
  - 'eristack/business-libs:AGENTS.md'
---

# Development conventions

Full guide: `knowledge/dev-conventions.md`.

## Package design targets

1. **Cheap (tokens)** — ≤3 files to integrate; export what apps would copy
2. **Predictable** — same core in React + server; string-first; no silent coercion
3. **Reliable** — Drizzle/DB default; tests on real paths; memory stores tests-only
4. **Clear boundaries** — recommend first; consumers must not reinvent domain glue

Full table: `knowledge/agent-workflow.md` § Design targets.

## Quick rules

- **GitHub Flow** — feature branch → PR → `main` only
- **Changesets** required for user-facing package changes; not for docs/CI-only
- **One file per package**, **`patch` on 0.1.x** — `pnpm changesets:check` enforces (no mega changelog, no accidental 1.0.0)
- **Core vs adapters** — no framework imports in core; adapters are separate exports
- **Child resources** — credentials / refresh / formats hang off app-owned entities
- **Docs** — `packages/<category>/<name>/docs` is source of truth; don’t duplicate in the web app
- **HARD RULE** — every package iteration updates docs + Intent skills + recipes (if discoverable) + `pnpm knowledge:sync` / `knowledge:check`
- **Scope** — change only what the task needs

## AI working docs (monorepo)

Three buckets: `_ai-docs/wip/` (ephemeral), `_ai-docs/brainstorm/` (names), `_ai-docs/audit/` (snapshot). See `_ai-docs/README.md`.

1. While working: `_ai-docs/wip/<topic>/` from `_template/overview.md` (frontmatter: promotes-to, skills, recipes)
2. When finished: promote to package docs / site / skills / recipes; sync catalog
3. Delete the WIP folder after promotion