docs: add AGENTS.md and fix agent role defs for deno-first project

- Add AGENTS.md with project overview, conventions, commands, and heritage notes
- Fix all npm→deno command references in coordinator, implementation-specialist, poc-specialist
- Fix project name in coordinator spawn template (@alkdev/operations→@alkdev/storage)
- Remove hub-specific content (future model, hub operations) from coordinator
- Add project-specific conventions to implementation-specialist (no comments, TypeBox, slow types, etc.)
- Add deno-specific review checks to code-reviewer
- Fix file path examples in implementation-specialist (packages/core→src/graphs)
- Update sdd_process.md to remove hub-specific references and architecture doc list
- Update architect examples to use storage component names
This commit is contained in:
2026-05-28 12:29:39 +00:00
parent 8c68dd6b07
commit 351fc98ec1
7 changed files with 141 additions and 54 deletions

78
AGENTS.md Normal file
View File

@@ -0,0 +1,78 @@
# AGENTS.md — @alkdev/storage
Project-specific guidance for agents working on this package.
## Project Overview
`@alkdev/storage` is a deno-first TypeScript package providing typed graph storage with dual database hosts (SQLite for spokes, PostgreSQL for the hub). It uses the metagraph pattern (graphTypes → nodeTypes → edgeTypes → typed graph instances) from the earlier `@ade` prototype.
## Architecture Snapshot
```
@alkdev/storage/
├── mod.ts # Re-exports graphs/ only (zero db deps)
├── deno.json # JSR config, imports, tasks, lint rules
├── src/
│ ├── graphs/ # Schema types + SchemaBuilder (no db deps)
│ ├── sqlite/ # SQLite host (drizzle-orm/libsql)
│ │ ├── tables/ # Drizzle table definitions
│ │ ├── relations.ts # Drizzle relations
│ │ ├── schema.ts # Re-exports
│ │ └── client.ts # Injectable createSqliteDatabase()
│ └── pg/ # PostgreSQL host (NOT YET IMPLEMENTED)
└── test/
```
### Subpath Exports (JSR/npm)
- `@alkdev/storage` → graphs types + SchemaBuilder (zero deps)
- `@alkdev/storage/sqlite` → SQLite tables, relations, client (drizzle-orm + libsql)
- `@alkdev/storage/pg` → PostgreSQL tables, relations, client (NOT YET IMPLEMENTED)
This design ensures consumers don't bundle database drivers they don't use.
## Key Decisions
1. **Deno-first, npm-second via JSR**: Package is published to JSR (`deno publish`). npm compatibility is automatic via JSR's npm layer (`@jsr/alkdev__storage`). No separate dnt build step.
2. **No comments in code**: Per project convention across @alkdev packages.
3. **JSR slow types excluded from lint**: Drizzle's deeply inferred generics (`sqliteTable`, `createInsertSchema`, `relations`) make explicit type annotations impractical. We use `--allow-slow-types` on publish and `"exclude": ["no-slow-types"]` in lint config. This is a known technical debt item — can be tightened iteratively.
4. **Injectable clients**: `createSqliteDatabase(client)` takes a client, not env vars. Module-level side effects are forbidden.
5. **Dependencies**: `@alkdev/typebox` and `@alkdev/drizzlebox` are npm deps (not yet on JSR). This works fine — JSR handles npm dependencies natively.
## Commands
```bash
deno check mod.ts src/graphs/mod.ts src/sqlite/mod.ts # Type check
deno lint # Lint (slow-types excluded)
deno fmt # Format
deno test --allow-all test/ # Run tests
deno publish --allow-slow-types --dry-run # Dry-run publish
```
## Source Heritage
The `graphs/` and `sqlite/` modules were adapted from `@ade/ade-v0/packages/core/graphs` and `@ade/ade-v0/packages/storage_sqlite`. Key changes from the originals:
- `@sinclair/typebox``@alkdev/typebox`
- `drizzle-typebox``@alkdev/drizzlebox`
- `@ade/core` imports → relative imports within `src/graphs/`
- `import type { GraphConfig }``import { GraphConfig }` (TypeBox schemas are both values and types)
- `Relation` type alias removed (JSR slow type)
- `client.ts` refactored to be injectable
- Module-level `db` and `client` exports removed
## File Conventions
- All source files use `.ts` extension with explicit extensions in imports (Deno convention)
- Entry points are `mod.ts` files that re-export from subdirectories
- TypeBox schemas are named with PascalCase (`NodeType`, `GraphConfig`)
- Drizzle table objects are named with camelCase (`graphTypes`, `nodeTypes`)
- Schema objects from drizzlebox are named with PascalCase (`InsertGraph`, `SelectGraph`)
## What's Not Done Yet
- `src/pg/` — PostgreSQL host (same table shapes, `pgTable` + `jsonb` + `timestamp` + `pgEnum`)
- Tests
- Repository/CRUD layer (currently only table definitions, no typed query functions)
- Hub-specific tables (sessions, messages, parts, call graphs, tasks, etc.)
- JSR publication setup (need to create scope/package on jsr.io first)