Plan

A plan is an ordered sequence of steps that compose bullets into workflows. Plans reference other bullets (data, scripts, guidance, and other plans) and define how they work together.

Purpose

Plans orchestrate multiple bullets into coherent workflows. Each step in the plan references a bullet and specifies how it connects to other steps. The steps execute in strict order as defined in the array.

Plans are the only bullet type that references other bullets. Scripts, data, and guidance are standalone - only plans create connections between bullets.

Step Syntax

Each step has a type tag indicating which kind of bullet it references:

steps:
  - data: bullet://example/customer-data@1.0
  
  - guidance: bullet://example/analysis-tips@1.0
  
  - plan: bullet://example/data-preprocessing@1.0
  
  - script: bullet://example/sentiment-analyzer@2.0
    inputs:
      data:
        description: The preprocessed data from the plan step

Plans can reference other plans, enabling hierarchical composition of workflows. This is central to the design - complex workflows are built by composing smaller, reusable plans.

Only scripts have inputs: - everything else (data, guidance, plans) is standalone and just referenced.

Plan Composition

Plans can reference other plans as steps, enabling hierarchical composition of complex workflows. This is a fundamental design principle - larger workflows are built by composing smaller, focused, reusable plans.

When a plan references another plan, the referenced plan executes completely as a single step. The results from the referenced plan become available in the execution context for subsequent steps to use.

steps:
  # Step 1: Execute a complete data validation plan
  - plan: bullet://example/data-validation@1.0
  
  # Step 2: Execute a complete data cleaning plan
  - plan: bullet://example/data-cleaning@2.0
  
  # Step 3: Use the validated and cleaned data
  - script: bullet://example/process-validated-data@1.0
    inputs:
      data:
        description: The validated and cleaned data from the previous plans

This composition model enables:

Modularity: Break complex workflows into smaller, testable pieces
Reusability: Share common sub-workflows across multiple plans
Maintainability: Update a sub-plan once, and all referencing plans benefit
Clear abstraction: Plans can work at different levels of detail

For example, a high-level "quarterly report" plan might compose several sub-plans for data collection, analysis, and formatting - each of which is independently useful and testable.

Placeholders for Runtime Resolution

When a plan needs input that varies by user or context, use a placeholder step with an inline description. This makes plans reusable across different users and contexts without hardcoding specific data or implementations.

steps:
  # Placeholder - executor resolves what bullet satisfies this requirement
  - placeholder: "Customer feedback data from past quarter"
    type: data
    constraints:
      - "Must include customer_id, feedback_text, timestamp fields"
      - "Must be in CSV or JSON format"
  
  # Script uses whatever fills the placeholder
  - script: bullet://example/sentiment-analyzer@2.0
    inputs:
      data:
        description: The customer feedback data from the placeholder

At execution time, the executor resolves what bullet satisfies this requirement through discovery, context inference, or on-demand generation. See Placeholders for detailed information about resolution strategies and how placeholders enable reusable plans.

YAML Schema

id: bullet://example/plan-sentiment-analysis@2.0.0
 
# ... standard bullet metadata (see bullets.mdx) ...
# type: plan
 
payload:
  # The user's requirement that this plan fulfills
  intent: Analyze customer sentiment from feedback data
  
  # Clarity and readiness tracking
  intent_clarity:
    ambiguity_score: 0.15  # 0.0 (clear) to 1.0 (ambiguous)
    missing_criteria: []   # Empty when intent is clear
    ready_to_formalize: true  # false if intent needs clarification
  
  # Optional context
  context: |
    Processes customer feedback to identify sentiment patterns
    and generate summary insights.
  
  # Execution constraints
  constraints:
    budget_usd: 0.50
    max_runtime_seconds: 300
    safety: no_destructive_actions
  
  # What success looks like
  success_criteria:
    - All feedback analyzed
    - Sentiment scores generated
    - Summary report created
  
  # The workflow steps (strictly ordered)
  steps:
    # Step 1: Placeholder for user data
    - placeholder: "Customer feedback data from Q4"
      type: data
      constraints:
        - "CSV or JSON format with required fields"
    
    # Step 2: Include analysis guidance (standalone)
    - guidance: bullet://example/sentiment-guidelines@1.0
    
    # Step 3: Run sentiment analysis (has inputs)
    - script: bullet://example/sentiment-analyzer@2.0
      inputs:
        data:
          description: The customer feedback data from the placeholder
        config:
          value:
            model: "standard"
            threshold: 0.7
    
    # Step 4: Generate report using previous results
    - script: bullet://example/report-generator@1.0
      inputs:
        analysis:
          description: The sentiment analysis results from the previous step
        format:
          value: "markdown"

Data Flow

Script inputs are resolved through context assembly by the AI executor. Use value: for literal values and description: for context-dependent inputs that the executor resolves intelligently.

See Script inputs for complete details on input specification and context assembly.

Intent and Constraints

intent: Clear statement of what this plan accomplishes

context: Optional background information

constraints: Hard limits on execution:

budget_usd: Maximum cost
max_runtime_seconds: Maximum execution time
safety: Safety level requirements

success_criteria: Assertions that define when the plan has succeeded

Intent Clarity and Formalization

Before a plan can be formalized and executed, the intent must be sufficiently clear. The intent_clarity section tracks whether the plan is ready to proceed or needs further clarification.

ambiguity_score (0.0 to 1.0): Indicates how ambiguous the intent is. A score of 0.0 means the intent is completely clear with all necessary details specified. A score of 1.0 means the intent is highly ambiguous and cannot be reliably executed. Plans should generally not be formalized until the ambiguity_score is below 0.3.

missing_criteria: An array of specific questions or clarifications needed before the plan can be formalized. When the intent is clear, this array is empty. When ambiguous, it contains concrete questions that need answers:

intent_clarity:
  ambiguity_score: 0.6
  missing_criteria:
    - "Which data source should be used - production or staging?"
    - "What's the expected output format - JSON, CSV, or PDF?"
    - "Should historical data be included, and if so, how far back?"
  ready_to_formalize: false

ready_to_formalize: A boolean gate that determines whether the plan can proceed to execution. This should be false when:

The ambiguity_score is too high (typically > 0.3)
The missing_criteria array is non-empty
Critical details are undefined or contradictory

When ready_to_formalize is false, the system should engage in clarifying dialogue with the user to resolve the missing_criteria before formalizing the plan steps.

This clarity tracking prevents premature execution of poorly-defined plans and provides explicit guidance on what needs to be clarified, improving the user experience and execution reliability.

Data Self-Improvement