tidaldb/AGENTS.md

AGENTS.md

Agent instructions for tidalDB.

Team

Agent	Identity	Model	Invoke when
@tidal-engineer	Jon Gjengset — principal Rust database engineer	opus	Implementing features, storage internals, signal system, query engine, debugging correctness
@tidal-visionary	Spencer Kimball — product and roadmap strategist	opus	Planning milestones, scoping phases, build-vs-defer decisions, roadmap sequencing
@tidal-researcher	Andy Pavlo — database systems researcher	opus	Prior art surveys, library evaluation, architectural research, producing docs/research/ docs
@tidal-distributed	Kyle Kingsbury — distributed-systems engineer	opus	Network transports, cluster coordination, multi-node deployment, cross-node query routing, HA
@tidal-storyteller	Marketing and technical writer	sonnet	Marketing site (site/), blog posts, public-facing copy

Agent definitions live in .claude/agents/. CLAUDE.md §Agents is the canonical roster (this table mirrors it — keep them in sync); see it for the @knowledge-librarian utility agent and the vendored @kai-park/@kaya-osei/@mira-vasquez Aeries team that backs the aeries-* skills.

---

SDLC

Required reading: .sdlc/guidance.md — engineering principles that govern all implementation decisions on this project.

This project uses sdlc as its SDLC state machine. sdlc manages feature lifecycle, artifacts, tasks, and milestones. It emits structured directives via sdlc next --json that any consumer (Claude Code, custom scripts, or humans) acts on to decide what to do next.

Consumer scaffolding is installed globally under ~/.claude/commands/, ~/.gemini/commands/, ~/.opencode/command/, and ~/.agents/skills/ — available across all projects. Use /sdlc-specialize in Claude Code to generate a project-specific AI team (agents + skills) tailored to this project's tech stack and roles.

Key Commands

• sdlc feature create <slug> --title "..." — create a new feature
• sdlc next --for <slug> --json — get the next action directive (JSON)
• sdlc next — show all active features and their next actions
• sdlc artifact approve <slug> <type> — approve an artifact to advance the phase
• sdlc state — show project state
• sdlc feature list — list all features and their phases
• sdlc task list [<slug>] — list tasks for a feature (or all tasks)

Lifecycle

draft → specified → planned → ready → implementation → review → audit → qa → merge → released

Treat this lifecycle as the default pathway. You can use explicit manual transitions when needed, but approvals/artifacts are the recommended way to keep quality and traceability.

Artifact Types

spec design tasks qa_plan review audit qa_results

CRITICAL: Never edit .sdlc/ YAML directly

All state changes go through sdlc CLI commands. See §6 of .sdlc/guidance.md for the full command reference. Direct YAML edits corrupt state.

Directive Interface

Use sdlc next --for <slug> --json to get the next directive. The JSON output tells the consumer what to do next (action, message, output_path, is_heavy, gates).

Consumer Commands

• /sdlc-next <slug> — execute one step, then stop (human controls cadence)
• /sdlc-run <slug> — run autonomously to completion
• /sdlc-status [<slug>] — show current state
• /sdlc-plan — distribute a plan into milestones, features, and tasks
• /sdlc-milestone-uat <milestone-slug> — run the acceptance test for a milestone
• /sdlc-pressure-test <milestone-slug> — pressure-test a milestone against user perspectives
• /sdlc-vision-adjustment [description] — align all docs, sdlc state, and code to a vision change
• /sdlc-architecture-adjustment [description] — align all docs, code, and sdlc state to an architecture change
• /sdlc-enterprise-readiness [--stage <stage>] — analyze production readiness
• /sdlc-setup-quality-gates — set up pre-commit hooks and quality gates
• /sdlc-cookbook <milestone-slug> — create developer-scenario cookbook recipes
• /sdlc-cookbook-run <milestone-slug> — execute cookbook recipes and record results
• /sdlc-ponder [slug] — open the ideation workspace for exploring and committing ideas
• /sdlc-ponder-commit <slug> — crystallize a pondered idea into milestones and features
• /sdlc-guideline <slug-or-problem> — build an evidence-backed guideline through five research perspectives and TOC-first distillation
• /sdlc-suggest — analyze project state and suggest 3-5 ponder topics to explore next
• /sdlc-beat [domain | feature:<slug> | --week] — step back with a senior leadership lens; evaluate if we're building the right thing in the right direction; stores history in .sdlc/beat.yaml
• /sdlc-recruit <role> — recruit an expert thought partner as a persistent agent
• /sdlc-empathy <subject> — deep user perspective interviews before decisions
• /sdlc-spike <slug> — <need>; [see <ref>] — research, prototype, validate, and report; produces working prototype + findings in .sdlc/spikes/<slug>/findings.md
• /sdlc-convo-mine [file or text] — mine conversation dumps for signal; apply 5 perspective lenses, group themes, launch parallel ponder sessions per group

Tool Suite

Project-scoped TypeScript tools in .sdlc/tools/ — callable by agents and humans during any lifecycle phase. Read .sdlc/tools/tools.md for the full help menu.

• sdlc tool list — show installed tools
• sdlc tool run <name> [args] — run a tool; pass --json '{...}' for complex input
• sdlc tool sync — regenerate tools.md after adding a custom tool
• sdlc tool scaffold <name> "desc" — create a new tool skeleton

Core tools: ama (codebase Q&A), quality-check (runs platform shell gates)

Use /sdlc-tool-run, /sdlc-tool-build, /sdlc-tool-audit, /sdlc-tool-uat in Claude Code for guided tool workflows.

Project: tidalDB