Change Protocol

Formal change plans that make AI modifications auditable, reviewable, and reversible

What is the Change Protocol?

The Change Protocol is a formal process for planning system changes before any code or spec is mutated. Instead of directly editing YAML files or generated code, an AI agent (or a human) creates a Change Plan — a structured artifact that describes what will change, what is affected, what the risks are, and what requires human review.

Change plans are not optional bureaucracy. They are the mechanism that makes AI-driven code changes safe. An agent that follows the Change Protocol can modify a complex system while giving humans full visibility into the blast radius of every change.

PlanRequest Structure

A change plan begins with a PlanRequest submitted to the plan generator:

interface PlanRequest {
  title: string;
  description: string;
  author?: string;          // defaults to "ai-agent"
  capabilityChanges: Array<{
    capability: string;       // capability name
    action: ChangeAction;     // add, modify, remove, rename
    description: string;
    newEntities?: string[];
    newPolicies?: string[];
    newInvariants?: string[];
    breakingChange?: boolean; // defaults to false
  }>;
}

The request declares the intent (title and description), the author, and a list of capability-level changes. Each change specifies an action, any new specs it introduces, and whether it constitutes a breaking change.

Change Actions

Risk Classification

The plan generator computes a risk level automatically by analyzing the impact surface and the nature of the changes. Risk classification follows deterministic rules:

The "affected items" count is the sum of affected modules, capabilities, invariants, and policies across all impact surfaces computed from the AI System Graph.

The ChangePlan Artifact

The generator produces a full ChangePlan with the following structure:

• id — Deterministic ID generated from SHA-256 hash of title + timestamp
• title, description, author — From the request
• status — One of: draft, proposed, approved, rejected, implemented
• risk — Computed risk level: low, medium, high, critical
• summary — Intent, scope, estimated impact radius, whether human review is required, whether there are breaking changes
• capabilityChanges — The list of capability-level changes with their actions and new specs
• affectedEntities — Entities impacted directly or indirectly
• affectedModules — Modules impacted directly or indirectly
• affectedPolicies — Policies impacted directly or indirectly
• affectedInvariants — Invariants impacted directly or indirectly
• affectedRoutes — Routes impacted directly or indirectly
• migrationNotes — Data migration steps needed
• generatedArtifactsToRefresh — Generated files that need recompilation
• testsLikelyAffected — Test files that probably need updates
• specsToUpdate — Spec YAML files that must be modified
• humanReviewFlags — Reasons why a human should review this plan
• rolloutNotes — Deployment sequencing notes
• openQuestions — Unresolved questions for the team

Human Review Flags

The generator automatically adds human review flags when:

• Any capability change is marked as a breaking change
• Any capability is being removed
• Invariants are affected (business rules may need re-verification)
• Risk level is high or critical

Example Change Plan

Here is a real change plan YAML from the SaaS billing example app, proposing to add team billing with shared subscriptions:

id: plan-example-team-billing
title: Add team billing with shared subscriptions
description: >
  Add team billing capabilities allowing workspaces to share subscription costs
  across team members while preserving personal subscriptions.
createdAt: "2025-03-14T00:00:00Z"
author: architect
status: draft
risk: medium
summary:
  intent: Enable shared team billing alongside personal subscriptions
  scope: billing, workspaces
  estimatedImpactRadius: 8
  requiresHumanReview: true
  breakingChanges: false
capabilityChanges:
  - capability: create_team_subscription
    action: add
    description: Create a team subscription shared across workspace members
    newEntities:
      - team_subscription
    newPolicies:
      - team_billing_admin_policy
    newInvariants:
      - team_subscription_requires_pro_plan
    breakingChange: false
  - capability: split_invoice
    action: add
    description: Split an invoice across team members
    newInvariants:
      - split_amounts_must_equal_total
    breakingChange: false
affectedEntities:
  - name: subscription
    impact: direct
    description: Modified to support team subscriptions
  - name: invoice
    impact: direct
    description: Needs split billing support
  - name: workspace
    impact: indirect
    description: Team billing context
affectedModules:
  - name: billing
    impact: direct
    description: Primary module for billing changes
  - name: workspaces
    impact: indirect
    description: Team context affects workspace
humanReviewFlags:
  - Affects billing invariants — verify no duplicate subscription logic
  - New team billing policy needs security review
  - Invoice splitting requires financial accuracy review
openQuestions:
  - Should team subscriptions support mixed billing cycles?
  - What happens to team subscription when workspace owner transfers?
  - How to handle partial payments in split invoices?

Plan Statuses

CLI Commands

Create a new change plan from the command line:

sysmara plan create --title "Add team billing" --description "Enable shared subscriptions"

View an existing change plan:

sysmara plan show plan-example-team-billing

The plan can be rendered as Markdown, JSON, or terminal-formatted output depending on your needs.

AI-Safe Change Workflows

The Change Protocol is the control loop that prevents AI agents from making unreviewed, high-risk changes. An agent that wants to modify your system must first create a change plan. The plan computes impact from the AI System Graph, classifies risk, flags items for human review, and identifies which specs and generated artifacts are affected. Only after the plan is reviewed and approved (either automatically for low-risk changes or by a human for high-risk ones) does the agent proceed to mutate specs and run the compiler.

This gives teams an audit trail of every AI-driven change, the ability to reject changes before they happen, and confidence that the agent understands the full blast radius of what it is about to do.