jordan 5ceef74f3b chore: bootstrap SDLC state machine for tidalDB

- Initialize .sdlc/ with config, guidance, and state machine
- Register M0-M8 as released milestones (full engine track history)
- Seed M9 (Community Sync & Revocation) and M10 (Governance & Agent Rights) with features
- Seed product milestones P0-P4 and PG1 gate with features from existing planning docs
- Add Team section to AGENTS.md (tidal-engineer, tidal-visionary, tidal-researcher, tidal-storyteller)
- Add knowledge-librarian agent for .sdlc/knowledge/ curation
- Gitignore .sdlc/telemetry.redb (volatile binary state)
- Add .ai/ scaffold (project knowledge index)

2026-03-03 00:41:41 -07:00

5.6 KiB

Raw Blame History

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-storyteller`	Marketing and technical writer	sonnet	Marketing site (`site/`), blog posts, public-facing copy

Agent definitions live in .claude/agents/. Full context in CLAUDE.md §Agents.

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

5.6 KiB Raw Blame History