CANON.yaml Reference

Deprecation Notice

SPECWRIGHT.yaml is deprecated but still supported for backward compatibility. Canon checks for CANON.yaml first, then falls back to SPECWRIGHT.yaml. New projects should use CANON.yaml.

The CANON.yaml file configures Canon behavior for a repository. Place it in the repository root.

Schema

# Required
version: "1"

# Optional: team metadata
team: string              # Team name
ticket_system: string     # Default ticket system (jira, linear, github)
project_key: string       # Default project key
slack_channel: string     # Slack channel for notifications

# Spec configuration
specs:
  doc_paths: string[]     # Glob patterns for files to index
  auto_tickets: boolean   # Auto-create tickets from spec sections
  require_review: boolean # Require review before ticket creation

# Agent behavior
agents:
  pr_analysis: boolean    # Enable PR analysis comments
  doc_updates: boolean    # Enable doc update suggestions
  stale_detection: string | false  # Duration or false
  realization_check: boolean       # Enable AC realization tracking

# Simple ticket sync
sync:
  system: string          # jira, linear, or github
  project_key: string     # Project key for ticket creation
  create_tickets: boolean # Auto-create tickets
  reverse_sync: boolean   # Sync ticket status back to specs

# Advanced: multi-system ticket routing
ticket_systems:
  <name>:
    system: string        # jira, linear, or github
    project: string       # Project key
    status_map:           # Spec status → ticket status mapping
      draft: string
      todo: string
      in_progress: string
      done: string
      blocked: string
      deprecated: string
    hierarchy:            # Section depth → issue type mapping
      2: string           # e.g., "Epic"
      3: string           # e.g., "Story"
      4: string           # e.g., "Sub-task"
    auto_parent: boolean  # Auto-link child tickets to parent

routing:
  - match:
      tags: string[]      # Match on spec tags
      team: string        # Match on team
      default: boolean    # Default route
    target: string        # ticket_systems key

Fields

version

Required. Schema version. Currently only "1" is supported.

team

Team name used for ticket routing and dashboards.

ticket_system

Default ticket system. One of: jira, linear, github.

project_key

Default project key for ticket creation (Jira project key, Linear team key, or GitHub owner/repo).

slack_channel

Slack channel for notifications (e.g., "#payments-eng").

specs

specs.doc_paths

Type: string[]Default: ["docs/specs/*.md"]

Glob patterns for files to index. All matched files become part of the agent's knowledge base.

specs:
  doc_paths:
    - "docs/specs/*.md"
    - "docs/**/*.md"
    - "README.md"
    - "CHANGELOG.md"

specs.auto_tickets

Type: booleanDefault: false

When true, the agent automatically creates tickets from spec sections.

specs.require_review

Type: booleanDefault: true

When true, auto-created tickets require review before creation.

agents

agents.pr_analysis

Type: booleanDefault: true

Enable PR analysis comments. Set to false to disable the bot commenting on PRs.

agents.doc_updates

Type: booleanDefault: true

Enable doc update suggestions in PR comments.

agents.stale_detection

Type: string | falseDefault: "30d"

Duration string (e.g., "30d", "7d") before flagging stale sections, or false to disable.

agents.realization_check

Type: booleanDefault: true

Enable acceptance criteria realization tracking in PR analysis.

sync

Simple ticket sync configuration. For multi-system routing, use ticket_systems instead.

sync.system

Type: string

Ticket system: jira, linear, or github.

sync.project_key

Type: string

Project key for ticket creation.

sync.create_tickets

Type: booleanDefault: true

Auto-create tickets from spec sections.

sync.reverse_sync

Type: booleanDefault: true

Sync ticket status changes back to specs.

ticket_systems / routing

Advanced multi-system ticket routing. See the Ticket Sync guide for detailed usage.

Examples

Minimal

version: "1"

specs:
  doc_paths:
    - "docs/specs/*.md"

Full-Featured

version: "1"

team: payments
ticket_system: jira
project_key: PAY
slack_channel: "#payments-eng"

specs:
  doc_paths:
    - "docs/specs/*.md"
    - "docs/**/*.md"
    - "README.md"
    - "CHANGELOG.md"
  auto_tickets: true
  require_review: true

agents:
  pr_analysis: true
  doc_updates: true
  stale_detection: "30d"
  realization_check: true

sync:
  system: jira
  project_key: PAY
  create_tickets: true
  reverse_sync: true