docs

Coograph is a graph-first context layer for AI coding agents. The OSS core ships in the repo and is MIT-licensed. These docs are the short version. The repo's README is the long version and stays canonical.

Where to start

• Getting started: install, first build, first query.
• Code graph: what the graph contains, how it's built, how to query it.
• Workflow: Plan → Propose → Apply → Review → Archive, and the agents that drive it.
• Ultra review: the optional multi-agent review for big changes: hostile reviewers, refuters, a verdict, and a stop rule.
• OpenSpec: the four files every change is written in, the gate, and how the archive feeds Retro.
• Models: run each agent on a different model, opt-in, never defaulted, and always reported.
• Retro: records broken rules and session cost, proposes instruction and hook edits as an OpenSpec.
• Instruction layout: keep instruction files under a budget per tier, surface gotchas only when they apply, restructure maps that grew into changelogs.

Two posture rules

Two non-negotiable rules ship with every project Coograph initializes. Both live as banners at the top of CLAUDE.md and .github/copilot-instructions.md:

• CODE-GRAPH FIRST — every codebase navigation starts with a graph query. Grep is fallback, only when the graph is genuinely absent.
• OPENSPEC OR STOP — multi-file or behavior-changing edits go through an OpenSpec proposal that the user approves before code is written.

Both rules are designed to be impossible to "forget mid-conversation." See Workflow.

Repo layout

.github/code-graph/      — MCP server, parsers, git hooks
.github/agents/          — Planner, Reviewer, Debugger, Verifier, Explore, Retro
.github/skills/          — coograph-propose, coograph-apply, etc.
.github/retro/           — Retro analyzer, rule registry, README
.github/scripts/         — Drift, idempotency and plugin-sync checks
.claude/hooks/           — Lifecycle hooks (block-generated, log-bash, capture-signals, …)
.agents/ .codex/ .opencode/ — Per-tool native config
plugin/                  — Generated Claude Code plugin
.claude-plugin/          — Marketplace manifest
openspec/changes/        — Active proposals
openspec/changes/archive/— Completed proposals
examples/                — A finished initialized project

License

MIT. Free forever for the OSS core. Pro is bespoke services — see /pro.