feat(skills): add release split workflow helpers

.agents/skills/kqode-release-split-decision/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: kqode-release-split-decision
+description: "Record a KQode release-split decision from any branch or worktree. Use during PR review or extraction when a technical decision, queue-boundary change, ordering change, or future-PR instruction must be saved into the active docs/release/vX.Y.Z-pr-queue.md ledger on the control branch."
+---
+
+# KQode Release Split Decision
+
+Record release-split decisions into the active queue ledger from any branch or worktree without mutating the current PR branch.
+
+## Inputs
+
+Use the user's prompt as the decision text. Identify:
+
+- the release, for example `v0.2.0`;
+- the affected PR number or queue item, if any;
+- whether the decision changes queue order, PR boundaries, extraction behavior, validation, cleanup, or future-release closeout.
+
+If the decision text is missing or too vague to record, ask one focused question before editing.
+
+## Workflow
+
+### 1. Find the active ledger
+
+First check the current checkout:
+
+```bash
+find docs/release -maxdepth 1 -name 'v*-pr-queue.md' -print 2>/dev/null
+```
+
+If no ledger exists in the current checkout, search remote control branches:
+
+```bash
+git fetch origin --prune
+git branch -r --list 'origin/chore/*release-split-ledger'
+```
+
+For `vX.Y.Z`, expect:
+
+```text
+origin/chore/vX.Y.Z-release-split-ledger
+docs/release/vX.Y.Z-pr-queue.md
+```
+
+If multiple ledgers or control branches match and the user did not specify a release, ask which release to update.
+
+### 2. Use the control checkout
+
+Never edit the ledger in a feature or PR extraction worktree. Use the control branch checkout:
+
+1. If the current branch is the matching `chore/vX.Y.Z-release-split-ledger`, use it.
+2. Else inspect worktrees:
+
+   ```bash
+   git worktree list --porcelain
+   ```
+
+3. If a worktree for `chore/vX.Y.Z-release-split-ledger` already exists, use that path.
+4. Otherwise create one outside the repo root:
+
+   ```bash
+   git worktree add ../KQode.release-split-ledger-vX.Y.Z \
+     chore/vX.Y.Z-release-split-ledger
+   ```
+
+If only `origin/chore/vX.Y.Z-release-split-ledger` exists locally, create the local branch from it:
+
+```bash
+git worktree add ../KQode.release-split-ledger-vX.Y.Z \
+  -b chore/vX.Y.Z-release-split-ledger origin/chore/vX.Y.Z-release-split-ledger
+```
+
+### 3. Update the ledger
+
+Edit only `docs/release/vX.Y.Z-pr-queue.md`.
+
+Always add a row under `## Queue Changes`:
+
+```md
+| YYYY-MM-DD | <decision summary> | <approval source> | <affected queue items and exact instruction> |
+```
+
+Also update the affected queue item outline when the decision applies to future extraction:
+
+- **Extraction notes** for hunk ownership, final-state rules, branch naming, or validation.
+- **Folded fixes and docs ownership** for review fixes or docs assignment.
+- **Dependencies** when queue order changes.
+- **Validation** when a new required check is added.
+- The live queue row when status, branch, base SHA, PR URL, or validation changes.
+
+If the decision changes queue order or PR boundaries, make every downstream dependency update in the same ledger edit. If you cannot confidently update dependencies, stop and report the unresolved dependency impact.
+
+### 4. Commit and push from the control checkout
+
+Use explicit pathspecs:
+
+```bash
+git add docs/release/vX.Y.Z-pr-queue.md
+git commit -m "docs(release): record split decision" -- docs/release/vX.Y.Z-pr-queue.md
+git push
+```
+
+Include the standard commit trailers required by the repository instructions.
+
+### 5. Report the saved decision
+
+Report:
+
+- control branch and commit hash;
+- ledger path;
+- queue items touched;
+- whether future queue extraction must read a new decision before proceeding.
+
+## Rules
+
+- Do not mutate the current PR worktree except for read-only inspection.
+- Do not edit plan documents for execution decisions; use the queue ledger.
+- Do not silently change queue order or PR boundaries without an explicit approval note.
+- Do not create or push tags, version bumps, or release branches.
+- Do not use `git add .`; stage only the ledger path.

.agents/skills/kqode-release-split-plan/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: kqode-release-split-plan
+description: "Create or review a KQode release-split plan from a branch delta. Use when a large release-candidate branch must be frozen, scanned, and split into focused main-based PRs with a queue ledger, PR boundaries, migration ordering, and validation rules."
+---
+
+# KQode Release Split Plan
+
+Create or review a release-split plan for turning a large release-candidate branch into a rolling queue of focused, main-based PRs.
+
+## Inputs
+
+Use the user's prompt to identify:
+
+- the release-candidate branch, defaulting to the current branch when unspecified;
+- the review base, defaulting to `origin/main`;
+- the target release branch name, usually `release/vX.Y.Z`;
+- any existing requirements, brainstorm, or plan file paths.
+
+If the release branch name or candidate branch is ambiguous, ask one focused question before proceeding.
+
+## Workflow
+
+### 1. Gather branch facts
+
+Run read-only git probes:
+
+```bash
+git branch --show-current
+git rev-parse --verify origin/main
+git rev-parse --verify HEAD
+git log --reverse --format='%h%x09%s' origin/main..HEAD
+git diff --name-status origin/main..HEAD
+git branch --list release/v*
+git ls-remote --heads origin 'release/v*'
+git tag --list 'v*'
+```
+
+If a target release branch already exists locally or remotely, stop and ask for an explicit decision. Do not overwrite release refs.
+
+### 2. Classify the delta
+
+Group commits and changed files by feature, infrastructure unit, migration chain, workflow/documentation unit, and review-fix ownership.
+
+Call out:
+
+- weak or opaque commit messages that require hunk ownership;
+- commits that mix unrelated concerns;
+- migration files whose numbering must remain contiguous after splitting;
+- provider credential or secret-storage changes that must land final-state only;
+- docs/research/plan markers that need an owning PR instead of a catch-all.
+
+### 3. Draft the rolling queue
+
+Prefer one queue item per coherent feature, infrastructure unit, or tightly coupled fix set. Use function-oriented branch names:
+
+```text
+feat/vX.Y.Z-<function-name>
+fix/vX.Y.Z-<function-name>
+ci/vX.Y.Z-<function-name>
+refactor/vX.Y.Z-<function-name>
+```
+
+Do not reuse the release-candidate source branch name as a PR function name when the branch contains many features.
+
+For every queue item record:
+
+- number, branch, title, boundary, dependencies;
+- representative commits or ranges;
+- expected file clusters;
+- folded fixes/docs/tests;
+- extraction notes, especially hunk-split commits;
+- validation expected before opening.
+
+### 4. Write or update artifacts
+
+For a new split, create or update:
+
+- `docs/brainstorms/<date>-<topic>-requirements.md` when requirements are missing;
+- `docs/plans/<date>-001-<topic>-plan.md`;
+- `docs/release/vX.Y.Z-pr-queue.md`.
+
+Keep plan documents as decision artifacts. Put progress and operational state in the release queue ledger.
+
+### 5. Include required gates
+
+The plan must require:
+
+- commit requirements, plan, and initial ledger before freezing;
+- clean tracked worktree before creating the release branch;
+- blocking secret scan before pushing a release snapshot branch;
+- no `v*` tag, version bump, or release automation during split setup;
+- one open PR at a time unless explicit approval changes the queue;
+- fresh `origin/main` worktrees for every extraction PR;
+- full CI-equivalent checks before opening each PR;
+- final equivalence check after the queue lands.
+
+### 6. Review before handoff
+
+Before finishing, verify that the queue has no generic catch-all polish PR. Any leftover must be folded into a parent PR or listed as an explicit exact-item PR requiring approval.
+
+## Rules
+
+- Use release branches only as read-only snapshots after freeze.
+- Use `origin/main` as the PR base unless the user explicitly changes the model.
+- Do not preserve original commit boundaries when hunk-level extraction gives a cleaner review boundary.
+- Do not plan temporary behavior that a later PR removes; every opened PR must represent final intended behavior for its boundary.
+- Keep migration ordering forward-only and contiguous in every intermediate PR state.