canon

Canon

Spec-driven development, automated.
Write structured specs in markdown. AI agents handle PR reviews, ticket sync, and code verification.

---

The Problem

Documentation drifts the moment it's written. Specs live in Notion or Confluence, disconnected from the code they describe. Tickets lose context. Nobody knows if what shipped actually matches what was planned.

Canon fixes this by treating specs as living programs — structured markdown that AI agents continuously verify against your codebase.

What Canon Does

Spec-Aware PR Reviews — When a PR opens, Canon analyzes the diff against relevant specs, identifies which acceptance criteria are addressed, and flags gaps.

Bidirectional Ticket Sync — Spec sections become tickets in Jira, Linear, or GitHub Issues. Close a ticket and the spec updates. Mark a section done and the ticket closes.

Code-Aware Verification — AI reads your code to verify that acceptance criteria are actually implemented — not just that a ticket was closed.

Coverage Dashboard — Track spec completion across your org by repo, team, and status.

CLI & MCP Server — The canon CLI provides plan, verify, status, and sync commands. The MCP server gives any AI coding agent (Claude Code, Cursor, Windsurf) access to your spec knowledge base.

How It Works

                    ┌─────────────────┐
                    │   PM writes     │
                    │  structured     │
                    │     spec        │
                    └───────┬─────────┘
                            │
                            ▼
              ┌─────────────────────────────┐
              │   Canon indexes all markdown │
              │  (specs, ADRs, guides, READMEs) │
              └─────────────┬───────────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
     ┌────────────┐ ┌────────────┐ ┌────────────┐
     │ PR opened  │ │  Tickets   │ │ Cron: spec │
     │ → analyze  │ │ → sync     │ │ → verify   │
     │   vs spec  │ │   sections │ │   vs code  │
     └─────┬──────┘ └─────┬──────┘ └─────┬──────┘
           │              │              │
           └──────────────┼──────────────┘
                          ▼
              ┌─────────────────────────────┐
              │   Spec updates with evidence │
              │   (realized-in, status, PRs)  │
              └─────────────────────────────┘

Specs define intent (what should be built). Code reveals reality (what shipped). Canon closes the loop between the two.

Choose Your Path

Path	Best for	What you get
GitHub App	Teams wanting full automation	PR analysis, ticket sync, doc maintenance, coverage dashboard
CLI	Individual developers	canon setup, status, sync, verify, plan, audit
MCP Server	AI-assisted development	Spec search and context in Claude Code, Cursor, Windsurf
Claude Code Plugin	Claude Code users	Slash commands for spec-driven workflows
Self-Hosted	Full control	Deploy on your own K8s cluster

Quick Start

Install

pip install canonhq        # CLI + MCP server
canon setup                # Creates CANON.yaml in your repo

Create a spec with AI

Using the Claude Code plugin:

> /canon-new

Creating spec: User Authentication
✓ Generated docs/specs/user-auth.md with 4 sections, 12 acceptance criteria

Or connect any MCP-compatible agent (Claude Code, Cursor, Windsurf) to the Canon knowledge base:

{
  "mcpServers": {
    "canon": {
      "command": "uvx",
      "args": ["--from", "canonhq", "canon-mcp"]
    }
  }
}

Work with specs