Changeset creation

Workflow Changeset creation

agent starscribe

tags

workflowchangeset

A changeset records which spec documents were modified in a batch of work and links those changes to Git commits. It is the primary hand-off mechanism between the specification and the implementation: agents use changesets to understand what changed, why, and where to look.

Create a changeset whenever a meaningful set of spec documents is updated together — at minimum once per feature or domain edit cycle.

Phase 1 — Identify the Commits

Ask:

1. Which Git commit hashes contain the spec changes? (space-separated, short hashes are fine)
2. If the changes are not yet committed, note the expected commit message — the hash can be filled in after commit.

Phase 2 — Document Touched Documents

For each spec document that was modified, create a touched entry:

Ask for each touched document:

• What is its qualified id? (e.g. feature/add-bookmark, domain/bookmarks)
• What specifically changed? (one sentence: added, removed, renamed, extended — be concrete)

Group related changes together. A changeset covering one feature plus its domain is normal. A changeset spanning five unrelated domains is a sign the changes should be split.

Phase 3 — Draft & Confirm

Present the draft for confirmation before writing. Output: content/changesets/{id}.changeset.mdoc

After writing, run pnpm compile to verify the changeset appears in the aggregate changelog.

---

Do’s and Don’ts

Do:

• Create a changeset whenever a meaningful set of spec documents is updated together
• Group related changes together (one feature plus its domain is normal)
• Use concrete, one-sentence descriptions for each touched document
• Include Git commit hashes when available; note expected messages if not yet committed
• Run pnpm compile after writing to verify the changeset appears in the changelog

Don’t:

• Don’t span five unrelated domains in a single changeset — split them instead
• Don’t use vague descriptions like “updated” — be concrete about what changed
• Don’t create a changeset for trivial formatting-only changes
• Don’t skip the compile verification after writing

Definition of Done

• Draft presented to user for confirmation
• Document written as content/changesets/{id}.changeset.mdoc with correct frontmatter and root tag
• All touched document ids are valid qualified ids
• Changes are described concretely in one sentence each
• Related changes are grouped logically
• All cross-references resolve to existing documents
• pnpm compile succeeds and changeset appears in aggregate changelog

linktag > changesetlinktag > touched