sync-docs-release git:20260724.bd6a02aA

Immutable. This exact content never changes and is served at /api/v1/blob/cf5ca1cdff19508e.

---
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:

> 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.

Wait for the agent to return. Relay its 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.