canary

CANARY

Agentic-Coding-Friendly Requirement Tracking System

CANARY is a requirement tracking system that embeds tokens directly into source code, enabling precise tracking of features, tests, benchmarks, and documentation. This bridges the gap between requirements and implementation, ensuring that an agent coding system has not only the ability to be precise in the specification and planning phases but the outputs of which can be measured and verified automatically.

The CANARY system is designed with autonomous AI agents in mind, providing slash commands and structured data to facilitate agent workflows. It also prescribes a test-first development approach through constitutional principles (guidance the tooling verifies via evidence, not a technical gate that blocks writing code), ensuring that quality is prioritized over speed.

Quick Start

Installation

APT (Debian/Ubuntu) – Recommended

Canary publishes .deb packages to the APT repository at apt.codepros.org (same pattern as void).

# Import the Codepros APT signing key
curl -fsSL https://apt.codepros.org/codepros-keyring.gpg | sudo tee /usr/share/keyrings/codepros-archive-keyring.gpg > /dev/null

# Add the Codepros APT repository
echo "deb [signed-by=/usr/share/keyrings/codepros-archive-keyring.gpg] https://apt.codepros.org/ stable main" | sudo tee /etc/apt/sources.list.d/codepros.list

# Update and install
sudo apt update
sudo apt install canary

From source

# Install from source
go install devnw.dev/canary/cmd/canary@latest

# Or clone and build
git clone https://gitlab.com/devnw/codepros/oss/canary
cd canary
make build

Repository (for the pages site)

The code is hosted on GitLab; github.com/devnw/canary is a read-only mirror.

• Repository: GitLab
• Code Ref: pkg.go.dev

Initialize Your Project

# Create a new project
canary init my-project

# This creates:
# .canary/
#   ├── memory/constitution.md      # Project principles
#   ├── templates/                   # Spec and plan templates
#   ├── specs/                       # Individual requirements
#   └── canary.db                    # Token database
# GAP_ANALYSIS.md                    # Requirement tracking

Your First Requirement

# Create a specification (AI agent)
/canary.specify Add user authentication with JWT tokens

/canary.plan CBIN-001

/canary.implement

# The primary functions like specify, plan, and implement can be run
# via the CLI but won't really do much for a user. They are designed
# for AI agents to call programmatically.

# User's can find all of the command options through the --help flag

# Build database and query progress
canary index
canary show CBIN-001
canary status CBIN-001

How It Works

CANARY Tokens

Tokens are structured comments that track requirements:

// CANARY: REQ=CBIN-105; FEATURE="UserAuth"; ASPECT=Security; STATUS=TESTED; TEST=TestUserAuth; UPDATED=2026-08-29
func AuthenticateUser(creds *Credentials) (*Session, error) {
    // implementation
}

Legacy Tokens & Normalization

For backward compatibility the scanner accepts older token patterns and normalizes them:

Rules:

1. Bare ID segments (e.g. REQ-7) inside a CANARY line are accepted.
2. When both a bare legacy ID and a canonical REQ= key appear, the REQ= value wins.
3. Only the final numeric segment is zero‑padded to three digits.

Use the canonical format in new code:

// CANARY: REQ=CBIN-005; FEATURE="Parser"; ASPECT=Engine; STATUS=IMPL; UPDATED=2025-10-18

Legacy forms are supported for historical tokens but should not be added to new implementations.

Token Lifecycle:

STUB → IMPL → TESTED → BENCHED

• STUB: Placeholder, not yet implemented
• IMPL: Implementation exists, tests missing
• TESTED: Declared tested — verification requires a passing evidence record for every declared test at the current commit
• BENCHED: Declared benchmarked — verification requires a bench evidence record for every declared benchmark at the current commit

Architecture Aspects

CANARY organizes code by architectural concerns:

• API - Public interfaces, exported functions
• CLI - Command-line interfaces
• Engine - Core algorithms and business logic
• Storage - Databases, persistence, repositories
• Security - Authentication, authorization, encryption
• Docs - Documentation files
• Wire - Serialization, protocols, networking
• Planner - Planning and scheduling
• Bench - Performance benchmarks
• FrontEnd - User interface
• Dist - Distribution and deployment

Dependency Management (CBIN-147)

Express dependencies between requirements:

## Dependencies

### Full Dependencies (entire requirement needed)

- CBIN-146 (Multi-Project Support - required for token namespacing)

### Partial Dependencies (specific features/aspects)

- CBIN-140:GapRepository,GapService (only gap storage needed)
- CBIN-133:Engine (only Engine aspect required)

Features:

• Circular dependency detection using DFS algorithm
• Transitive dependency resolution
• Evidence-based satisfaction (a dependency is satisfied by verified evidence, not by declared status)
• Reverse dependency queries
• ASCII tree visualization

canary deps check CBIN-147        # Check if dependencies satisfied
canary deps graph CBIN-147 --status  # Visualize dependency tree
canary deps reverse CBIN-146      # What depends on this?
canary deps validate              # Check entire graph for cycles

Verification Gates

Prevent overclaiming with evidence-based verification. A declared STATUS=TESTED or STATUS=BENCHED is only an author's claim; canary verify checks it against recorded evidence, not against the declared status:

# Scan codebase for tokens
canary scan --out status.json --csv status.csv

# Verify claims in GAP_ANALYSIS.md against recorded evidence
canary verify --root . --claims GAP_ANALYSIS.md
# Exits 0 if every claimed requirement has a passing evidence record, at the
# current commit, for every TEST=/BENCH= it declares. Exits 1 otherwise
# (including an empty claims file, and a dirty working tree — pass
# --allow-dirty to accept one).

Evidence is produced by running the real test/benchmark suite and recording the result, not by editing a token by hand. The trusted path is canary evidence run, which executes the command itself so the resulting records are marked origin: "executed" — the only origin canary verify accepts by default:

# Run tests + benchmarks under canary's own supervision, emit an evidence
# file on stdout, then merge it into the evidence store
canary evidence run --project <KEY> -- go test -count=1 -json -bench=. -benchtime=1x ./... > evidence.json
canary evidence ingest --in evidence.json --out .canary/evidence.json

# Now verification can find that evidence
canary verify --root . --claims GAP_ANALYSIS.md

If you already have a go test -json stream you did not produce with canary evidence run (e.g. captured from a CI job's logs), from-go-test maps it to evidence records instead — but since canary did not run the command itself, those records are marked origin: "imported" and canary verify refuses them by default; pass --allow-imported to accept them:

go test -count=1 -json -bench=. -benchtime=1x ./... > gotest.json
canary evidence from-go-test --project <KEY> < gotest.json > evidence.json
canary evidence ingest --in evidence.json --out .canary/evidence.json

# --allow-imported is required here: these records are origin "imported"
canary verify --root . --claims GAP_ANALYSIS.md --allow-imported

from-go-test derives the commit from --root's git HEAD and refuses a dirty working tree unless --allow-dirty is given; it validates schema and matches the record to that commit, but — like any imported evidence — does not authenticate who produced the underlying test-event stream (see the trust boundary below).

Trust boundary

A Canary evidence record is a structured assertion derived from a test-event stream, and origin is a producer label, not a cryptographic guarantee: canary evidence run stamps "executed" (canary launched the command itself, recorded the actual argv, and retained the raw output under .canary/artifacts/ keyed by its digest), from-go-test stamps "imported" (the stream came from somewhere else), and evidence ingest preserves whatever origin the input file already carries — it does not relabel records, so a CI pipeline that runs evidence run then ingests the result onto a shared store still produces "executed" records. canary verify accepts only "executed" evidence unless --allow-imported is given, and evidence produced with --allow-dirty is marked dirty and can never verify anything. Because origin is only a label, the field is only as trustworthy as the filesystem/pipeline that produced the store: nothing here authenticates who ran the command or stops a store from being hand-edited before ingest. Cross-machine trust needs a signed/attested evidence envelope, which is not designed yet — tracked as a follow-up in GAP_ANALYSIS.md.

GAP_ANALYSIS.md Format:

# Requirements Gap Analysis

## Claimed Requirements

✅ CBIN-101 - Scanner Core
✅ CBIN-102 - Verify Gate

## Gaps

- [ ] CBIN-103 - Status JSON (needs tests)

Core Commands

Query and Inspection

canary show CBIN-105          # Display all tokens for a requirement
canary files CBIN-105         # List implementation files
canary status CBIN-105        # Show progress summary
canary grep "Authentication"  # Search tokens by pattern
canary list --status TESTED --aspect API  # Filtered listing

Workflow Automation

canary next                   # Get next priority requirement
canary next --prompt          # Generate AI agent prompt
canary implement CBIN-105     # Get implementation guidance
canary implement fuzzy        # Fuzzy match requirement

Specification Management

canary specify                # Create new specification
canary specify update CBIN-105  # Modify existing spec
canary plan CBIN-105          # Generate implementation plan

Documentation Tracking

canary doc status CBIN-105 UserAuth     # Check doc currency
canary doc update --req CBIN-105        # Update doc hashes
canary doc report --show-undocumented   # Coverage report

Dependency Management

canary deps check CBIN-147         # Check dependency satisfaction
canary deps graph CBIN-147 --status  # Show dependency tree
canary deps reverse CBIN-146       # Show reverse dependencies
canary deps validate               # Detect circular dependencies

Multi-Project Support (CBIN-146)

# Global mode (default)
canary index                  # Uses ~/.canary/canary.db

# Local mode (project-specific)
canary index --local          # Uses .canary/canary.db

# Project management
canary projects list          # List all projects
canary projects add my-app    # Register project
canary projects switch my-app # Change context

Complete Workflow

For AI Agents

1. Agent runs: /canary.next
2. System returns next priority requirement with:
   - Full specification
   - Implementation plan
   - Constitution principles
   - Test-first guidance
3. Agent implements following RED-GREEN-REFACTOR
4. Agent places CANARY tokens in code
5. Agent updates token STATUS as work progresses
6. Agent verifies with /canary.scan
7. Repeat from step 1

For Human Developers

# Morning routine
canary next                   # See what's next

# Review requirement
cat .canary/specs/CBIN-105-fuzzy-search/spec.md
cat .canary/specs/CBIN-105-fuzzy-search/plan.md

# Implement with test-first
# 1. Write failing test (RED)
# 2. Implement minimum code to pass (GREEN)
# 3. Refactor (REFACTOR)
# 4. Add CANARY tokens
# 5. Update STATUS field

# Verify progress
canary status CBIN-105
canary verify --claims GAP_ANALYSIS.md

# Check what's next
canary next

Key Features

🎯 Test-First Discipline

Constitutional principles direct agents to write tests before implementation; canary verify then checks the recorded evidence:

## Article IV: Test-First Imperative

All features SHALL be implemented using test-first development (TDD).
Tests MUST be written before implementation code.

📊 Real-Time Progress Tracking

canary status CBIN-105
# Output:
# Requirement: CBIN-105 (Fuzzy Search)
# Total tokens: 8
# Status breakdown:
#   TESTED: 6 (75%)
#   IMPL: 1 (12.5%)
#   STUB: 1 (12.5%)
# Incomplete work:
#   - FuzzyRanking (Engine): IMPL → needs tests
#   - FuzzyConfig (API): STUB → not implemented

🔍 Powerful Search

canary grep Authentication
# Searches across:
# - Requirement IDs
# - Feature names
# - Aspects
# - Owners
# - Files
# Returns tokens with file locations and line numbers

📚 Documentation Currency

Track documentation status with cryptographic hashes:

// CANARY: REQ=CBIN-105; FEATURE="FuzzySearch"; ASPECT=Engine; STATUS=TESTED; TEST=TestFuzzySearch; DOC=user:docs/user/search-guide.md; DOC_HASH=a3f5b8c2e1d4a6f9; UPDATED=2026-08-29

canary doc status CBIN-105 FuzzySearch
# Status: DOC_CURRENT (hash matches)

# After editing docs/user/search-guide.md:
canary doc status CBIN-105 FuzzySearch
# Status: DOC_STALE (hash mismatch)

canary doc update --req CBIN-105 --feature FuzzySearch
# Recalculates and updates DOC_HASH

🔗 Dependency Tracking

Full dependency graph with cycle detection:

canary deps graph CBIN-147 --status
# Output:
# CBIN-147 (Specification Dependencies)
# ├── ✅ CBIN-146 (Multi-Project Support)
# │   └── ✅ CBIN-129 (Database Migrations)
# └── ✅ CBIN-140:GapRepository,GapService
#     ├── ✅ CBIN-133:Engine
#     └── ❌ CBIN-135:Storage (STATUS=IMPL, needs tests)
#
# Summary: 3 satisfied, 1 blocking

🤖 AI Agent Integration

Slash commands for autonomous workflows:

• /canary.next - Get next priority with full context
• /canary.show <req-id> - Display requirement tokens
• /canary.status <req-id> - Check progress
• /canary.implement <req-id> - Get implementation guidance
• /canary.scan - Verify token placement
• /canary.specify - Create new requirement
• /canary.plan <req-id> - Generate implementation plan

🚀 GitHub Copilot Integration

CANARY automatically configures GitHub Copilot with project-specific instructions:

canary init my-project
# Creates .github/instructions/ with CANARY workflow guidance

What Gets Configured:

• Repository-wide instructions - CANARY token format, test-first development, constitutional principles
• Path-specific guidance - Context-aware help for specs, tests, and .canary/ directory
• Automatic discovery - Works with both GitHub Copilot CLI and VS Code Copilot Chat

Instruction Files Created:

.github/instructions/
├── repository.md              # CANARY workflow fundamentals
├── .canary/
│   ├── instruction.md        # CANARY directory guidelines
│   └── specs/
│       └── instruction.md    # Specification writing (WHAT/WHY, not HOW)
└── tests/
    └── instruction.md        # Test-first development guidelines

Verification:

# Using GitHub Copilot CLI
gh copilot suggest "What is the CANARY token format?"

# Using VS Code Copilot Chat
# Ask: "@workspace What is the CANARY token format?"

Features:

• ✅ Zero manual configuration required
• ✅ Preserves custom instructions on re-init
• ✅ Project key substitution in templates
• ✅ Compatible with Copilot CLI and VS Code

Re-initialization Safe:

# Customize your instructions
echo "# Custom Rule" >> .github/instructions/repository.md

# Re-run init - your customizations are preserved
canary init --local
# ⏭️  Skipping existing instruction file: repository.md

Documentation

User Documentation

• Getting Started Guide - Installation, core concepts, complete walkthrough
• Query Commands Guide - show, files, status, grep commands
• Next Priority Guide - Automated workflow assistant
• Implement Command Guide - Implementation guidance
• Specification Modification Guide - Creating and updating specs
• Documentation Tracking Guide - DOC= and DOC_HASH= fields

Developer Documentation

• CLAUDE.md - AI agent context and slash commands
• .canary/AGENT_CONTEXT.md - Complete agent reference
• REQUIREMENTS.md - Original self-canary requirements
• CANARY_POLICY.md - Token format and policy

Architecture Documentation

• Architecture Decision Records - ADR-001: Documentation Tracking

Project Structure

canary/
├── cmd/canary/              # Main CLI application
│   ├── main.go             # CLI entry point and command registration
│   └── *_test.go           # Command tests
├── cli/                    # Root command assembly (Commands())
├── pkg/
│   ├── canaryscan/         # The scanner and token parser
│   ├── specs/              # Specification and dependency engine
│   ├── storage/            # SQLite database layer + migrations
│   ├── cmds/               # One package per CLI subcommand
│   ├── sources/            # Requirement-ID source configuration
│   ├── ticket/             # Ticket-destination integrations
│   └── ...                 # evidence, drift, upgrade, migrate, etc.
├── mcp/                    # MCP server for AI-assistant integration
├── gate/                   # Managed-marker engine (init doc updates)
├── .canary/
│   ├── memory/
│   │   └── constitution.md          # Project principles
│   ├── templates/
│   │   ├── spec-template.md         # Requirement template
│   │   └── plan-template.md         # Implementation plan template
│   └── specs/
│       └── CBIN-XXX-feature/        # Individual requirements
│           ├── spec.md
│           └── plan.md
├── docs/
│   ├── user/               # User-facing documentation
│   ├── architecture/       # Architecture decision records
│   └── *.md                # Various docs
├── GAP_ANALYSIS.md         # Requirement tracking
├── CLAUDE.md               # AI agent guide
└── README.md               # This file

Development

Build

make build          # Build binary
make test           # Run tests
make bench          # Run benchmarks
make fuzz           # Run fuzz targets
make verify         # Self-verify with CANARY: scan, produce evidence, canary verify

Self-Canary

CANARY uses itself for requirement tracking:

# Scan the codebase
canary scan --root . --out status.json --csv status.csv

# Produce evidence from the real test run (this is what `make verify` does),
# then verify claims against it
canary evidence run --project <KEY> -- go test -count=1 -json ./... > evidence.json
canary evidence ingest --in evidence.json --out .canary/evidence.json
canary verify --claims GAP_ANALYSIS.md

# Check dependencies
canary deps validate

canary scan --verify is a deprecated spelling that now delegates entirely to canary verify — same checks, same verdict, same exit code. Use canary verify directly.

Testing

# Unit tests
go test ./...

# Package tests (scanner, specs engine, storage, ...)
go test ./pkg/specs/...

# Benchmarks
go test ./pkg/... -bench=. -benchmem

# Audit acceptance tests
go test ./internal/audit/...

MCP Server

CANARY ships an MCP (Model Context Protocol) server so AI assistants can drive it through tools rather than shelling out:

canary mcp

• Bind address: the server listens on 127.0.0.1 (loopback) by default, so it is not reachable off the host unless you deliberately expose it.
• Auth model: mutating tools require a bearer token; read-only tools can be gated behind a separate read token. On a loopback bind with no token configured, requests from localhost are accepted.
• Tool list: the authoritative, generated list of exposed tools lives in docs/MCP_TOOLS.md. See docs/MCP_QUICK_START.md for IDE wiring.

Contributing

We welcome contributions! Please:

1. Check existing requirements: canary list
2. Create a specification: canary specify
3. Follow test-first development
4. Place CANARY tokens in your code
5. Update documentation with DOC= fields
6. Verify before submitting: canary verify --claims GAP_ANALYSIS.md

See CONTRIBUTING.md for detailed guidelines.

License

Licensed under the terms found in LICENSE.

Acknowledgments

CANARY was inspired by:

• spec-kit methodology for requirement-first development
• Test-Driven Development (TDD) principles
• Evidence-based claims — inspired by formal verification (CANARY does not perform formal verification)
• Zero-trust verification — inspiration from security engineering; see the trust boundary below for what is and is not authenticated

Built with love by Developer Network.

Related Projects

• Claude Code - AI coding assistant with CANARY integration
• spec-kit - Specification-driven development methodology

Getting Help

• Documentation: Start with Getting Started Guide
• Command Help: canary --help or canary <command> --help
• GitLab Issues: Report bugs and request features
• Discussions: no separate Discussions forum; use Issues

Ready to start? → Getting Started Guide

For AI Agents → CLAUDE.md

For API Documentation → pkg.go.dev

CANARY: Making every feature claim searchable, verifiable, and traceable.