canary

README

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 enforces a test-first development approach through constitutional principles, 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://github.com/devnw/canary.git
cd canary
make build

Repository (for the pages site)

The code is hosted on GitHub:

• Repository: Github
• 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=2025-10-18
func AuthenticateUser(creds *Credentials) (*Session, error) {
    // implementation
}

Legacy Tokens & Normalization

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

Legacy Form	Normalized
CBIN-5	CBIN-005
CBIN-42	CBIN-042
REQ-7	REQ-007
REQ-12	REQ-012
REQ-GQL-4	REQ-GQL-004

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: Fully tested with passing tests
• BENCHED: Tested and performance benchmarked

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
• Status-based satisfaction (only TESTED/BENCHED satisfy)
• 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 automatic verification:

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

# Verify claims in GAP_ANALYSIS.md
canary scan --verify GAP_ANALYSIS.md --strict
# Exits with code 2 if:
# - Claimed requirements lack TESTED/BENCHED status
# - Tokens are stale (>30 days old)

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 scan --verify GAP_ANALYSIS.md

# Check what's next
canary next

Key Features

🎯 Test-First Enforcement

Constitutional principles ensure tests before implementation:

## 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=2025-10-18

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
│   ├── deps.go             # Dependency management commands (CBIN-147)
│   └── *_test.go           # Command tests
├── internal/
│   ├── specs/              # Specification and dependency engine
│   │   ├── types.go        # Data models (Token, Dependency, Graph)
│   │   ├── parser_dependency.go      # Dependency parser
│   │   ├── validator.go             # Circular dependency detection
│   │   ├── status_checker.go        # Dependency satisfaction
│   │   ├── graph_generator.go       # Tree visualization
│   │   └── *_test.go                # Comprehensive test suite
│   └── storage/            # SQLite database layer
│       ├── storage.go      # Database operations
│       └── migrations.go   # Schema migrations
├── .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
├── tools/canary/           # Legacy scanner (CBIN-101, 102, 103)
├── GAP_ANALYSIS.md         # Requirement tracking
├── CLAUDE.md               # AI agent guide
└── README.md               # This file

Performance

CANARY is designed for speed and efficiency:

• Circular Detection: O(V+E) using DFS, <209ms for 500 requirements
• Database Queries: SQLite with indexes, <50ms for typical queries
• Scanning: Streams file I/O, <10s for 50k files
• Memory: ≤512 MiB RSS for large repositories

Development

Build

make build          # Build binary
make test           # Run tests
make bench          # Run benchmarks
make verify         # Self-verify with CANARY

Self-Canary

CANARY uses itself for requirement tracking:

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

# Verify claims
canary scan --verify GAP_ANALYSIS.md --strict

# Check dependencies
canary deps validate

Testing

# Unit tests
go test ./...

# Integration tests
go test ./internal/specs -run Integration

# Benchmarks
go test ./internal/specs -bench=. -benchmem

# Acceptance tests
go test ./tools/canary/internal -run Acceptance -v

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 scan --verify 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 from formal verification
• Zero-trust verification from security engineering

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
• GitHub Issues: Report bugs and request features
• Discussions: Ask questions and share experiences

---

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.

Documentation

Index

• Constants
• func CheckStaleness(rep Report, dur time.Duration) error
• func FormatFilesList(fileGroups map[string][]*storage.Token) string
• func FormatGrepResults(tokens []*storage.Token) string
• func FormatGrepResultsByRequirement(tokens []*storage.Token) string
• func FormatTokensTable(tokens []*storage.Token, groupBy string) string
• func GrepTokens(db *storage.DB, pattern string, limit int) ([]*storage.Token, error)
• func GroupTokens(tokens []*storage.Token, groupBy string) map[string][]*storage.Token
• func ParseGAPClaims(path string) (map[string]claim, error)
• func Run(rep Report, out, csv string) error
• func VerifyClaims(rep Report, claims map[string]claim) error
• func WriteCSV(rep Report, path string) error
• type Canary
• type Report
  • func Scan(root string) (Report, error)

Constants

const CanaryEnd = "END"

const CanaryKey = "CANARY"

const CanaryStart = "START"

const CommentPrefix = "<!--"

const CommentSuffix = "-->"

Functions

func CheckStaleness

func CheckStaleness(rep Report, dur time.Duration) error

CheckStaleness delegates to gate.CheckStalenessTokens for consistency.

func FormatFilesList

func FormatFilesList(fileGroups map[string][]*storage.Token) string

FormatFilesList converts fileGroups (map[file][]tokens) into a human-readable summary grouped by aspect.

func FormatGrepResults

func FormatGrepResults(tokens []*storage.Token) string

FormatGrepResults returns human readable list output for grep tokens.

func FormatGrepResultsByRequirement

func FormatGrepResultsByRequirement(tokens []*storage.Token) string

FormatGrepResultsByRequirement groups grep tokens by requirement.

func FormatTokensTable

func FormatTokensTable(tokens []*storage.Token, groupBy string) string

FormatTokensTable renders grouped tokens (used by show command).

func GrepTokens

func GrepTokens(db *storage.DB, pattern string, limit int) ([]*storage.Token, error)

CANARY: REQ=CBIN-205; FEATURE="ContextCaps"; ASPECT=API; STATUS=IMPL; UPDATED=2026-08-28 GrepTokens returns tokens whose feature/file/test/bench/reqID match pattern (case-insensitive substring), bounded by limit (<=0 uses the storage layer's own small default; see storage.DefaultSearchLimit).

NOTE: SearchTokens' SQL already matches keywords, feature, req_id, file_path, test, and bench columns (bounded by LIMIT), so a single bounded call covers every column this function's contract advertises. Previously this loaded the entire token table via db.ListTokens(nil, "", "", 0) to catch file/test/bench matches that the old (narrower) SearchTokens couldn't produce; that full-table union is no longer needed now that SearchTokens covers those columns itself.

func GroupTokens

func GroupTokens(tokens []*storage.Token, groupBy string) map[string][]*storage.Token

GroupTokens groups tokens by aspect/status (default aspect).

func ParseGAPClaims

func ParseGAPClaims(path string) (map[string]claim, error)

func Run

func Run(rep Report, out, csv string) error

Run executes a scan and writes JSON/CSV outputs. Caller supplies already-built report. This separates CLI main from library logic.

func VerifyClaims

func VerifyClaims(rep Report, claims map[string]claim) error

func WriteCSV

func WriteCSV(rep Report, path string) error

WriteCSV unchanged; moved here after refactor for legacy consumers.

Types

type Canary

type Canary struct {
	Key   string
	Start string
	End   string
}

type Report

type Report struct {
	GeneratedAt  time.Time        `json:"generated_at"`
	Requirements []requirementRow `json:"requirements"`
	Summary      summary          `json:"summary"`
}

Report is the canonical legacy output structure retained for backward compatibility.

func Scan

func Scan(root string) (Report, error)

Scan now delegates to the generic gate.Scanner, converting the result into the legacy report. Backward-compatible: existing tests and callers expect auto-promotion logic preserved.