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:
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
@@ -372,17 +378,4 @@ After completing a task graph or milestone, run a brief AAR:
|
||||
2. <specific improvement to make>
|
||||
```
|
||||
|
||||
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.) |
|
||||
This AAR is how the process improves over time. Be honest and specific.
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user