[■]─[▪] sidecar
Get Started
Documentation

Prompt Compile

sidecar prompt compile turns a task packet (or a freestanding spec) into a single compiled prompt: deterministic, trimmed to budget, and emitted as either markdown or a JSON envelope with a full section trace. It's what every sidecar run calls under the hood, and it's useful on its own for iterating on a prompt or composing one from another tool.

From a task packet Stable

Compile a packet by id:

$ sidecar prompt compile T-001
$ sidecar prompt compile T-001 --runner claude --agent-role builder-app
$ sidecar prompt compile T-001 --explain
$ sidecar prompt compile T-001 --format json -o out.json

Flags:

  • --runner codex|claude — tag the compiled prompt for a specific runner.
  • --agent-role <role> — inject an agent role into the prompt.
  • --budget <n> / --budget-max <n> — override the default target and safety ceiling.
  • --section-policy id=keep|trim-last|drop,... — per-section trimming overrides.
  • --explain — prints a per-section trace (policy, tokens, items kept/total) to stderr.
  • --format json — emit the standard envelope with markdown and full metadata.sections trace.
  • -o <path> — write the compiled output to a file.

All compile runs apply automatic token budgeting. See Prompt Token Budgeting for the trimming model, required-section list, and budget defaults.

Freestanding prompt specs Beta

sidecar prompt compile also accepts a .yaml/.yml/.json spec file — no TaskPacket required. This lets you iterate on prompts directly, or compose them programmatically from another tool. 

$ sidecar prompt compile ./my-prompt.yaml
$ sidecar prompt compile ./my-prompt.yaml --explain
$ sidecar prompt compile ./my-prompt.yaml --budget 1500 --budget-max 2000
$ sidecar prompt compile ./my-prompt.yaml --section-policy notes=drop,examples=trim-last
$ sidecar prompt compile ./my-prompt.yaml -o out.md
$ sidecar prompt compile ./my-prompt.yaml --format json

Spec schema

my-prompt.yaml yaml 
header:
  - "# My Prompt"
  - "Optional preamble rendered verbatim."

sections:
  - id: objective           # optional — auto-slugified from title if omitted
    title: Objective
    required: true          # forces policy=keep (never trimmed or dropped)
    content: |              # text section: string or string[]
      Describe the goal in one or two sentences.

  - title: Notes
    list:                   # list section
      - First note
      - Second note
      - Third note
    empty_placeholder: "- no notes yet"
    trim:
      policy: trim-last     # keep | trim-last | drop
      limit: 2              # target-pass cap
      limit_strict: 1       # safety-valve cap
      overflow_label: notes # renders "+ N more notes (see task packet for full list)"

budget:
  target: 1200              # soft target
  max: 1500                 # hard ceiling before strict pass

policy_overrides:
  notes: keep               # override per-section trim policies by id

Trim policies

  • keep — never trim or drop (default for text sections and required: true)
  • trim-last — apply limit on the target pass, limit_strict on the strict pass (lists only)
  • drop — remove the whole section on the strict pass when still over budget

--explain prints a per-section trace to stderr. --format json emits the standard envelope with markdown plus a full metadata.sections trace for programmatic use.

Related