CueLoop Prompt System

Status: Active Owner: Maintainers Source of truth: this document for its stated scope Parent: Feature Documentation

Purpose: Comprehensive guide to CueLoop's prompt template system, including embedded defaults, override mechanisms, template variables, and prompt flow.

Overview

CueLoop uses a sophisticated prompt system to guide AI agents through task execution. The system is designed around these core principles:

Embedded Defaults: All default prompts are embedded in the Rust binary at compile time, ensuring CueLoop works out-of-the-box without external dependencies.
Repository Overrides: Teams can customize prompts per repository by placing override files in .cueloop/prompts/.
Template Variables: Dynamic placeholders ({{TASK_ID}}, {{USER_REQUEST}}, etc.) are replaced at runtime with context-specific values.
Multi-Phase Composition: Worker prompts are composed by combining base prompts with phase-specific wrappers.
RepoPrompt Integration: Optional integration with RepoPrompt tools for enhanced codebase exploration and planning.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                     PROMPT RESOLUTION FLOW                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────┐    ┌──────────────────┐                   │
│  │  Embedded       │    │  Repository      │                   │
│  │  Defaults       │    │  Overrides       │                   │
│  │  (Binary)       │    │  (.cueloop/prompts)│                   │
│  └────────┬────────┘    └────────┬─────────┘                   │
│           │                      │                              │
│           └──────────┬───────────┘                              │
│                      ▼                                          │
│           ┌─────────────────┐                                  │
│           │  Template       │                                  │
│           │  Loading        │                                  │
│           │  (with fallback)│                                  │
│           └────────┬────────┘                                  │
│                    │                                            │
│                    ▼                                            │
│           ┌─────────────────┐                                  │
│           │  Variable       │                                  │
│           │  Expansion      │                                  │
│           │  ({{VAR}})      │                                  │
│           └────────┬────────┘                                  │
│                    │                                            │
│                    ▼                                            │
│           ┌─────────────────┐                                  │
│           │  Prompt         │                                  │
│           │  Composition    │                                  │
│           │  (Phase wraps)  │                                  │
│           └────────┬────────┘                                  │
│                    │                                            │
│                    ▼                                            │
│           ┌─────────────────┐                                  │
│           │  Final Rendered │                                  │
│           │  Prompt         │                                  │
│           │  → Runner       │                                  │
│           └─────────────────┘                                  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Embedded Defaults

Default prompts are embedded in the CueLoop binary using Rust's include_str! macro. They live in:

crates/cueloop/assets/prompts/
├── worker.md                     # Base worker prompt
├── worker_phase1.md              # Phase 1 (planning) wrapper
├── worker_phase2.md              # Phase 2 (implementation, 2-phase)
├── worker_phase2_handoff.md      # Phase 2 handoff (3-phase)
├── worker_phase3.md              # Phase 3 (review) wrapper
├── worker_single_phase.md        # Single-pass execution
├── task_builder.md               # Task creation from user request
├── task_updater.md               # Task field updates
├── scan_general_v2.md            # General scan mode (v2)
├── scan_maintenance_v1.md        # Maintenance scan (v1)
├── scan_maintenance_v2.md        # Maintenance scan (v2)
├── scan_innovation_v1.md         # Innovation scan (v1)
├── scan_innovation_v2.md         # Innovation scan (v2)
├── merge_conflicts.md            # Merge conflict resolution
├── code_review.md                # Phase 3 code review body
├── completion_checklist.md       # Implementation completion
├── phase2_handoff_checklist.md   # Phase 2 handoff steps
└── iteration_checklist.md        # Refinement iteration steps

Fallback Behavior

When loading a prompt, CueLoop follows this resolution order:

Check for override at .cueloop/prompts/<name>.md
If override exists → use it
If override missing → use embedded default
If override errors → propagate error (don't silently fall back)

This ensures that:

New repositories work immediately with sensible defaults
Teams can incrementally customize only the prompts they need
Malformed override files are caught early

Prompt Overrides

To customize prompts for a repository, create files in .cueloop/prompts/:

mkdir -p .cueloop/prompts

# Override the base worker prompt
cat > .cueloop/prompts/worker.md << 'EOF'
# CUSTOM MISSION
You are an autonomous engineer specializing in this codebase...

# CONTEXT (READ IN ORDER)
1. `AGENTS.md`
2. `.cueloop/README.md`
3. Task details via `cueloop task show {{TASK_ID}}`

{{PROJECT_TYPE_GUIDANCE}}
EOF

# Override phase 1 planning
cat > .cueloop/prompts/worker_phase1.md << 'EOF'
# CUSTOM PLANNING MODE

CURRENT TASK: {{TASK_ID}}

{{BASE_WORKER_PROMPT}}

## OUTPUT REQUIREMENT
Produce a detailed implementation plan...
EOF

File Naming Convention

Prompt File	Purpose	Required Placeholders
`worker.md`	Base worker behavior	`{{PROJECT_TYPE_GUIDANCE}}` (if enabled)
`worker_phase1.md`	Planning phase	`{{TASK_ID}}`, `{{TOTAL_PHASES}}`, `{{PLAN_PATH}}`, `{{BASE_WORKER_PROMPT}}`
`worker_phase2.md`	Implementation (2-phase)	`{{TASK_ID}}`, `{{PLAN_TEXT}}`, `{{CHECKLIST}}`
`worker_phase2_handoff.md`	Implementation (3-phase)	Same as phase2
`worker_phase3.md`	Code review phase	`{{TASK_ID}}`, `{{CODE_REVIEW_BODY}}`, `{{COMPLETION_CHECKLIST}}`
`worker_single_phase.md`	Single-pass execution	`{{TASK_ID}}`, `{{CHECKLIST}}`, `{{BASE_WORKER_PROMPT}}`
`task_builder.md`	Task creation	`{{USER_REQUEST}}`, `{{HINT_TAGS}}`, `{{HINT_SCOPE}}`
`task_updater.md`	Task updates	`{{TASK_ID}}`
`scan_general_v2.md`	Repository scanning	`{{USER_FOCUS}}`, `{{PROJECT_TYPE_GUIDANCE}}`
`merge_conflicts.md`	Conflict resolution	`{{CONFLICT_FILES}}`
`code_review.md`	Review body	`{{TASK_ID}}`
`completion_checklist.md`	Completion steps	`{{TASK_ID}}`

Validation Rules

Override files must preserve required placeholders:

// From registry.rs - task_builder requires these placeholders:
const TASK_BUILDER_REQUIRED: &[RequiredPlaceholder] = &[
    RequiredPlaceholder {
        token: "{{USER_REQUEST}}",
        error_message: "Template error: task builder prompt template is missing...",
    },
    // ...
];

If an override is missing required placeholders, CueLoop fails fast with a clear error message.

Instruction Files

Configured agent.instruction_files are prepended as authoritative content at the top of every prompt. CueLoop does not auto-inject ~/.codex/AGENTS.md or repo AGENTS.md; prompt text should not imply otherwise.

Available Prompts

Base Worker (`worker.md`)

The foundation prompt used across all phases. Defines:

Mission statement
Context reading order (AGENTS.md, .cueloop/README.md, etc.)
Operating rules (don't ask permission, fix root causes, etc.)
Pre-flight safety checks
Stop/cancel semantics

Key Placeholders:

{{TASK_ID}} - Current task identifier
{{PROJECT_TYPE_GUIDANCE}} - Code vs Docs priorities
{{INTERACTIVE_INSTRUCTIONS}} - TTY-specific guidance (usually empty)

Phase 1: Planning (`worker_phase1.md`)

Wraps the base worker for the planning phase:

Instructs the agent to produce a plan file only
Prohibits file modifications (except plan cache)
Emphasizes standalone plan quality for Phase 2 execution

Key Placeholders:

{{TOTAL_PHASES}} - Number of phases (2 or 3)
{{PLAN_PATH}} - Where to write the plan (e.g., .cueloop/cache/plans/CL-0001.md)
{{ITERATION_CONTEXT}} - Refinement guidance for multi-iteration runs
{{REPOPROMPT_BLOCK}} - Tool instructions when RepoPrompt is enabled

Phase 2: Implementation (`worker_phase2.md`)

Wraps the base worker for implementation (2-phase workflow):

Receives the plan from Phase 1
Executes implementation
Runs the configured CI gate when enabled and completes task

Key Placeholders:

{{PLAN_TEXT}} - Content of the Phase 1 plan
{{CHECKLIST}} - Completion checklist
{{ITERATION_COMPLETION_BLOCK}} - Rules for non-final iterations

Phase 2 Handoff (`worker_phase2_handoff.md`)

3-phase workflow variant that stops after implementation:

Same implementation focus as worker_phase2
Stops after configured Phase 2 validation is satisfied; agent.ci_gate.enabled=false skips only the configured CI command/requirement (not the Phase 2 run or Phase 3 handoff)
Leaves dirty working tree for Phase 3 review

Phase 3: Review (`worker_phase3.md`)

Code review and finalization phase:

Reviews Phase 2 changes against standards
Makes refinements if needed
Handles final completion
Treats agent.ci_gate.enabled=false as skipping only configured CI validation, not Phase 3 review/completion work

Key Placeholders:

{{CODE_REVIEW_BODY}} - The code_review.md content
{{PHASE2_FINAL_RESPONSE}} - Context from Phase 2 execution
{{PHASE3_COMPLETION_GUIDANCE}} - Final vs non-final iteration rules

Single Phase (`worker_single_phase.md`)

Combined plan+implement for simple tasks:

Brief planning allowed
Direct implementation
No separate plan file required

Task Builder (`task_builder.md`)

Converts user requests into queue tasks:

Analyzes user request
Generates proper task JSON
Inserts into .cueloop/queue.jsonc

Key Placeholders:

{{USER_REQUEST}} - Original user input
{{HINT_TAGS}} - Suggested tags (may be empty)
{{HINT_SCOPE}} - Suggested scope (may be empty)

Example user request flow:

cueloop task build "Fix the login button styling"
# → Loads task_builder.md
# → Renders with {{USER_REQUEST}} = "Fix the login button styling"
# → Agent creates task in queue.json

Scan Prompts (`scan_*.md`)

Repository scanning for actionable tasks:

General: Broad codebase analysis
Maintenance: Focus on tech debt, bugs, upkeep
Innovation: Feature gaps, improvements, new capabilities

Key Placeholders:

{{USER_FOCUS}} - Area of focus (e.g., "authentication module")
{{PROJECT_TYPE_GUIDANCE}} - Code vs Docs priorities

Merge Conflicts (`merge_conflicts.md`)

Parallel run conflict resolution:

Special handling for queue.json/done.json
General conflict resolution for other files

Key Placeholders:

{{CONFLICT_FILES}} - List of files with conflicts

Code Review (`code_review.md`)

Review body injected in Phase 3:

Coding standards reference
Review responsibilities
CI gate policies

Checklists

completion_checklist.md: Steps for finishing implementation, including the explicit contract that agent.ci_gate.enabled=false skips only CueLoop-managed CI validation and never disables run/task execution. phase2_handoff_checklist.md: Steps for 3-phase handoff; when agent.ci_gate.enabled=false, Phase 2 implementation and handoff still continue. iteration_checklist.md: Steps for refinement iterations; disabled CI gate configuration skips only the configured CI command/requirement, and iteration work continues.

Template Variables

Standard Placeholders

Placeholder	Description	Example
`{{TASK_ID}}`	Current task identifier	`CL-0001`
`{{USER_REQUEST}}`	Original user input	"Fix login button"
`{{USER_FOCUS}}`	Scan focus area	"authentication"
`{{HINT_TAGS}}`	Suggested tags	`["ui", "bug"]`
`{{HINT_SCOPE}}`	Suggested scope	`["src/auth/"]`
`{{PLAN_PATH}}`	Plan cache file path	`.cueloop/cache/plans/CL-0001.md`
`{{PLAN_TEXT}}`	Content of plan file	(full plan markdown)
`{{TOTAL_PHASES}}`	Phase count	`2` or `3`
`{{CONFLICT_FILES}}`	Conflicted file list	`["file1.rs", "file2.rs"]`

Config Access

Access configuration values via {{config.section.key}}:

CI Gate Command: {{config.agent.ci_gate_display}}
CI Gate Enabled: {{config.agent.ci_gate_enabled}}
Git Commit/Push: {{config.agent.git_publish_mode}}
Runner: {{config.agent.runner}}
Model: {{config.agent.model}}
Queue Prefix: {{config.queue.id_prefix}}

Available config paths:

config.agent.runner
config.agent.model
config.agent.reasoning_effort
config.agent.iterations
config.agent.followup_reasoning_effort
config.agent.claude_permission_mode
config.agent.ci_gate_display
config.agent.ci_gate_enabled
config.agent.git_publish_mode
config.queue.id_prefix
config.queue.id_width
config.project_type
config.version

Environment Variables

Access environment variables with shell-style syntax:

Home directory: ${HOME}
With default: ${UNKNOWN_VAR:-default_value}
Escaped: $${LITERAL} or \${LITERAL}

Environment variables are expanded before config values.

Project Type Guidance

The {{PROJECT_TYPE_GUIDANCE}} placeholder injects project-specific priorities:

Code Projects

## PROJECT TYPE: CODE

This is a code repository. Prioritize:
- Implementation correctness and type safety
- Test coverage and regression prevention
- Performance and resource efficiency
- Clean, maintainable code structure

Documentation Projects

## PROJECT TYPE: DOCS

This is a documentation repository. Prioritize:
- Clear, accurate information
- Consistent formatting and structure
- Accessibility and readability
- Examples and practical guidance

Configuration

Set project type in .cueloop/config.jsonc:

{
  "project_type": "code"
}

There is no dedicated cueloop config set subcommand; edit the config file directly.

Template Control

Not all prompts receive project type guidance. The registry controls this:

// From registry.rs
PromptTemplateId::Worker => PromptTemplate {
    // ...
    project_type_guidance: true,  // Injected
},
PromptTemplateId::WorkerPhase1 => PromptTemplate {
    // ...
    project_type_guidance: false, // Not injected (inherits from base)
},

RepoPrompt Integration

When RepoPrompt tooling is enabled, CueLoop injects additional instructions:

Tool Injection (`repoprompt_tool_injection`)

Adds preference-based RepoPrompt guidance:

## REPOPROMPT TOOLING (WHEN CONNECTED)
You are running in a RepoPrompt-enabled environment. Prefer RepoPrompt tools when they are available in this harness.

The injected guidance describes the usual RepoPrompt MCP tool inventory while making it clear that other repository tools remain valid when RepoPrompt is unavailable.

Plan Requirement (`repoprompt_plan_required`)

Adds RepoPrompt planning guidance:

## REPOPROMPT PLANNING FLOW
When `context_builder` is available, use it as the standard planning path.

The planning block still keeps the hard artifact boundary intact: Phase 1 must write the final plan to {{PLAN_PATH}} because later phases read that file.

Configuration

Enable RepoPrompt integration in .cueloop/config.jsonc:

{
  "agent": {
    "repoprompt_tool_injection": true,
    "repoprompt_plan_required": true
  }
}

CLI Fallback

The instructions include a CLI fallback for when MCP tools are unavailable:

## CLI FALLBACK (WHEN MCP TOOLS ARE UNAVAILABLE)
If RepoPrompt MCP tools are unavailable, prefer the RepoPrompt CLI when it exists:
- Start with `rp-cli --help`
- Optionally use `rp -h` if the wrapper is installed
- `rp-cli` commonly uses `-e` to execute an expression such as `rp-cli -e 'tree'`

Prompt Flow

Worker Prompt Composition

┌─────────────────────────────────────────────────────────┐
│                  WORKER PROMPT FLOW                      │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  Phase 1: Planning                                       │
│  ┌─────────────┐                                         │
│  │ worker.md   │  Base prompt with PROJECT_TYPE_GUIDANCE │
│  └──────┬──────┘                                         │
│         │                                                │
│         ▼                                                │
│  ┌─────────────────┐                                     │
│  │ worker_phase1   │  Wraps base, adds REPOPROMPT_BLOCK  │
│  │   .md           │  and planning constraints           │
│  └────────┬────────┘                                     │
│           │                                              │
│           ▼                                              │
│  ┌─────────────────┐     ┌─────────────┐                │
│  │ Rendered Prompt │  +  │ ITERATION_  │  (if multi-   │
│  │                 │     │ CONTEXT       │   iteration)  │
│  └─────────────────┘     └─────────────┘                │
│                                                          │
│  ─────────────────────────────────────────────────────  │
│                                                          │
│  Phase 2: Implementation                                 │
│  ┌─────────────┐                                         │
│  │ worker.md   │  Base prompt                            │
│  └──────┬──────┘                                         │
│         │                                                │
│         ▼                                                │
│  ┌─────────────────┐                                     │
│  │ worker_phase2   │  Wraps base, injects PLAN_TEXT      │
│  │   .md           │  and CHECKLIST                      │
│  └────────┬────────┘                                     │
│           │                                              │
│           ▼                                              │
│  ┌─────────────────┐     ┌─────────────────────────┐    │
│  │ Rendered Prompt │  +  │ ITERATION_COMPLETION_   │    │
│  │                 │     │ BLOCK (if non-final)    │    │
│  └─────────────────┘     └─────────────────────────┘    │
│                                                          │
│  ─────────────────────────────────────────────────────  │
│                                                          │
│  Phase 3: Review                                         │
│  ┌─────────────┐                                         │
│  │ worker.md   │  Base prompt                            │
│  └──────┬──────┘                                         │
│         │                                                │
│         ▼                                                │
│  ┌─────────────────┐                                     │
│  │ worker_phase3   │  Wraps base, injects CODE_REVIEW_   │
│  │   .md           │  BODY and COMPLETION_CHECKLIST      │
│  └────────┬────────┘                                     │
│           │                                              │
│           ▼                                              │
│  ┌─────────────────┐     ┌─────────────────────────┐    │
│  │ Rendered Prompt │  +  │ PHASE3_COMPLETION_      │    │
│  │                 │     │ GUIDANCE                │    │
│  └─────────────────┘     └─────────────────────────┘    │
│                                                          │
└─────────────────────────────────────────────────────────┘

Scan Prompt Flow

┌─────────────────┐
│  scan_general   │  Load template
│    _v2.md       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Expand Config   │  {{config.agent.*}}
│   Variables     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Inject Project  │  {{PROJECT_TYPE_GUIDANCE}}
│  Type Guidance  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Replace Focus   │  {{USER_FOCUS}}
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Validate: No    │  Ensure all {{...}} resolved
│ Unresolved Vars │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Final Prompt   │  → Runner
└─────────────────┘

Task Builder Flow

User Request ──► Load task_builder.md ──► Validate Required Placeholders
                                               │
                                               ▼
                    ┌──────────────────────────────────────────┐
                    │  Render with:                            │
                    │  - {{USER_REQUEST}} = user input         │
                    │  - {{HINT_TAGS}} = suggested tags        │
                    │  - {{HINT_SCOPE}} = suggested scope      │
                    │  - {{PROJECT_TYPE_GUIDANCE}}             │
                    └─────────────────────┬────────────────────┘
                                          │
                                          ▼
                    ┌──────────────────────────────────────────┐
                    │  Validate: No unresolved placeholders    │
                    └─────────────────────┬────────────────────┘
                                          │
                                          ▼
                    ┌──────────────────────────────────────────┐
                    │  Agent creates task in queue.json        │
                    └──────────────────────────────────────────┘

Best Practices

Creating Overrides

Start with the default: Copy the embedded default as a starting point
Preserve required placeholders: Check the registry for required tokens
Test validation: Run cueloop queue validate after changes
Document changes: Add comments explaining customizations

Example override with comments:

<!-- Custom worker prompt for MyProject -->
<!-- Changes: Added security review requirement -->

# MISSION
You are an autonomous engineer for MyProject...

## SECURITY REVIEW (ADDED)
Before completing any task:
- Check for exposed secrets in new code
- Verify input validation on new endpoints
- Review SQL queries for injection risks

# CONTEXT (READ IN ORDER)
...

Variable Safety

Always use {{VAR}} syntax for template variables
Use ${VAR} for environment variables
Escape literal ${ with $${ or \${
The validation step catches unresolved {{...}} placeholders

Multi-Repository Setup

For organizations with multiple repositories:

# Create a shared prompt template repository
git clone https://github.com/org/cueloop-prompts.git

# Link to each project
cd project-a
ln -s ../cueloop-prompts/worker.md .cueloop/prompts/worker.md
ln -s ../cueloop-prompts/worker_phase1.md .cueloop/prompts/worker_phase1.md

Debugging Prompts

Use --debug flag to see rendered prompts:

# Debug mode writes raw prompts to log
cueloop run --debug

# Check the debug log
cat .cueloop/logs/debug.log | grep -A 50 "Rendered prompt"

Reference

Source Code Locations

Component	Path
Public API	`crates/cueloop/src/prompts.rs`
Internal Modules	`crates/cueloop/src/prompts_internal/`
Registry	`crates/cueloop/src/prompts_internal/registry.rs`
Utilities	`crates/cueloop/src/prompts_internal/util.rs`
Worker Phases	`crates/cueloop/src/prompts_internal/worker_phases.rs`
Template System	`crates/cueloop/src/template/`
Embedded Defaults	`crates/cueloop/assets/prompts/`

FilesExpand file tree

prompts.md

Latest commit

History

prompts.md

File metadata and controls

CueLoop Prompt System

Overview

Architecture Diagram

Embedded Defaults

Fallback Behavior

Prompt Overrides

File Naming Convention

Validation Rules

Instruction Files

Available Prompts

Base Worker (worker.md)

Phase 1: Planning (worker_phase1.md)

Phase 2: Implementation (worker_phase2.md)

Phase 2 Handoff (worker_phase2_handoff.md)

Phase 3: Review (worker_phase3.md)

Single Phase (worker_single_phase.md)

Task Builder (task_builder.md)

Scan Prompts (scan_*.md)

Merge Conflicts (merge_conflicts.md)

Code Review (code_review.md)

Checklists

Template Variables

Standard Placeholders

Config Access

Environment Variables

Project Type Guidance

Code Projects

Documentation Projects

Configuration

Template Control

RepoPrompt Integration

Tool Injection (repoprompt_tool_injection)

Plan Requirement (repoprompt_plan_required)

Configuration

CLI Fallback

Prompt Flow

Worker Prompt Composition

Scan Prompt Flow

Task Builder Flow

Best Practices

Creating Overrides

Variable Safety

Multi-Repository Setup

Debugging Prompts

Reference

Source Code Locations

Related Documentation

Base Worker (`worker.md`)

Phase 1: Planning (`worker_phase1.md`)

Phase 2: Implementation (`worker_phase2.md`)

Phase 2 Handoff (`worker_phase2_handoff.md`)

Phase 3: Review (`worker_phase3.md`)

Single Phase (`worker_single_phase.md`)

Task Builder (`task_builder.md`)

Scan Prompts (`scan_*.md`)

Merge Conflicts (`merge_conflicts.md`)

Code Review (`code_review.md`)

Tool Injection (`repoprompt_tool_injection`)

Plan Requirement (`repoprompt_plan_required`)