Plan Format

Plans are incremental artifacts produced by comparing two Product Graphs. They list node-level changes, transitive impact propagation, and actionable tasks for generators. Plans are the bridge between what changed in your spec and what needs to happen in your codebase.

Plan Structure

A plan is a JSON artifact with three top-level sections: changes, impacts, and tasks.

plan.json

{
  "format": "prodara-plan",
  "version": "0.1.0",
  "changes": [
    {
      "nodeId": "board.entity.task",
      "changeKind": "structurally_changed"
    },
    {
      "nodeId": "board.workflow.assign_task",
      "changeKind": "added"
    }
  ],
  "impacts": [
    {
      "nodeId": "board.surface.board_view",
      "reason": "binds changed entity",
      "via": "binds",
      "depth": 1
    }
  ],
  "tasks": [
    {
      "taskId": "task-001",
      "action": "regenerate",
      "nodeId": "board.entity.task",
      "reason": "structurally_changed"
    },
    {
      "taskId": "task-002",
      "action": "generate",
      "nodeId": "board.workflow.assign_task",
      "reason": "added"
    },
    {
      "taskId": "task-003",
      "action": "verify",
      "nodeId": "board.surface.board_view",
      "reason": "impacted via binds (depth 1)"
    }
  ]
}

Change Kinds

The compiler classifies every node difference into one of six change kinds:

Kind	Description	Example
added	New node in the current graph	A new entity was declared
removed	Node present in previous but not current	A workflow was deleted
renamed	Node identity changed	Entity renamed from `task` to `ticket`
structurally_changed	Fields, types, or shape modified	A field type changed from `string` to `integer`
behaviorally_changed	Logic, steps, or transitions modified	A workflow transition was updated
policy_changed	Governance or constitution modified	Security policy changed to require MFA

Impact Propagation

When a node changes, Prodara follows graph edges outward through 40+ edge types to identify all downstream nodes that may be affected. Each impacted node includes:

reason - Why this node was impacted (e.g., "reads changed entity")
via - The edge kind that carried the impact (e.g., reads, field_type)
depth - How many edges away the change propagated (1 = direct, 2+ = transitive)

{
  "nodeId": "board.surface.board_view",
  "reason": "binds changed entity board.entity.task",
  "via": "binds",
  "depth": 1
}

Task Actions

The planner converts changes and impacts into actionable tasks:

generate - Create new artifacts for an added node
regenerate - Update artifacts for a changed or impacted node
remove - Delete artifacts for a removed node
verify - Check artifacts for an impacted (but unchanged) node to confirm they still work

Incremental Spec

The plan is enriched into an Incremental Spec that adds node metadata and organizes tasks into six category slices for targeted generation:

backend - Server-side models, workflows, and databases
frontend - Client-side models, surfaces, and rendering
api - Data contracts, serialization, and integrations
runtime - Secrets, environments, and deployments
schema - Data schemas, storage definitions, and types
test - Spec tests and validation rules

Generating a Plan

# Generate a plan by diffing against the last build
prodara plan --format json ./project

# Full build includes planning automatically
prodara build ./project

# Check what changed without rebuilding
prodara diff ./project

Build State

Plans are stored in the .prodara/ directory alongside build state. The compiler automatically manages these files to enable incremental builds:

.prodara/
├── build.json    # Build metadata, timestamps, and source hashes
├── product-graph.json    # Previous Product Graph snapshot
└── plan.json     # Latest incremental plan