Branching Guide¶

Branch Architecture¶

integration  (permanent protected — the stable trunk)
    └── ← staging merges here after all checks pass

staging  (permanent protected — integration gate)
    ← feat/cap{N}-<desc>    (code feature branches — deleted after merge)
    ← bug/cap{N}-<desc>     (bug fix branches — deleted after merge)
    ← docs/cap{N}-<desc>    (auto-generated after feat/bug merge — deleted after merge)
    ← gh/<desc>             (GitHub Actions workflow changes)
    ← claude/<desc>         (.claude/, skills, memory changes)

release/v{major}.{minor}.{patch}  (short-lived — deleted after release)
    └── release.yml creates git tag v{X.Y.Z} — the tag is the durable version marker

Local development happens directly — no shared sandbox branch. New work starts from a fresh branch off staging (or integration for hotfixes).

Branch Types¶

Prefix	Purpose	Triggers
`feat/cap{N}-<desc>`	New feature	`wheel-build.yml` on push
`bug/cap{N}-<desc>`	Bug fix	`wheel-build.yml` on push
`docs/cap{N}-<desc>`	Auto-generated or manual docs	`docs-check.yml` on push
`gh/<desc>`	CI/GitHub Actions changes	`wheel-build.yml` on push
`claude/<desc>`	Claude Code config changes	`wheel-build.yml` on push
`release/v{ver}`	Release pipeline (short-lived)	`release.yml` on push

Capability ID System¶

Every feature or bug fix is assigned a capability ID (cap001, cap002, ...).

Assigning a Cap ID¶

Read docs/capabilities.md to find the next unused ID
Create branch: feat/cap{N}-<short-desc> or bug/cap{N}-<short-desc>
Prefix all commits: [cap{N}] short message
Title PRs: [cap{N}] Description of capability

Format Rules¶

IDs are zero-padded to 3 digits: cap001, cap010, cap999
Extensible beyond 3 digits: cap1000
IDs are never reused or skipped

Branch Protection¶

Branch	Requires PR	Status Checks	Force Push
`integration`	Yes	all `pr-checks` jobs	Blocked
`staging`	Yes	all `pr-checks` jobs	Blocked

Required status checks (must all pass before merge): - pr-checks / unit-tests - pr-checks / smoke-test - pr-checks / e2e-podman-ubuntu - pr-checks / e2e-podman-windows - pr-checks / docs-build

Workflow: Feature Development¶

1. git checkout staging && git pull
2. git checkout -b feat/cap{N}-<desc>
3. ... develop, commit with [cap{N}] prefix ...
4. git push -u origin feat/cap{N}-<desc>
5. Open PR → staging
6. All pr-checks pass → merge
7. docs-generate.yml auto-creates docs/cap{N}-<desc> PR
8. When staging is stable: open PR → integration

Tip

If a PR check fails with a transient GitHub error, use gh run rerun <run-id> --failed to retry only the failed jobs. Use --admin force merge only as a last resort after multiple retries confirm a persistent infrastructure failure — never to bypass real failures. See CI/CD Workflows Reference for the full retry procedure.

Workflow: Release¶

1. git checkout integration && git pull
2. git checkout -b release/v{X}.{Y}.{Z}
3. git push -u origin release/v{X}.{Y}.{Z}
4. release.yml runs, builds wheel, creates GitHub Release, and tags v{X.Y.Z}
5. git push origin --delete release/v{X}.{Y}.{Z}  (tag persists — branch deleted)

Git tags (v{X.Y.Z}) are the durable version markers. Release branches are deleted after the GitHub Release is confirmed.

CI/CD Workflows¶

For the full workflow trigger matrix, Test PyPI dev artifact flow, and CI retry procedure, see the CI/CD Workflows Reference.

Automated Docs Generation¶

After a feat/* or bug/* branch merges to staging, the docs-generate.yml workflow:

Detects the source branch type and cap ID from the merge commit
Calls the Anthropic API (claude-sonnet-4-6) to generate:
A patch note entry for docs/patch-notes.md
A capability registry row for docs/capabilities.md
Creates a docs/cap{N}-<desc> branch with the changes
Opens a PR to staging with the docs-auto label

Prerequisite: The ANTHROPIC_API_KEY secret must be set in the GitHub repo (Settings → Secrets → Actions). This requires an Anthropic API key from console.anthropic.com — not a Claude.ai Pro subscription.