--- 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