platform-engineering-labs/formae-apply

Apply Infrastructure (Reconcile Mode)

Use the apply_forma MCP tool in reconcile mode to deploy or update infrastructure.

How Reconcile Works

Reconcile guarantees the target infrastructure matches the forma file exactly:

• Resources in the file but not deployed are created
• Deployed resources not in the file are destroyed
• Differences between file and deployed state are updated

This is the standard mode for planned deployments.

Workflow

1. Confirm the forma file path with the user
2. Always simulate first: call apply_forma with mode: reconcile, simulate: true
3. Present the simulation results clearly:
   • Resources to be created
   • Resources to be updated (show what changes)
   • Resources to be destroyed
4. Ask for explicit confirmation before proceeding
5. If confirmed: call apply_forma with mode: reconcile, simulate: false
6. The command runs asynchronously. Poll get_command_status to monitor progress:
   • Wait 5 seconds between polls (sleep 5). Do NOT poll in a tight loop.
   • Only report state transitions — do NOT print anything unless a resource changed status since the last poll (e.g., in_progress → completed, in_progress → failed). Silently poll until something changes.
   • When reporting, summarize what changed (e.g., "3 resources created, VPC now deploying") rather than dumping the full JSON.
7. Report the final result

Error Recovery

If get_command_status returns a failed state:

1. Report which resources failed and the error messages clearly.
2. Do NOT automatically retry — ask the user how to proceed.
3. Common options to offer:
   • Fix and retry: address the root cause (permissions, quotas, naming conflicts) then re-run the workflow from simulation.
   • Roll back to a previous state: reconcile with the previous forma file to converge infrastructure back toward the prior desired state. Reconcile cannot restore destroyed data or undo billable side effects from the partial deployment — flag this caveat to the user before proceeding.
   • Investigate: use get_command_status details or provider logs to diagnose further.

Force Flag

If the simulation reports drift (out-of-band changes detected), the apply may be rejected. The user can choose to:

• Investigate: Use /formae-fix-code-drift to understand the changes
• Force: Set force: true to overwrite the drift

Important

• NEVER use pkl eval to evaluate forma files — ALWAYS use formae eval --output-consumer machine. Forma files use formae-specific extensions that only the formae CLI can resolve, and --output-consumer machine ensures parseable output instead of human-formatted text.
• NEVER skip the simulation step
• NEVER apply without user confirmation
• For targeted urgent fixes, use /formae-patch instead