@erclx/canon 4.0.0

package/claude/skills/git-pr/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: git-pr
+description: Generates pull request titles and descriptions from git diffs. Use for any PR creation or update, such as when asked to "open a pull request".
+---
+
+# Git PR
+
+## Context
+
+Read these files in parallel:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/branch.md`: branch format, valid types, and constraints
+- `${CLAUDE_SKILL_DIR}/../../standards/pr.md`: structure, rules, and banned phrases
+- `${CLAUDE_SKILL_DIR}/references/labels.md`: label map format, matching, and the missing-label warning. Skip when the project has no `.claude/canon/pr-labels.toml`.
+- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
+- `${CLAUDE_SKILL_DIR}/../../standards/versioning.md`: phase label vs semver discipline
+
+Resolve the base ref first, because the log range and the diff below both consume it:
+
+```bash
+git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
+```
+
+Then run these commands in parallel to gather git context:
+
+- `git remote get-url origin 2>/dev/null || echo "NO_REMOTE"`
+- `git branch --show-current 2>/dev/null || echo "unknown"`
+- `git log <base>..HEAD --oneline 2>/dev/null || echo "NO_COMMITS"`
+- `git diff <base> HEAD -- . ':(exclude)*.lock' ':(exclude)*-lock.json' 2>/dev/null || echo "NO_DIFF"`
+- `git diff --name-only <base> HEAD 2>/dev/null || echo "NO_FILES"`
+
+## Diff baseline
+
+Prefer `origin/main` over local `main`. Both reads resolve against `<base>`, so the commits listed and the changes described come from one scope.
+
+`git diff main..HEAD` is the form the diff replaces. A two-dot range compares tips and resolves no merge base, so once local `main` advances past the branch point it reports main's newer commits as reversed changes and the description describes work the branch never did. On `main` itself the local ref resolves to HEAD and every committed change drops out instead.
+
+`git log main..HEAD` is the matching defect on the commit side. It excludes what local `main` reaches, so a local `main` trailing `origin/main` leaves commits in the range that are already on the remote and are not this branch's work. The diff resolved from `<base>` excludes those same commits, and the description then lists commits whose changes appear nowhere in it. Reading both against `<base>` is what keeps the two halves describing one branch.
+
+The baseline is unusable in two cases:
+
+- No merge base resolves against either ref.
+- The base equals HEAD, whichever ref resolved it. Nothing is committed ahead of the base to compare against.
+
+Either case leaves both reads empty, which the no-commits guard below catches. Stop there rather than composing a description from an empty diff.
+
+## Guards
+
+- If branch name does not match `<type>/<description>` format (valid types are defined in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`), stop and output:
+  `❌ Branch name does not follow conventions. Run /git-branch to rename first.`
+- If no commits ahead of main, stop and output:
+  `❌ No commits ahead of main. Nothing to PR.`
+
+## Response format
+
+### Preview
+
+- **Title:** <title>
+- **Files changed:** <count>
+- **Analysis:** <brief summary of impact>
+
+After outputting the preview, execute the final command immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+### Testing checkboxes
+
+Follow Testing discipline in `${CLAUDE_SKILL_DIR}/../../standards/pr.md`. Run each check before writing its line, then tick the box and state the result the run reported. Never pre-check based on intent or past sessions.
+
+Leave a box unchecked only for the human-only cases the reference defines, and name which human and why on the same line. A request for the reviewer is not a test result, so it belongs under `## For the reviewer` rather than in the Testing list.
+
+### Pre-publish scan
+
+Before running the final command, run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against the PR title and body. The title and body go straight to the remote with nothing checking them on the way, so run the scan regardless of what backs it downstream. It covers the phase-label check as well as the characters, since both go to a reader who has no task board. It applies on top of the banned phrases in `${CLAUDE_SKILL_DIR}/../../standards/pr.md`.
+
+A `pull_request` workflow job now backs the phase-label half for this repository, running `canon labels scan` against the opened title and body. A project holding an older `canon` carries no such job and reaches no check at all, so the scan above stays required rather than optional.
+
+### Resolving the pull request
+
+The run resolves the pull request once, in the final command below, and every later step reads what that command printed. Nothing else looks the number up again.
+
+`gh pr view` is the form this replaces. It resolves by head branch and ignores state, so a branch name reused after an earlier pull request merged returns the closed one. The detection then takes the edit path and rewrites a merged pull request's title and body, and the run reports that pull request's URL as the one it opened, so nothing surfaces the write landing on the wrong object. Scoping the lookup with `--state open` returns empty there and sends the run down the create path.
+
+The lookup scopes to the base as well as the head. One head can carry open pull requests against two bases, and a lookup reading the first result would pick between them by list order. Resolving the base from the repository's default branch is what makes the detection and `gh pr create` agree on which pull request the run is about.
+
+A detached HEAD gives `git branch --show-current` an empty result, which would read as no open pull request and create a second one. The branch-name guard above stops the run first, since an empty name does not match `<type>/<description>`.
+
+### Labels
+
+Ask the CLI first:
+
+```bash
+canon labels audit --base <base> --json
+```
+
+The record carries `labels`, the set this branch earns, and `uncovered`, the changed paths no row of the map reaches. Join `labels` with commas into `pr_labels` below. Report each `uncovered` path beside the result line, naming the map so the reader knows where a row would go, since a surface nobody covered merges bare and nothing else says so.
+
+Branch on the record rather than on the exit. An operator's shell profile may wrap `canon` in a function whose status comes from a trailing command, and the binary exits 1 for an unknown subcommand and 1 for an ordinary refusal alike.
+
+A `reason` of `no-map` is the answer that the project declared no map, which earns no labels and no warning: a label set this skill supplied would be a guess about that project's surfaces. Stop there and label nothing.
+
+Every other `reason` is a map or a range the verb could not read, which is `unreadable-map`, `no-domains`, `no-base`, and `unreadable-changes`, plus `bad-base` for a ref this skill resolved wrongly. Take the fallback below and warn beside the result line, naming the reason. A map with a typo in it still has rows a prefix match can reach, and reading the refusal as an absence would open the pull request with no labels and nothing said, which is the surface merging bare that the verb exists to name.
+
+The fallback is reading `.claude/canon/pr-labels.toml` and matching it against the name-only diff per `${CLAUDE_SKILL_DIR}/references/labels.md`. It also covers no record coming back at all, which is an installed `canon` predating the verb, since a skill reaches a target the moment it merges while the CLI reaches one only when a release publishes. The fallback labels correctly and reports no uncovered path, which is the half only the verb carries.
+
+Leave `pr_labels` empty when no map resolves or no prefix matches, which skips the labelling command rather than running it against nothing.
+
+### Final command
+
+Detect an open pull request on the current head and branch: edit it in place when one exists, create it otherwise. This keeps the body in sync on a follow-up push instead of erroring on `gh pr create`.
+
+Labels apply after that branch converges, against a pull request that already exists. `gh pr create --label` refuses a label the remote does not carry and opens no pull request at all, so a mistyped row costs the run rather than the label. One command after the fact also covers the create and the edit path together.
+
+```bash
+mkdir -p .claude/.tmp/pr
+cat <<'BODY' > .claude/.tmp/pr/body.md
+<body content following pr.md template exactly>
+BODY
+pr_labels="<comma-separated labels, empty when the map resolves to nothing>"
+git push -u origin HEAD || exit 1
+base_branch=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) || exit 1
+pr_number=$(gh pr list --head "$(git branch --show-current)" --base "$base_branch" --state open --json number --jq '.[0].number // empty')
+if [ -n "$pr_number" ]; then
+  pr_url=$(gh pr edit "$pr_number" --title "<title>" --body-file .claude/.tmp/pr/body.md) || exit 1
+else
+  pr_url=$(gh pr create --title "<title>" --body-file .claude/.tmp/pr/body.md) || exit 1
+  pr_number=${pr_url##*/}
+fi
+if [ -n "$pr_labels" ]; then
+  gh pr edit "$pr_number" --add-label "$pr_labels" >/dev/null ||
+    printf 'Label apply failed. Create a missing label with: gh label create <name>\n' >&2
+fi
+rm -rf .claude/.tmp/pr
+printf 'number=%s\nurl=%s\n' "$pr_number" "$pr_url"
+```
+
+### Record the number on the task
+
+Write the `number` the final command printed onto the task the branch is closing. Do not resolve it again. A head branch that carried an earlier pull request now has two, and a second `gh pr view` would pick between them by a precedence rule nothing here states. Reading what created or edited the pull request needs no such rule.
+
+The task is the one whose `Plan:` line names the plan this branch implemented. Name that plan by its file, which is `.claude/plans/feature-<slug>.md` at the main worktree root with `<slug>` derived per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. `claude-feature` writes the plan under the branch slug, so the two correspond on any branch that came through the plan-to-execute path. When the session already knows which plan it implemented, because a caller read it earlier in the chain, use that filename instead of re-deriving.
+
+```bash
+canon tasks pull-request <number> --plan feature-<slug> --json
+```
+
+The slug is a guess at which plan this branch carries rather than a fact about the task, which is why the verb re-checks it against the board and refuses instead of writing on a near miss. A branch whose slug names no plan file falls to the silent skip below, the same as one whose plan no task cites.
+
+The verb resolves the board at the main worktree root in-process, adds `Pull request: #NNN` under the `Plan:`, `Groundwork:`, `Intake:`, or `Issue:` lines the task already carries, and corrects the number in place when the line exists. This is the route because the write is an edit inside an existing file, which the file-editing tools refuse from a linked worktree and which no shell stream editor may make. See Worktrees in `CLAUDE.md`.
+
+Skip this silently when the record is `ok: false` and `reason` is `no-board`, `no-match`, or `ambiguous`. Those are the three cases a guessed write would compound: no board, no task naming the plan, or more than one. One task, one pull request, and a wrong match archives the wrong task unattended once the branch merges. Report any other refusal rather than swallowing it.
+
+The number is what lets the merge close the task. Every merge on `main` is a squash carrying it in the subject, so the number survives where a branch name does not, and `post-merge` reads it back to call `canon tasks archive`. Writing it here rather than at worktree time is what makes it a pull request number rather than a branch the squash discards.
+
+## After execution
+
+Respond with one line, using the `url` the final command printed:
+
+`✅ PR: <url>`
+
+Add a second line only when the labelling command printed its warning, quoting the label `gh` refused:
+
+`⚠️ Labels not applied: <what gh reported>`
+
+Do not add any other text.

package/claude/skills/git-pr/references/labels.md

@@ -0,0 +1,95 @@
+---
+title: Label reference
+description: Path-to-label map format, prefix matching against the changed set, and the one-time label creation a map requires
+---
+
+# Label reference
+
+## Scope
+
+Governs the labels a pull request carries: the map a project declares, how a changed path resolves to a label, and what a label missing from the remote costs.
+
+Does not govern:
+
+- Pull request title and body: `pr.md`
+- Branch naming: `branch.md`
+- Issue labels, which `git-issue` derives from the issue type rather than from a diff
+
+## Map format
+
+The map lives at `.claude/canon/pr-labels.toml` in the project root. Each key under `[domains]` is a label name and its value is the list of path prefixes that earn it.
+
+```toml
+[domains]
+api = ["services/api/"]
+web = ["apps/web/", "packages/ui/"]
+```
+
+A label takes more than one prefix when two folders read as one surface. Two labels may claim overlapping prefixes, and a path under both earns both.
+
+Matching is prefix-anchored, so a row written for an authoring root reaches nothing under the copy a project consumes. A surface living only under a dotted folder carries its own prefix on the row that owns its subject, and a folder holding several subjects rather than one splits across the rows that own them.
+
+The map is authored by hand, so a surface added after it was written labels nothing until someone adds a row. `canon labels audit` is what names that surface before the branch merges.
+
+## Paths a map declines to label
+
+A path that moves only when a release or a generator rewrites it earns no row. Release automation applies its own label, and a domain label on a generated file gives a mechanical edit a subject it does not have.
+
+Both go under a `[declined]` table keyed by the reason, in the same file and matched by the same prefix rule:
+
+```toml
+[declined]
+release-managed = ["CHANGELOG.md", "package.json"]
+generated = ["build/manifest.json"]
+```
+
+A table rather than a comment because the check reads it. A path here is a decision already taken and a path under neither table is a gap nobody has gotten to, and a report that could not tell those apart would be useful about neither.
+
+A path claimed by a `[domains]` row and a `[declined]` row takes the label. It already has a subject, so reporting it as deliberately unlabelled would contradict the label the same run applies.
+
+## Reporting a surface no row reaches
+
+```bash
+canon labels audit --base <base> --json
+```
+
+The record carries `labels`, `declined`, and `uncovered`. It exits 2 when `uncovered` has anything in it and 1 when it refuses, with `reason` naming the cause: `no-map` for a project that declared none, and a parse or range failure otherwise.
+
+It reports and never gates. Whether an uncovered surface deserves a label is a judgment only the person who owns that surface can make, and a push failing on one teaches a contributor to route around the check while nothing about the surface has changed.
+
+What it leaves unmeasured is a prefix reaching no path, so a row left behind by a deleted folder stays in the map. That is the map going stale from the other side and a second measure rather than this one.
+
+## Matching
+
+- Take the changed set from `git diff --name-only <base> HEAD`, resolved against the same base as the diff the body is written from
+- A path earns a label when the path starts with one of that label's prefixes
+- Collect the distinct labels across the whole set, ordered as the map declares them, so two runs over one branch produce one string
+- Pass the result as a single comma-separated value. An empty result runs no labelling step.
+
+## Applying
+
+Apply labels after the pull request resolves, never as a flag on the create. `gh pr create --label` fails whole on a label the remote does not carry, so a name the map got wrong opens no pull request at all and the run stops with the branch pushed and nothing to review. A `gh pr edit --add-label` against a pull request that already exists costs a warning instead, and it is one command across both the create and the edit path rather than two flags that have to stay in step.
+
+Labelling runs whenever this skill runs and at no other time. Nothing else computes the set, so a push made any other way leaves the labels exactly as the last run left them. Any caller invoking this skill again reaches the step again, and it recomputes over the whole branch diff rather than over the new commits.
+
+An ordinary branch therefore labels once, when the pull request opens. The return leg that answers a review hands its push to `git-followup`, which refreshes the body without invoking this skill, so the commits that answer a review reach no labelling step.
+
+A follow-up push reaching a surface the earlier ones did not merges under-labelled, with nothing to report the miss. Keeping the step in one skill is worth that cost, since a review fix lands in the files the review named and rarely opens a surface the branch had not already touched.
+
+`--add-label` adds and never removes. A label a person applied by hand is not this skill's to strip, and a re-run over a branch that has since dropped a surface keeps the label that surface earned.
+
+## A label the remote does not carry
+
+Warn and continue rather than creating it, naming the command in the warning:
+
+```bash
+gh label create <name> --description "<text>"
+```
+
+Creating a label writes to the repository settings from a run the user invoked to open a pull request, and a label created from a typo in the map is harder to notice than a warning is.
+
+The refusal names the label it rejected and applies none of the set, so a warning that reaches nobody leaves the run reading exactly like one that labelled. Surface it beside the result line rather than letting the pull request URL stand alone.
+
+## Release pull requests
+
+Release automation opens its own pull requests without this skill and applies its own labels, so nothing here needs a skip condition for them.

package/claude/skills/git-ship/REQUIREMENT.md

@@ -0,0 +1,42 @@
+---
+name: git-ship
+description: What the ship chain is for, the gaps it closes, and why it does not implement or review
+---
+
+# Git ship requirement
+
+## Gap
+
+Without this skill, the post-feature sequence runs from memory. Doc sync gets skipped, so the pull request ships with planning docs describing the previous scope, or it runs after staging has already closed and its output never reaches a commit. Chaining by hand is also where a session narrates between steps, which turns one flow into a conversation and invites a decision at every boundary.
+
+The sequence also reaches the remote on work nothing re-checked. This skill is the resume point `claude-autoship` names at four of its stop points, including the one a failed verify takes, so the fix the user makes by hand after that stop is pushed with no suite run against it. Every branch shipped so far passed that verify on its first attempt, which is why the path has produced no instance rather than being closed.
+
+## Must
+
+- Run the project's verify commands before the sequence starts, and stop on a failure rather than fixing it
+- Say so and continue when the project names no verify command, since silence there reads as a suite that passed
+- Invoke each step through the Skill tool in the stated order and continue without waiting
+- Stage after the sync skills write, so what they produced reaches a commit
+- Emit no text between steps. The sequence is the unit and prose inside it reopens settled decisions.
+- Name the one point a wrapping caller may act at, so a chain built on this one is not left to pick a gap of its own
+- Name the condition under which the closing block is not emitted, since a caller that closes on its own block leaves two instructions about the last line and nothing deciding between them
+- Watch continuous integration to a terminal state, and stop on a failure naming the check
+- Stop memory work at the Propose phase
+
+## Must not
+
+- Auto-trigger. Shipping is a decision the user takes, and the tool permission dialog on the push and the pull request is the gate that holds it now that the frontmatter no longer disables model invocation.
+- Fix a failing check. The stop is the point, since a green pull request reached by auto-fix hides what broke.
+- Run the memory Apply phase. Promoting an entry changes how the agent operates and ships as its own change.
+- Attempt a fix for a failing verify. The user is already making one, which is what brought the run back here.
+- Implement or review. This chain starts from work already believed done.
+
+## Guards
+
+- A failing verify stops the run before the sync skills write, so the tree is left as the user left it
+- A failing check stops the sequence. This is the one place text is allowed between steps.
+
+## Out of scope
+
+- Implementation and review, which `claude-autoship` chains ahead of this same sequence. That skill is the full pipeline and this one is the resume point after a stop, which is why the two overlap by design. Verification is the one of the three that belongs on both, since a resume point that trusts the caller's verify trusts a run that stopped.
+- The behavior of each step, owned by the skill invoked. This skill owns the order and nothing else.

package/claude/skills/git-ship/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: git-ship
+description: Runs the full post-feature workflow by syncing docs, staging commits, renaming the branch, and opening a PR. Use after implementing a feature, or when asked to "ship", "ship this", or "ship it". Do NOT auto-trigger. Shipping is a decision the user takes.
+---
+
+# Ship
+
+Run the full post-feature workflow by invoking each skill in sequence using the Skill tool. After each skill returns, invoke the next step immediately in the same response.
+
+Do not output any text between steps and do not wait for user input. Tool permission dialogs are the only interrupts allowed. The final output is `✅ Shipped`, unless a wrapping caller states it closes on its own block, which `claude-autoship` does.
+
+## Verify
+
+Run the verify commands `CLAUDE.md` names (lint, typecheck, tests) before the sequence starts. On a failure, stop: `❌ Verify failed. Fix the reported errors and run /git-ship again.` Make no fix attempt. This skill is the resume point after a stop, so the fix is the one the user is already making.
+
+When `CLAUDE.md` names no verify command, say so on one line and continue. A project with no suite is not a project with a failing one.
+
+Verify runs ahead of the sync skills so a stop leaves the tree exactly as the user left it. Re-running a suite the caller already ran costs one command, and the path it closes is the one that has no other guard: `claude-autoship` verifies at its own Step 3 and then hands four of its stop points straight back here, so a fix made by hand after one of those stops otherwise reaches the remote with nothing re-run.
+
+## Pre-check
+
+Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If output is empty and there are unstaged changes, run `git add -A` to stage everything before proceeding.
+
+## Sequence
+
+1. Invoke `canon:claude-memory-capture` to route what this session learned to the context entries that own it and write the residue to `.claude/memory/`
+2. Invoke `canon:claude-docs` to sync internal planning docs against session decisions, folding in the routed facts
+3. Invoke `canon:docs-sync` to sync public docs against changes since main
+4. Run `git add -A` to stage any files the sync skills wrote
+5. Invoke `canon:git-stage` to group staged changes and commit by concern
+6. Invoke `canon:git-branch` to rename branch to match conventional format
+7. Invoke `canon:git-pr` to push branch and open pull request
+8. After the PR opens, watch CI. Poll `gh pr checks <number>` until no check is pending, then read the final status. On all-pass, continue. On any failure, stop the sequence and report the failing check with its URL. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
+9. If step 1 wrote or updated at least one memory file, invoke `canon:claude-memory-review` scoped to those entries to propose fixes while session context is fresh. If the pen got nothing, skip this step.
+
+A caller wrapping this sequence may act between step 7 and step 8, which is the one gap the order leaves open, since the pull request exists there and nothing has read its checks yet. `claude-autoship` marks the pull request draft in it. Nothing else may go there, and a caller that needs a step anywhere else in the sequence is asking for a change to this body rather than for a place to stand.
+
+Capture leads the sequence because a routed fact lands in a context entry, which is a tracked file. Running it after the pull request opens leaves that edit off the branch entirely, so the fact reaches nothing. Memory files are gitignored either way, which is what hid the ordering while capture wrote only those.
+
+Stop at the Propose phase. Do not run Apply. Promoting an entry to `CLAUDE.md` or a skill body ships as its own change, separate from this feature.
+
+## After completion
+
+Output up to four lines:
+
+```plaintext
+✅ Shipped
+<N facts routed to context entries>
+<N memories captured in .claude/memory/>
+<Memory proposal at .claude/review/memory/memory-review-<slug>.md>
+```
+
+Omit the second line if nothing routed. Omit the third and fourth if `claude-memory-capture` wrote no memory file this session, since an empty pen means no scoped review and no proposal.
+
+Emit nothing here when a wrapping caller states it closes on its own block. `claude-autoship` is that caller and its block carries these same three trailing lines above a first line naming the draft state, so emitting both reports one run twice. A caller that states no such thing gets this block, which is every direct invocation.

package/claude/skills/git-split/REQUIREMENT.md

@@ -0,0 +1,39 @@
+---
+name: git-split
+description: What branch splitting is for, the gaps it closes, and how it differs from grouping a staged diff
+---
+
+# Git split requirement
+
+## Gap
+
+Without this skill, a branch carrying unrelated commits ships as one pull request, which a reviewer reads by skimming because no single concern holds it together. Split by hand, commits get cherry-picked in an order that leaves a branch missing something it depends on. Merge order is the sharpest failure: merging the wrong branch first lands every other branch's content on main and leaves the remaining pull requests empty after rebase, with no signal that anything went wrong. Every body it writes stages under `.claude/.tmp/` and leaves through `gh`, neither of which the audit hook watches, so a banned character survives into a published pull request and has to be edited on the remote.
+
+## Must
+
+- Refuse a dirty tree, since cherry-picking across branches abandons uncommitted work with no record of it
+- Group by concern from both the commit messages and the file paths, preferring fewer branches over a branch per commit
+- Classify the groups as independent or stacked before generating any command, because the base of every branch follows from that one call
+- Account for every commit ahead of main in the preview
+- State the merge order and the reason behind it, since the order is not recoverable from reading the pull requests afterward
+- Carry the restack loop for stacked mode, where each branch is rebased onto main once the one below it merges
+- Scan every generated title and body for banned characters and internal phase labels as an explicit step before opening a pull request
+
+## Must not
+
+- Split when one concern already covers the branch
+- Rename a branch whose name already matches its concern
+- Leave a commit unaccounted for. A dropped commit is silent and the branch it came from may already be gone.
+- Merge the pull requests it opens
+
+## Guards
+
+- Dirty working tree: stop and name both recoveries
+- On `main`: stop
+- No commits ahead of main: stop
+
+## Out of scope
+
+- Partitioning a staged diff into commits, which `git-stage` owns. The two resemble each other and take different input: this one starts from commits that already exist and emits branches.
+- The message on each commit, which `git-commit` owns
+- Merging, which stays the user's call. The skill states the order and stops.

package/claude/skills/git-split/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: git-split
+description: Splits a mixed-commit branch into focused branches off main using cherry-pick. Use when a branch has unrelated commits, asking "split this branch", or needing to separate concerns into reviewable PRs.
+---
+
+# Git split
+
+Before proposing a split, read in parallel:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/branch.md`: format, types, length limit, and constraints
+- `${CLAUDE_SKILL_DIR}/../../standards/pr.md`: PR title format, body sections, and content rules
+
+Follow both exactly.
+
+## Context
+
+Run these commands in parallel to gather git context:
+
+- `git status --porcelain 2>/dev/null || echo "NO_STATUS"`
+- `git branch --show-current 2>/dev/null || echo "NO_BRANCH"`
+- `git log main..HEAD --oneline --no-decorate --stat 2>/dev/null || echo "NO_COMMITS"`
+
+## Guards
+
+- If working tree is dirty (non-empty `git status --porcelain`), stop:
+  `❌ Working tree is dirty. Commit or stash changes before splitting.`
+- If current branch is `main` or `master`, stop:
+  `❌ Already on main. Nothing to split.`
+- If no commits ahead of main, stop:
+  `❌ No commits ahead of main. Nothing to split.`
+
+## Grouping rules
+
+- Group commits by concern using both commit messages and file paths.
+- Prefer fewer branches: combine related commits into one branch.
+- Only split into separate branches when concerns are clearly independent.
+- Identify the primary concern of the current branch. Rename it using `git branch -m` if the current name does not already match. Skip the rename if it already matches. Secondary concerns are extracted as new focused branches via cherry-pick.
+- If no single concern dominates (dumping-ground branch with no clear primary), split all commits into new focused branches and add `git branch -d <current>` to delete the original.
+- Propose one new branch per secondary concern following branch.md format.
+- Classify groups as independent or stacked before generating commands.
+- Independent groups: each group's commits apply to `main` without the others. Base every branch on `main`.
+- Stacked groups: groups are ordered and each depends on the commits before it. Base each branch on the previous group's branch. Cherry-pick only that group's commits onto it. The base branch already carries all prior commits.
+
+## Response format
+
+### Preview
+
+**Current branch:** <branch_name>
+**Total commits ahead of main:** <count>
+**Mode:** Independent | Stacked
+
+| Group     | Branch               | Base           | Commits | Count |
+| --------- | -------------------- | -------------- | ------- | ----- |
+| <concern> | <type>/<description> | main           | <shas>  | <n>   |
+| <concern> | <type>/<description> | <prior-branch> | <shas>  | <n>   |
+
+**All <total> commits accounted for.**
+
+- For the primary concern (the current branch), show `<current_branch> → <new_name>` only when renaming. Show `<current_branch>` alone if the existing name already matches the concern.
+- For stacked mode, list rows in merge order: branches based on `main` first, then each layer above. For independent mode, list the primary concern first.
+
+If Mode is Stacked, append this line to the preview:
+
+`🔁 Sequential squash-merge loop. Squash-merge each PR bottom-up with --delete-branch. After each merge, signal me so I can restack the next branch onto main before you merge it.`
+
+If Mode is Independent, append this line to the preview:
+
+`🔁 Squash-merge secondaries first, primary last. The primary keeps every cherry-picked commit, so merging it first lands every secondary's content on main and leaves the secondary PRs empty after rebase.`
+
+After outputting the preview, execute the final commands immediately. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+
+Before running them, run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against every title and body. Each body stages under `.claude/.tmp/` and leaves through `gh`, so the hook sees neither and this scan is the only gate. Each resulting branch reaches the `pull_request` check the git-pr surface carries once its own pull request opens, but not before, so this scan is what catches a leak ahead of that.
+
+### Final commands
+
+For independent mode, base every branch on `main`:
+
+```bash
+# Rename current branch to reflect primary concern
+git branch -m <current_branch> <new_name>
+
+# Create, cherry-pick, push, and open PR for each secondary branch
+mkdir -p .claude/.tmp/pr-split
+git switch -c <branch> main && git cherry-pick <sha> <sha> \
+  && git push -u origin <branch> \
+  && (cat <<'BODY' > .claude/.tmp/pr-split/<branch>.md
+<body following pr.md template, written from the cherry-picked commits>
+BODY
+) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<branch>.md \
+  && rm .claude/.tmp/pr-split/<branch>.md
+
+# Return to primary branch, push, and open its PR
+git checkout <new_name> && git push -u origin <new_name> \
+  && (cat <<'BODY' > .claude/.tmp/pr-split/<new_name>.md
+<body following pr.md template, written from the primary's commits>
+BODY
+) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<new_name>.md \
+  && rm .claude/.tmp/pr-split/<new_name>.md
+
+# Clean up the body-file dir if all PRs succeeded (no-op when non-empty)
+rmdir .claude/.tmp/pr-split 2>/dev/null || true
+```
+
+For stacked mode, base each branch on the previous and cherry-pick only that group's commits:
+
+```bash
+# Rename current branch to reflect primary concern
+git branch -m <current_branch> <new_name>
+
+mkdir -p .claude/.tmp/pr-split
+
+# Group 1: based on main
+git switch -c <branch-1> main && git cherry-pick <g1-sha> <g1-sha> \
+  && git push -u origin <branch-1> \
+  && (cat <<'BODY' > .claude/.tmp/pr-split/<branch-1>.md
+<body following pr.md template, written from the cherry-picked commits>
+BODY
+) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<branch-1>.md \
+  && rm .claude/.tmp/pr-split/<branch-1>.md
+
+# Group 2: based on <branch-1>, this group's commits only
+git checkout -b <branch-2> && git cherry-pick <g2-sha> <g2-sha> \
+  && git push -u origin <branch-2> \
+  && (cat <<'BODY' > .claude/.tmp/pr-split/<branch-2>.md
+<body following pr.md template, written from the cherry-picked commits>
+BODY
+) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<branch-2>.md \
+  && rm .claude/.tmp/pr-split/<branch-2>.md
+
+# Return to primary branch, push, and open its PR
+git checkout <new_name> && git push -u origin <new_name> \
+  && (cat <<'BODY' > .claude/.tmp/pr-split/<new_name>.md
+<body following pr.md template, written from the primary's commits>
+BODY
+) && gh pr create --title "<title>" --body-file .claude/.tmp/pr-split/<new_name>.md \
+  && rm .claude/.tmp/pr-split/<new_name>.md
+
+# Clean up the body-file dir if all PRs succeeded (no-op when non-empty)
+rmdir .claude/.tmp/pr-split 2>/dev/null || true
+```
+
+## After execution
+
+Respond with exactly one line:
+
+`✅ Renamed: <old> → <new> | PRs: <primary-url>, <url1>, <url2>`
+
+Do not add any other text.
+
+## Stacked merge loop
+
+When the user signals the previous stacked PR has merged, restack the next one.
+
+1. Rebase and push. The own-commit-count comes from the original split table.
+   `git fetch origin main && git checkout <branch> && git rebase --onto origin/main HEAD~<own-commit-count> && git push --force-with-lease`
+2. Verify the PR's base auto-retargeted to main with `gh pr view <num> --json baseRefName`. If not, `gh pr edit <num> --base main`.
+3. Reply: `✅ <branch> rebased onto main. Ready for squash-merge.`
+
+Edge cases:
+
+- If this branch's commits modify a file added by an unmerged upstream PR, wait for that PR to merge before rebasing.
+- If the PR was orphaned by base-branch deletion, recreate it with `gh pr create --base main --head <branch>` and a regenerated body.

package/claude/skills/git-stage/REQUIREMENT.md

@@ -0,0 +1,39 @@
+---
+name: git-stage
+description: What commit grouping is for, the gaps it closes, and how it differs from splitting a branch
+---
+
+# Git stage requirement
+
+## Gap
+
+Without this skill, a staged diff spanning several concerns lands as one commit, so a later revert takes unrelated work with it. A renamed file staged as two separate paths records an add and a delete, losing the rename git would otherwise detect. Commits also land in the order the files happened to be listed rather than the order they depend on, so a bisect stops on a commit that cannot build.
+
+The routing failure sits on top of those. A description claiming every commit request pulls in the single-concern one this skill has no grouping to do on, and a staged set carrying a hunk-level selection reaches the unstage below and comes back widened to whole files, which is the one case the staged-set rule cannot hold.
+
+## Must
+
+- Read the commit format reference and the prose standard before generating
+- Decline the single-concern and the hunk-level staged set in the description, naming the sibling that takes each. The widening is a property of the unstage, so it cannot be fixed here and has to be routed around.
+- Derive the groups from the staged diff, with lockfiles excluded from the derivation context
+- Account for every staged file in the preview, so a dropped file is visible before execution
+- Order the commits so a dependency lands before the file that imports it
+- Keep a rename pair in one group and restage both paths together, so git still detects the rename at commit time
+- Unstage everything first, then restage per group, since the incoming staged set is one undifferentiated blob
+- Count each subject against the length limit and shorten before executing
+
+## Must not
+
+- Stage a file the user did not stage. The staged set is the input and widening it changes what ships.
+- Split a rename pair across groups
+- Emit anything after the result line. This runs inside a longer flow and prose here buries the next step.
+
+## Guards
+
+- Nothing staged: stop and name the command that stages
+
+## Out of scope
+
+- Composing a single commit from the whole staged diff, which `git-commit` owns. That skill commits the staged set untouched, so a hunk-level selection belongs there and never here.
+- Splitting commits across branches, which `git-split` owns. The two partition different things: this one takes a staged diff and emits commits, that one takes commits and emits branches.
+- Pushing and opening the pull request, which `git-pr` owns