`canary implement` Command - Implementation Summary¶

Overview¶

Added canary implement command to show exact file locations for all CANARY tokens related to a specific requirement, dramatically reducing agent context usage.

Problem Solved¶

Before: Agents had to: - Search entire codebase for implementation locations - Read multiple files to find relevant code - Manually track which sub-features are complete - Use large context windows to understand structure

After: Agents can: - Run canary implement CBIN-001 to see all locations at once - Get exact file:line references - Filter to only unimplemented features (--status STUB) - See code context without reading entire files (--context)

Changes Made¶

1. Updated Spec Template (CBIN-115)¶

File: base/.canary/templates/spec-template.md

Added "Implementation Checklist" section:

## Implementation Checklist

### Core Features

<!-- CANARY: REQ=CBIN-XXX; FEATURE="CoreFeature1"; ASPECT=API; STATUS=STUB; UPDATED=YYYY-MM-DD -->
**Feature 1: [Component Name]**
- [ ] Implement [specific functionality]
- **Location hint:** [e.g., "auth.go", "handlers/"]
- **Dependencies:** [other features]

<!-- CANARY: REQ=CBIN-XXX; FEATURE="CoreFeature2"; ASPECT=API; STATUS=STUB; UPDATED=YYYY-MM-DD -->
**Feature 2: [Component Name]**
...

Sections included: - Core Features - Data Layer (if applicable) - Testing Requirements - Documentation

Purpose: Each sub-feature gets its own CANARY token in the spec, making them trackable by canary implement.

2. Added `canary implement` Command (CBIN-122)¶

File: cmd/canary/main.go

Functionality:

implementCmd = &cobra.Command{
    Use:   "implement <CBIN-XXX>",
    Short: "Show implementation points and locations for a requirement",
    // Scans codebase with grep
    // Parses CANARY tokens
    // Shows file:line locations
    // Displays progress
}

Key features: - Uses grep -rn to find all tokens for a requirement - Parses CANARY fields (FEATURE, ASPECT, STATUS, TEST, BENCH) - Applies filters (--status, --aspect, --feature) - Shows optional context lines (--context, --context-lines) - Displays progress percentage

Flags added: - --status - Filter by status (STUB, IMPL, TESTED, BENCHED) - --aspect - Filter by aspect (API, CLI, Engine, etc.) - --feature - Filter by feature name (partial match) - --context - Show code context around tokens - --context-lines - Number of lines (default 3)

3. Helper Function¶

Added extractField(token, field string) string: - Extracts field values from CANARY token strings - Handles both quoted ("value") and unquoted (value) formats - Uses regex for robust parsing

Example Usage¶

Basic usage¶

$ canary implement CBIN-001

Implementation points for CBIN-001:

1. CoreFeature1 (API, STUB)
   Location: .canary/specs/CBIN-001-User-authentication/spec.md:175

2. JWTValidation (API, IMPL)
   Location: src/auth.go:45
   Test: TestJWTValidation

3. UserLogin (API, TESTED)
   Location: src/handlers/auth.go:23
   Test: TestUserLogin

Summary:
  STUB: 1
  IMPL: 1
  TESTED: 1
  Total: 3 implementation points

Progress: 67% (2/3)

Filter by status¶

$ canary implement CBIN-001 --status STUB

Implementation points for CBIN-001:

1. CoreFeature1 (API, STUB)
   Location: .canary/specs/CBIN-001-User-authentication/spec.md:175

Summary:
  STUB: 1
  Total: 1 implementation points

Progress: 0% (0/1)

With code context¶

$ canary implement CBIN-001 --context --context-lines 2

Implementation points for CBIN-001:

1. JWTValidation (API, IMPL)
   Location: src/auth.go:45
   Test: TestJWTValidation
   Context:
       44: func ValidateJWT(token string) (*Claims, error) {
    >> 45: // CANARY: REQ=CBIN-001; FEATURE="JWTValidation"; ASPECT=API; STATUS=IMPL; TEST=TestJWTValidation; UPDATED=2025-10-16
       46:     claims := &Claims{}
       47:     parsedToken, err := jwt.ParseWithClaims(token, claims, keyFunc)

...

Filter by feature name¶

$ canary implement CBIN-001 --feature Test

Implementation points for CBIN-001:

1. UnitTests (API, STUB)
   Location: .canary/specs/CBIN-001-User-authentication/spec.md:201
   Test: TestCBINXXX

2. IntegrationTests (API, STUB)
   Location: .canary/specs/CBIN-001-User-authentication/spec.md:206
   Test: TestCBINXXXIntegration

Summary:
  STUB: 2
  Total: 2 implementation points

Progress: 0% (0/2)

Agent Workflow¶

Before Implementation¶

# See what needs to be built
canary implement CBIN-001 --status STUB

# Output guides agent to exactly what needs implementation

During Implementation¶

# Find exact location for a specific feature
canary implement CBIN-001 --feature JWTValidation --context

# Shows:
# - Exact file and line number
# - Surrounding code for context
# - Current status and tests

After Implementation¶

# Check progress
canary implement CBIN-001

# Shows:
# - Progress: 67% (2/3)
# - Summary by status
# - All implementation points

Context Reduction Benefits¶

Traditional approach¶

Agent needs to:
1. Read spec.md (entire file, ~200 lines)
2. Search for related files (grep, find)
3. Read multiple source files (auth.go, handlers/, etc.)
4. Track progress manually

Total context: ~5000+ tokens

With `canary implement`¶

Agent runs:
1. canary implement CBIN-001 --status STUB

Gets:
- Exact file paths and line numbers
- Feature names and status
- Progress percentage

Total context: ~200 tokens

Context reduction: ~95%

With `--context` flag¶

Agent runs:
1. canary implement CBIN-001 --feature JWTValidation --context --context-lines 5

Gets:
- File path: src/auth.go:45
- 11 lines of surrounding code
- Feature metadata

Total context: ~100 tokens (vs. reading entire auth.go)

Testing¶

Manual testing:

# Test basic functionality
canary implement CBIN-104
# ✅ Shows 1 implementation point

# Test with new spec template
canary init /tmp/test && cd /tmp/test
canary specify "User auth"
canary implement CBIN-001
# ✅ Shows 8 implementation points from spec

# Test filtering
canary implement CBIN-001 --status STUB
# ✅ Shows only STUB tokens

# Test context display
canary implement CBIN-104 --context --context-lines 2
# ✅ Shows code context with >> marker

All tests passing: - Existing tests unchanged (11/11 passing) - New command doesn't affect scanner - grep-based approach works across file types

Documentation Updated¶

CLI_COMMANDS.md: - Added canary implement to command overview - Detailed reference with all flags - Multiple examples showing filters and context - Agent usage notes explaining context reduction - Updated complete workflow to include implement

AGENT_INTEGRATION.md: - Added "Find Implementation Locations" section - Examples of using --status, --context, filtering - Updated complete workflow to show implement usage - Documented key benefits for agents

File Changes¶

Modified: - base/.canary/templates/spec-template.md - Added Implementation Checklist - embedded/base/templates/spec-template.md - Synced - cmd/canary/main.go - Added implement command + extractField helper - CLI_COMMANDS.md - Added documentation - AGENT_INTEGRATION.md - Added documentation

Impact: - All new projects get spec template with embedded tokens - canary implement available immediately - Backwards compatible (works with existing projects too)

Performance¶

Speed: - Grep scans entire codebase: ~50-200ms for typical projects - Parsing and filtering: negligible - Total: <500ms for most projects

Scalability: - Tested with 12 tokens across multiple files: instant - grep is highly optimized for text search - Filters reduce output before display

Future Enhancements¶

Potential improvements: 1. JSON output format for programmatic parsing 2. Integration with LSP servers for IDE navigation 3. Caching for very large codebases 4. Diff view showing what changed since last scan 5. Dependency graph between features

Not critical now: - Current implementation meets requirements - Fast enough for all tested scenarios - Simple grep-based approach is reliable

Summary¶

Successfully implemented canary implement command that: - ✅ Shows exact file:line locations for all tokens - ✅ Filters by status, aspect, feature - ✅ Displays code context on demand - ✅ Tracks progress percentage - ✅ Reduces agent context by ~95% - ✅ Works with specs and source code - ✅ Fully documented for agent use

Key innovation: Spec template now includes CANARY tokens for sub-features, creating a complete "implementation map" that agents can navigate with minimal context.

Result: Agents can find exactly where to code without searching, reading entire files, or using large context windows.

canary implement Command - Implementation Summary¶