Change
Rhythm

Summary

This post defines how non-trivial work moves through the framework from intent to merge.

The change-rhythm layer standardizes:

• four phases (plan, open, implement, close) treated as workflow, not paperwork
• scratch plans living outside the repo at ~/.claude/agent-governance-plans/
• commit messages and PR history as the primary narrative layer
• Decision Records as the only durable artifact, including negative and failed-approach decisions
• five agent-* commands that automate the rhythm

The appendix contains the command shims, the change-rhythm playbooks, and a sample Decision Record template. Part 1 covered the routing layer this rhythm sits on top of. Part 3 covers review, verification, and deployment.

Problem

A common pattern for AI-assisted change management, and the one an earlier draft of this RFC proposed, is to require every non-trivial change to produce two committed artifacts: a plan.md written before the work starts, and a review.md written after. Both live under docs/changes/NNNNNNN-slug/ and ship in the same commit as the code change.

That shape has four concrete problems.

It treats a transient artifact as if it were durable

A plan written before a change is exploratory by nature. It becomes obsolete the moment implementation begins. Committing it into the repo freezes an early-stage document into version history, where it competes for attention with the actual result. Future readers encountering docs/changes/0000042-migrate-auth/plan.md cannot tell whether it still represents reality, and neither can the next agent loading it.

It duplicates git and PR history

A review.md describing what was built, what changed from the plan, and what was learned is largely the same information already captured by the PR description, the commit sequence, and the PR review thread. Maintaining a separate committed file on top of that produces three competing narratives, each with slightly different content.

It applies polish pressure

When an artifact is about to be committed into the repo, authors polish it. That is correct behavior for code and for durable docs. It is wasted effort for a plan that only needs to guide the next hour of work. The framework should not force polish onto throwaway material.

It fails negative decisions

The most valuable durable records are the ones that prevent repeated mistakes: "we tried X, reverted, because Y," or "we considered X and rejected it because Z." In a plan-and-review model, a failed-and-reverted change produces only a revert commit, with no document that preserves the lesson. The rationale disappears with the branch.

All four problems share a root cause. The framework conflated "the process of changing the system" with "the durable record of decisions the system depends on." Those are different artifacts with different lifetimes and different audiences.

Goals

• Keep phase discipline (plan, open, implement, close) as the workflow spine.
• Make the durable artifact distinct from the transient artifact.
• Give negative and failed-approach decisions a first-class home.
• Let commit messages and PR history do the narrative work they are already good at.
• Keep the scratch-plan surface out of the repo so authors can write freely.
• Provide a small command set that automates the rhythm without adding ceremony.
• Hand cleanly off to the review and verify layer for what happens once a PR exists.

Non-Goals

• Replace git, GitHub, or any PR tool.
• Prescribe a single Decision Record format for every repo.
• Define the review, verify, or deployment discipline. Those live in part 3.
• Force every change through the full rhythm. Trivial one-line fixes do not need a scratch plan.
• Replace repo-local architecture or runbook docs with Decision Records.

Proposed Design

1. Phases as Rhythm

Non-trivial work moves through four phases. Each phase has a clear output, and each output is a real artifact somewhere in the system, not a document written for the sake of process.

graph LR
    PLAN["Plan
scratch file outside repo"]:::routing
    OPEN["Open
branch + draft PR"]:::api
    IMPL["Implement
small commits, clear messages"]:::data
    CLOSE["Close
merge + optional ADR"]:::onDemand

    PLAN --> OPEN
    OPEN --> IMPL
    IMPL --> CLOSE

    classDef routing fill:#5C3E14,stroke:#E8A849,color:#fff,stroke-width:1.5px
    classDef api fill:#1B3D3A,stroke:#4ECDC4,color:#fff,stroke-width:1.5px
    classDef data fill:#2A3054,stroke:#7B93DB,color:#fff,stroke-width:1.5px
    classDef onDemand fill:#3A2054,stroke:#B07CD8,color:#fff,stroke-width:1.5px
        

The phases are rhythm, not paperwork. They describe the shape of work, not a set of documents that must be produced. Trivial changes (a one-line fix, a typo, a config tweak) can collapse plan and implement into a single commit and skip the rest. The discipline applies when the change is big enough to benefit from thinking first.

2. Scratch Plans

Scratch plans live at ~/.claude/agent-governance-plans/<slug>.md. Three path properties matter:

• Outside the repo. Plans never ship with the change. They exist to guide thinking, not to document history.
• Namespaced under agent-governance-. Not under ~/.claude/plans/, which is Claude Code's native plans directory and may be used by the Plan Mode feature or future Claude Code facilities. Namespacing keeps the framework from colliding with the tool it runs on.
• Sibling of the framework install, not inside it. If it lived at ~/.claude/agent-governance/plans/, a framework upgrade or reinstall could wipe in-flight plans. Keeping it at ~/.claude/agent-governance-plans/ means the install directory stays purely runtime code, and the plans directory stays purely user state.

A typical scratch plan looks like this:

# Migrate auth to OIDC

## Context

Current auth stack stores sessions in Redis with a custom token format.
Legal flagged it for new compliance requirements. Need to move to OIDC
with a standard session token.

## Approach

1. Add OIDC provider config (Auth0 tenant already exists).
2. Swap middleware: intercept on /auth/callback, exchange code for token.
3. Migration: old sessions keep working for 24h, new logins go OIDC.
4. Rip old Redis session code once zero old sessions remain.

## Open

- Do we keep the Redis cluster for rate limiting?
- Rollback plan if OIDC provider is down at cutover?

This file is not a deliverable. It is a working surface. The agent and the author can revise it freely as implementation reveals new information. When the change merges, the file is deleted. Nothing about it is committed to the repo.

3. Commit Messages as Primary Narrative

Once a PR is open, the commit sequence is the primary narrative layer. A well-formed commit message does what a committed review.md used to do: it tells a future reader what the change is, what motivated it, and what was considered.

The framework's policy on commit messages is minimal and operational:

• Use Conventional Commits: type(scope): short description on the first line.
• Keep commits small enough that one message covers them.
• The body explains the why: constraints, alternatives rejected, and anything that is not obvious from the diff.
• Reference external artifacts (issues, ADRs) by path or ID, not by prose.

A commit message that matches this shape:

feat(auth): swap session middleware for OIDC exchange

New logins go through the OIDC callback path. Old Redis-backed sessions
keep working for 24h via a compatibility shim in SessionStore.lookup.

Considered extending the existing custom token format to carry the OIDC
claims, but the compliance review (see DR-014) required dropping the
custom format entirely, not extending it.

Follow-up: remove the compatibility shim once the 24h window closes.

A reader in 18 months who runs git blame on the middleware gets the rationale without having to find a document that may or may not still exist. The diff shows what changed. The message shows why. If there was a durable architectural implication, a referenced Decision Record carries it.

4. Decision Records as the Only Durable Artifact

A Decision Record is the durable record of a choice the system now depends on. It lives under docs/agents/decisions/ in the repo, as a numbered file with a short, stable name:

repo/
└── docs/agents/decisions/
    ├── DR-001-adopt-framework.md
    ├── DR-013-drop-custom-session-tokens.md
    ├── DR-014-oidc-over-custom-jwt.md
    └── DR-022-reverted-shadow-db.md

Decision Records are written on demand, not as a side effect of every change. The test for writing one is strict:

• Architectural shift. A lasting change to how the system is structured.
• Rejected alternative. A credible option was considered and not taken. Future readers are likely to suggest it again.
• Failed or reverted approach. An attempt was made, did not work, was reverted. The record prevents the next agent from repeating it.
• Non-obvious constraint. A compliance requirement, a performance target, a legal obligation, or a business rule that shaped the decision.
• Cross-cutting trade-off. A decision that affects more than one subsystem, where the reasoning is harder to reconstruct from diffs.

If none of those apply, no Decision Record is needed. The commit message is enough.

A minimal Decision Record format:

---
id: DR-022
title: Reverted shadow-database rollout
status: superseded
date: 2026-03-05
---

# DR-022 · Reverted shadow-database rollout

## Context

We attempted a shadow-database rollout for the new reporting pipeline.
Writes were mirrored to a parallel Postgres instance for three weeks.

## Decision

Reverted. The shadow cluster is decommissioned.

## Consequences

- Reporting pipeline continues on the primary.
- The cost / operational overhead of maintaining two write paths exceeded
  the verification value for this specific migration.
- The technique is not invalidated in general, only for pipelines under
  this write volume.

## Alternatives considered

- Keep the shadow cluster read-only: rejected, no value without writes.
- Migrate via a blue/green cutover: chosen as follow-up (see DR-024).

Two properties make this shape work as the only durable artifact:

• Negative decisions are first-class. A revert leaves a Decision Record behind. The lesson survives the branch.
• Decision Records are small and focused. One decision per record. When a later decision supersedes an earlier one, the status line changes and the new record references the old one by ID.

Decision Records are not a replacement for architecture docs, runbooks, or reference material. Those live under docs/agents/reference/ and are allowed to be long, opinionated, and evergreen. A Decision Record is frozen to the moment of the decision and only updated by superseding records.

5. Evergreen Docs in the Same Commit

A change that affects evergreen documentation updates that documentation in the same commit as the code change. The evergreen docs are the ones that describe the current state of the system, not the history of how it got there:

• CLAUDE.md at the repo root: routing, conventions, current workflow
• README.md: setup, commands, current shape
• docs/agents/policy/*: binding rules, updated when rules change
• docs/agents/reference/*: subsystem detail, updated when the subsystem changes

This is the one documentation discipline that is not optional. Stale evergreen docs are worse than no docs: they mislead both humans and agents. If the change touches behavior that an evergreen doc describes, the doc update ships with the code.

6. What Replaces a Browsable docs/changes/

A committed docs/changes/ directory does give one thing the new rhythm does not: a browsable "here is what has happened in this repo" view that does not require any tool beyond a file browser. That view is genuinely useful for onboarding and for quickly scanning recent activity.

The new rhythm replaces it with three sources that together cover the same ground:

The trade is deliberate. The new rhythm loses a low-effort browse view in exchange for narratives that stay accurate, a decision catalog that is short and focused, and no dual-maintenance burden between code and process artifacts.

Change-Rhythm Capabilities

The rhythm is automated through five agent-* commands. Each command corresponds to a phase, except for agent-record-decision, which is callable standalone whenever a decision needs to be preserved.

Plan Change

/agent-plan-change writes a scratch plan at ~/.claude/agent-governance-plans/<slug>.md. It does not touch the repo. It prompts for context, the approach, and the open questions, and leaves the file open for iteration. The slug is derived from the intent and can be passed explicitly.

Open Change

/agent-open-change turns a scratch plan into a branch and a draft PR. It reads the plan, creates the branch, pushes an initial empty commit or a small scaffold, and opens the PR with a description derived from the plan. From this point, the PR is the working surface, not the scratch file.

Implement Change

/agent-implement-change executes the plan in small commits with clear messages. It loads the scratch plan for reference, loads the framework policy on commit hygiene, and walks the change step by step. The plan can be revised during implementation; it is never the source of truth, the code is.

Close Change

/agent-close-change runs at merge time. It verifies that evergreen docs have been updated, prompts the author on whether a Decision Record is warranted, and if so, invokes /agent-record-decision. Once the PR is merged, the scratch plan at ~/.claude/agent-governance-plans/<slug>.md is deleted.

Record Decision

/agent-record-decision writes a Decision Record under docs/agents/decisions/. It can be called from /agent-close-change at merge time, or standalone at any point (for example, to record a rejected RFC, or to capture a lesson from an incident). It enforces the decision-record shape: a single decision, a status, a context, the alternatives considered, and the consequences.

Usage

The change-rhythm commands are installed alongside the routing commands from part 1, under ~/.claude/commands/, using the reserved agent-* namespace.

graph LR
  PLAN["/agent-plan-change
scratch plan
outside the repo"]:::routing
  OPEN["/agent-open-change
branch + draft PR"]:::api
  IMPL["/agent-implement-change
small commits"]:::data
  CLOSE["/agent-close-change
merge + optional ADR"]:::onDemand
  DR["/agent-record-decision
standalone ADR"]:::decision

  PLAN --> OPEN
  OPEN --> IMPL
  IMPL --> CLOSE
  CLOSE -.-> DR
  DR -.-> CLOSE

  classDef routing fill:#5C3E14,stroke:#E8A849,color:#fff,stroke-width:1.5px
  classDef api fill:#1B3D3A,stroke:#4ECDC4,color:#fff,stroke-width:1.5px
  classDef data fill:#2A3054,stroke:#7B93DB,color:#fff,stroke-width:1.5px
  classDef onDemand fill:#3A2054,stroke:#B07CD8,color:#fff,stroke-width:1.5px
  classDef decision fill:#4A1E3A,stroke:#E85D75,color:#fff,stroke-width:1.5px
        

The commands are process-oriented. They do not know anything about a specific repo's domain. Repo-specific change wizards (for example, /frontend-change) belong in the repo layer and can call these commands internally.

Part 3 begins where /agent-open-change ends. The draft PR it produces is the trigger point for the auto-triggered self-review described in the next post.

Example: a reverted migration

Consider the shadow-database migration referenced above. The rhythm produces the following trail:

1. /agent-plan-change shadow-db writes ~/.claude/agent-governance-plans/shadow-db.md. The file explains the goal, the mirroring approach, and the open questions.
2. /agent-open-change creates a branch, opens a draft PR titled "Shadow-DB rollout for reporting pipeline," and uses the plan as the PR description.
3. /agent-implement-change walks the change: add shadow writer, add comparison reporter, stage-deploy, observe.
4. The observation period exposes that mirrored writes are adding unacceptable latency to the primary path. The team decides to revert.
5. /agent-record-decision DR-022-reverted-shadow-db writes the Decision Record (shown above) under docs/agents/decisions/.
6. The PR is force-closed with a revert commit. The scratch plan at ~/.claude/agent-governance-plans/shadow-db.md is deleted.

The durable record is one Decision Record plus the revert commit. The scratch plan never entered the repo. The team's next attempt (DR-024, blue/green cutover) can reference DR-022 and skip the failed path without rediscovering it the hard way.

Tradeoffs

Benefits

• Plans stay private and cheap to revise, because they are not committed.
• Commit messages and PR history do the narrative work they are already good at.
• The Decision Record catalog is short and high-signal, because it is only written for durable rationale.
• Negative and reverted decisions are first-class, so lessons survive branches.
• Evergreen docs stay accurate, because they ship in the same commit as behavior changes.
• The five-command surface is thin enough to live inside a repeatable rhythm.

Costs

• Authors must write better commit messages. The rhythm depends on them.
• Deciding when to write a Decision Record is a judgment call; some teams will under-record and others over-record.
• A browsable docs/changes/ view goes away. Readers who want a quick scan rely on git log, the PR list, and the decision catalog instead.
• Scratch plans living outside the repo means they do not participate in PR review. That is the point, but it means context that used to be in the plan has to move into the PR description or the commit messages.

These costs are acceptable because they buy a cleaner split between transient and durable artifacts, a realistic home for negative decisions, and an end to the dual-maintenance burden between committed process docs and the code they describe.

Recommendation

Adopt this rhythm once the routing layer from part 1 is in place:

• install the five agent-* commands under ~/.claude/commands/
• keep scratch plans outside the repo at ~/.claude/agent-governance-plans/
• retire any existing committed plan.md / review.md pattern
• add docs/agents/decisions/ to each repo and start numbering Decision Records
• treat commit messages as the narrative, not a summary
• update evergreen docs in the same commit as the change that invalidates them

Part 3 completes the series with the discipline that sits on top of this rhythm: auto-triggered self-review on every PR, the review dimensions that structure it, verification gates, and deployment.