From c8a6813d8fea605d968303f34ecefdcda469f285 Mon Sep 17 00:00:00 2001 From: Kefei Qian Date: Tue, 14 Jul 2026 17:02:38 +0800 Subject: [PATCH] feat(skills): add release split workflow helpers Add project skills for drafting release-split plans, operating approved queue ledgers, and recording review-time decisions from any worktree. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 4c127c9c-ac00-4a90-be0f-4357720a6a8d --- .../kqode-release-split-decision/SKILL.md | 119 +++++++++++ .../skills/kqode-release-split-plan/SKILL.md | 107 ++++++++++ .../skills/kqode-release-split-work/SKILL.md | 189 ++++++++++++++++++ 3 files changed, 415 insertions(+) create mode 100644 .agents/skills/kqode-release-split-decision/SKILL.md create mode 100644 .agents/skills/kqode-release-split-plan/SKILL.md create mode 100644 .agents/skills/kqode-release-split-work/SKILL.md diff --git a/.agents/skills/kqode-release-split-decision/SKILL.md b/.agents/skills/kqode-release-split-decision/SKILL.md new file mode 100644 index 00000000..273a01e0 --- /dev/null +++ b/.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 | | | | +``` + +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. diff --git a/.agents/skills/kqode-release-split-plan/SKILL.md b/.agents/skills/kqode-release-split-plan/SKILL.md new file mode 100644 index 00000000..32591e85 --- /dev/null +++ b/.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- +fix/vX.Y.Z- +ci/vX.Y.Z- +refactor/vX.Y.Z- +``` + +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/--requirements.md` when requirements are missing; +- `docs/plans/-001--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. diff --git a/.agents/skills/kqode-release-split-work/SKILL.md b/.agents/skills/kqode-release-split-work/SKILL.md new file mode 100644 index 00000000..ea9ebdbe --- /dev/null +++ b/.agents/skills/kqode-release-split-work/SKILL.md @@ -0,0 +1,189 @@ +--- +name: kqode-release-split-work +description: "Continue approved KQode release-split work from docs/release/vX.Y.Z-pr-queue.md. Use after a queue PR merges or when asked to prepare the next PR: reads prior decisions, updates the ledger, creates a fresh main-based sibling worktree, extracts, validates, opens exactly one PR, and records status." +--- + +# KQode Release Split Work + +Continue approved release-split work from its ledger. This skill is for operating the rolling PR queue after the release snapshot and plan already exist. + +## Inputs + +Use the user's prompt to identify the ledger path. Default to the only file matching: + +```bash +docs/release/v*-pr-queue.md +``` + +For v0.2.0, the ledger is: + +```bash +docs/release/v0.2.0-pr-queue.md +``` + +If multiple ledgers match and the user did not name one, ask which release to continue. + +## Workflow + +### 1. Start from the control branch + +Confirm the current branch is the release-split control branch, not the frozen release-candidate branch: + +```bash +git branch --show-current +git status --short --branch +``` + +For v0.2.0, continue from: + +```text +chore/v0.2.0-release-split-ledger +``` + +If currently on `release/v*` or the frozen source branch, stop and switch to the control branch before editing the ledger. + +### 2. Refresh remote state + +```bash +git fetch origin --prune +``` + +Inspect open/merged queue PRs with `gh pr view` using the PR URLs in the ledger. If an open PR has not merged, do not prepare the next PR unless the ledger explicitly allows parallel review. + +### 3. Mark merged PRs in the ledger + +When a queue PR has merged: + +1. Update its row status to `merged`. +2. Record the merge SHA in reviewer notes or the relevant outline. +3. Add a `Queue Changes` row with the merge event and next queue item. +4. Commit and push only the ledger update. + +Use explicit pathspec commits: + +```bash +git add docs/release/vX.Y.Z-pr-queue.md +git commit -m "docs(release): mark merged" -- docs/release/vX.Y.Z-pr-queue.md +git push +``` + +### 4. Pick the next queue item + +Choose the first `pending` item whose dependencies are all `merged`. If any dependency is still `open`, `pending`, or `blocked`, stop and report the blocker. + +Mark the item `extracting` in the ledger before creating the branch, then commit and push that ledger update. + +Before extraction, read every row under `## Queue Changes` plus the target item outline. If a decision affects the target item, copy it into the PR body's **Extraction notes**, **Folded fixes**, **Validation**, or **Queue approval** field as appropriate. If any applicable decision is not reflected in the target outline, update and commit the ledger first, then continue. + +### 5. Create a fresh sibling worktree + +Never extract directly in the control checkout. Create a sibling worktree from fresh `origin/main`: + +```bash +mkdir -p ../KQode.release-split-worktrees +git worktree add ../KQode.release-split-worktrees/- \ + -b origin/main +``` + +Use `release/vX.Y.Z` as the read-only source for cherry-picks, hunk extraction, and equivalence checks. + +### 6. Extract the branch + +Use the ledger outline: + +- direct cherry-pick only when the source commit is clean for the boundary; +- hunk-split mixed commits when needed; +- fold docs/tests/review fixes into the earliest PR that introduces the behavior they protect; +- preserve migration ordering with the next contiguous migration version on current `main`; +- never add temporary behavior that a later PR removes. + +For v0.2.0 PR02, the expected extraction is: + +```bash +git cherry-pick 9cfe801 +``` + +### 7. Validate before opening + +Run checks appropriate to the touched files. For source/TUI changes, use the CI-equivalent bar: + +```bash +cargo fmt --all --check +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo build --workspace --all-targets +cargo test --workspace +cargo xtask tui-typecheck +cargo xtask tui-test +``` + +For workflow/docs-only PRs, still run a focused validation such as diff review plus repository checks that are reasonably relevant. If a check is skipped, record why in the PR body and ledger. + +Run a secret scan before pushing a branch created from the release snapshot: + +```bash +gitleaks git . --log-opts='origin/main..HEAD' --redact --no-banner +``` + +### 8. Review, commit, push, and open one PR + +Commit the extraction branch with focused commits. Run review before opening when the diff contains behavior changes; apply validated fixes before PR creation. + +Before opening, verify the branch includes all existing ledger decisions that apply to the item. If a review finding creates a decision for future PRs, invoke `kqode-release-split-decision` (or manually update the control ledger) before opening the current PR. + +Open exactly one ready-for-review PR: + +```bash +git push -u origin +gh pr create --base main --head \ + --title "" \ + --body-file <prepared-pr-body> +``` + +The PR body must include: + +- Boundary +- Representative commits +- Dependencies +- Base SHA +- Folded fixes +- Extraction notes +- Validation +- Queue approval + +### 9. Update and commit the ledger + +After opening the PR: + +1. Set the queue row status to `open`. +2. Fill base SHA, PR URL, validation, and reviewer notes. +3. Add a `Queue Changes` row. +4. Commit and push the ledger update on the control branch. +5. Stop. Do not start the next PR until this PR merges. + +### 10. Close out after the final queue item + +When every queue row is `merged`, do not delete branches immediately. First: + +1. Compare final `main` against `release/vX.Y.Z` for production/tooling behavior equivalence. +2. Document intentional residual deltas in the ledger. +3. Run the project release workflow, usually by invoking `kqode-version-bump`. +4. Verify the GitHub Release and npm publishing completed when applicable. +5. Mark the ledger `closed` or add a final Queue Changes closeout row. + +Only after the release is verified: + +- remove local extraction worktrees; +- delete merged extraction branches locally and remotely; +- delete or archive `release/vX.Y.Z` only if explicitly approved; +- merge or archive the ledger somewhere durable; +- delete the control branch last. + +## Rules + +- Keep `release/vX.Y.Z` and the frozen source branch read-only. +- Keep all operational state in `docs/release/vX.Y.Z-pr-queue.md` on the control branch. +- Do not use the old source branch name as a PR function name. +- Do not open multiple PRs unless the ledger records explicit approval. +- Do not silently change queue order or PR boundaries; record approval first. +- Use explicit pathspecs for ledger commits so concurrent staged changes are not swept in. +- Keep the control ledger until the release is verified and cleanup is complete.