Next Priority Command User Guide

Requirement: CBIN-132 Status: Complete Last Updated: 2025-10-17

Overview

The canary next command is your automated workflow assistant that identifies the highest priority unimplemented requirement and generates comprehensive implementation guidance. It eliminates manual prioritization decisions by intelligently selecting work based on priority scores, dependencies, status, and age.

Key Benefits:

Automated Prioritization: No manual decision-making - system selects optimal next task
Comprehensive Guidance: Generated prompts include spec, constitution, tests, and examples
Dependency-Aware: Automatically resolves DEPENDS_ON relationships
Constitutional Adherence: Every prompt includes relevant project principles
Fast Selection: <100ms query time even in large codebases

Getting Started

Prerequisites

CANARY CLI installed
(Recommended) Database indexed with canary index
(Optional) .canary/memory/constitution.md for project principles

Quick Start

Get next priority task:

canary next

Generate full implementation prompt:

canary next --prompt

Usage

Basic Usage: Summary Mode

Display next priority requirement without full prompt:

canary next

Output:

📌 Next Priority: CBIN-138 - MultilineTokens

Priority: 3 | Status: STUB | Aspect: Engine
Specification: .canary/specs/CBIN-138-multiline-tokens/spec.md

Dependencies:
  ✅ CBIN-101 - ScannerCore (TESTED)

Ready to implement! Run with --prompt flag for full guidance.

Prompt Generation Mode

Generate comprehensive implementation prompt:

canary next --prompt

Output includes:

Requirement specification
Implementation plan (if exists)
Constitutional principles
Test-first workflow guidance
Token placement examples
Success criteria checklist
Dependency information

Filtering by Status

Select next STUB requirement only:

canary next --status STUB

Select next IMPL requirement needing tests:

canary next --status IMPL

Filtering by Aspect

Select next Engine work:

canary next --aspect Engine

Select next CLI work:

canary next --aspect CLI

Dry Run Mode

Preview what would be selected without generating prompt:

canary next --dry-run

JSON Output

Get machine-readable output for automation:

canary next --json

Common Workflows

Workflow 1: Agent Autonomous Work

Scenario: AI agent completing task after task automatically

# 1. Agent completes current task
# 2. Agent runs next command
canary next --prompt

# 3. Agent reads generated prompt
# 4. Agent implements requirement following guidance
# 5. Agent places CANARY tokens
# 6. Agent updates status to TESTED
# 7. Repeat from step 2

This creates a continuous implementation loop where the agent always knows what to work on next.

Workflow 2: Human Developer Daily Planning

Scenario: Developer starting work day

# 1. Check what's next
canary next

# 2. Review the requirement details
cat .canary/specs/CBIN-138-multiline-tokens/spec.md

# 3. Decide to implement
canary next --prompt > implementation-guidance.md

# 4. Follow guidance in implementation-guidance.md
# 5. Mark complete and get next task
canary next

Workflow 3: Filtered Sprint Planning

Scenario: Sprint focused on API aspects

# 1. See all API work available
canary list --aspect API --status STUB

# 2. Get next API priority
canary next --aspect API --prompt

# 3. Implement API feature
# 4. Repeat for sprint duration

Workflow 4: Dependency-Driven Development

Scenario: System automatically resolves dependencies

# Current state:
#   CBIN-105 (PRIORITY=1, DEPENDS_ON=CBIN-104)
#   CBIN-104 (PRIORITY=3, STATUS=STUB)

# System selects CBIN-104 first (dependency)
canary next
# Output: CBIN-104 - Must be completed before CBIN-105

# After CBIN-104 is TESTED, system selects CBIN-105
canary next
# Output: CBIN-105 - Now unblocked!

Examples

Example 1: First Implementation

Scenario: Starting fresh after canary init

$ canary next --prompt

Output:

# Implementation Guidance: CBIN-101 - ScannerCore

## Priority Information
- Requirement ID: CBIN-101
- Priority: 1 (Highest)
- Status: STUB
- Aspect: Engine

## Specification

[Full spec.md content loaded here...]

## Constitutional Principles

From .canary/memory/constitution.md:

**Article IV: Test-First Imperative**
All features SHALL be implemented using test-first development...

**Article V: Simplicity and Anti-Abstraction**
Prefer simple, direct solutions over complex abstractions...

## Implementation Guidance

### Step 1: Write Tests (RED phase)
Create test file at: internal/scanner/scanner_test.go

```go
// CANARY: REQ=CBIN-101; FEATURE="ScannerCore"; ASPECT=Engine; STATUS=STUB; TEST=TestCANARY_CBIN_101_Engine_BasicScan; UPDATED=2025-10-17
func TestCANARY_CBIN_101_Engine_BasicScan(t *testing.T) {
    // Test implementation...
}

[... continued with full implementation guidance ...]


### Example 2: No Work Available

**Scenario:** All requirements completed

```bash
$ canary next

Output:

🎉 All requirements completed! No work available.

Suggestions:
  • Run: canary scan --verify GAP_ANALYSIS.md
  • Review completed requirements
  • Consider creating new specifications

Congratulations on completing the project roadmap!

Example 3: Dependency Blocking

Scenario: High priority requirement is blocked

$ canary next --dry-run

Output:

Next priority (dry run): CBIN-104 - TokenParser
Priority: 3 | Status: STUB | Aspect: Engine
Location: .canary/specs/CBIN-104-token-parser/spec.md

Note: CBIN-105 (PRIORITY=1) is blocked by this requirement.
Completing CBIN-104 will unblock CBIN-105.

Example 4: Database Fallback

Scenario: Database not yet created

$ canary next

Output:

ℹ️  Database not found, scanning filesystem...

📌 Next Priority: CBIN-101 - ScannerCore

[... rest of output ...]

💡 Tip: Run 'canary index' to improve performance

Best Practices

For AI Agents

Run after every completion - Use canary next after marking each requirement TESTED
Always use --prompt - Get full context for correct implementation
Follow test-first guidance - Respect RED → GREEN → REFACTOR workflow
Update tokens immediately - Change STATUS as you progress through phases
Verify dependencies - Check that DEPENDS_ON requirements are TESTED

For Human Developers

Morning routine - Start day with canary next to see priorities
Review before commit - Use dry-run mode to preview next work
Filter by skill - Use --aspect to match your expertise
Track progress - Watch priority numbers decrease as work completes
Update priorities - Use canary prioritize to adjust as needs change

For CI/CD Systems

Use --json mode - Machine-readable output for automation
Check exit codes - 0 = success/no work, non-zero = error
Batch processing - Implement multiple requirements in sequence
Checkpoint tracking - Create checkpoints after each completion
Fail gracefully - Handle "no work available" as success

Priority Determination

The system uses a multi-factor algorithm to determine priority:

Factor 1: Explicit PRIORITY Field

PRIORITY=1  (Highest priority)
PRIORITY=2
PRIORITY=3
PRIORITY=4
PRIORITY=5  (Default)
...
PRIORITY=10 (Lowest priority)

Lower numbers selected first.

Factor 2: STATUS Value

Among requirements with same PRIORITY:

STUB - Not yet implemented (highest urgency)
IMPL - Implemented but needs tests
TESTED - Skip (already complete)
BENCHED - Skip (already complete)

Factor 3: Dependencies (DEPENDS_ON)

Requirements with unmet dependencies are automatically skipped. The system selects blocking dependencies first.

Example:

CBIN-105: DEPENDS_ON=CBIN-104
CBIN-104: STATUS=STUB

Result: CBIN-104 selected (must complete before CBIN-105)

Factor 4: Age (UPDATED Field)

Among requirements with same PRIORITY and STATUS, older tokens (older UPDATED dates) get slight priority boost to prevent stale work from accumulating.

Troubleshooting

Problem: "No tokens found"

Symptoms:

Error: no tokens found in database or filesystem

Solutions:

Run canary index to build database
Check that CANARY tokens exist: grep -r "CANARY:" .
Verify .canaryignore isn't excluding all files
Check you're in project root directory

Problem: "All requirements completed" but work remains

Symptoms:

🎉 All requirements completed!

But you know there are STUB requirements.

Solutions:

Check if hidden requirements exist: canary list --include-hidden --status STUB
Verify status filters: canary list --status STUB (see all STUB items)
Check if requirements are in ignored directories (templates, tests, etc.)
Rebuild database: canary index

Problem: Dependency Loop Detected

Symptoms:

Error: circular dependency detected: CBIN-105 → CBIN-106 → CBIN-105

Solutions:

Review DEPENDS_ON fields in both requirements
Remove circular dependency (one requirement must not depend on the other)
Update CANARY tokens to reflect correct dependency order
Run canary index to refresh dependency graph

Problem: Prompt Generation Fails

Symptoms:

Error: failed to generate prompt: template execution failed at line 42

Solutions:

Check that specification file exists at referenced path
Verify constitution.md exists at .canary/memory/constitution.md
Ensure spec.md is valid markdown (no corrupted characters)
Run without --prompt flag to test selection logic independently

FAQ

Q: Can I manually override priority selection?

A: Not directly. Use canary prioritize <REQ-ID> <feature> <new-priority> to adjust priorities, then run canary next again.

Q: Does the command modify any files?

A: No. canary next is read-only. It identifies and generates prompts but doesn't modify code or tokens.

Q: How do I implement multiple requirements in parallel?

A: Run canary next --json multiple times with different filters (e.g., by aspect) to get independent work items for parallel development.

Q: What if I disagree with the selected priority?

A: You can:

Adjust PRIORITY fields in CANARY tokens
Use --status or --aspect filters to narrow selection
Use canary implement <specific-req-id> to manually select a requirement

Q: Does this work without a database?

A: Yes! The command falls back to filesystem scanning if .canary/canary.db doesn't exist. Performance is slightly slower but functionality is identical.

Q: How does this integrate with slash commands?

A: The /canary.next slash command in AI agents automatically runs canary next --prompt and feeds the result directly to the agent as implementation guidance.

Integration Examples

Integration 1: GitHub Actions Workflow

name: Auto-implement next requirement

on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours

jobs:
  auto-implement:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install canary
        run: go install ./cmd/canary
      - name: Get next requirement
        id: next
        run: |
          canary next --json > next.json
          echo "req_id=$(jq -r '.ReqID' next.json)" >> $GITHUB_OUTPUT
      - name: Implement with AI agent
        run: |
          # Call your AI agent API here
          # Pass requirement from steps.next.outputs.req_id

Integration 2: Pre-commit Hook

#!/bin/bash
# .git/hooks/pre-commit

# Show next priority after commit
canary next --dry-run

Integration 3: Claude Code Workflow

In Claude Code IDE:

User: /canary.next
Claude: [Reads generated prompt]
Claude: I'll implement CBIN-138 (MultilineTokens) following the specification...
[Claude implements, tests, and updates tokens]
User: continue
Claude: [Automatically runs /canary.next again for next task]

Last verified: 2025-10-17 with canary v0.1.0 Implementation status: BENCHED (fully tested and benchmarked)

Uh oh!

FilesExpand file tree

next-priority-guide.md

Latest commit

History

next-priority-guide.md

File metadata and controls

Next Priority Command User Guide

Overview

Getting Started

Prerequisites

Quick Start

Usage

Basic Usage: Summary Mode

Prompt Generation Mode

Filtering by Status

Filtering by Aspect

Dry Run Mode

JSON Output

Common Workflows

Workflow 1: Agent Autonomous Work

Workflow 2: Human Developer Daily Planning

Workflow 3: Filtered Sprint Planning

Workflow 4: Dependency-Driven Development

Examples

Example 1: First Implementation

Example 3: Dependency Blocking

Example 4: Database Fallback

Best Practices

For AI Agents

For Human Developers

For CI/CD Systems

Priority Determination

Factor 1: Explicit PRIORITY Field

Factor 2: STATUS Value

Factor 3: Dependencies (DEPENDS_ON)

Factor 4: Age (UPDATED Field)

Troubleshooting

Problem: "No tokens found"

Problem: "All requirements completed" but work remains

Problem: Dependency Loop Detected

Problem: Prompt Generation Fails

FAQ

Related Documentation

Integration Examples

Integration 1: GitHub Actions Workflow

Integration 2: Pre-commit Hook

Integration 3: Claude Code Workflow