From 351fc98ec15a69f07a16111d6f6ffe4895ee1195 Mon Sep 17 00:00:00 2001 From: "glm-5.1" Date: Thu, 28 May 2026 12:29:39 +0000 Subject: [PATCH] docs: add AGENTS.md and fix agent role defs for deno-first project MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .opencode/agents/architect.md | 4 +- .opencode/agents/code-reviewer.md | 19 ++++- .opencode/agents/coordinator.md | 33 ++++---- .opencode/agents/implementation-specialist.md | 30 +++++-- .opencode/agents/poc-specialist.md | 2 +- AGENTS.md | 78 +++++++++++++++++++ docs/sdd_process.md | 29 ++----- 7 files changed, 141 insertions(+), 54 deletions(-) create mode 100644 AGENTS.md diff --git a/.opencode/agents/architect.md b/.opencode/agents/architect.md index 6a4a08f..aec8975 100644 --- 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. \ No newline at end of file +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. \ No newline at end of file diff --git a/.opencode/agents/code-reviewer.md b/.opencode/agents/code-reviewer.md index 7b87a77..0424c32 100644 --- 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 diff --git a/.opencode/agents/coordinator.md b/.opencode/agents/coordinator.md index 6731180..8ada4ff 100644 --- 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}}. ", 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 @@ -372,17 +378,4 @@ After completing a task graph or milestone, run a brief AAR: 2. ``` -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.) | \ No newline at end of file +This AAR is how the process improves over time. Be honest and specific. \ No newline at end of file diff --git a/.opencode/agents/implementation-specialist.md b/.opencode/agents/implementation-specialist.md index 2d2a0cf..0b2df73 100644 --- 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 diff --git a/.opencode/agents/poc-specialist.md b/.opencode/agents/poc-specialist.md index 91b3892..1b36fe7 100644 --- 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. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..cade2b5 --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/sdd_process.md b/docs/sdd_process.md index 9388c24..15b708b 100644 --- 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