ccb-github

# CCB GitHub Release Maintainer

## Core Rule

Treat GitHub as the user-facing product page. A release is not done until local version files, npm package metadata, both READMEs, changelog, GitHub Release, release assets, npm registry state, and Actions status all agree.

GitHub's repository homepage renders README from the default branch, not from the latest release tag. If release documentation is prepared on a feature or hotfix branch, merge that branch to the default branch before calling the homepage updated.

Use repository `SeemSeam/claude_codex_bridge` unless the user explicitly gives a different repo.

For CCB releases, npm publishing is part of the release surface by default. If `package.json`, npm wrapper scripts, README npm install snippets, or `.github/workflows/npm-publish.yml` are missing or stale during release preparation, create or repair them before the release commit and before creating or pushing the release tag. Do not create a tag first and add npm publish support in a later branch commit.

## Execution Contract

When the user asks for a final release or homepage result, do the git/GitHub work instead of only describing it:

1. Make the file edits, including npm package/workflow/docs auto-completion for release work.
2. Run the local checks.
3. Commit the changes.
4. Push the working branch.
5. Merge to the default branch when README/GitHub homepage state must change.
6. Push the default branch.
7. Create/push the release tag only after the intended release commit contains all required release and npm files, when package contents changed and the user asked for a release.
8. Create or update the GitHub Release page.
9. Wait for required GitHub Actions, release assets, and npm Trusted Publishing for npm-enabled releases.
10. Run the published checker and npm registry verification, then report the result.

Keep the checker read-only. Git writes, GitHub Release writes, workflow reruns, and tag operations are explicit agent actions done in the sequence above, not hidden inside the checker.

## Quick Audit

From the CCB repo root, run the bundled checker before and after release work:

```bash
CHECKER="dev_tools/skills/ccb-github/scripts/check_release_state.py"

python "$CHECKER" --phase prepare --repo SeemSeam/claude_codex_bridge
python "$CHECKER" --phase published --repo SeemSeam/claude_codex_bridge --wait-seconds 1800
```

The checker is read-only. It catches mechanical drift, but still manually inspect the top of `README.md` and `README_zh.md` because stale "What's New" prose can be semantically wrong even when version numbers are correct.

Use `--phase dev` for ordinary CCB development or maintainer tooling changes that are not intended to create a package release. Use `--wait-seconds 0` for lightweight commit/push work where the user did not ask to wait for GitHub Actions:

```bash
python "$CHECKER" --phase dev --repo SeemSeam/claude_codex_bridge --wait-seconds 0
```

`--phase dev` checks that the worktree is clean, the branch is pushed, and the change set is classified as development-only vs package/release-impacting. When `--wait-seconds` is greater than 0, it also waits for required GitHub workflows.

`--phase published` checks both release state and homepage state: GitHub latest release, release assets, `SHA256SUMS`, release workflows, branch validation workflows, and README/README_zh as rendered from the repository default branch. Use `--wait-seconds 1800` immediately after tagging so the checker waits for `Release Artifacts` and uploaded assets instead of reporting transient failures. The checker does not replace npm registry verification; for CCB releases, also verify `npm view @seemseam/ccb version dist-tags --json`.

## Decision Tree

- Before tagging: run `--phase prepare`; fix every FAIL before creating a tag. Also inspect the npm publication surface and auto-complete missing `package.json`, npm wrapper scripts, README npm install snippets, and `.github/workflows/npm-publish.yml` before tagging.
- After pushing a tag or creating a release: run `--phase published --wait-seconds 1800`; fix every FAIL before reporting success.
- After an interruption during release/tag work: run both phases, then follow the recovery runbook below from the first failing state. After an interruption during ordinary development, run only `--phase dev`.
- During README-only maintenance: still run `--phase prepare` so version badges, release notes, install URLs, and memory wording stay aligned.
- During normal development: run `--phase dev --wait-seconds 0` after commit/push; use a positive wait only when the user asks for CI verification or the change is risky enough to need it.
- When the user asks for the final published result, include commit, push, merge-to-main when needed, GitHub Actions verification, Release assets verification, npm registry verification, and homepage README verification.

## Development Version Management

Use this for CCB development changes, including `dev_tools`, tests, docs, CI, and maintainer workflows.

1. Classify the change:
   - `dev_tools/`, tests, docs, and CI-only checks usually do not require a package release.
   - `lib/`, `ccb`, `bin/`, installer scripts, release build scripts, `VERSION`, `package.json`, `.github/workflows/npm-publish.yml`, README release notes, or `CHANGELOG.md` may affect users and must be considered for release.
2. Run targeted tests first, then the smallest broad check that matches the risk.
3. Commit the development change.
4. Push the branch.
5. Run:
   ```bash
   python dev_tools/skills/ccb-github/scripts/check_release_state.py --phase dev --repo SeemSeam/claude_codex_bridge --wait-seconds 0
   ```
6. If `--phase dev` reports runtime/package changes and the user wants a published package, switch to the Release Preparation Checklist and Publish Sequence, including npm auto-completion.
7. If the change is development-only, do not create a tag or GitHub Release.

`--phase dev` is intentionally strict about local and p