/restructure-commits

name: restructure-commits
description: Restructure branch commits into logical component-based commits for HyperShift PRs

Restructure Commits by Component

Rewrite a feature branch into one commit per architectural group (API, Dependencies, Vendor, CLI, HO, CPO, E2E, Docs, Tooling) without changing the branch's final file content.

This is the canonical, model-neutral procedure. Any coding agent or human can follow it with `git`, `python3` (standard library only), `make`, and optionally `gh`. All paths are relative to the repository root.

When to Use

• The user asks to "redo", "restructure", "squash by component", or "organize" commits
• Preparing a branch for PR review, or cleaning history after addressing review comments

Ownership

`ownership.json` maps every path to a group; `commit_layout.py` applies it. Both the file and the table below are generated by `generate_ownership.py` (`make ownership-rules`, also run by `make update`); never edit them by hand. Commit groups in this order and skip groups with no changes:

<!-- BEGIN GENERATED: python3 skills/restructure-commits/generate_ownership.py --> | Order | Group | Commit prefix | Allowed `<type>` | Owns | |-------|-------|---------------|------------------|------| | 1 | API | `<type>(api)` | `feat`, `fix`, `build`, `refactor` | API types, markers, and the api/ module definition (api/go.mod and api/go.sum stay together) | | 2 | Dependencies | `build(deps)` | fixed | Root, tools, and workspace module definitions; never mixed with generated vendor trees | | 3 | Vendor | `chore(api)` | fixed | Generated output: vendor trees, clients, zz_generated files, generated CRD manifests, and other files marked as generated | | 4 | CLI | `<type>(cli)` | `feat`, `fix`, `refactor`, `test` | hypershift and hcp CLIs, with their tests, testdata, and fixtures | | 5 | HO | `<type>(hypershift-operator)` | `feat`, `fix`, `refactor`, `perf`, `test` | hypershift-operator binaries and Go code shared by binaries of more than one group | | 6 | CPO | `<type>(control-plane-operator)` | `feat`, `fix`, `refactor`, `perf`, `test` | control-plane-operator binaries and the Go code only they use, such as control plane sidecars | | 7 | E2E | `test(e2e)` | fixed | E2E, integration, and envtest suites, including API validation tests | | 8 | Docs | `docs` | fixed | User and contributor documentation and agent guidance files | | 9 | Tooling | `<type>(<scope>)` | `build`, `ci`, `chore`, `docs` | Everything else: build system, CI configuration, scripts, container builds, helper modules, AI agent tooling | <!-- END GENERATED -->

• **Derived, not curated.** Each binary built by `make build` belongs to the group in the generator's policy, and

other top-level Go directories follow the binaries that import them (several groups: HO; none: Tooling). Files marked as generated, Makefile output directories, and vendor trees go to Vendor; hand-written files inside them keep their component's group.

• **First match wins.** Specific exceptions are listed before broad directories; `ownership.json` lists the rules in

precedence order with the reason for each.

• **Modules vs generated trees:** `api/go.mod` and `api/go.sum` stay in API; root, tools, and workspace module files

go in Dependencies; every vendor tree goes in Vendor. A commit must never mix module definitions with vendor output.

• **Tests and fixtures:** component tests, `testdata/`, and `zz_fixture_*` files stay with their owning component.

Only `test/`, `api/**/*_test.go`, and CRD envtest suites go to E2E.

• **No silent defaults:** an unclassified path blocks the rewrite. Run `make ownership-rules`, which gives every

path in the checkout a group, and commit the result before the snapshot. If a derived group is wrong, agree the right one with the user and change the generator's policy (see Maintenance).

• Several consecutive commits in the same group are allowed; groups must never interleave or appear out of order.

Procedure

TOOL=skills/restructure-commits/commit_layout.py

1. Preflight (read-only except for the backup branch)

1. **Resolve the real target.** Determine the PR base repository and branch, for example from `gh pr view --json url,baseRefName`; ask the user when there is no PR. Pick the remote whose URL points at that base repository and the remote that hosts the PR branch. Do not assume remote names, do not assume `main` (release branches are valid targets), and do not rebase unless the user asks for it.

   BRANCH=$(git symbolic-ref --short HEAD)
   TARGET_REMOTE=<remote for the PR base repository>
   TARGET_BRANCH=<PR base branch, e.g. main or release-4.18>
   PUSH_REMOTE=<remote that hosts $BRANCH>
   git fetch "$TARGET_REMOTE" "refs/heads/$TARGET_BRANCH"
   MERGE_BASE=$(git merge-base FETCH_HEAD HEAD)
   PUSHED_SHA=$(git ls-remote "$PUSH_REMOTE" "refs/heads/$BRANCH" | cut -f1)   # empty if never pushed
   if [ -n "$PUSHED_SHA" ]; then
     git fetch "$PUSH_REMOTE" "refs/heads/$BRANCH"
     git merge-base --is-ancestor "$PUSHED_SHA" HEAD || echo "STOP: remote $BRANCH has commits not in HEAD"
   fi

If the remote branch has commits that are not in local `HEAD` (review suggestions, "Update branch", a collaborator's push), stop and ask the user to integrate them first; the rewrite would otherwise discard them.

2. **Finish background work.** Wait for running generators, formatters, `make update`, or tests that write files. 3. **Handle existing work explicitly.** If `git status --porcelain --untracked-files=all` is not empty, stop and ask whether to commit it to the branch first, stash it with `git stash push --include-untracked -m "restructure-commits: preserved work"` (restore it at the end), or abort. Never use `git reset --hard`, `git checkout -- .`, `git clean`, or drop stashes or branches. 4. **Record the snapshot and create a backup branch.** Report these values to the user.

   ORIG_HEAD_SHA=$(git rev-