Creating Prompts

Prompts are reusable templates that configure the initial context for agents when creating workspaces. They help standardize common workflows like code reviews, bug fixes, or feature implementation.

Config File Locations

| Scope | Path | Override Priority | |---------|---------------------------------------|-------------------| | Global | ~/.config/sidecar/config.json | Lower | | Project | .sidecar/config.json (in project) | Higher |

Project prompts override global prompts with the same name (case-sensitive match).

Config Format

json
{
  "prompts": [
    {
      "name": "Code Review",
      "ticketMode": "optional",
      "body": "Do a detailed code review of {{ticket || 'open reviews'}}.\nFocus on correctness, edge cases, and test coverage."
    }
  ]
}

Prompt Fields

name (required)

Display name shown in the prompt picker. Keep it concise.

ticketMode (optional)

Controls how the ticket/task field behaves:

| Mode | Behavior | |------------|-----------------------------------------------| | optional | Task field shown, can be empty (default) | | required | Task must be selected before creating | | none | Task field is hidden, prompt stands alone |

body (required)

The prompt text sent to the agent. Supports template variables. Use \n for newlines.

Template Variables

{{ticket}}

Expands to the selected task ID. Returns empty string if no task selected.

json
"body": "Fix issue {{ticket}}."
// With task td-abc123: "Fix issue td-abc123."
// Without task: "Fix issue ."

{{ticket || 'fallback'}}

Expands to task ID, or the fallback text if no task selected.

json
"body": "Review {{ticket || 'all open items'}}."
// With task td-abc123: "Review td-abc123."
// Without task: "Review all open items."

Only single quotes work for fallback text:

• {{ticket || 'default'}} -- works
• {{ticket || "default"}} -- does NOT work

Examples

Task-Required Workflow

json
{
  "name": "Implement Task",
  "ticketMode": "required",
  "body": "Begin work on {{ticket}}. Use td to track progress.\nRead the task description carefully before starting."
}

Standalone Workflow

json
{
  "name": "Run Tests",
  "ticketMode": "none",
  "body": "Run the full test suite. Fix any failures.\nReport a summary when complete."
}

Flexible Workflow

json
{
  "name": "Code Review Session",
  "ticketMode": "optional",
  "body": "Start a review session for {{ticket || 'open reviews'}}.\nCreate td tasks for any issues found."
}

Backlog Refinement

json
{
  "name": "Backlog Refinement",
  "ticketMode": "none",
  "body": "Start a backlog refinement session. Use td to find all tasks in the backlog starting with the oldest. For each task:\n\n1. Determine relevance - has it been implemented, is it still needed? If not relevant, comment on the task and close it. If questionable, leave open with notes.\n\n2. Update tasks with out-of-date code references to reflect the current state of the codebase.\n\nUse sub-agents to analyze multiple tasks in parallel. Present a report of findings and changes when complete."
}

Default Prompts

If no config file exists, the app creates one with 5 built-in templates:

• Begin Work on Ticket (required)
• Code Review Ticket (required)
• Plan to Epic (No Impl) (none)
• Plan to Epic + Implement (none)
• TD Review Session (none)

Press d in the prompt picker to install defaults if none are configured.

Scope Indicators

In the prompt picker, prompts show their source:

• [G] - Global prompt (from ~/.config/sidecar/)
• [P] - Project prompt (from .sidecar/)

Important Notes

• Prompt names must match exactly (case-sensitive) for project overrides
• Only single quotes work in fallback syntax
• ticketMode defaults to optional if omitted
• Config files are loaded when creating a workspace; restart the app to reload
• Keep names short (they appear in a table with limited width)
• Use \n for newlines in prompt bodies