prompts

README

Canary Prompts - Hierarchical Structure

Overview

The Canary prompts package provides a hierarchical organization of prompts for all CLI commands. Each command has its own dedicated prompt file describing its purpose, behavior, and standards.

Directory Structure

prompts/
|-- commands/              # Command-specific prompts
|   |-- bug/
|   |   |-- bug.md         # Bug command prompt
|   |-- checkpoint/
|   |   |-- checkpoint.md  # Checkpoint command prompt
|   |-- constitution/
|   |   |-- constitution.md # Constitution command prompt
|   |-- create/
|   |   |-- create.md      # Create command prompt
|   |-- db/
|   |   |-- db.md          # Database command prompt
|   |-- deps/
|   |   |-- deps.md        # Dependencies command prompt
|   |-- doc/
|   |   |-- doc.md         # Documentation command prompt
|   |-- files/
|   |   |-- files.md       # Files command prompt
|   |-- gap/
|   |   |-- gap.md         # Gap command prompt
|   |-- grep/
|   |   |-- grep.md        # Grep command prompt
|   |-- implement/
|   |   |-- implement.md   # Implement command prompt
|   |-- index/
|   |   |-- index.md       # Index command prompt
|   |-- list/
|   |   |-- list.md        # List command prompt
|   |-- mcp/
|   |   |-- mcp.md         # MCP server command prompt
|   |-- migrate/
|   |   |-- migrate.md     # Orphan/upgrade/onboard/migrate-from prompt
|   |-- next/
|   |   |-- next.md        # Next command prompt
|   |-- plan/
|   |   |-- plan.md        # Plan command prompt
|   |-- prioritize/
|   |   |-- prioritize.md  # Prioritize command prompt
|   |-- project/
|   |   |-- project.md     # Project command prompt
|   |-- scan/
|   |   |-- scan.md        # Scan command prompt
|   |-- search/
|   |   |-- search.md      # Search command prompt
|   |-- show/
|   |   |-- show.md        # Show command prompt
|   |-- specify/
|   |   |-- specify.md     # Specify command prompt
|   |-- specs/
|   |   |-- specs.md       # Specs command prompt
|   |-- status/
|   |   |-- status.md      # Status command prompt
|   |-- view/
|       |-- view.md        # View command prompt
|-- sys/                   # System-level meta-prompt templates (served raw
|   |                      # via --prompt <name>; {{VAR}} placeholders are
|   |                      # intentional, see the header comment in each file)
|   |-- init.md            # Initialization prompt
|   |-- policy.md          # Policy prompt
|   |-- requirements.md    # Requirements prompt
|   |-- evaluate.md        # Evaluation prompt
|-- prompts.go             # Go API for accessing prompts
|-- prompts_test.go        # Tests for prompt API
|-- README.md              # This file

Usage

Go API

import "devnw.dev/canary/prompts"

// Get a specific command prompt
content, err := prompts.GetCommand("scan")
if err != nil {
    log.Fatal(err)
}
fmt.Println(content)

// List all available commands
commands, err := prompts.ListCommands()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Available commands: %v\n", commands)

// Get all command prompts as a map
allPrompts, err := prompts.GetAllCommands()
if err != nil {
    log.Fatal(err)
}

// Parse a command prompt into structured data
prompt, err := prompts.ParseCommandPrompt("scan")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Command: %s\n", prompt.Command)
fmt.Printf("Full content: %s\n", prompt.FullContent)

Legacy System Prompts

// Legacy API still supported
all := prompts.All()
fmt.Println(all["init"])
fmt.Println(all["policy"])

// Or use individual variables
fmt.Println(prompts.Init)
fmt.Println(prompts.Policy)
fmt.Println(prompts.Requirements)
fmt.Println(prompts.Evaluate)

Command Prompt Structure

Each command prompt file follows this structure:

Header

# [Command Name] Command Prompt

## Purpose
Brief description of what the command does.

Task Description

## Task
Detailed description of what needs to be implemented.

Expected Behavior

## Expected Behavior
Examples of how the command should work:

\`\`\`bash
canary command --flag value
\`\`\`

Output Format

## Output Format
Description and examples of command output.

Standards

## Standards
- Implementation guidelines
- Best practices
- Performance requirements
- Error handling expectations

Categories

One-Call Context

• view - Full picture of a requirement in one call (status, files, tests, deps, spec, ticket)

Core Token Management

Commands that deal with CANARY tokens directly:

• list - List/filter tokens
• show - Show requirement details
• create - Generate token template
• status - Show progress stats
• search - Search by keywords
• next - Get next priority requirement

Workflow & Development

Commands for the development workflow:

• scan - Scan codebase for tokens
• specify - Create requirement specification
• plan - Generate implementation plan
• implement - Get implementation guidance
• index - Index tokens to database

Query & Navigation

Commands for exploring the codebase:

• files - Find files for requirement
• grep - Search by pattern in fields

Management

Commands for project management:

• prioritize - Set requirement priority
• checkpoint - Create state snapshots
• constitution - Manage project principles
• deps - Manage dependencies
• project - Manage project configuration

Bug Tracking

Commands for bug management:

• bug - Bug lifecycle management (list, create, show, update)
• gap - Gap analysis feedback

Documentation

Commands for documentation:

• doc - Generate documentation
• specs - Manage specifications

Infrastructure

Commands for system management:

• db - Database operations
• migrate - Orphan spec generation, legacy token-shape upgrades, onboarding, spec-kit/legacy-canary migration (database schema migrations are canary migrate <steps>, a separate command not documented under this prompt)
• mcp - MCP server for AI assistants

Adding New Commands

To add a new command prompt:

1. Create a new directory: commands/yourcommand/
2. Create the prompt file: commands/yourcommand/yourcommand.md
3. Follow the standard prompt structure
4. The prompt will be automatically embedded and available via the API

Example:

mkdir -p prompts/commands/newcmd
cat > prompts/commands/newcmd/newcmd.md << 'EOF'
# New Command Prompt

## Purpose
Description of the new command.

## Task
Implementation details.

## Expected Behavior
Usage examples.

## Standards
Guidelines and requirements.
EOF

The new prompt will be automatically available:

content, err := prompts.GetCommand("newcmd")

Testing

Run tests to verify all prompts are accessible:

go test ./prompts/...

Embedding

All prompts are embedded into the binary using Go's embed directive. This means:

• No external files needed at runtime
• Fast access (no disk I/O)
• Version-controlled with code
• Single binary distribution

Benefits

For Developers

• Clear guidelines for each command
• Consistent command behavior
• Easy to reference during implementation

For AI Assistants

• Structured prompts for each tool
• Clear expectations and standards
• Examples and formats

For Documentation

• Single source of truth
• Auto-generated docs possible
• Version-controlled

Future Enhancements

Potential improvements:

• Structured parsing of prompt sections
• Validation of prompt completeness
• Generation of command documentation from prompts
• Template variable substitution
• Multi-language prompt support
• Prompt versioning system

Related Files

• cli/ - CLI command implementations
• mcp/ - MCP server that exposes commands to AI
• pkg/storage/ - Database layer used by commands
• .canary/templates/ - User-facing templates

License

Copyright (c) 2025 by Developer Network.

For more details, see the LICENSE file in the root directory of this source code repository or contact Developer Network at info@devnw.com.

Documentation

Index

• Variables
• func All() map[string]string
• func GetAllCommands() (map[string]string, error)
• func GetCommand(command string) (string, error)
• func ListCommands() ([]string, error)
• type CommandPrompt
  • func ParseCommandPrompt(command string) (*CommandPrompt, error)

Variables

var (
	Init         string
	Policy       string
	Requirements string
	Evaluate     string
)

System prompts (legacy - kept for compatibility)

Functions

func All

func All() map[string]string

All returns all system prompts (legacy function)

func GetAllCommands

func GetAllCommands() (map[string]string, error)

GetAllCommands returns all command prompts as a map

func GetCommand

func GetCommand(command string) (string, error)

GetCommand returns the prompt for a specific command

func ListCommands

func ListCommands() ([]string, error)

ListCommands returns all available command prompts

Types

type CommandPrompt

type CommandPrompt struct {
	Command     string
	Purpose     string
	Behavior    string
	Examples    []string
	Standards   string
	FullContent string
}

CommandPrompt represents a structured command prompt

func ParseCommandPrompt

func ParseCommandPrompt(command string) (*CommandPrompt, error)

ParseCommandPrompt parses a command prompt into structured fields This is a simple parser - could be enhanced to extract specific sections