pi-docgraph

Purpose: Primary documentation entry point for human developers. Introduces the project, explains how to install and use it, and links to detailed documentation.

Audience: Human

Source of Truth: Codebase (implementation is authoritative)

Last Updated: 2026-08-10

What is pi-docgraph?

pi-docgraph is an AI-native documentation graph extension for the Pi coding agent. It turns a project's documentation into a small, interconnected graph that AI agents can navigate efficiently instead of reading everything.

Most repositories keep documentation in a few large files. When an AI agent works on a task, it must load the whole docs folder to find what it needs — which burns tokens, slows down responses, and makes docs harder to maintain. pi-docgraph solves this by structuring documentation so an agent can determine relevance instantly and read only the 1–2 documents it actually needs.

The project is grounded in one core principle: code is always the source of truth. Documentation explains, summarizes, and navigates the implementation — it never overrides it.

Who is it for?

• Developers using the Pi coding agent who want their AI assistant to work faster and more accurately by keeping documentation well-organized and up to date.
• Teams who want a lightweight, code-adjacent documentation workflow with clear ticket tracking, without adopting a heavyweight documentation platform.

How it helps

• Saves AI context and tokens — Agents read only relevant documents, not the entire docs folder, so responses are faster and cheaper.
• Keeps docs in sync with code — The docgraph_init tool scaffolds a standard doc set, and docgraph_sync validates cross-references and refreshes timestamps after changes.
• Tracks work as tickets — A Kanban-style board under docs/tickets/ organizes implementation tickets by status and priority, so the agent knows what to work on next.
• Gives agents context automatically — On session start, the extension tells the AI whether the graph is initialized and how to use it.

Practical use cases

• Onboard a new (or existing) project — Run docgraph_init to scaffold a consistent documentation structure, then let the agent maintain it.
• Plan and execute work — Create tickets with priorities and acceptance criteria (docgraph_ticket_create), track them on the board (/docgraph:tickets), and update their status as work proceeds.
• Keep docs trustworthy — After refactors, run docgraph_sync to catch broken links and keep the docs aligned with the implementation.

What makes it different

• Graph, not monolith — Every document has one clear responsibility and links to related docs rather than duplicating content.
• Metadata-first navigation — Each document begins with a compact metadata block (purpose, audience, dependencies), so agents judge relevance before reading the body.
• Built for AI and humans — README.md serves human onboarding while AGENTS.md acts as a router for AI agents, with the conventions written out in docs/PHILOSOPHY.md.
• Codeless to run — It's a Pi extension, so setup is a single install command; no separate server or database is required.

Features

• Selective retrieval — AI agents read only the documents relevant to the current task, not the entire docs folder.
• Ticket-driven workflows — Kanban-style ticket board under docs/tickets/ with status tracking, priorities, and acceptance criteria.
• Code-as-source-of-truth — Documentation describes the implementation; when they disagree, the code wins.
• Cross-reference validation — docgraph_sync detects broken links between documents.
• Metadata-driven navigation — Every document has a metadata block so agents can determine relevance before reading the body.
• Context injection — Automatically informs AI agents about the documentation system via before_agent_start.

Installation

Prerequisites

• Node.js ≥ 22
• Pi coding agent installed

As a Pi Extension

pi install npm:@ryanyonzon/pi-docgraph

After installation, restart your Pi session. The extension will detect whether the documentation graph has been initialized and inform the AI agent accordingly.

Quick Start

1. Initialize the documentation graph

From within a Pi session, ask the AI agent:

Run docgraph_init to scaffold the documentation structure.

This creates:

File	Purpose
README.md	Human entry point
AGENTS.md	AI agent entry point & documentation router
docs/SPEC.md	What the system does and why
docs/ARCHITECTURE.md	How the system is built
docs/API.md	Communication contracts
docs/DESIGN.md	Design system conventions
docs/ROADMAP.md	Long-term vision and direction
docs/BACKLOG.md	Current work queue
docs/tickets/	Individual implementation tickets

2. Read documentation selectively

docgraph_read docs/ARCHITECTURE.md

Returns the metadata block and body so the agent can determine relevance at a glance.

3. Create a ticket

docgraph_ticket_create "Add dark mode support" P2

4. Sync after code changes

docgraph_sync docs/API.md

Validates cross-references and updates the Last Updated timestamp.

User Commands

These are slash commands available inside Pi:

Command	Description
/docgraph:init	Check if the documentation graph is initialized
/docgraph:sync	Prompt the agent to validate and update docs
/docgraph:tickets	Display the Kanban ticket board
/docgraph:graph	Display the documentation graph structure

AI Tools

The extension registers these tools for the AI agent:

Tool	Description
docgraph_init	Scaffold the documentation structure
docgraph_read	Read a document's metadata and body
docgraph_sync	Validate cross-references and update timestamps
docgraph_update	Modify a document field
docgraph_ticket_create	Create a new implementation ticket
docgraph_ticket_update	Update ticket status, priority, or content
docgraph_ticket_list	List tickets, optionally filtered by status

Documentation Philosophy

This extension implements the conventions described in docs/PHILOSOPHY.md. The core principles are:

1. Code is the source of truth — never modify code to match docs.
2. Selective retrieval — agents should rarely need more than 1–2 documents per task.
3. Graph, not monolith — every document has one clear responsibility.
4. Metadata-first — the metadata block tells you whether to keep reading.

Project Structure

pi-docgraph/
├── src/
│   ├── index.ts          # Extension entry point
│   ├── types.ts          # Type definitions
│   ├── utils.ts          # File I/O, metadata parsing, ticket persistence
│   ├── tools/
│   │   ├── doc-init.ts   # docgraph_init implementation
│   │   ├── doc-read.ts   # docgraph_read implementation
│   │   ├── doc-sync.ts   # docgraph_sync implementation
│   │   ├── doc-update.ts # docgraph_update implementation
│   │   ├── ticket-create.ts
│   │   ├── ticket-update.ts
│   │   └── ticket-list.ts
│   ├── commands/
│   │   └── index.ts      # Slash command handlers
│   └── events/
│       └── index.ts      # Event handlers (context injection)
├── test/
│   ├── utils.test.ts     # Link-path, metadata, backlog, ticket, validation tests
│   ├── helpers.ts        # Shared mock Pi and temp-repo test helpers
│   └── <...>.test.ts     # Additional per-module test files
│                        # (tools, commands, events, lifecycle, etc.)
├── package.json
├── tsconfig.json
├── tsconfig.test.json
└── LICENSE

Related Documentation

• docs/PHILOSOPHY.md — Full documentation conventions

License

MIT © Ryan Yonzon