Change
Rhythm

Summary

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

The change-rhythm layer standardizes:

• three phases (start, resume, close) treated as workflow, not paperwork
• scratch plans living outside the repo at ~/.claude/agent-governance-plans/, optionally seeded from a Claude Code Plan Mode session
• commit messages and PR history as the primary narrative layer
• Decision Records as the only durable artifact, including negative and failed-approach decisions
• four 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.

Problem

A change-management framework needs answers to two questions. What guides the work as it happens? And what record survives once the work has shipped?

The natural-looking answer collapses both questions into one artifact pair: a plan file written before the work starts, and a review file written after, both committed alongside the code. 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 cannot tell whether it still represents reality, and neither can the next agent loading it.

It duplicates git and PR history

A retrospective file 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 those 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." When the plan and the review live as committed files tied to a successful merge, 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 model conflates "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, and they want different homes.

Goals

• Keep phase discipline (start, resume, 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.
• Stay compatible with Claude Code's native Plan Mode so a /plan session can seed a change without rewriting it.
• Provide a small command set that automates the rhythm without adding ceremony.

Non-Goals

• Replace git, GitHub, or any PR tool. Branch creation, pushing, and PR opening stay in the standard tools.
• Prescribe a single Decision Record format for every repo.
• Define a code-review or deployment discipline. Those are adjacent and out of scope here.
• 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 three 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
    START["Start
load governance + scratch plan
(optional Plan Mode seed)"]:::routing
    RESUME["Resume
reload context in a later session"]:::api
    CLOSE["Close
discard plan + optional ADR"]:::onDemand

    START --> RESUME
    RESUME --> CLOSE
    START --> 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 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 skip the rhythm entirely. The discipline applies when the change is big enough to benefit from thinking first, or long enough that the next session needs a way back into context.

Three things deliberately stay out of the framework's lifecycle: branch creation, push, and PR opening. Those are well-handled by git and gh already, and pulling them into agent-* commands would either duplicate that surface or constrain it. Start gets governance ready. Resume reloads it. Close discards the scratch plan. Everything else stays in the tools that already do it well.

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.

Seeding from Claude Code Plan Mode

Claude Code's native Plan Mode (/plan) produces a structured plan during exploration. That plan is exactly the right starting material for a scratch plan, and the framework does not require the author to retype it. /agent-start-change accepts an optional plan reference (a path under ~/.claude/plans/, or the most recent plan if no reference is given) and uses it to seed ~/.claude/agent-governance-plans/<slug>.md.

After seeding, the scratch plan is the working surface. The original Plan Mode artifact stays where Claude Code put it; the scratch plan diverges as implementation reveals new information. The two paths are deliberately separate so that Plan Mode remains usable on its own, and so that a framework reinstall never disturbs Plan Mode state.

3. Commit Messages as Primary Narrative

Once commits start landing on the branch, the commit sequence is the primary narrative layer. A well-formed commit message 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.

Capture as a step, not a habit

Without the workflow, durable rationale survives only if the author remembers to write it down. That is not reliable. The same person who would have written a Decision Record on Tuesday forgets by Thursday; the next agent picking up the change has no signal that one was even owed.

The rhythm makes the Decision Record test a structural step. /agent-close-change loads policy/change-rhythm.md, applies the five-trigger test against the change, and prompts the author. The author still decides (the test is a checkpoint, not a generator), but the question is asked every time, against the same criteria.

The same property holds across sessions. /agent-resume-change reloads policy/change-rhythm.md along with the scratch plan, so rationale that was emerging in session one is still in working memory in session three, with the same trigger test waiting at close. The information persists because the workflow reloads it, not because the author carries it.

This is the load-bearing claim of the rhythm. Following the commands turns durable-rationale capture from a habit into a structural step. Reliability is not absolute (the test is a judgment call, and "no Decision Record needed" is a valid answer), but it is far higher than any model that depends on the author noticing in the right moment.

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. Where the Narrative Lives

If plans are throwaway and reviews are not committed, where does someone learn what happened in this repo? Three sources, each with a clear job:

Each source has a single job, and the three together cover the full range from "what literally changed in this commit" to "why does this subsystem exist at all." Nothing is duplicated across them, and nothing has to be polished into a separate committed artifact to make the narrative work.

Change-Rhythm Capabilities

The rhythm is automated through four agent-* commands: one for each phase, plus agent-record-decision, which is callable standalone whenever a decision needs to be preserved.

Start Change

/agent-start-change gets governance docs ready for a new change. It loads the change-rhythm policy and the relevant playbook, resolves a slug from the intent (or from the explicit argument), and writes a scratch plan at ~/.claude/agent-governance-plans/<slug>.md.

If a Claude Code /plan session produced a recent plan, /agent-start-change will offer to seed the scratch plan from it. Pass an explicit plan path to override, or pass --no-seed to start blank.

The command does not create a branch. It does not push. It does not open a pull request. Those stay in git and gh, where they belong.

Resume Change

/agent-resume-change reloads context for an in-flight change in a later session. It resolves the slug from the argument or from the current branch, reloads the change-rhythm policy, reloads the scratch plan, and orients on the current branch state (commits since start, evergreen docs touched, open questions in the plan). After resume, the agent is back where it left off without rediscovering the framework on every session boundary.

Within a single session, work flows directly out of /agent-start-change. Resume exists for the realistic case where a change spans days and sessions, not as a required intermediate step.

Close Change

/agent-close-change runs at the end of the change. 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 through normal git/gh flow, 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 change end, 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
  START["/agent-start-change
load governance
+ scratch plan"]:::routing
  RESUME["/agent-resume-change
reload context
in a later session"]:::api
  CLOSE["/agent-close-change
discard plan
+ optional ADR"]:::onDemand
  DR["/agent-record-decision
standalone ADR"]:::decision

  START --> RESUME
  RESUME --> CLOSE
  START --> 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 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.

Example: a reverted migration

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

1. The author runs Claude Code's /plan mode to think through the rollout. Plan Mode writes a plan under ~/.claude/plans/.
2. /agent-start-change shadow-db seeds ~/.claude/agent-governance-plans/shadow-db.md from the Plan Mode artifact and loads the change-rhythm policy. No branch, no PR; just the scratch plan and the loaded governance.
3. The author creates a branch with git checkout -b shadow-db and starts implementing. Commits use Conventional Commits and update evergreen docs in the same commit as behavior changes.
4. Mid-change, work pauses for two days. On return, /agent-resume-change reloads the scratch plan, the policy, and orients on the current branch state. Work continues.
5. Once a draft PR exists (opened with gh pr create --draft), the observation period exposes that mirrored writes are adding unacceptable latency to the primary path. The team decides to revert.
6. /agent-close-change prompts on whether a Decision Record is warranted. The author confirms, and /agent-record-decision DR-022-reverted-shadow-db writes the Decision Record (shown above) under docs/agents/decisions/.
7. The PR is 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 four-command surface is thin enough to live inside a repeatable rhythm, and resume specifically handles the cross-session reality of AI-assisted work.
• Branch and PR mechanics stay in git and gh, where they are already well-handled.

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.
• Scratch plans living outside the repo means they do not participate in PR review. That is the point, but it means context the author wants reviewers to see has to move into the PR description or the commit messages.
• Reading the repo's history requires three habits (commits, PR list, decisions) instead of one directory. The discipline pays off, but the muscle has to be built.

These costs are acceptable because they buy a cleaner split between transient and durable artifacts, a realistic home for negative decisions, and narratives that stay accurate without dual-maintenance.

Recommendation

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

• install the four agent-* commands under ~/.claude/commands/
• keep scratch plans outside the repo at ~/.claude/agent-governance-plans/
• let /agent-start-change seed from Claude Code Plan Mode when a /plan session was used
• 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
• open and merge PRs with gh; the framework deliberately stays out of branch and PR mechanics