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
2026-05-28 12:29:39 +00:00
parent 8c68dd6b07
commit 351fc98ec1
7 changed files with 141 additions and 54 deletions
--- a/.opencode/agents/architect.md
+++ b/.opencode/agents/architect.md
@@ -29,7 +29,7 @@ Before writing architecture:
 ### 2. Identify Documentation Scope

 Determine the appropriate scope for each document:
- **Component-level**: One document per major component (e.g., `call-graph.md`, `spoke-runner.md`)
+- **Component-level**: One document per major component (e.g., `graphs-schema.md`, `sqlite-host.md`)
 - **Cross-cutting**: Shared patterns in overview documents
 - **Decision records**: Significant decisions in separate ADR files

@@ -145,4 +145,4 @@ Send exploration work to Research Specialist:
 3. **Implementation details**: Don't describe HOW at the code level
 4. **Outdated sections**: Remove or update stale content immediately
 5. **Missing context**: Always explain WHY decisions were made
-6. **Consumer dispatch in library docs**: When writing a library's architecture, describe what consumers need (graph construction, analysis, security constraints) — not how they dispatch it (tool registry mapping tables, CLI→action tables). That belongs in the consumer's own architecture.
+6. **Consumer dispatch in library docs**: When writing a library's architecture, describe what consumers need (graph construction, analysis, security constraints) — not how they dispatch it (tool registry mapping tables, CLI→action tables, hub coordination calls). That belongs in the consumer's own architecture.
--- a/.opencode/agents/code-reviewer.md
+++ b/.opencode/agents/code-reviewer.md
@@ -85,9 +85,24 @@ Verify:
 - Edge cases considered
 - No brittle tests (over-mocked, timing-dependent)

-#### D. Static Analysis
+#### D. Static Analysis (Deno toolchain)

-Run linters and type checks appropriate to the project toolchain.
+Run the project's type check, lint, and format commands:
+```bash
+deno check mod.ts src/graphs/mod.ts src/sqlite/mod.ts  # Type check
+deno lint                                               # Lint (slow-types excluded per project config)
+deno fmt --check                                        # Format check
+```
+
+#### D2. Project Convention Checks
+
+For this project, also verify:
+- No comments in code (per project convention)
+- Slow types are only in known problem areas (drizzle ORM generics) — no new slow types outside those
+- Imports use explicit `.ts` extensions (Deno convention)
+- TypeBox schemas are values+types (no `import type` for schema symbols)
+- Entry points are `mod.ts` files that re-export
+- Clients are injectable (no module-level side effects, no env vars)

 #### E. Security

--- a/.opencode/agents/coordinator.md
+++ b/.opencode/agents/coordinator.md
@@ -1,5 +1,5 @@
 ---
-description: Orchestrate parallel task execution across worktrees and sessions. Uses open-coordinator plugin for worktree management and session coordination. Transitions to hub coordination operations when available.
+description: Orchestrate parallel task execution across worktrees and sessions. Uses open-coordinator plugin for worktree management and session coordination.
 mode: primary
 temperature: 0.2
 ---
@@ -78,7 +78,7 @@ This is the most critical coordinator responsibility. Follow it exactly:

 3. **Validate after every merge:**
   ```bash
-   npm run build && npm run lint && npm test
+   deno check mod.ts src/graphs/mod.ts src/sqlite/mod.ts && deno lint && deno test --allow-all test/
   ```
   Never skip this. A merge that breaks the build is worse than no merge.

@@ -160,7 +160,7 @@ The `prompt` parameter supports `{{task}}` template substitution. Use it, but al
 Example prompt template:

 ```
-You are an implementation specialist for the @alkdev/operations project.
+You are an implementation specialist for the @alkdev/storage project.

 Your task: {{task}}

@@ -168,13 +168,19 @@ Your task: {{task}}
 2. Read the task file, then read all referenced source files and architecture docs.
 3. Pull main into your branch first: git fetch origin && git merge origin/main --no-edit
 4. Implement the changes, following all acceptance criteria.
-5. Run npm run build, npm run lint, npm test. Fix any failures.
+5. Run deno check mod.ts src/graphs/mod.ts src/sqlite/mod.ts, deno lint, deno test --allow-all test/. Fix any failures.
 6. Commit ONLY source code — do not commit task files (tasks/*.md). The coordinator manages task status on main.
 7. Push: git push origin $(git branch --show-current)
 8. Notify: worktree({action: "notify", args: {message: "Task completed: {{task}}. <brief summary>", level: "info"}})

-Key project constraints:
- [project-specific constraints from AGENTS.md or README]
+Key project constraints (@alkdev/storage):
+- Deno-first: use deno check, deno lint, deno fmt, deno test (not npm)
+- No comments in code
+- TypeBox (not Zod): use @alkdev/typebox and @alkdev/drizzlebox
+- JSR slow types excluded (known debt in drizzle generics)
+- Injectable clients, no module-level side effects
+- Import .ts extensions explicitly
+- TypeBox schemas are values+types (no import type for schema symbols)
 ```

 ### Partial Generation Spawning
@@ -373,16 +379,3 @@ After completing a task graph or milestone, run a brief AAR:
 ```

 This AAR is how the process improves over time. Be honest and specific.
-
-## Future Model (Hub Operations)
-
-When the hub is operational, coordination transitions to native operations via the call protocol. The coordination logic stays the same; only the transport changes.
-
-| Current (open-coordinator) | Future (hub operations) |
-|---|---|
-| `worktree({action: "spawn", ...})` | `hub.call("coord.spawn", ...)` |
-| `worktree({action: "sessions"})` | `hub.call("coord.status", ...)` |
-| `worktree({action: "message", ...})` | `hub.call("coord.message", ...)` |
-| `worktree({action: "abort", ...})` | `hub.call("coord.abort", ...)` |
-| In-process plugin | Hub call protocol over websocket |
-| Single machine only | Remote spokes (vast.ai, ubicloud, etc.) |
--- a/.opencode/agents/implementation-specialist.md
+++ b/.opencode/agents/implementation-specialist.md
@@ -54,7 +54,7 @@ OpenCode spawns a NEW shell per command. The open-coordinator plugin auto-inject

 ```bash
 # ✅ CORRECT — workdir is auto-injected
-npm test
+deno test --allow-all test/

 # ✅ ALSO CORRECT — explicit workdir still works
 bash({ command: "npm test", workdir: "/path/to/worktree" })
@@ -95,20 +95,23 @@ If blocked → Safe Exit (see below)
 4. **Write tests** as needed

 **File paths:** Always relative to worktree root
- ✅ `packages/core/src/mod.ts`
+- ✅ `src/graphs/mod.ts`
 - ❌ Absolute paths to the main repo (outside your worktree)

 ### 4. Self-Verify

 ```bash
-# Run tests (adjust for project toolchain)
-npm test
+# Type check
+deno check mod.ts src/graphs/mod.ts src/sqlite/mod.ts

-# Check lint
-npm run lint
+# Lint
+deno lint

-# Verify changes
-git diff --stat
+# Run tests
+deno test --allow-all test/
+
+# Format check
+deno fmt --check
 ```

 Check each acceptance criterion in the task file.
@@ -179,6 +182,17 @@ When available, use memory tools to manage your context:

 This is especially important for complex tasks that span many file operations.

+## Project Conventions (@alkdev/storage)
+
+Read `AGENTS.md` at project root for full details. Key rules:
+
+1. **No comments in code** — Per project convention.
+2. **TypeBox, not Zod** — Use `@alkdev/typebox` and `@alkdev/drizzlebox` for schema/validation.
+3. **Explicit .ts extensions** — All imports must include the `.ts` extension (Deno convention).
+4. **JSR slow types** — Drizzle's deeply inferred generics make explicit annotations impractical. Use `--allow-slow-types`. Do not annotate drizzle table definitions.
+5. **Injectable clients** — `createSqliteDatabase(client)` takes a client, not env vars. No module-level side effects.
+6. **Naming conventions** — TypeBox schemas: PascalCase (`NodeType`). Drizzle tables: camelCase (`graphTypes`). Drizzlebox schemas: PascalCase (`InsertGraph`).
+
 ## Key Principles

 1. **Read first** - understand before implementing
--- a/.opencode/agents/poc-specialist.md
+++ b/.opencode/agents/poc-specialist.md
@@ -49,7 +49,7 @@ The open-coordinator plugin auto-injects `workdir` for bash commands when the se

 ```bash
 # ✅ CORRECT — workdir is auto-injected
-npm test
+deno test --allow-all test/
 ```

 **Do NOT use `cd` in commands** — it doesn't persist and the plugin handles routing.
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -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)
--- a/docs/sdd_process.md
+++ b/docs/sdd_process.md
@@ -2,10 +2,10 @@

 ## Overview

-This document defines the SDD process for the alk.dev project. It leverages:
- **Operation registry + call protocol** for typed, composable tool invocation
- **Hub coordination operations** (`coord.spawn`, `coord.status`, `coord.message`, etc.) for parallel worktree/session orchestration
- **OpenCode CLI** as the agent execution environment (via the open-coordinator plugin as stopgap, transitioning to native hub operations)
+This document defines the SDD process for the @alkdev/storage package. It leverages:
+- **OpenCode CLI** as the agent execution environment
+- **Open-coordinator plugin** for worktree management and parallel session orchestration
+- **Structured task graphs** with dependency analysis and safe exit protocols

 ## Core Principles

@@ -473,29 +473,16 @@ State moves from in-process tracking to Postgres `mappings` table. The open-coor

 docs/
 ├── architecture/
-│   ├── hub-architecture.md
-│   ├── call-graph.md
-│   ├── spoke-runner.md
-│   ├── operations.md
-│   ├── mcp-server.md
-│   ├── coordination.md
-│   ├── storage/                  # Decomposed: README.md, table-reference.md, per-domain schema files, tasks.md
-│   │   └── (ADRs in decisions/)
-│   ├── agent-sessions.md
-│   ├── pubsub-redis.md
-│   └── infrastructure.md
+│   └── storage/                  # Decomposed: README.md, table-reference.md, per-domain schema files
+│       └── (ADRs in decisions/)
 ├── sdd_process.md             # This document
 └── decisions/                 # ADRs

 tasks/
 ├── architecture/
-│   └── auth-design.md
+│   └── ...
 ├── implementation/
-│   ├── storage/
-│   │   ├── tasks-table.md
-│   │   └── migrations.md
-│   └── auth/
-│       └── oauth-flow.md
+│   └── ...
 └── (taskgraph validates & analyzes dependency graph)

 .worktrees/                    # Created by coordinator