# AGENTS.md

> **Purpose:** Documentation router and entry point for AI coding agents. Helps AI determine which documentation is relevant.
>
> **Audience:** AI
>
> **Source of Truth:** Codebase (implementation is authoritative)
>
> **Last Updated:** 2026-08-10
>
> **Depends On:** None
>
> **Referenced By:** [README.md](README.md), [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md)

## Project Context

`@ryanyonzon/pi-docgraph` is a Pi coding agent extension that maintains an AI-native documentation graph: selective retrieval, a Kanban-style ticket board under `docs/tickets/`, and code as the source of truth. Entry point: `src/index.ts`, which registers 7 tools (`docgraph_*`), 4 slash commands (`docgraph:*`), and event handlers. The extension's philosophy and documentation conventions are specified in [docs/PHILOSOPHY.md](docs/PHILOSOPHY.md).

## Commands

- Type-check (build): `npm run build` (also `npm run check`)
- Tests: `npm test` — `tsx --test "test/**/*.test.ts"`
- Type-check tests: `npm run test:types` (`tsc -p tsconfig.test.json`)
- Watch mode: `npm run dev`

## Conventions

- **ESM + strict TypeScript** (NodeNext resolution): production imports use `.js` extensions; test files import with `.ts` extensions.
- One responsibility per file: tools in `src/tools/`, commands in `src/commands/`, events in `src/events/`, shared logic in `src/utils.ts`, types in `src/types.ts`. Registration functions are named `registerDocgraph*`.
- Tests use `node:test` + `node:assert/strict` with the shared `mockPi()`/temp-repo helpers from `test/helpers.ts`.
- **TDD is mandatory**: write the failing test first, then implement, then refactor.
- Conventional commits (`fix:`, `feat:`, `test:`, `docs:`, ...).
- Codebase is authoritative; update docs when they disagree with implementation.

## Constraints

- Do not claim acceptance criteria / Definition of Done items complete without actually verifying them.
- Do not weaken or rewrite acceptance criteria to make tickets appear complete.
- Managed docs (`README.md`, `AGENTS.md`, `docs/*`) keep a metadata block at the top (Purpose/Audience/Source of Truth/Last Updated/Depends On/Referenced By); `docgraph_sync` validates cross-references, so update `Referenced By` when links change.