Change Plans

A structured workflow for proposing, reviewing, and implementing system changes.

What Is a Change Plan?

A change plan is a formal document that describes a proposed modification to your system. It includes what will change, why it needs to change, what the impact will be, and how risky the change is. Change plans are generated as YAML files that can be reviewed by team members or AI agents before implementation begins.

Change plans bring the rigor of RFC-style proposals to everyday development. Instead of making changes and hoping nothing breaks, you create a plan first, review the blast radius, and then proceed with full awareness of the consequences.

The Change Plan Workflow

Create a plan. Use the CLI to generate a change plan document with a title describing the proposed change.
Review the impact. The plan includes automatic impact analysis showing what will be affected.
Assess the risk. Each plan is assigned a risk level based on the scope and nature of the changes.
Get approval. Share the plan with your team or feed it to an AI agent for review.
Implement. Make the changes described in the plan, then validate with sysmara build.

Creating a Change Plan

Use the sysmara plan create command to generate a new plan:

npx sysmara plan create "Add payment processing to billing module"

This creates a YAML file in your project with the plan details. The planner automatically runs impact analysis for any entities or capabilities mentioned in the plan.

Viewing a Change Plan

Use sysmara plan show to display an existing plan:

npx sysmara plan show plans/add-payment-processing.yaml

Plans can be rendered in multiple formats:

Terminal — Formatted for human reading in the console, with colors and indentation.
Markdown — Suitable for pull request descriptions, documentation, or wiki pages.
JSON — Machine-readable format for tooling and AI agent consumption. Use the --json flag.

PlanRequest Format

When creating a plan programmatically or understanding what goes into one, a PlanRequest contains:

title — A short description of the proposed change.
description — Detailed explanation of what and why.
targets — The specific specs being modified (e.g., entity:Payment, capability:ChargeCard).
type — The kind of change: add, modify, remove, or refactor.

Risk Levels

Each change plan is classified with a risk level based on the impact surface:

Risk Level	Criteria	Recommended Action
Low	Affects few specs, no cross-module impact, no invariants involved	Proceed with normal review
Medium	Crosses module boundaries or affects invariants	Requires team review before implementation
High	Large blast radius, affects critical paths, or modifies shared entities	Requires thorough review and staged rollout

Example Change Plan

Here is a complete example of a change plan YAML file:

title: Add payment processing to billing module
description: |
  Introduce a Payment entity and ChargeCard capability to handle
  credit card processing within the billing module. This connects
  to the existing Subscription and Invoice entities.
type: modify
targets:
  - entity:Payment
  - capability:ChargeCard
  - module:billing

risk: medium

impact:
  affected_capabilities:
    - CreateSubscription
    - ChargeInvoice
    - ChargeCard
  affected_modules:
    - billing
  affected_entities:
    - Payment
    - Invoice
    - Subscription
  affected_invariants:
    - PaymentAmountPositive

steps:
  - Create Payment entity spec in system/entities/payment.yaml
  - Define ChargeCard capability in system/capabilities/charge-card.yaml
  - Add PaymentAmountPositive invariant
  - Update billing module to include new entity and capability
  - Run sysmara validate to check for errors
  - Run sysmara build to generate updated graph and diagnostics

notes: |
  The ChargeCard capability will need a policy for PCI compliance.
  Consider adding a RequirePCIScope policy before production deployment.

How Teams Use Change Plans in Practice

Change plans integrate naturally into development workflows:

Pull request descriptions. Render the plan as markdown and include it in your PR body so reviewers can see the impact at a glance.
AI-assisted development. Feed the plan to an AI agent along with the system map. The agent can then implement the changes described in the plan while respecting the system's constraints.
Architecture reviews. For high-risk changes, the plan serves as the basis for an architecture discussion. The impact surface shows exactly what is at stake.
Audit trail. Keep plan files in version control. Over time, they form a history of why architectural decisions were made.

Automating Plan Review

Since plans are YAML files with a known structure, you can automate review steps:

# In CI: reject high-risk plans without explicit approval
npx sysmara plan show plans/my-change.yaml --json | \
  jq -e '.risk != "high"' || echo "High-risk plan requires approval"

You can also use sysmara validate after implementing a plan to confirm that the changes are consistent with the rest of the system.