Change-Rhythm
File Skeletons

---
description: Get governance docs ready and write a scratch plan to ~/.claude/agent-governance-plans/<slug>.md.
---

Workflow:
1. Resolve a slug from `$ARGUMENTS`, or ask for one if not provided.
2. Resolve an optional Plan Mode seed:
   - If `--seed=<path>` is passed, use that path under `~/.claude/plans/`.
   - Else, if a recent Plan Mode plan exists, offer to seed from it.
   - If `--no-seed` is passed, start blank.
3. Load `$CLAUDE_HOME/docs/agents/policy/change-rhythm.md`.
4. Load `$CLAUDE_HOME/docs/agents/playbooks/start-change.md`.
5. Create `~/.claude/agent-governance-plans/<slug>.md`. Seed from the
   Plan Mode artifact if one was resolved; otherwise prompt for context,
   approach, and open questions.
6. Print the full path of the scratch plan for the author to iterate on.
7. Do not create a branch. Do not stage or commit. Do not open a PR.
   Branch and PR mechanics live in `git` and `gh`.

The scratch plan is private working state. It is discarded at close.

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

---
description: Reload the scratch plan and governance docs for an in-flight change.
---

Workflow:
1. Resolve the slug from `$ARGUMENTS`, or infer it from the current branch
   name.
2. Resolve the scratch plan at `~/.claude/agent-governance-plans/<slug>.md`.
   If it does not exist, stop and redirect to `/agent-start-change`.
3. Load `$CLAUDE_HOME/docs/agents/policy/change-rhythm.md`.
4. Load `$CLAUDE_HOME/docs/agents/playbooks/resume-change.md`.
5. Reload the scratch plan. Re-read the open questions and the next step.
6. Orient on current branch state: commits since branch creation, evergreen
   docs touched, files in the diff that the plan has not yet acknowledged.
7. Summarize where the change left off and what comes next.

Resume does not modify anything. It is a context-rebuild, not a write.

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. Once the PR is merged through normal git/gh flow, delete
   `~/.claude/agent-governance-plans/<slug>.md`.

Closing fails open: if Step 4 is skipped, the change still ships. A
missing Decision Record is a judgment call, not a gate. Merging the PR
itself is normal git/gh; close prepares for it, it does not perform it.

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: [start, resume, close]
source_of_truth: $CLAUDE_HOME/docs/agents/policy/change-rhythm.md
---

# Change-Rhythm Policy

## Phases

Non-trivial work moves through three phases: start, resume, close. Resume
exists for cross-session continuation; within a single session, work flows
directly from start to close. Trivial changes (one-line fixes, typos,
config tweaks) may skip the rhythm entirely.

## Boundaries

The framework does not own branch creation, push, or PR opening. Those
stay in `git` and `gh`. Start gets governance ready. Resume reloads it.
Close discards the scratch plan.

## 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: [start]
source_of_truth: $CLAUDE_HOME/docs/agents/playbooks/start-change.md
---

# Start Change Playbook

## Steps

1. Resolve a slug. Short, hyphen-separated, descriptive.
2. Resolve an optional Plan Mode seed:
   - Explicit `--seed=<path>` wins.
   - Else, scan `~/.claude/plans/` for a recent matching plan and offer it.
   - `--no-seed` disables seeding.
3. Load `policy/change-rhythm.md` so commit hygiene and ADR triggers are
   in working memory.
4. Open `~/.claude/agent-governance-plans/<slug>.md`. If a seed was
   resolved, copy it as the starting content; otherwise, 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?
5. Stop. Do not touch the repo. Do not create a branch. Do not push.
   Branch and PR mechanics live in `git` and `gh`.

## Rules

- The scratch plan is private. Write freely, revise freely.
- Plans are deleted at close. Do not treat them as archival.
- If the plan exceeds a page, the change is probably too large. Consider
  splitting.
- Plan Mode seeds are starting material, not source of truth. The scratch
  plan diverges as implementation reveals new information.

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

# Resume Change Playbook

## Steps

1. Resolve the slug from the argument or from the current branch name.
2. Confirm the scratch plan exists at
   `~/.claude/agent-governance-plans/<slug>.md`. If not, redirect the
   author to `/agent-start-change`.
3. Reload `policy/change-rhythm.md`.
4. Reload the scratch plan. Re-read the open questions and the next step.
5. Inspect current branch state:
   - commits since branch creation
   - evergreen docs touched
   - files in the diff that the plan does not yet acknowledge
6. Summarize the gap between the plan and the current state. Surface any
   open questions the author left for themselves.

## Rules

- Resume is read-only. It does not stage, commit, or push.
- Resume does not recreate the scratch plan. If the plan is missing, the
  change has either closed or never started.
- Within a single session, prefer continuing directly from start. Use
  resume when context has actually been lost (a new session, a long
  pause, a switch from another change).

---
kind: playbook
binding: false
scope: framework
phases: [close]
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. Hand back to the author for normal git/gh flow: mark the PR ready,
   request review, merge.
5. Once the PR is merged, 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.
- Close prepares for merge. It does not perform it. Merging stays in
  `gh` (or whatever platform tool the team uses).

---
kind: playbook
binding: false
scope: framework
phases: [close]
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: [close]
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