git:20260724.bd6a02a to git:20260728.e421935

9 added, 13 removed. Audit A to A.

---

name: sync-docs-release

description: Use when the user wants to sync docs and then cut a release in one shot. Combines sync-docs → land the doc changes (branch + PR, or a direct commit when the repo allows it) → create-release in sequence. Triggers on phrases like "sync docs and release", "sync and cut a release", "update docs and publish a release".

---

# sync-docs-release

Runs three operations in strict sequence. Do not skip steps or reorder them.

## Step 1 — Sync docs

Invoke the `sync-docs-runner` subagent via the Agent tool:

- `subagent_type`: `sync-docs-runner`

- `description`: `Sync docs to recent commits`

- `prompt`: Pass through the user's request verbatim plus any session context (target branch, last-sync SHA, specific files, etc.). Do not paste workflow steps into the prompt.

- - `model`: Omit by default. Override only if the user explicitly names a different LLM.

Wait for the agent to return. Relay its summary to the user before proceeding.

## Step 2 — Land the doc changes

sync-docs leaves its edits uncommitted in whatever checkout it ran in. **Never commit them to the repository's default branch**, and never treat a direct commit as acceptable merely because the checkout happens to be sitting on that branch.

First, if `git status` shows no doc changes at all, report "no doc changes to commit" and go straight to Step 3.

Otherwise pick the landing path:

1. Read the current branch (`git rev-parse --abbrev-ref HEAD`) and the default branch (`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`).

2. Check the repo's `CLAUDE.md` / `AGENTS.md` for a branch, worktree, or pull-request policy.

3. Choose:

- **Branch + PR** — the default. Required whenever the checkout is on the default branch or the repo mandates worktree/PR landing, and the right choice whenever the policy is unclear.

- **Direct commit** — only when the checkout is already on a non-default working branch *and* no repo rule forbids committing there.

### Direct-commit path

- Commit the doc changes using the Haiku model. Spawn an Agent with `model: haiku` and the following prompt:

+ Commit the doc changes directly in the main session:

- > Create a git commit for the doc changes just produced by sync-docs. Steps:

- > 1. Run `git status` and `git diff` to see all changes.

- > 2. Run `git log --oneline -10` to understand the commit message style used in this repo.

- > 3. Confirm you are NOT on the repository's default branch. If you are, stop and report that instead of committing.

- > 4. Stage only documentation files changed by sync-docs (CLAUDE.md, AGENTS.md, SKILL.md, README.md, and any other .md files that were modified — never stage .env, secrets, or unrelated files).

- > 5. If there is nothing staged after step 4 (nothing changed), skip the commit and report "no doc changes to commit".

- > 6. Otherwise, draft a concise commit message focused on the "why" and create the commit: `git commit -m "$(cat <<'EOF'\n<message>\nEOF\n)"`.

- > 7. Run `git status` to verify.

- > Do not push.

+ 1. Run `git status` and `git diff` to see all changes.

+ 2. Run `git log --oneline -10` to understand the commit message style used in this repo.

+ 3. Confirm you are NOT on the repository's default branch. If you are, stop and report that instead of committing.

+ 4. Stage only documentation files changed by sync-docs (CLAUDE.md, AGENTS.md, SKILL.md, README.md, and any other .md files that were modified — never stage .env, secrets, or unrelated files).

+ 5. If there is nothing staged after step 4 (nothing changed), skip the commit and report "no doc changes to commit".

+ 6. Otherwise, draft a concise commit message focused on the "why" and create the commit: `git commit -m "$(cat <<'EOF'\n<message>\nEOF\n)"`.

+ 7. Run `git status` to verify.

- Wait for the agent to return. Relay its result (commit SHA or "no changes") to the user.

+ Do not push. Report the result (commit SHA or "no changes") to the user.

### Branch + PR path

Do this in the main session rather than delegating it — it pushes and opens a PR:

1. Save the edits as a patch before touching anything: `git diff -- <doc files> > <scratchpad>/docs-sync.patch`. Verify the patch is non-empty.

2. Only once the patch exists, restore the original checkout: `git checkout -- <doc files>`.

3. `git fetch origin`, then create a worktree off the latest default branch with the branch prefix the repo requires (`cc/` on Claude Code) — e.g. `cc/sync-docs-<date>`.

4. Apply the patch in the worktree with `git apply`, confirm the resulting diff matches what sync-docs produced, and stage only doc files.

5. Commit with a message focused on the "why", ending in the repo's attribution footer.

6. Push the branch and open a PR against the default branch, following the repo's PR title and body conventions.

A release cut before that PR merges will not contain the doc changes, so ask the user once — via AskUserQuestion — how Step 3 should relate to it:

- **Merge the doc PR once its checks pass, then release from the updated default branch** (recommend this one).

- **Release now without the doc changes**, leaving the PR open.

- **Stop here** — no release.

Treat their answer as authorization for that action. Never merge without asking, and never merge past failing checks.

## Step 3 — Create a release

Skip this step entirely if the user chose "stop here".

If they chose merge-then-release, first wait for the PR's checks (`gh pr checks <n> --watch`), merge it, then update the local default branch (`git checkout <default> && git pull --ff-only`) and remove the worktree — the release must be cut from a checkout that actually contains the merged docs.

Then invoke the `create-release-runner` subagent via the Agent tool:

- `subagent_type`: `create-release-runner`

- `description`: `Cut and publish a release`

- `prompt`: Pass through the user's original request verbatim plus any context they provided (target version or bump type, release-notes specifics, etc.), including how the doc changes landed — the PR number and merge commit, or the fact that they are still unmerged. Do not paste workflow steps.

- - `model`: Omit by default. Override only if the user explicitly names a different LLM.

After the agent returns, relay its summary and the release URL to the user.