{"id":36920175,"url":"https://github.com/devnw/canary","last_synced_at":"2026-01-12T16:14:29.490Z","repository":{"id":319718968,"uuid":"1060870533","full_name":"devnw/canary","owner":"devnw","description":"Creator, Manager and Manager of Agent Prompts and Canary Tokens in Agent Repositories","archived":false,"fork":false,"pushed_at":"2025-11-01T16:42:46.000Z","size":8536,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-01T18:09:14.046Z","etag":null,"topics":["agentic-ai","agentic-ai-development","agentic-coding","agentic-systems","agentic-workflow","agentic-workflows","augmented-engineering","canary-development","claude-code","coding-agent","coding-agents","copilot-coding-agent","measurement-based-agent-coding","spec-kit","specification-pattern"],"latest_commit_sha":null,"homepage":"https://canary.devnw.dev/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devnw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":".github/AGENTS.md","dco":null,"cla":null},"funding":{"github":["devnw","benjivesterby"]}},"created_at":"2025-09-20T19:01:46.000Z","updated_at":"2025-10-20T14:01:26.000Z","dependencies_parsed_at":"2025-10-20T02:33:32.635Z","dependency_job_id":null,"html_url":"https://github.com/devnw/canary","commit_stats":null,"previous_names":["devnw/canary"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/devnw/canary","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devnw%2Fcanary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devnw%2Fcanary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devnw%2Fcanary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devnw%2Fcanary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devnw","download_url":"https://codeload.github.com/devnw/canary/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devnw%2Fcanary/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28342344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T15:50:39.657Z","status":"ssl_error","status_checked_at":"2026-01-12T15:49:49.297Z","response_time":98,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agentic-ai-development","agentic-coding","agentic-systems","agentic-workflow","agentic-workflows","augmented-engineering","canary-development","claude-code","coding-agent","coding-agents","copilot-coding-agent","measurement-based-agent-coding","spec-kit","specification-pattern"],"created_at":"2026-01-12T16:14:29.402Z","updated_at":"2026-01-12T16:14:29.477Z","avatar_url":"https://github.com/devnw.png","language":"Go","funding_links":["https://github.com/sponsors/devnw","https://github.com/sponsors/benjivesterby"],"categories":[],"sub_categories":[],"readme":"# CANARY\n\n**Agentic-Coding-Friendly Requirement Tracking System**\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?logo=go)](https://go.dev/)\n[![Build](https://github.com/devnw/canary/actions/workflows/build.yml/badge.svg)](https://github.com/devnw/canary/actions/workflows/build.yml)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)\n[![Go Reference](https://pkg.go.dev/badge/go.devnw.com/canary.svg)](https://pkg.go.dev/go.devnw.com/canary)\n[![Version](https://img.shields.io/github/v/tag/devnw/canary?sort=semver\u0026style=plastic)](https://github.com/devnw/canary/releases)\n\nCANARY is a requirement tracking system that embeds tokens directly into \nsource code, enabling precise tracking of features, tests, benchmarks, and \ndocumentation. This bridges the gap between requirements and implementation,\nensuring that an agent coding system has not only the ability to be precise\nin the specification and planning phases but the outputs of which can be\nmeasured and verified automatically.\n\nThe CANARY system is designed with autonomous AI agents in mind, providing\nslash commands and structured data to facilitate agent workflows. It also\nenforces a test-first development approach through constitutional principles,\nensuring that quality is prioritized over speed.\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install from source\ngo install go.devnw.com/canary/cmd/canary@latest\n\n# Or clone and build\ngit clone https://github.com/devnw/canary.git\ncd canary\nmake build\n```\n\n## Repository\n\nThe code is hosted on GitHub:\n\n- Repository: [Github](https://github.com/devnw/canary)\n- Code Ref: [pkg.go.dev](https://pkg.go.dev/go.devnw.com/canary)\n\n### Initialize Your Project\n\n```bash\n# Create a new project\ncanary init my-project\n\n# This creates:\n# .canary/\n#   ├── memory/constitution.md      # Project principles\n#   ├── templates/                   # Spec and plan templates\n#   ├── specs/                       # Individual requirements\n#   └── canary.db                    # Token database\n# GAP_ANALYSIS.md                    # Requirement tracking\n```\n\n### Your First Requirement\n\n```bash\n# Create a specification (AI agent)\n/canary.specify Add user authentication with JWT tokens\n\n/canary.plan CBIN-001\n\n/canary.implement\n\n# The primary functions like specify, plan, and implement can be run\n# via the CLI but won't really do much for a user. They are designed\n# for AI agents to call programmatically.\n\n# User's can find all of the command options through the --help flag\n\n# Build database and query progress\ncanary index\ncanary show CBIN-001\ncanary status CBIN-001\n```\n\n## How It Works\n\n### CANARY Tokens\n\nTokens are structured comments that track requirements:\n\n```go\n// CANARY: REQ=CBIN-105; FEATURE=\"UserAuth\"; ASPECT=Security; STATUS=TESTED; TEST=TestUserAuth; UPDATED=2025-10-18\nfunc AuthenticateUser(creds *Credentials) (*Session, error) {\n    // implementation\n}\n```\n\n**Token Lifecycle:**\n\n```\nSTUB → IMPL → TESTED → BENCHED\n```\n\n- **STUB**: Placeholder, not yet implemented\n- **IMPL**: Implementation exists, tests missing\n- **TESTED**: Fully tested with passing tests\n- **BENCHED**: Tested and performance benchmarked\n\n### Architecture Aspects\n\nCANARY organizes code by architectural concerns:\n\n- **API** - Public interfaces, exported functions\n- **CLI** - Command-line interfaces\n- **Engine** - Core algorithms and business logic\n- **Storage** - Databases, persistence, repositories\n- **Security** - Authentication, authorization, encryption\n- **Docs** - Documentation files\n- **Wire** - Serialization, protocols, networking\n- **Planner** - Planning and scheduling\n- **Bench** - Performance benchmarks\n- **FrontEnd** - User interface\n- **Dist** - Distribution and deployment\n\n### Dependency Management (CBIN-147)\n\nExpress dependencies between requirements:\n\n```markdown\n## Dependencies\n\n### Full Dependencies (entire requirement needed)\n- CBIN-146 (Multi-Project Support - required for token namespacing)\n\n### Partial Dependencies (specific features/aspects)\n- CBIN-140:GapRepository,GapService (only gap storage needed)\n- CBIN-133:Engine (only Engine aspect required)\n```\n\n**Features:**\n- Circular dependency detection using DFS algorithm\n- Transitive dependency resolution\n- Status-based satisfaction (only TESTED/BENCHED satisfy)\n- Reverse dependency queries\n- ASCII tree visualization\n\n```bash\ncanary deps check CBIN-147        # Check if dependencies satisfied\ncanary deps graph CBIN-147 --status  # Visualize dependency tree\ncanary deps reverse CBIN-146      # What depends on this?\ncanary deps validate              # Check entire graph for cycles\n```\n\n### Verification Gates\n\nPrevent overclaiming with automatic verification:\n\n```bash\n# Scan codebase for tokens\ncanary scan --out status.json --csv status.csv\n\n# Verify claims in GAP_ANALYSIS.md\ncanary scan --verify GAP_ANALYSIS.md --strict\n# Exits with code 2 if:\n# - Claimed requirements lack TESTED/BENCHED status\n# - Tokens are stale (\u003e30 days old)\n```\n\n**GAP_ANALYSIS.md Format:**\n\n```markdown\n# Requirements Gap Analysis\n\n## Claimed Requirements\n✅ CBIN-101 - Scanner Core\n✅ CBIN-102 - Verify Gate\n\n## Gaps\n- [ ] CBIN-103 - Status JSON (needs tests)\n```\n\n## Core Commands\n\n### Query and Inspection\n\n```bash\ncanary show CBIN-105          # Display all tokens for a requirement\ncanary files CBIN-105         # List implementation files\ncanary status CBIN-105        # Show progress summary\ncanary grep \"Authentication\"  # Search tokens by pattern\ncanary list --status TESTED --aspect API  # Filtered listing\n```\n\n### Workflow Automation\n\n```bash\ncanary next                   # Get next priority requirement\ncanary next --prompt          # Generate AI agent prompt\ncanary implement CBIN-105     # Get implementation guidance\ncanary implement fuzzy        # Fuzzy match requirement\n```\n\n### Specification Management\n\n```bash\ncanary specify                # Create new specification\ncanary specify update CBIN-105  # Modify existing spec\ncanary plan CBIN-105          # Generate implementation plan\n```\n\n### Documentation Tracking\n\n```bash\ncanary doc status CBIN-105 UserAuth     # Check doc currency\ncanary doc update --req CBIN-105        # Update doc hashes\ncanary doc report --show-undocumented   # Coverage report\n```\n\n### Dependency Management\n\n```bash\ncanary deps check CBIN-147         # Check dependency satisfaction\ncanary deps graph CBIN-147 --status  # Show dependency tree\ncanary deps reverse CBIN-146       # Show reverse dependencies\ncanary deps validate               # Detect circular dependencies\n```\n\n### Multi-Project Support (CBIN-146)\n\n```bash\n# Global mode (default)\ncanary index                  # Uses ~/.canary/canary.db\n\n# Local mode (project-specific)\ncanary index --local          # Uses .canary/canary.db\n\n# Project management\ncanary projects list          # List all projects\ncanary projects add my-app    # Register project\ncanary projects switch my-app # Change context\n```\n\n## Complete Workflow\n\n### For AI Agents\n\n```\n1. Agent runs: /canary.next\n2. System returns next priority requirement with:\n   - Full specification\n   - Implementation plan\n   - Constitution principles\n   - Test-first guidance\n3. Agent implements following RED-GREEN-REFACTOR\n4. Agent places CANARY tokens in code\n5. Agent updates token STATUS as work progresses\n6. Agent verifies with /canary.scan\n7. Repeat from step 1\n```\n\n### For Human Developers\n\n```bash\n# Morning routine\ncanary next                   # See what's next\n\n# Review requirement\ncat .canary/specs/CBIN-105-fuzzy-search/spec.md\ncat .canary/specs/CBIN-105-fuzzy-search/plan.md\n\n# Implement with test-first\n# 1. Write failing test (RED)\n# 2. Implement minimum code to pass (GREEN)\n# 3. Refactor (REFACTOR)\n# 4. Add CANARY tokens\n# 5. Update STATUS field\n\n# Verify progress\ncanary status CBIN-105\ncanary scan --verify GAP_ANALYSIS.md\n\n# Check what's next\ncanary next\n```\n\n## Key Features\n\n### 🎯 Test-First Enforcement\n\nConstitutional principles ensure tests before implementation:\n\n```markdown\n## Article IV: Test-First Imperative\nAll features SHALL be implemented using test-first development (TDD).\nTests MUST be written before implementation code.\n```\n\n### 📊 Real-Time Progress Tracking\n\n```bash\ncanary status CBIN-105\n# Output:\n# Requirement: CBIN-105 (Fuzzy Search)\n# Total tokens: 8\n# Status breakdown:\n#   TESTED: 6 (75%)\n#   IMPL: 1 (12.5%)\n#   STUB: 1 (12.5%)\n# Incomplete work:\n#   - FuzzyRanking (Engine): IMPL → needs tests\n#   - FuzzyConfig (API): STUB → not implemented\n```\n\n### 🔍 Powerful Search\n\n```bash\ncanary grep Authentication\n# Searches across:\n# - Requirement IDs\n# - Feature names\n# - Aspects\n# - Owners\n# - Files\n# Returns tokens with file locations and line numbers\n```\n\n### 📚 Documentation Currency\n\nTrack documentation status with cryptographic hashes:\n\n```go\n// CANARY: REQ=CBIN-105; FEATURE=\"FuzzySearch\"; ASPECT=Engine; STATUS=TESTED;\n// TEST=TestFuzzySearch; DOC=user:docs/user/search-guide.md;\n// DOC_HASH=a3f5b8c2e1d4a6f9; UPDATED=2025-10-18\n```\n\n```bash\ncanary doc status CBIN-105 FuzzySearch\n# Status: DOC_CURRENT (hash matches)\n\n# After editing docs/user/search-guide.md:\ncanary doc status CBIN-105 FuzzySearch\n# Status: DOC_STALE (hash mismatch)\n\ncanary doc update --req CBIN-105 --feature FuzzySearch\n# Recalculates and updates DOC_HASH\n```\n\n### 🔗 Dependency Tracking\n\nFull dependency graph with cycle detection:\n\n```bash\ncanary deps graph CBIN-147 --status\n# Output:\n# CBIN-147 (Specification Dependencies)\n# ├── ✅ CBIN-146 (Multi-Project Support)\n# │   └── ✅ CBIN-129 (Database Migrations)\n# └── ✅ CBIN-140:GapRepository,GapService\n#     ├── ✅ CBIN-133:Engine\n#     └── ❌ CBIN-135:Storage (STATUS=IMPL, needs tests)\n#\n# Summary: 3 satisfied, 1 blocking\n```\n\n### 🤖 AI Agent Integration\n\nSlash commands for autonomous workflows:\n\n- `/canary.next` - Get next priority with full context\n- `/canary.show \u003creq-id\u003e` - Display requirement tokens\n- `/canary.status \u003creq-id\u003e` - Check progress\n- `/canary.implement \u003creq-id\u003e` - Get implementation guidance\n- `/canary.scan` - Verify token placement\n- `/canary.specify` - Create new requirement\n- `/canary.plan \u003creq-id\u003e` - Generate implementation plan\n\n### 🚀 GitHub Copilot Integration\n\n\u003c!-- CANARY: REQ=CBIN-148; FEATURE=\"InitDocs\"; ASPECT=Docs; STATUS=IMPL; UPDATED=2025-10-19 --\u003e\n\nCANARY automatically configures GitHub Copilot with project-specific instructions:\n\n```bash\ncanary init my-project\n# Creates .github/instructions/ with CANARY workflow guidance\n```\n\n**What Gets Configured:**\n\n- **Repository-wide instructions** - CANARY token format, test-first development, constitutional principles\n- **Path-specific guidance** - Context-aware help for specs, tests, and .canary/ directory\n- **Automatic discovery** - Works with both GitHub Copilot CLI and VS Code Copilot Chat\n\n**Instruction Files Created:**\n\n```\n.github/instructions/\n├── repository.md              # CANARY workflow fundamentals\n├── .canary/\n│   ├── instruction.md        # CANARY directory guidelines\n│   └── specs/\n│       └── instruction.md    # Specification writing (WHAT/WHY, not HOW)\n└── tests/\n    └── instruction.md        # Test-first development guidelines\n```\n\n**Verification:**\n\n```bash\n# Using GitHub Copilot CLI\ngh copilot suggest \"What is the CANARY token format?\"\n\n# Using VS Code Copilot Chat\n# Ask: \"@workspace What is the CANARY token format?\"\n```\n\n**Features:**\n- ✅ Zero manual configuration required\n- ✅ Preserves custom instructions on re-init\n- ✅ Project key substitution in templates\n- ✅ Compatible with Copilot CLI and VS Code\n\n**Re-initialization Safe:**\n\n```bash\n# Customize your instructions\necho \"# Custom Rule\" \u003e\u003e .github/instructions/repository.md\n\n# Re-run init - your customizations are preserved\ncanary init --local\n# ⏭️  Skipping existing instruction file: repository.md\n```\n\n## Documentation\n\n### User Documentation\n\n- **[Getting Started Guide](docs/user/getting-started.md)** - Installation, core concepts, complete walkthrough\n- **[Query Commands Guide](docs/user/query-commands-guide.md)** - show, files, status, grep commands\n- **[Next Priority Guide](docs/user/next-priority-guide.md)** - Automated workflow assistant\n- **[Implement Command Guide](docs/user/implement-command-guide.md)** - Implementation guidance\n- **[Specification Modification Guide](docs/user/spec-modification-guide.md)** - Creating and updating specs\n- **[Documentation Tracking Guide](docs/user/documentation-tracking-guide.md)** - DOC= and DOC_HASH= fields\n\n### Developer Documentation\n\n- **[CLAUDE.md](CLAUDE.md)** - AI agent context and slash commands\n- **[.canary/AGENT_CONTEXT.md](.canary/AGENT_CONTEXT.md)** - Complete agent reference\n- **[REQUIREMENTS.md](docs/REQUIREMENTS.md)** - Original self-canary requirements\n- **[CANARY_POLICY.md](docs/CANARY_POLICY.md)** - Token format and policy\n\n### Architecture Documentation\n\n- **[Architecture Decision Records](docs/architecture/)** - ADR-001: Documentation Tracking\n\n## Project Structure\n\n```\ncanary/\n├── cmd/canary/              # Main CLI application\n│   ├── main.go             # CLI entry point and command registration\n│   ├── deps.go             # Dependency management commands (CBIN-147)\n│   └── *_test.go           # Command tests\n├── internal/\n│   ├── specs/              # Specification and dependency engine\n│   │   ├── types.go        # Data models (Token, Dependency, Graph)\n│   │   ├── parser_dependency.go      # Dependency parser\n│   │   ├── validator.go             # Circular dependency detection\n│   │   ├── status_checker.go        # Dependency satisfaction\n│   │   ├── graph_generator.go       # Tree visualization\n│   │   └── *_test.go                # Comprehensive test suite\n│   └── storage/            # SQLite database layer\n│       ├── storage.go      # Database operations\n│       └── migrations.go   # Schema migrations\n├── .canary/\n│   ├── memory/\n│   │   └── constitution.md          # Project principles\n│   ├── templates/\n│   │   ├── spec-template.md         # Requirement template\n│   │   └── plan-template.md         # Implementation plan template\n│   └── specs/\n│       └── CBIN-XXX-feature/        # Individual requirements\n│           ├── spec.md\n│           └── plan.md\n├── docs/\n│   ├── user/               # User-facing documentation\n│   ├── architecture/       # Architecture decision records\n│   └── *.md                # Various docs\n├── tools/canary/           # Legacy scanner (CBIN-101, 102, 103)\n├── GAP_ANALYSIS.md         # Requirement tracking\n├── CLAUDE.md               # AI agent guide\n└── README.md               # This file\n```\n\n## Performance\n\nCANARY is designed for speed and efficiency:\n\n- **Circular Detection**: O(V+E) using DFS, \u003c209ms for 500 requirements\n- **Database Queries**: SQLite with indexes, \u003c50ms for typical queries\n- **Scanning**: Streams file I/O, \u003c10s for 50k files\n- **Memory**: ≤512 MiB RSS for large repositories\n\n## Development\n\n### Build\n\n```bash\nmake build          # Build binary\nmake test           # Run tests\nmake bench          # Run benchmarks\nmake verify         # Self-verify with CANARY\n```\n\n### Self-Canary\n\nCANARY uses itself for requirement tracking:\n\n```bash\n# Scan the codebase\ncanary scan --root . --out status.json --csv status.csv\n\n# Verify claims\ncanary scan --verify GAP_ANALYSIS.md --strict\n\n# Check dependencies\ncanary deps validate\n```\n\n### Testing\n\n```bash\n# Unit tests\ngo test ./...\n\n# Integration tests\ngo test ./internal/specs -run Integration\n\n# Benchmarks\ngo test ./internal/specs -bench=. -benchmem\n\n# Acceptance tests\ngo test ./tools/canary/internal -run Acceptance -v\n```\n\n## Contributing\n\nWe welcome contributions! Please:\n\n1. Check existing requirements: `canary list`\n2. Create a specification: `canary specify`\n3. Follow test-first development\n4. Place CANARY tokens in your code\n5. Update documentation with DOC= fields\n6. Verify before submitting: `canary scan --verify GAP_ANALYSIS.md`\n\nSee [CONTRIBUTING.md](docs/CONTRIBUTING.md) for detailed guidelines.\n\n## License\n\nLicensed under the terms found in [LICENSE](https://github.com/devnw/canary/blob/main/LICENSE).\n\n## Acknowledgments\n\nCANARY was inspired by:\n- **spec-kit** methodology for requirement-first development\n- **Test-Driven Development (TDD)** principles\n- **Evidence-based claims** from formal verification\n- **Zero-trust verification** from security engineering\n\nBuilt with love by [Developer Network](https://devnw.com).\n\n## Related Projects\n\n- [Claude Code](https://claude.com/claude-code) - AI coding assistant with CANARY integration\n- [spec-kit](https://github.com/spec-kit) - Specification-driven development methodology\n\n## Getting Help\n\n- **Documentation**: Start with [Getting Started Guide](docs/user/getting-started.md)\n- **Command Help**: `canary --help` or `canary \u003ccommand\u003e --help`\n- **GitHub Issues**: [Report bugs and request features](https://github.com/devnw/canary/issues)\n- **Discussions**: [Ask questions and share experiences](https://github.com/devnw/canary/discussions)\n\n---\n\n**Ready to start?** → [Getting Started Guide](docs/user/getting-started.md)\n\n**For AI Agents** → [CLAUDE.md](CLAUDE.md)\n\n**For API Documentation** → [pkg.go.dev](https://pkg.go.dev/go.devnw.com/canary)\n\n---\n\n*CANARY: Making every feature claim searchable, verifiable, and traceable.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevnw%2Fcanary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevnw%2Fcanary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevnw%2Fcanary/lists"}