Plan Placeholders

Placeholders make plans reusable. Instead of hardcoding specific bullets, plans describe what they need and the system figures out what to use at runtime.

Why Placeholders Matter

Think of a plan as a recipe. You could write "use the tomatoes in my fridge," which only works if you have those specific tomatoes. Or you could write "use fresh tomatoes," and let someone figure out where to get them based on what's available.

Placeholders work the same way. A plan says "I need user documents for analysis" without specifying which documents. When the plan runs, the system looks at what the user actually has—uploaded files, saved collections, database queries—and uses what makes sense.

This means one plan works for everyone. The same "analyze documents" plan adapts to each user's actual data without needing custom versions.

How Resolution Works

When a plan hits a placeholder step, the system tries several strategies in order:

Check the conversation: Did the user just upload a file or mention data? Use that.

Search private bullets: Does the user have saved data bullets that match? Reuse them.

Generate on-demand: No existing match? Create a new bullet by fetching from an API, running a database query, or processing available content.

Ask the user: If the system provides a specific bullet ID, use exactly that.

The system validates that whatever it finds meets the placeholder's requirements before proceeding.

Example

Here's how a placeholder looks in a plan:

steps:
  - placeholder: "User's email inbox data from the last month"
    type: data
    constraints:
      - "Must include message content, sender, timestamp"
      - "Must be from the last 30 days"
  
  - script: bullet://example/email-triage@2.0
    inputs:
      messages:
        description: The email inbox data from the placeholder

When Alice runs this plan, the system might fetch her Gmail data and wrap it in a data bullet. When Bob runs it, the system might use his Outlook data instead. Same plan, different data, both work.

Reproducibility

Even though placeholders resolve differently for different users, everything is recorded. The execution manifest captures exactly which bullet was used to fill each placeholder. This means you can replay any execution with the exact same bullets, even though the original plan used flexible placeholders.