Prompt Config

Structure and fields of the PromptConfig JSONB object that defines how each role's prompts are constructed.

Every role stores its prompt configuration in a prompt_config JSONB column. This object controls the system prompt, task templates, output templates, and memory profile for the role.

PromptConfig Structure

{
  "system_prompt": "You are a senior software developer...",
  "developer_prompt": "Follow these project conventions...",
  "templates": {
    "ticket_task": "Implement the following ticket:\n\nTitle: {{ ticket.title }}\n...",
    "chat_task": "Respond to the user's message:\n\n{{ chat.message }}",
    "gate_eval": "Evaluate whether the output meets the criteria:\n\n{{ gate.criteria }}",
    "cron_task": "Perform your scheduled maintenance check..."
  },
  "output_templates": {
    "agent_done": "Task complete. Summarize what was done.",
    "gate_pass": "PASS",
    "gate_fail": "FAIL: describe what needs to be fixed"
  },
  "memory_profile": {
    "core_focus": ["Architecture patterns", "Performance best practices"],
    "project_focus": ["API endpoints", "Database schema decisions"],
    "priority_categories": ["architecture", "api_design"]
  }
}

Fields

system_prompt

Required. The role's core identity prompt. This is sent as the system message to the LLM provider.

Use this for stable, task-independent instructions: personality, expertise area, behavioral rules, and communication style.

You are a senior software architect with expertise in distributed systems.
You focus on maintainability, scalability, and clean API design.
Always explain your reasoning before making changes.

Optional. Application-level instructions sent as a developer message (for providers that support it) or appended to the system prompt. Use this for project-wide conventions, coding standards, or workflow rules that apply across all task types.

Follow the project's existing patterns. Use TypeScript strict mode.
All API endpoints must have OpenAPI annotations.

When a mode session is active, the mode's system_addon is appended to the developer prompt.

templates

Required. A map of task-type-specific instruction templates. The worker selects the appropriate template based on the pipeline step type.

Key	Used When	Common Variables
`ticket_task`	Agent step processes a ticket	`{{ ticket.title }}`, `{{ ticket.description }}`, `{{ ticket.acceptance_criteria }}`
`chat_task`	Agent responds in chat	`{{ chat.message }}`
`gate_eval`	Gate step evaluates output	`{{ gate.criteria }}`, `{{ gate.previous_output }}`
`cron_task`	Cron-triggered agent step	`{{ global.timestamp }}`, `{{ project.name }}`

All three of ticket_task, chat_task, and gate_eval are required. The cron_task template is optional -- when absent and the step is triggered by a cron, the ticket_task template is used as a fallback.

Example ticket_task template:

Implement the following ticket:

Title: {{ ticket.title }}
Description: {{ ticket.description }}
Acceptance Criteria: {{ ticket.acceptance_criteria }}
Tags: {{ ticket.tags }}
Source: {{ ticket.source }}

{{ context.documents }}

{{ context.memory }}

Work on branch {{ git.branch }} and target {{ git.target_branch }} for PRs.

output_templates

Required. Templates that define the expected output format for different completion states. The pipeline executor uses these to parse the agent's final response.

Key	Purpose
`agent_done`	Instructions for how the agent should format its completion output
`gate_pass`	Output format when a gate evaluation passes
`gate_fail`	Output format when a gate evaluation fails

All three keys are required.

memory_profile

Optional. Configures what the role's memory system should focus on when storing and retrieving memories.

{
  "core_focus": [
    "Architecture patterns and decisions",
    "Performance optimization techniques"
  ],
  "project_focus": [
    "API endpoint conventions",
    "Database schema evolution"
  ],
  "priority_categories": [
    "architecture",
    "api_design",
    "performance"
  ]
}

Field	Scope	Description
`core_focus`	Cross-project	Expertise that persists across all projects. Accumulated knowledge the role builds over time.
`project_focus`	Per-project	Project-specific facts and decisions. Scoped to the current project.
`priority_categories`	Retrieval	Categories prioritized when retrieving memories for the prompt.

When a memory profile is configured, the worker injects a <memory-profile> XML block into the developer prompt instructing the agent to use the memory_store tool with the appropriate scope parameter ("core", "project", or "shared").

Validation Rules

The PromptConfig is validated before saving:

system_prompt must not be empty
templates must contain all three required keys: ticket_task, chat_task, gate_eval
output_templates must contain all three required keys: agent_done, gate_pass, gate_fail

Validation errors are returned as 422 Validation Error responses from the API.

Updating Prompt Config

Via API

# Get current prompt config
curl -H "Authorization: Bearer $TOKEN" \
  https://your-instance.com/api/v1/agent-roles/:id/prompt

# Update prompt config
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_config": {
      "system_prompt": "You are a code reviewer...",
      "developer_prompt": "",
      "templates": {
        "ticket_task": "Review the code for: {{ ticket.title }}",
        "chat_task": "{{ chat.message }}",
        "gate_eval": "Evaluate: {{ gate.criteria }}"
      },
      "output_templates": {
        "agent_done": "Review complete.",
        "gate_pass": "PASS",
        "gate_fail": "FAIL"
      },
      "memory_profile": {}
    }
  }' \
  https://your-instance.com/api/v1/agent-roles/:id/prompt

Resetting to Default

System-derived roles can be reset to the original system template:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  https://your-instance.com/api/v1/agent-roles/:id/reset

This overwrites the user's prompt_config with the system template's version. Only works for roles that were copied from a system template (source_role_id is set).

Prompt Config

On this page