whodb AGENTS.md

WhoDB Development Guide

WhoDB is a source-first data management tool. The public GraphQL API and frontend contract are built around SourceType, SourceContract, SourceObject, SourceObjectRef, and SourceSessionMetadata. The current execution layer is still powered mainly by database plugins under core/src/plugins/.

AGENTS.md is the canonical agent instruction file for this repository. Tool- specific files such as CLAUDE.md should import or point to this file instead of duplicating these instructions.

If the ee/ directory is present, read ee/AGENTS.md for additional context. Do not add any code, comments, or references to ee/ in the CE codebase.

Git Commits — Hard Rule

Never commit to main (or any branch) without the user explicitly saying "please commit this for me" (or unambiguously equivalent wording) in that turn. This applies regardless of task framing — "merge it into main locally" or "just write the code changes in main" means apply the file changes on that branch, not create a commit. If committing seems necessary to accomplish what was asked (e.g. to merge a branch), stop and ask first instead of assuming consent.

Terminology

• "EE agent" / "ee agent" means the in-app WhoDB EE browser AI agent feature (under ee/), NOT the coding-agent (Claude/Codex) configuration or any MCP server. When in doubt, ask which is meant before acting.

Non-Negotiable Rules

1. GraphQL-first - All new API functionality via GraphQL. Never add HTTP resolvers unless explicitly needed (e.g., file downloads)
2. No SQL injection - Never use fmt.Sprintf with user input for SQL. Use parameterized queries or GORM builders. See .agents/docs/sql-security.md
3. Plugin architecture - Never use switch dbType or if dbType == in shared code. All database-specific logic goes in plugins. See .agents/docs/plugin-architecture.md
4. Documentation requirements - All exported Go functions/types need doc comments. All exported TypeScript functions/components need JSDoc. See .agents/docs/documentation.md
5. Localization requirements - All user-facing strings must use t() with YAML keys. No fallback strings. No hardcoded UI text. When adding or updating keys, edit en_US only unless the user explicitly asks for other languages. See .agents/docs/localization.md
6. Verify before completing - For non-trivial tasks, define success criteria before editing. After finishing, verify: (1) type checks pass (pnpm run build:ce for frontend, go build ./cmd/whodb for backend), (2) no linting errors, (3) all added code is actually used (no dead code). See .agents/docs/verification.md
7. Show proof - When making a claim about how something outside of our codebase works, for example a 3rd party library or function, always provide official documentation or the actual code to back that up. Check online if you have to.