CANARY CLI Getting Started Guide

Last Updated: 2025-10-17

Overview

CANARY is a requirement tracking system that embeds tokens directly into source code, enabling precise tracking of features, tests, and documentation. This guide walks you through installing CANARY, understanding core concepts, and using the system effectively for both AI agents and human developers.

What You'll Learn:

Installing and initializing CANARY
Understanding CANARY tokens and their lifecycle
Core workflow: specify → plan → implement → verify
Querying and inspecting implementation progress
Maintaining documentation currency

Prerequisites

Go 1.20 or later installed
Git repository for your project (recommended)
Text editor or IDE

Installation

From Source

# Clone the repository
git clone https://github.com/yourusername/canary.git
cd canary

# Install the CLI
go install ./cmd/canary

# Verify installation
canary version

Quick Test

canary --help

You should see available commands including init, specify, plan, show, next, and more.

Core Concepts

CANARY Tokens

CANARY tokens are structured comments embedded in your code:

// CANARY: REQ=CBIN-105; FEATURE="Authentication"; ASPECT=API; STATUS=TESTED; UPDATED=2025-10-17

Token Fields:

REQ - Requirement ID (format: CBIN-###)
FEATURE - Short feature name (CamelCase, quoted)
ASPECT - Architecture aspect (API, CLI, Engine, Storage, Docs, etc.)
STATUS - Implementation status (STUB, IMPL, TESTED, BENCHED)
TEST - Test function name (when STATUS=TESTED)
BENCH - Benchmark function name (when STATUS=BENCHED)
DOC - Documentation reference (type:path, e.g., user:docs/user/guide.md)
DOC_HASH - SHA256 hash of documentation (first 16 chars)
UPDATED - Last modification date (YYYY-MM-DD)
OWNER - Owner/team identifier

Status Progression

Features follow a strict lifecycle:

STUB → IMPL → TESTED → BENCHED

STUB: Not yet implemented (placeholder)
IMPL: Implementation exists, tests missing
TESTED: Implementation complete with passing tests
BENCHED: Fully tested and performance benchmarked

Valid Aspects

CANARY organizes code by architectural aspects:

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

Quick Start: Your First CANARY Project

Step 1: Initialize a New Project

# Create project directory
mkdir my-app
cd my-app

# Initialize Go module
go mod init github.com/yourusername/my-app

# Initialize CANARY
canary init my-app

What this creates:

my-app/
├── .canary/
│   ├── memory/
│   │   └── constitution.md     # Project principles (empty template)
│   ├── templates/
│   │   ├── spec-template.md    # Requirement specification template
│   │   └── plan-template.md    # Implementation plan template
│   └── specs/                  # Individual requirement directories
├── GAP_ANALYSIS.md              # Requirement tracking
└── README.md                    # Project documentation

Step 2: Establish Project Principles

Before implementing features, define your project's governing principles:

# For AI agents (using slash commands)
/canary.constitution Create principles for test-first development and simplicity

# For human developers (manual creation)
# Edit .canary/memory/constitution.md with your team's principles

Example constitution.md:

# Project Constitution

## Article I: Test-First Imperative
All features SHALL be implemented using test-first development.
Tests MUST be written before implementation.

## Article II: Simplicity First
Prefer simple, direct solutions over complex abstractions.
Use Go standard library when possible.

## Article III: Documentation Currency
All TESTED features MUST have current documentation.
Documentation MUST be updated when behavior changes.

Step 3: Specify Your First Requirement

Use the /canary.specify command (AI agents) or canary specify CLI to create structured requirements:

# AI agent approach
/canary.specify Add user authentication with JWT tokens and password hashing

# Human developer approach (interactive)
canary specify
# Follow prompts to create requirement

This creates a specification at .canary/specs/CBIN-001-user-authentication/spec.md with:

Requirement ID (auto-generated)
User stories
Functional requirements
Acceptance criteria
Success metrics
Dependencies and constraints

See Specification Modification Guide for detailed information.

Step 4: Create an Implementation Plan

Generate technical guidance for your requirement:

# AI agent approach
/canary.plan CBIN-001 Use bcrypt for password hashing, standard library JWT

# Human developer approach
canary plan CBIN-001

This creates .canary/specs/CBIN-001-user-authentication/plan.md with:

Technical approach
File structure
Token placement strategy
Test plan
Implementation checklist

Step 5: Implement the Feature

Follow test-first development:

A. Write Tests First (RED phase)

// internal/auth/auth_test.go

// CANARY: REQ=CBIN-001; FEATURE="Authentication"; ASPECT=Security; STATUS=STUB; UPDATED=2025-10-17
func TestCANARY_CBIN_001_Security_PasswordHashing(t *testing.T) {
    password := "secure-password-123"

    // Hash password
    hashed, err := HashPassword(password)
    if err != nil {
        t.Fatalf("HashPassword failed: %v", err)
    }

    // Verify correct password
    if !VerifyPassword(hashed, password) {
        t.Error("VerifyPassword failed for correct password")
    }

    // Verify wrong password
    if VerifyPassword(hashed, "wrong-password") {
        t.Error("VerifyPassword succeeded for wrong password")
    }
}

Run tests (should fail):

go test ./internal/auth/
# Expected: FAIL (HashPassword and VerifyPassword don't exist yet)

B. Implement Feature (GREEN phase)

// internal/auth/auth.go

// CANARY: REQ=CBIN-001; FEATURE="Authentication"; ASPECT=Security; STATUS=IMPL; UPDATED=2025-10-17
package auth

import (
    "golang.org/x/crypto/bcrypt"
)

// HashPassword generates a bcrypt hash for the given password.
func HashPassword(password string) (string, error) {
    bytes, err := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
    return string(bytes), err
}

// VerifyPassword checks if the password matches the hash.
func VerifyPassword(hash, password string) bool {
    err := bcrypt.CompareHashAndPassword([]byte(hash), []byte(password))
    return err == nil
}

Run tests (should pass):

go test ./internal/auth/
# Expected: PASS

C. Update Token Status to TESTED

// internal/auth/auth_test.go

// CANARY: REQ=CBIN-001; FEATURE="Authentication"; ASPECT=Security; STATUS=TESTED; TEST=TestCANARY_CBIN_001_Security_PasswordHashing; UPDATED=2025-10-17
func TestCANARY_CBIN_001_Security_PasswordHashing(t *testing.T) {
    // ... test code ...
}

// internal/auth/auth.go

// CANARY: REQ=CBIN-001; FEATURE="Authentication"; ASPECT=Security; STATUS=TESTED; TEST=TestCANARY_CBIN_001_Security_PasswordHashing; UPDATED=2025-10-17
package auth
// ... implementation ...

Step 6: Index and Query Your Progress

Build the database for fast queries:

canary index

Inspect your implementation:

# Show all tokens for CBIN-001
canary show CBIN-001

# List implementation files
canary files CBIN-001

# Check completion status
canary status CBIN-001

See Query Commands Guide for detailed query capabilities.

Step 7: Scan and Verify

Generate progress reports:

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

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

Step 8: Document the Feature

Create user documentation:

# Create documentation file
vim docs/user/authentication-guide.md
# Write comprehensive user guide...

# Update token with DOC field
# In your source file:
// CANARY: REQ=CBIN-001; FEATURE="Authentication"; ASPECT=Security; STATUS=TESTED; TEST=TestCANARY_CBIN_001_Security_PasswordHashing; DOC=user:docs/user/authentication-guide.md; UPDATED=2025-10-17

# Calculate and add hash
canary doc update --req CBIN-001 --feature Authentication

# Verify documentation status
canary doc status CBIN-001 Authentication
# Expected: DOC_CURRENT

See Documentation Tracking Guide for details.

Core Workflows

Workflow 1: Autonomous AI Agent

AI agents can work independently using slash commands:

1. Agent completes current task
2. Agent runs: /canary.next
3. System returns next priority requirement with full guidance
4. Agent implements following test-first approach
5. Agent places CANARY tokens and updates status
6. Agent verifies with /canary.scan
7. Repeat from step 2

This creates a continuous implementation loop.

Workflow 2: Human Developer Daily Work

# Morning: Check what's next
canary next

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

# Get implementation guidance
canary next --prompt > implementation-guidance.md

# Implement following guidance
# ... write tests ...
# ... write implementation ...
# ... place tokens ...

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

# Check what's next
canary next

See Next Priority Guide for advanced usage.

Workflow 3: Feature Discovery and Modification

Search and update existing requirements:

# Search for authentication-related features
canary grep Authentication

# Find specific requirement
canary list --status IMPL | grep "Auth"

# Update existing specification
canary specify update CBIN-001
# Interactive prompts guide you through modification

See Specification Modification Guide for details.

Workflow 4: Implementation Guidance

Get detailed guidance for specific requirements:

# Get full implementation prompt
canary implement CBIN-105

# Or use fuzzy matching
canary implement fuzzy
# Selects best match for "fuzzy" keyword

See Implement Command Guide for details.

Querying and Inspecting Progress

CANARY provides four powerful query commands:

Show All Tokens

canary show CBIN-105

Displays all tokens for a requirement with:

Feature name
Aspect
Status
File location and line number
Test names
Owner

List Implementation Files

canary files CBIN-105

Shows which files contain implementations, grouped by aspect, with token counts.

Check Progress Summary

canary status CBIN-105

Displays:

Total tokens
Count by status (STUB, IMPL, TESTED, BENCHED)
Completion percentage
List of incomplete work

Search by Pattern

canary grep "FuzzyMatch"

Searches across:

Requirement IDs
Feature names
Aspects
Owners
Keywords

See Query Commands Guide for complete reference.

Best Practices

For AI Agents

Always start with constitution - Reference .canary/memory/constitution.md before implementing
Use test-first workflow - RED → GREEN → REFACTOR
Update tokens immediately - Change STATUS as you progress
Run /canary.next after each completion - Get next priority automatically
Verify with /canary.scan - Ensure tokens are correctly placed

For Human Developers

Morning routine - Start with canary next to see priorities
Write tests first - Follow RED → GREEN → REFACTOR religiously
Use query commands - Inspect progress with show/files/status
Update UPDATED field - Change date when modifying implementations
Document TESTED features - Add DOC= fields for completed work
Verify regularly - Run canary scan --verify GAP_ANALYSIS.md

For Teams

Establish constitution early - Define principles before implementing
Use ASPECT consistently - Agree on aspect taxonomy
Review token placement - Ensure tokens mark actual implementation locations
Track documentation currency - Use DOC= and DOC_HASH= fields
Automate scanning - Add canary scan to CI/CD pipeline
Update priorities - Use canary prioritize to reflect changing needs

Common Pitfalls

Pitfall 1: Skipping Tests

Problem: Marking STATUS=TESTED without TEST= field

Solution:

// Wrong
// CANARY: REQ=CBIN-105; FEATURE="Search"; ASPECT=API; STATUS=TESTED; UPDATED=2025-10-17

// Correct
// CANARY: REQ=CBIN-105; FEATURE="Search"; ASPECT=API; STATUS=TESTED; TEST=TestCANARY_CBIN_105_API_FuzzySearch; UPDATED=2025-10-17

Pitfall 2: Stale Documentation

Problem: Documentation exists but hasn't been updated after code changes

Solution: Use documentation tracking:

canary doc status CBIN-105 Search
# Shows: DOC_STALE (hash mismatch)

# Update documentation, then:
canary doc update --req CBIN-105 --feature Search

Pitfall 3: Missing Tokens in Implementation

Problem: Specification has tokens, implementation files don't

Solution: Place tokens at actual implementation locations:

// internal/search/fuzzy.go

// CANARY: REQ=CBIN-105; FEATURE="FuzzySearch"; ASPECT=Engine; STATUS=TESTED; TEST=TestFuzzyMatch; UPDATED=2025-10-17
func FuzzyMatch(pattern, text string) bool {
    // Implementation...
}

Pitfall 4: Inconsistent UPDATED Dates

Problem: Forgetting to update UPDATED field when modifying code

Solution: Use automated staleness detection:

canary scan --update-stale
# Automatically updates UPDATED field for tokens older than 30 days

Troubleshooting

Problem: "No tokens found"

canary show CBIN-999
# Error: no tokens found for CBIN-999

Solutions:

Verify requirement exists: canary list | grep CBIN-999
Check token format: grep -r "CBIN-999" .
Rebuild database: canary index

Problem: Database queries slow

canary show CBIN-105
# Takes >1 second

Solutions:

Check database exists: ls .canary/canary.db
Rebuild index: canary index
Check file count: Database is optimized for <10,000 files

Problem: Documentation shows as DOC_STALE

canary doc status CBIN-105 Search
# Status: DOC_STALE (hash mismatch)

Solutions:

Verify documentation was updated: git diff docs/user/search-guide.md
Recalculate hash: canary doc update --req CBIN-105 --feature Search
Check for typos in DOC path

Advanced Topics

Custom Aspects

Define project-specific aspects in your constitution:

## Valid Aspects

- **CustomerAPI** - Customer-facing API endpoints
- **AdminAPI** - Administrative API endpoints
- **Reporting** - Report generation and analytics

Use consistently across all tokens.

Priority Management

Control implementation order:

// CANARY: REQ=CBIN-105; FEATURE="Search"; ASPECT=API; STATUS=STUB; PRIORITY=1; UPDATED=2025-10-17

Lower numbers = higher priority. Use canary next to automatically select highest priority.

Dependency Tracking

Express dependencies between requirements:

// CANARY: REQ=CBIN-106; FEATURE="AdvancedSearch"; ASPECT=API; STATUS=STUB; DEPENDS_ON=CBIN-105; UPDATED=2025-10-17

canary next will automatically select CBIN-105 before CBIN-106.

CI/CD Integration

Add to your GitHub Actions workflow:

name: CANARY Verification

on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.20'
      - name: Install CANARY
        run: go install ./cmd/canary
      - name: Verify requirements
        run: canary scan --verify GAP_ANALYSIS.md --strict
      - name: Check documentation currency
        run: canary doc report

Reference

All CANARY Commands

canary init <project>          # Initialize new CANARY project
canary index                   # Build/rebuild token database
canary list [flags]            # List requirements with filtering
canary show <req-id>           # Display all tokens for requirement
canary files <req-id>          # List implementation files
canary status <req-id>         # Show progress summary
canary grep <pattern>          # Search tokens by pattern
canary next [flags]            # Get next priority requirement
canary implement <req-id>      # Get implementation guidance
canary specify [update]        # Create/modify specifications
canary plan <req-id>           # Generate implementation plan
canary scan [flags]            # Scan for tokens and verify
canary doc status <req> <feat> # Check documentation currency
canary doc update [flags]      # Update documentation hashes
canary doc report [flags]      # Generate documentation report
canary prioritize <req> <pri>  # Adjust requirement priority

Documentation Suite

Getting Started - This guide
Query Commands Guide - show, files, status, grep
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

Key Files

.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              # Specification
│       └── plan.md              # Implementation plan
└── canary.db                    # SQLite token database

GAP_ANALYSIS.md                   # Requirement tracking
CLAUDE.md                         # AI agent context

Getting Help

Command Help

canary --help                # General help
canary show --help           # Command-specific help

Documentation

README.md - Project overview
CLAUDE.md - AI agent guide
.canary/AGENT_CONTEXT.md - Complete agent context
User Guides - All user documentation

Community

GitHub Issues: Report bugs and request features
Discussions: Ask questions and share experiences

Next Steps

Now that you understand the basics:

Initialize your project: canary init my-project
Establish principles: Edit .canary/memory/constitution.md
Create your first requirement: Use /canary.specify or canary specify
Follow the workflow: specify → plan → implement → verify
Explore query commands: canary show, canary files, canary status
Use automated prioritization: canary next

For AI Agents: Reference this guide alongside CLAUDE.md for complete context.

For Human Developers: Bookmark the Query Commands Guide and Next Priority Guide for daily use.

Happy tracking!

Last verified: 2025-10-17 with canary v0.1.0

Uh oh!

FilesExpand file tree

getting-started.md

Latest commit

History

getting-started.md

File metadata and controls

CANARY CLI Getting Started Guide

Overview

Prerequisites

Installation

From Source

Quick Test

Core Concepts

CANARY Tokens

Status Progression

Valid Aspects

Quick Start: Your First CANARY Project

Step 1: Initialize a New Project

Step 2: Establish Project Principles

Step 3: Specify Your First Requirement

Step 4: Create an Implementation Plan

Step 5: Implement the Feature

A. Write Tests First (RED phase)

B. Implement Feature (GREEN phase)

C. Update Token Status to TESTED

Step 6: Index and Query Your Progress

Step 7: Scan and Verify

Step 8: Document the Feature

Core Workflows

Workflow 1: Autonomous AI Agent

Workflow 2: Human Developer Daily Work

Workflow 3: Feature Discovery and Modification

Workflow 4: Implementation Guidance

Querying and Inspecting Progress

Show All Tokens

List Implementation Files

Check Progress Summary

Search by Pattern

Best Practices

For AI Agents

For Human Developers

For Teams

Common Pitfalls

Pitfall 1: Skipping Tests

Pitfall 2: Stale Documentation

Pitfall 3: Missing Tokens in Implementation

Pitfall 4: Inconsistent UPDATED Dates

Troubleshooting

Problem: "No tokens found"

Problem: Database queries slow

Problem: Documentation shows as DOC_STALE

Advanced Topics

Custom Aspects

Priority Management

Dependency Tracking

CI/CD Integration

Reference

All CANARY Commands

Documentation Suite

Key Files

Getting Help

Command Help

Documentation

Community

Next Steps