Improve AGENTS.md accuracy, completeness, and agent efficiency

[nick-inkeep]

Summary

Overhauls AGENTS.md to fix factual inaccuracies, fill documentation gaps, and cut redundancy — so AI coding agents spend fewer tokens on stale or repeated instructions and more on correct ones. Every factual claim was verified against the actual codebase using 15+ parallel verification agents. Setup-dev gotchas were QA-tested against both greenfield and brownfield scenarios. Only AGENTS.md is changed (net -34 lines: +162/-196).

Architectural decisions

Verify-then-rewrite, not patch. Each section was evaluated against the codebase for accuracy and rewritten if needed. This caught compound errors (e.g., the original said pre-commit runs pnpm format — actually pre-push does; pre-commit runs lint-staged).

Redundancy removal with A/B/C classification. Each proposed cut was classified before applying:

• A-class (apply): Content duplicated verbatim elsewhere or generic filler (e.g., NewFeature code skeletons, Testing Patterns subsection duplicating the Testing section).
• B-class (apply with care): Unique nuggets buried in redundant sections — relocated before cutting (e.g., "don't publish changesets" moved to changeset section).
• C-class (preserve): Content that appeared redundant but was the only place defining specific values (e.g., Multi-Agent relation types with DB enum values, Doltgres branch-scoping patterns).

Setup-dev additions QA-tested against 12 items. Each candidate was evaluated from both greenfield (fresh clone) and brownfield (existing dev environment) perspectives. Only 3 of 12 candidates survived — the rest were either self-explanatory via error messages, already documented in .env comments, or had no behavioral impact.

Tables → lists for 2-column data. Two-column tables converted to plain bullet lists for readability.

Changes

Accuracy fixes

• A2A protocol — added definition (Google's A2A spec, JSON-RPC 2.0 over HTTP with SSE)
• Hono framework — added Hono v4 section with domain mount map (/manage, /run, /evals, /.well-known, /work-apps, /mcp)
• Package dependency graph — added full table of all packages and internal dependencies
• Multi-agent framework — added relation types table (transfer/delegate/tool) with DB enum values
• Pre-commit/pre-push hooks — fixed: pre-commit runs lint-staged (not pnpm format); pre-push runs pnpm format
• Test DB engine — corrected "in-memory SQLite" → "embedded Postgres (PGlite)"
• --run flag — corrected: already baked into package test scripts
• Documentation paths — fixed content/docs/ → content/
• Documentation framework — corrected to Next.js + Fumadocs
• Work-apps file locations — added missing entry

New sections

• Command Timing Guide — "when to run what" table with timing estimates, hooks documentation
• Database Operations table — expanded from 6 to 9 entries with per-DB scope and notes
• Skills System — documents auto-discovery and symlink structure
• Database Architecture — two-database engine details, Doltgres caveats, branch-scoping
• Commit message guidance — lightweight conventions

Setup-dev gotchas (QA-verified)

• Build prerequisite — pnpm setup-dev imports from agents-core/dist/; requires pnpm build first on fresh clones
• Stale .env trap — setup-dev does not merge new vars from .env.example into an existing .env; features fail silently after pulling changes that add env vars
• Jaeger debugging prerequisite — added note that the debugging commands section requires pnpm setup-dev:optional

Redundancy removed (~185 lines)

• Iteration flow / "Do not" list
• "What only CI can catch" / changeset responsibilities table
• DB ops table rows without unique notes
• Testing Patterns subsection (verbatim duplicate)
• Feature Development Examples (87 lines of generic skeletons)
• Migration db:drop rule (duplicate)
• Component sub-sections under mandatory checklist (folded into checklist items)
• "When Working with Agents" filler points
• AI Coding Assistant Guidance section (symlink info relocated)

Formatting

• Converted 2-column tables to plain bullet lists
• Removed unnecessary bold formatting from list items

Corrections to existing content

• graph.init() removed (doesn't exist)
• Builder patterns corrected: data-access functions inside agents-api, builders in SDK/CLI
• Mandatory checklist → change-type matrix (calibrated requirements per change type)
• sub_agents → sub_agent_relations

How to verify

1. Read the updated AGENTS.md top-to-bottom — sections should flow without repetition
2. Spot-check factual claims:
   • grep -r "app.route" agents-api/src/createApp.ts → Hono mount points
   • cat .husky/pre-commit → lint-staged (not pnpm format)
   • head -15 scripts/setup-dev.js → imports from agents-core/dist/
3. Verify setup-dev gotchas: ensureEnvFile() in packages/agents-core/src/setup/setup.ts — pure copy-if-missing, no merge

Test plan

• All factual corrections verified by codebase exploration agents
• Redundancy cuts evaluated individually for unique-content preservation
• Setup-dev items QA-tested: 12 candidates analyzed across greenfield/brownfield; 3 included, 9 skipped with justification
• No code changes — only AGENTS.md modified

Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
agents-api	Ignored	Preview	Feb 26, 2026 4:43pm
agents-docs	Ignored	Preview	Feb 26, 2026 4:43pm
agents-manage-ui	Ignored	Preview	Feb 26, 2026 4:43pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2196782

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR