▋
docs/02-prompts-and-templates.md

Prompts and Agent Templates

This document defines how prompts are structured and how template-based agents are configured. The goal is predictable, auditable behavior across providers.

Objectives

  • Consistent prompt structure across providers.
  • Editable role templates.
  • Explicit capabilities and permissions in task payloads.
  • Full prompt logging per turn.

Prompt architecture

Prompts are built in layers, with the same ordering across providers:

  1. System context
  2. Role template
  3. Mode preamble (PLANNING/IMPLEMENTATION)
  4. Task payload (nodes, edges, messages, handoffs)

Canonical prompt blocks

Each block is stored as an artifact for auditability.

System context

A stable framing of orchestration behavior:

  • Graph-first workflow
  • Observability requirements
  • Planning vs Implementation constraints
  • Loop safety expectations

Role template

Role templates are user-editable files (see Template resolution below).

Mode preamble

Injected based on global mode:

PLANNING:

  • Read-only repo access
  • Write access allowed only in docs/
  • Ask to switch to Implementation if code changes are needed

IMPLEMENTATION:

  • Code edits allowed
  • Docs updates allowed
  • Run verification when appropriate

Task payload

The task payload includes:

  • Run/node metadata
  • Capabilities + permissions
  • Known nodes + edges (ids + aliases)
  • Incoming messages and handoffs

Template resolution

Templates are loaded in this order:

  1. Repo overrides: docs/templates/