Change-Rhythm
File Skeletons

---
description: Write a scratch plan to ~/.claude/agent-governance-plans/<slug>.md.
---

Workflow:
1. Derive a slug from `$ARGUMENTS`, or ask for one if not provided.
2. Create (or overwrite) `~/.claude/agent-governance-plans/<slug>.md`.
3. Load `$CLAUDE_HOME/docs/agents/playbooks/plan-change.md`.
4. Prompt for context, approach, and open questions. Fill the file.
5. Do not touch the repo. Do not stage or commit anything.
6. Print the full path of the scratch plan for the author to iterate on.

The scratch plan is private working state. It is discarded on merge.

Pass any `$ARGUMENTS` through to the planning flow.

---
description: Create a branch and a draft PR from a scratch plan.
---

Workflow:
1. Resolve the scratch plan at `~/.claude/agent-governance-plans/<slug>.md`.
   Slug comes from `$ARGUMENTS` or is inferred from the current context.
2. Load `$CLAUDE_HOME/docs/agents/playbooks/open-change.md`.
3. Create a branch named after the slug.
4. Produce a PR description derived from the plan.
5. Open a draft PR against the repo's default base branch.
6. Leave the scratch plan in place. It continues to guide implementation.

The draft PR is the trigger point for Part 3's auto-triggered self-review.

Pass any `$ARGUMENTS` through.

---
description: Execute the current plan in small, well-messaged commits.
---

Workflow:
1. Load the scratch plan at `~/.claude/agent-governance-plans/<slug>.md`.
2. Load `$CLAUDE_HOME/docs/agents/policy/change-rhythm.md` for commit hygiene.
3. Load `$CLAUDE_HOME/docs/agents/playbooks/implement-change.md`.
4. Walk the plan step by step. Revise it as implementation reveals new info.
5. Produce commits with Conventional Commits headers and why-focused bodies.
6. Update evergreen docs (CLAUDE.md, README.md, architecture docs) in the
   same commit as the behavior change that invalidates them.

The plan is not the source of truth. The code is. Revise the plan freely.

Pass any `$ARGUMENTS` through.

---
description: Close out a change. Verify docs. Maybe record a decision. Discard the scratch plan.
---

Workflow:
1. Load `$CLAUDE_HOME/docs/agents/playbooks/close-change.md`.
2. Verify that evergreen docs have been updated in this branch.
3. Ask whether a Decision Record is warranted using the test in
   `$CLAUDE_HOME/docs/agents/policy/change-rhythm.md`.
4. If yes, invoke `/agent-record-decision` with a proposed slug and
   summary.
5. After the PR is merged, delete `~/.claude/agent-governance-plans/<slug>.md`.

Closing fails open: if Step 4 is skipped, the change still merges. A
missing Decision Record is a judgment call, not a gate.

Pass any `$ARGUMENTS` through.

---
description: Write a Decision Record under docs/agents/decisions/.
---

Workflow:
1. Load `$CLAUDE_HOME/docs/agents/playbooks/record-decision.md`.
2. Determine the next DR number by scanning existing `docs/agents/decisions/DR-*`.
3. Ask for a slug and a status (proposed, accepted, superseded, rejected).
4. Fill the Decision Record template with context, decision, consequences,
   and alternatives considered.
5. Reference any superseded DR by ID in the new record, and update the
   superseded record's status line.
6. Stage the new file. Do not auto-commit. The author decides when.

This command is callable standalone, not only from `/agent-close-change`.
Use it to capture rejected RFCs, incident postmortems, or any durable
rationale that the commit message cannot hold on its own.

Pass any `$ARGUMENTS` through.

---
kind: policy
binding: true
scope: framework
phases: [plan, implement, verify, commit]
source_of_truth: $CLAUDE_HOME/docs/agents/policy/change-rhythm.md
---

# Change-Rhythm Policy

## Phases

Non-trivial work moves through four phases: plan, open, implement, close.
Trivial changes (one-line fixes, typos, config tweaks) may collapse plan
and implement into a single commit.

## Scratch plans

- Scratch plans live at `~/.claude/agent-governance-plans/<slug>.md`.
- Scratch plans are never committed to the repo.
- Scratch plans are deleted once the change merges.
- Do not write plans to `~/.claude/plans/` (Claude Code native) or to
  `~/.claude/agent-governance/plans/` (framework install dir).

## Commit messages

- Use Conventional Commits: `type(scope): description` on the first line.
- Commit bodies explain why. Constraints, alternatives, non-obvious context.
- Keep commits small enough that one message covers them.
- Reference Decision Records by ID (for example `DR-014`).

## Evergreen docs

- Evergreen docs update in the same commit as the behavior change that
  invalidates them.
- Evergreen docs include `CLAUDE.md`, `README.md`, `docs/agents/policy/*`,
  `docs/agents/reference/*`, and any repo-specific architecture docs.
- Never commit a change that leaves an evergreen doc stale.

## Decision Records

Write a Decision Record when (and only when) the change produces durable
rationale that the commit message cannot hold on its own:

- architectural shift
- rejected alternative that is likely to be suggested again
- failed or reverted approach
- non-obvious constraint (compliance, performance, legal, business)
- cross-cutting trade-off affecting more than one subsystem

Do not write a Decision Record for routine bug fixes, cosmetic changes,
or docs-only updates.

## Decision Record shape

- One decision per record.
- Numbered sequentially: `DR-001`, `DR-002`, ...
- Frontmatter: id, title, status, date.
- Status is one of: proposed, accepted, superseded, rejected.
- When a later DR supersedes an earlier one, update the earlier DR's
  status to "superseded" and reference the new ID.

---
kind: playbook
binding: false
scope: framework
phases: [plan]
source_of_truth: $CLAUDE_HOME/docs/agents/playbooks/plan-change.md
---

# Plan Change Playbook

## Steps

1. Resolve a slug. Short, hyphen-separated, descriptive.
2. Open `~/.claude/agent-governance-plans/<slug>.md`.
3. Write three sections:
   - Context: what is the current state and why does it need to change?
   - Approach: what is the proposed path forward? Enumerate steps.
   - Open: what is unresolved? What needs the author's input?
4. Stop. Do not touch the repo yet.

## Rules

- The plan is private scratch. Write freely, revise freely.
- Plans are deleted on merge. Do not treat them as archival.
- If the plan exceeds a page, the change is probably too large. Consider
  splitting.

---
kind: playbook
binding: false
scope: framework
phases: [plan, implement]
source_of_truth: $CLAUDE_HOME/docs/agents/playbooks/open-change.md
---

# Open Change Playbook

## Steps

1. Read the scratch plan at `~/.claude/agent-governance-plans/<slug>.md`.
2. Create a branch named after the slug.
3. Derive the PR title from the plan context.
4. Derive the PR description from the plan: summary, approach, open questions.
5. Open the PR as a draft against the default base branch.
6. Leave the scratch plan in place. It still guides implementation.

## Rules

- Always open the PR as a draft. Marking it ready for review is an explicit
  step, usually at the end of implement.
- The PR description is the first public artifact. It should read as a
  standalone explanation, not as a copy of the scratch plan.
- Auto-triggered self-review runs on the draft. See Part 3.

---
kind: playbook
binding: false
scope: framework
phases: [implement]
source_of_truth: $CLAUDE_HOME/docs/agents/playbooks/implement-change.md
---

# Implement Change Playbook

## Steps

1. Reload the scratch plan. Reload `policy/change-rhythm.md`.
2. Walk the plan's approach steps, one at a time.
3. After each coherent unit of work, commit. Use Conventional Commits.
4. Update evergreen docs in the same commit as the behavior change.
5. Revise the scratch plan as implementation reveals new information.
6. Push to the draft PR. Auto-triggered self-review (Part 3) runs on
   each push.

## Rules

- Keep commits small. Each commit message should make sense standalone.
- Do not batch unrelated changes into one commit.
- Do not leave evergreen docs stale across commits. If a commit changes
  behavior described by an evergreen doc, update the doc in that commit.

---
kind: playbook
binding: false
scope: framework
phases: [verify, commit]
source_of_truth: $CLAUDE_HOME/docs/agents/playbooks/close-change.md
---

# Close Change Playbook

## Steps

1. Verify that evergreen docs are updated in this branch.
2. Apply the Decision Record test from `policy/change-rhythm.md`.
3. If a Decision Record is warranted, invoke `/agent-record-decision`.
4. Mark the PR ready for review. Complete any outstanding review gates
   (see Part 3).
5. Merge.
6. Delete `~/.claude/agent-governance-plans/<slug>.md`.

## Rules

- The scratch plan is deleted on merge. No exceptions.
- Skipping a Decision Record is a judgment call, not a policy violation.
- Do not let a Decision Record block a merge. If the rationale is
  important enough to slow a merge, that is itself a signal that the
  record should be written before close, not after.

---
kind: playbook
binding: false
scope: framework
phases: [commit]
source_of_truth: $CLAUDE_HOME/docs/agents/playbooks/record-decision.md
---

# Record Decision Playbook

## Steps

1. Scan `docs/agents/decisions/` for the highest existing DR number.
2. Propose the next number. Confirm with the author.
3. Ask for slug and status.
4. Fill the Decision Record template (see reference/decision-record-template.md).
5. If superseding an earlier DR, reference it by ID and update the earlier
   DR's status line to "superseded".
6. Stage the new file. Let the author commit when ready.

## Rules

- One decision per record. If the rationale spans multiple decisions,
  write multiple records.
- Keep records short. Long records signal that the decision is actually
  several decisions bundled together.
- A Decision Record does not need to explain background concepts.
  Reference docs do that. A DR records the choice, not the tutorial.

---
kind: reference
binding: false
scope: framework
phases: [commit]
source_of_truth: $CLAUDE_HOME/docs/agents/reference/decision-record-template.md
---

# Decision Record Template

```markdown
---
id: DR-NNN
title: <short imperative title>
status: proposed | accepted | superseded | rejected
date: YYYY-MM-DD
supersedes: [DR-XXX]   # optional
superseded_by: [DR-YYY] # optional
---

# DR-NNN · <short imperative title>

## Context

What is the situation that forced this decision? What constraints
(technical, compliance, business) apply?

## Decision

What was decided. One sentence if possible.

## Consequences

What changes as a result. What becomes easier, what becomes harder,
and what follow-up is implied.

## Alternatives considered

- Option A: why not
- Option B: why not
- Option C: chosen, for <reason>
```

## Status transitions

- `proposed`: under discussion
- `accepted`: in force
- `superseded`: replaced by a later DR; reference it via `superseded_by`
- `rejected`: considered and declined; keep for the record, do not delete