Imported from platform-engineering-labs/formae-mcp (skills/formae-policy/SKILL.md). Install upstream with npx skills add platform-engineering-labs/formae-mcp --skill formae-policy. Copyright stays with the author.

Manage Stack Policies

Use this skill to manage formae stack policies via natural language. Two policy types are supported:

• TTL — destroys a stack after a duration (TTLPolicy).
• Auto-reconcile — periodically reverts out-of-band changes (AutoReconcilePolicy).

Source and installation context

For mode none, the user-facing plan contains stack names, policy behavior, duration, affected resources and outcomes. Treat file paths, snippets, anchors and edits in the steps below as internal authoring details; ask about policy choices rather than files. Mode codebase retains selected-source reporting.

Pass the chosen profile on every policy planner and agent call. Call get_codebase_context with the actual harness working directory or reuse the selected context. For none, use prepare_authoring to retrieve the complete affected stacks into a fresh ~/.formae-ai/scratch/<operation-id>/ directory, preserving existing policies, targets, references and generators. A maintained project is optional.

Every planner call carries the selected context plus explicit forma_file inside that project or disposable directory, including delete_standalone_policy. Planners return snippets and anchors; the harness edits those files. Scans stay in that one selected root. Always pass that context on later apply/destroy calls. For shared policies affecting multiple stacks, prepare the complete set and review all affected stacks. Never switch global profiles or search the MCP process directory.

Use formae-apply for soft reconcile, drift decisions and the final combined confirmation. Suggest the optional message in that confirmation, allowing edit or clear. Keep disposable source and dependencies until outcome/retry inspection is complete, then remove the directory. Older agents without the required capabilities need a maintained complete source project.

Inline vs standalone — pick the right kind

• Inline policy — declared inside a single stack block. Use when the policy is one-off and applies to exactly one stack.
• Standalone (reusable) policy — declared at the top level of forma { } and referenced from one or more stacks via PolicyResolvable. Use when the same policy governs multiple stacks (e.g. a shared 1-hour ephemeral TTL applied to lifeline, dev, and staging).

When the user mentions attaching the same policy to more than one stack, or explicitly says "reusable" or "shared", default to standalone. Otherwise default to inline.

A stack may hold at most one policy per type. It cannot carry both an inline TTL and a standalone TTL. The tools enforce this and will refuse with an error naming the conflict; relay that error and offer to detach or remove the conflicting policy rather than working around it.

Defaults

• TTL onDependents defaults to "abort". Override with "cascade" if the user says "cascade", "destroy dependents too", or similar.
• Auto-reconcile interval defaults to 5 minutes (300 seconds) when the user does not specify one.

Always state the chosen defaults to the user before applying.

Workflow — set or update a policy

User says something like "expire lifeline in 20 minutes" or "auto-reconcile production every 10 minutes".

1. Parse the intent. Resolve the stack label and the policy parameters. Convert the duration to seconds (20m → 1200, 4h → 14400, 1d → 86400).
2. Verify the stack exists. Call list_stacks and find a matching label. If no match, present the available labels and ask the user which one they meant.
3. Show the user what's about to change. Briefly state: stack name, policy type, value, default fields filled in. Example: "I'll attach a TTL of 20 minutes (onDependents = "abort" by default) to the lifeline stack."
4. Plan the file edit. Call create_inline_policy with operation: "set", the resolved policy_type, and the relevant duration field (ttl_seconds or interval_seconds). The tool returns:
   • file_path — the PKL file declaring the stack.
   • operation — "create" or "update".
   • pkl_snippet — the text to insert.
   • insertion_anchor_start / insertion_anchor_end — the line range; for create they are equal (insert before that line); for update they cover the existing block (replace those lines).
   • existing_policy_snippet — only for update; use it for the before/after policy comparison, including the source diff in mode codebase.
   • imports_to_add — add each entry near the top of the file if missing.
5. Read the file.
6. Apply the edit. For create insert the snippet before the anchor line; for update replace the lines covered by the anchor range. Add any missing imports near the top of the file. Indent the snippet to match the surrounding context (the snippet is emitted unindented).
7. Review the change. In mode none, describe the policy's before/after behavior; in mode codebase, show the relevant source diff as well.
8. Prepare the preview. Source edits alone do not activate a policy. If the user declines, stop. In mode none, abandon the unsubmitted preview and clean up its disposable workspace; do not promise it will apply later. In mode codebase, explain that the local edit remains unapplied.
9. Simulate. Call apply_forma with mode: "reconcile", simulate: true, file_path: <returned file_path>.
10. Show the simulation, ask for explicit apply confirmation.
11. Apply for real. Call apply_forma with simulate: false. Then poll get_command_status every 5 seconds (with sleep 5); only report state transitions.

Workflow — remove a policy

User says "don't expire lifeline anymore", "stop auto-reconciling production", etc.

Same shape as set, but call create_inline_policy with operation: "remove". The tool returns:

• operation: "remove" — apply the deletion at the anchor lines.
• operation: "noop" — no policy of that type was attached. Tell the user there's nothing to remove and stop.

For remove, delete the lines covered by the anchor range. Use existing_policy_snippet to describe the policy being removed; show the source diff only in mode codebase.

If notes mentions "removed empty policies block", retain that source-cleanup detail internally in mode none; explain only the policy removed. In mode codebase, it can accompany the relevant source diff.

Workflow — create a standalone policy

User says "create a 1-hour ephemeral policy and attach it to lifeline and dev".

1. Parse the intent. Resolve a label, the policy type, and the duration in seconds. If the user gave no label, propose a descriptive one (ephemeral-1h, nightly-drift) and confirm it.
2. Ask which stacks to attach to, if the user has not said. Creating a standalone attaches it to nothing and changes no infrastructure by itself.
3. Plan the declaration. Call create_standalone_policy with label, policy_type and the duration field. It returns file_path, pkl_snippet, insertion_anchor_start/_end (equal — insert BEFORE that line, which is the forma block's closing brace), and imports_to_add.
   • operation: "noop" means a standalone with that label already exists. Say so and stop; updating in place is not supported (delete and recreate).
   • An ambiguity error means several files tie for "most stacks". Present the candidates, ask the user once which to use, and pass it as forma_file for the rest of the session.
4. Read the file, apply the edit with Edit, adding any missing imports near the top. Indent the snippet to match its surroundings.
5. Attach to each named stack. For each, run the attach workflow below through its edit step. Collect the set of files touched.
6. Simulate. Call apply_forma with mode: "reconcile", simulate: true on the file carrying the declaration. If attach targets live in other files, simulate each of those too.
7. Show the simulation, get explicit confirmation, apply for real, then poll get_command_status every 5 seconds and report only state transitions.

Workflow — attach a standalone policy to a stack

User says "attach ephemeral-1h to staging".

1. Call attach_standalone_policy with stack and policy_label. It returns file_path, pkl_snippet, insertion_anchor_start/_end (equal — insert BEFORE that line), imports_to_add, notes.
   • operation: "noop" means it is already attached. Say so and stop.
   • An error naming an inline policy of the same type: the stack already has one. Offer to remove it first (the remove workflow above), then retry.
   • An error naming a standalone of the same type: offer to detach that one first, then retry.
   • An error saying the policy is unknown to the agent: the declaration exists in source but has not been applied. Apply the declaring file first.
2. Read the file and apply the edit with Edit. Describe the policy attachment; show the source diff only in mode codebase.
3. Simulate with apply_forma reconcile, confirm, apply, poll.

Workflow — detach a standalone policy from a stack

User says "detach ephemeral-1h from lifeline".

1. Call detach_standalone_policy with stack and policy_label. It returns source_anchor_start/_end — the lines to delete — plus existing_resolvable_snippet for the diff.
   • operation: "noop" means it was not attached. Say so and stop.
   • If notes mentions "removed empty policies block", keep that source-cleanup detail internal in mode none; show it with the relevant source diff in mode codebase.
2. Delete the line range with Edit. Describe the policy detachment; show the source diff only in mode codebase.
3. Simulate with apply_forma reconcile, confirm, apply, poll.

Detaching does not delete the policy. It stays declared and stays attached to any other stacks.

Workflow — delete a standalone policy

User says "delete the ephemeral-1h policy".

1. Call delete_standalone_policy with label.
   • If it errors listing attached stacks, the policy is still in use. Tell the user which stacks, and offer to detach it from each (and apply those changes) before retrying. Do not try to force it.
2. On success the tool returns file_path, source_anchor_start/_end, existing_policy_snippet, and destroy_forma_pkl.
3. Show the plan and get confirmation before touching anything.
4. Delete the source declaration first with Edit. This ordering is deliberate: if a reconcile lands between the edit and the destroy, the agent sees no policy in any forma and does nothing. Reversed, a reconcile in between would recreate the policy.
   • If notes warns about a local binding, also remove the bare reference inside forma { } and any <binding>.res entries, or the file will not evaluate.
5. Write destroy_forma_pkl verbatim to a temporary file inside the selected workspace, so the existing PklProject/dependencies and source context remain available.
6. Call destroy_forma with file_path: <temp>, simulate: true. Show the result, get explicit confirmation, then call it with simulate: false and poll.
7. Delete the temp file.

If the destroy returns a Skip operation with ReferencingStacks, someone attached the policy between the pre-check and the destroy. Say the policy still exists and name the attaching stacks. In mode codebase, also explain that the source has already been edited and needs reconciliation with this outcome. In mode none, keep the disposable edit internal; never report successful deletion.

Version gating. The standalone-policy tools require formae ≥ 0.82.0, and the auto-reconcile policy type requires formae ≥ 0.88.0. On an older local formae the tool refuses with a requires formae >= X.Y.Z message — relay it and suggest upgrading, or fall back to an inline TTL policy where that fits.

Workflow — show policies on a stack

User asks "what policies are on lifeline?".

1. Call list_stacks, locate the stack, surface its inline Policies.
2. Call list_policies, filter to entries whose AttachedStacks includes the target stack label.
3. Present both, and label which is which — inline policies belong to that stack alone; a standalone attached to it may also govern other stacks (its AttachedStacks shows them all). This distinction matters: removing an inline policy affects one stack, while deleting a standalone affects every stack it is attached to. No file edits, no apply.

Important

• NEVER use pkl eval — ALWAYS use formae eval --output-consumer machine. Forma files use formae-specific extensions.
• NEVER apply without simulating first.
• NEVER apply without explicit user confirmation.
• Pkl is the code interface in both maintained and disposable workspaces. Central accepted desired intent is recorded by real reconcile; an edit or preview alone is not acceptance.
• When a planner returns ambiguous source candidates, resolve within the selected source. In mode codebase, ask which candidate file to edit if needed. In mode none, reprepare the complete requested stack or ask which infrastructure stack/policy the user means; never make them choose a temporary file.
• A stack holds at most one policy per type. Never work around a conflict error by editing the PKL directly — resolve it by removing or detaching the conflicting policy.
• Standalone policies are created and deleted, never updated in place. To change one, delete it and recreate it, or convert the stack to an inline policy.
• If a tool reports the selected schema is too old for policies, mode codebase requires a separate schema-upgrade decision. In mode none, verify the prepared source matches the connected agent and use its supported schema; if that agent lacks the capability or its schema is unavailable, explain the policy capability limitation and stop. Never guess a newer schema or imply upgrading a schema upgrades the agent.