alkdev/storage
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 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:
glm-5.1
2026-05-28 12:29:39 +00:00
parent 8c68dd6b07
commit 351fc98ec1
7 changed files with 141 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
.opencode/agents/architect.md
View File

@@ -29,7 +29,7 @@ Before writing architecture:
### 2. Identify Documentation Scope ### 2. Identify Documentation Scope
Determine the appropriate scope for each document: 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 - **Cross-cutting**: Shared patterns in overview documents
- **Decision records**: Significant decisions in separate ADR files - **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 3. **Implementation details**: Don't describe HOW at the code level
4. **Outdated sections**: Remove or update stale content immediately 4. **Outdated sections**: Remove or update stale content immediately
5. **Missing context**: Always explain WHY decisions were made 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.

19
.opencode/agents/code-reviewer.md
View File

@@ -85,9 +85,24 @@ Verify:
- Edge cases considered - Edge cases considered
- No brittle tests (over-mocked, timing-dependent) - 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 #### E. Security

33
.opencode/agents/coordinator.md
View File

@@ -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 mode: primary
temperature: 0.2 temperature: 0.2
--- ---
@@ -78,7 +78,7 @@ This is the most critical coordinator responsibility. Follow it exactly:
3. **Validate after every merge:** 3. **Validate after every merge:**
```bash ```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. 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: 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}} Your task: {{task}}
@@ -168,13 +168,19 @@ Your task: {{task}}
2. Read the task file, then read all referenced source files and architecture docs. 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 3. Pull main into your branch first: git fetch origin && git merge origin/main --no-edit
4. Implement the changes, following all acceptance criteria. 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. 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) 7. Push: git push origin $(git branch --show-current)
8. Notify: worktree({action: "notify", args: {message: "Task completed: {{task}}. <brief summary>", level: "info"}}) 8. Notify: worktree({action: "notify", args: {message: "Task completed: {{task}}. <brief summary>", level: "info"}})
Key project constraints: Key project constraints (@alkdev/storage):
- [project-specific constraints from AGENTS.md or README] - 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 ### Partial Generation Spawning
@@ -372,17 +378,4 @@ After completing a task graph or milestone, run a brief AAR:
2. <specific improvement to make> 2. <specific improvement to make>
``` ```
This AAR is how the process improves over time. Be honest and specific. 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.) |

30
.opencode/agents/implementation-specialist.md
View File

@@ -54,7 +54,7 @@ OpenCode spawns a NEW shell per command. The open-coordinator plugin auto-inject
```bash ```bash
# ✅ CORRECT — workdir is auto-injected # ✅ CORRECT — workdir is auto-injected
npm test deno test --allow-all test/
# ✅ ALSO CORRECT — explicit workdir still works # ✅ ALSO CORRECT — explicit workdir still works
bash({ command: "npm test", workdir: "/path/to/worktree" }) bash({ command: "npm test", workdir: "/path/to/worktree" })
@@ -95,20 +95,23 @@ If blocked → Safe Exit (see below)
4. **Write tests** as needed 4. **Write tests** as needed
**File paths:** Always relative to worktree root **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) - ❌ Absolute paths to the main repo (outside your worktree)
### 4. Self-Verify ### 4. Self-Verify
```bash ```bash
# Run tests (adjust for project toolchain) # Type check
npm test deno check mod.ts src/graphs/mod.ts src/sqlite/mod.ts
# Check lint # Lint
npm run lint deno lint
# Verify changes # Run tests
git diff --stat deno test --allow-all test/
# Format check
deno fmt --check
``` ```
Check each acceptance criterion in the task file. 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. 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 ## Key Principles
1. **Read first** - understand before implementing 1. **Read first** - understand before implementing

2
.opencode/agents/poc-specialist.md
View File

@@ -49,7 +49,7 @@ The open-coordinator plugin auto-injects `workdir` for bash commands when the se
```bash ```bash
# ✅ CORRECT — workdir is auto-injected # ✅ 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. **Do NOT use `cd` in commands** — it doesn't persist and the plugin handles routing.

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)

29
docs/sdd_process.md
View File

@@ -2,10 +2,10 @@
## Overview ## Overview
This document defines the SDD process for the alk.dev project. It leverages: This document defines the SDD process for the @alkdev/storage package. It leverages:
- **Operation registry + call protocol** for typed, composable tool invocation - **OpenCode CLI** as the agent execution environment
- **Hub coordination operations** (`coord.spawn`, `coord.status`, `coord.message`, etc.) for parallel worktree/session orchestration - **Open-coordinator plugin** for worktree management and parallel session orchestration
- **OpenCode CLI** as the agent execution environment (via the open-coordinator plugin as stopgap, transitioning to native hub operations) - **Structured task graphs** with dependency analysis and safe exit protocols
## Core Principles ## Core Principles
@@ -473,29 +473,16 @@ State moves from in-process tracking to Postgres `mappings` table. The open-coor
docs/ docs/
├── architecture/ ├── architecture/
│ ├── hub-architecture.md │ └── storage/ # Decomposed: README.md, table-reference.md, per-domain schema files
│ ├── call-graph.md │ └── (ADRs in decisions/)
│ ├── 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
├── sdd_process.md # This document ├── sdd_process.md # This document
└── decisions/ # ADRs └── decisions/ # ADRs
tasks/ tasks/
├── architecture/ ├── architecture/
│ └── auth-design.md │ └── ...
├── implementation/ ├── implementation/
│ ├── storage/ │ └── ...
│ │ ├── tasks-table.md
│ │ └── migrations.md
│ └── auth/
│ └── oauth-flow.md
└── (taskgraph validates & analyzes dependency graph) └── (taskgraph validates & analyzes dependency graph)
.worktrees/ # Created by coordinator .worktrees/ # Created by coordinator