ase-repo-stage
Stage only the part of the current Git working copy changes which belongs to a topic, to the last `CHANGELOG.md` entry, to the last turn, or to the entire session, by picking and, if necessary, splitt
SKILL.mdplugin/skills/ase-repo-stage/SKILL.md
GitHub@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md
<purpose name="ase-repo-stage"> Stage a Part of the Changes </purpose><expand name="getopt" arg1="ase-repo-stage" arg2="--entry|-e --turn|-t --session|-s --merge|-m --no-verify|-V --worktree|-w --changelog|-c --commit|-C"> $ARGUMENTS </expand>
<objective> *Stage* only the part of the current Git working copy changes which belongs to a *selection* -- a topic, the last `CHANGELOG.md` entry, the last turn, or the entire session -- by picking and, if necessary, *splitting* hunks, and *check* that the staged state builds on its own. </objective>Procedure
Throughout the entire skill, you MUST NEVER modify the content of
any working copy file yourself: only the Git index is changed, the
working copy is only temporarily stashed and restored by STEP 4, and
only the chained ase-repo-changelog skill of STEP 5 may edit a file.
Whenever this skill stops early after STEP 1.5, first undo the
intent-to-add marks of all files of <intent-files/> which carry no
staged content by running the corresponding command (taken exactly as
given) per file: git reset -q -- "<file/>".
- <step id="STEP 1: Determine Selection and Change Set">
Set <topic><getopt-arguments/></topic>, with any leading and trailing whitespace stripped. If more than one of <getopt-option-entry/>, <getopt-option-turn/>, and <getopt-option-session/> is equal
<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: options `--entry`, `--turn`, and `--session` are mutually exclusive </template>true, only output the following <template/> and then immediately STOP:Determine the selection mode <mode/>: set it to
entry,turn, orsessionif the corresponding option is equaltrue. Otherwise, infer it from <topic/>: set it toturnif <topic/> refers to the changes of the last (or previous) turn, tosessionif it refers to all changes of the current session, toentryif it refers to the last ChangeLog entry, and in all these cases strip the referring words from <topic/>. Otherwise, set it totopic. An explicitly given option always overrides the inference, and a remaining non-empty <topic/> always narrows the modesentry,turn, andsession.If <mode/> is
<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: no selection given -- neither a topic nor `--entry`, `--turn`, or `--session` </template>topicand <topic/> is empty, only output the following <template/> and then immediately STOP:Otherwise, set <selection/> to a brief rendering of <mode/> and <topic/> (like
<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ⇌ selection: **<selection/>** </template>topic "<topic/>",last ChangeLog entry,last turn, orsession, narrowed to "<topic/>") and only output the following <template/>:Determine the repository root by running the corresponding command (taken exactly as given) and capturing its output into <repo-root/>. If this command fails, only output the following <template/> and then immediately STOP:
<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: no Git repository </template>git rev-parse --show-toplevel- <if condition="<getopt-option-merge/> is not equal `true`">
The selection *replaces* the current index content. Determine
the staged and the unstaged files by running the corresponding
commands (taken exactly as given):
git -C "<repo-root/>" -c core.quotepath=off diff --cached --name-onlygit -C "<repo-root/>" -c core.quotepath=off diff --name-onlyIf a file occurs in both lists, its staged version exists nowhere else and would be lost by resetting the index, so only output the following <template/> and then immediately STOP, leaving everything untouched:
<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: files with both staged and unstaged changes -- use `--merge` or commit the staged changes first </template>Otherwise, if the first list is not empty, unstage everything by running the corresponding command (taken exactly as given), which leaves the working copy untouched:
</if> <else> The selection is staged *on top* of the current index content, which hence stays untouched. Do not output anything. </else>git -C "<repo-root/>" reset -q Determine the untracked files by running the corresponding command (taken exactly as given), skipping every entry below the
.ase/directory, as it carries ASE's own state:git -C "<repo-root/>" -c core.quotepath=off ls-files --others --exclude-standardSet <intent-files/> to the remaining files and mark each of them as intent-to-add by running the corresponding command (taken exactly as given), so its content shows up as an ordinary, splittable creation diff:
git -C "<repo-root/>" add -N -- "<file/>"Determine the diff details and the diff statistics of the working copy against the index by running the corresponding commands (taken exactly as given) and capturing their full outputs into <diff/> and <stat/>:
git -C "<repo-root/>" diff --binary
<if condition="<diff/> is empty"> Only output the following <template/> and then *STOP*: <template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ status: **no changes to stage** </template> </if>git -C "<repo-root/>" diff --numstat
- <step id="STEP 2: Select Changes">
Determine the selected changes -- the changed lines of <diff/> which belong to the selection -- according to <mode/>:
topic: the changes which semantically belong to <topic/>.
<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: no uncommitted `CHANGELOG.md` entry found </template>entry: the changes which realize the last ChangeLog entry, i.e. the entry added or modified by the uncommitted change of theCHANGELOG.mdfile in <diff/> (if several, the one <topic/> names, else the last one in file order), plus the lines of this entry itself. If <diff/> adds or modifies no such entry, only output the following <template/> and then STOP:
<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: no changes of the <mode/> found in the conversation context </template>turnresp.session: the changes made by your own file-modifying tool calls (likeEditandWrite) of the last turn before this skill invocation resp. of the entire current session, as carried by the conversation context. If the context carries no such modifications which are still part of <diff/>, only output the following <template/> and then STOP:
For the modes
entry,turn, andsession, a non-empty <topic/> additionally narrows the selected changes to those which semantically belong to <topic/>.Keep mutually dependent changes together: if a selected change only builds together with an unselected one (like a use and its import or declaration), select the latter, too, and mention it in its file summary of STEP 3.
Set <n-files/>, <n-hunks/>, and <n-split/> to the number of files, hunks, and partially selected hunks with selected changes. A binary file diff is never split, so it is either selected entirely or not at all.
<if condition="no changes were selected"> Only output the following <template/> and then *STOP*: <template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ status: **nothing selected for staging** </template> </if>
- <step id="STEP 3: Stage Changes">
Set <tmp-dir/> to the value of the
TMPDIRenvironment variable if it is known in the current session context, and to/tmpotherwise. Do not output anything.Assemble <patch/> from <diff/>: keep the complete
diff --gitfile headers and the@@hunk headers of all files and hunks with selected changes, and drop all others. Keep an entirely selected hunk verbatim. Turn a partially selected hunk into a sub-hunk, exactly like an edited hunk ofgit add -p: keep its context lines and its selected+and-lines, turn every unselected-line into a context line by replacing its leading-by a space, and drop every unselected+line. Its@@header stays unchanged, as--recountfixes its counts.Besides these marker changes, <patch/> stays byte-exact: you MUST NEVER re-wrap, re-indent, or re-encode a line, normalize or strip trailing whitespace, omit the trailing newline, or re-render any part of it as Markdown.
Use the
Writetool to write <patch/> to the patch file<tmp-dir/>/ase-stage.patch, and apply it to the index only by running the corresponding command (taken exactly as given):
<if condition="this command fails"> Keep the patch file for inspection, only output the following <template/>, and then *STOP*: <template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: patch failed to apply -- kept as `<tmp-dir/>/ase-stage.patch` </template> </if>git -C "<repo-root/>" apply --cached --recount --whitespace=nowarn "<tmp-dir/>/ase-stage.patch"Undo the intent-to-add mark of every file of <intent-files/> without selected changes by running the corresponding command (taken exactly as given) per file, and then remove the patch file by running the corresponding command (taken exactly as given):
git -C "<repo-root/>" reset -q -- "<file/>"rm -f "<tmp-dir/>/ase-stage.patch"Only output the following <template/>, with one
<template> ○ `<file/>`: <summary/> [...] ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ✚ staged: **<n-files/>** files, **<n-hunks/>** hunks (**<n-split/>** split), ▶ status: **selection staged** </template>○line per staged file and an ultra brief <summary/> of its staged changes:
<step id="STEP 4: Verify Staged State" condition="<getopt-option-no-verify/> is not equal `true`">
Determine the build command <build/> of the project: prefer the command the project-level AI guidance files (
<if condition="no build command can be determined"> Only output the following <template/> and then *skip* the remaining sub-steps of this step: <template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ status: **no build command found -- check skipped** </template> </if>AGENTS.md,CLAUDE.md, or similar) name for building, else derive it from the build configuration (like thebuildscript ofpackage.json, the default target of aMakefile, or the native build command of the language). Prefer a single top-level command which builds and type-checks the entire project.Set <build-ok/> to the outcome of running <build/> on the staged state alone, determined by the first applicable case:
- <if condition="the working copy carries neither unstaged changes nor untracked files besides those below `.ase/`"> The working copy already equals the staged state (check it via `git -C "<repo-root/>" diff --quiet` and a re-run of the untracked files command of STEP 1.5), so run <build/> with <repo-root/> as its working directory. </if>
- <elseif condition="<getopt-option-worktree/> is equal `true`">
Build in a *temporary worktree*: determine <check-dir/> by
calling the `ase_worktree_path(id: "ase-repo-stage", temp:
true, create: true)` tool of the `ase` MCP server -- you
*MUST* *NEVER* assemble this path yourself. If <check-dir/>
is still a registered worktree of an earlier run, remove it
first. Then run the corresponding commands (taken exactly as
given), where the redirection captures the binary-safe
staged diff:
git -C "<repo-root/>" worktree add --detach "<check-dir/>" HEADgit -C "<repo-root/>" diff --cached --binary > "<tmp-dir/>/ase-stage-check.patch"git -C "<check-dir/>" apply --whitespace=nowarn "<tmp-dir/>/ase-stage-check.patch"Link every git-ignored dependency directory of the working copy (like each
node_modulesdirectory, found viafind "<repo-root/>" -name node_modules -type d -prune -not -path "*/.ase/*") into the same relative location of <check-dir/> vialn -s "<dependency-dir/>" "<check-dir/>/<relative-dir/>", so <build/> runs without a fresh installation. Then run <build/> with <check-dir/> as its working directory, and finally clean up by running the corresponding commands (taken exactly as given):git -C "<repo-root/>" worktree remove --force "<check-dir/>"
</elseif>rm -f "<tmp-dir/>/ase-stage-check.patch" - <else>
Build *in place*: run the corresponding commands (taken
exactly as given) and compare the outputs of the first and
the third command -- only if they *differ* was the stash
really created:
git -C "<repo-root/>" rev-parse -q --verify refs/stashgit -C "<repo-root/>" stash push -q --keep-index --include-untracked -m "ase-repo-stage"git -C "<repo-root/>" rev-parse -q --verify refs/stashIf the stash was not created, only output the following <template/> and then immediately STOP, as the working copy stays untouched:
<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: stashing the unstaged changes failed -- staged state not checked </template>Otherwise, run <build/> with <repo-root/> as its working directory, and then always -- also on a failed build -- restore the working copy by running the corresponding commands (taken exactly as given), where the reset is safe because the stash carries both the index and the working copy:
git -C "<repo-root/>" reset -q --hardgit -C "<repo-root/>" stash pop -q --indexIf the
<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: restoring the working copy failed -- the changes are kept in `git stash list` as `ase-repo-stage` </template> <ase-tpl-hint level="minimal"> Remove the conflicting files the build created and restore the changes via `git stash pop --index`. </ase-tpl-hint> </else>git stash popcommand fails, only output the following <template/> and then immediately STOP:
- <if condition="<build-ok/> indicates success"> Only output the following <template/>: <template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ⚙ build: `<build/>`, ▶ status: **staged state builds** </template> </if> <else> The staged selection stays as it is, and the chaining of STEP 5 is *skipped*. Only output the following <template/>, where <errors/> are the *essential* error lines of the build output as a fenced code block: <template> <errors/> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ⚙ build: `<build/>`, ▶ ERROR: staged state does not build </template> <ase-tpl-hint level="minimal"> The selection most likely lacks a dependent change -- re-run `/ase-repo-stage` with a refined topic. </ase-tpl-hint> </else>
<step id="STEP 5: Chain into ChangeLog and Commit" condition="(<getopt-option-changelog/> is equal `true` or <getopt-option-commit/> is equal `true`) and STEP 4 reported no build failure">
- <if condition="<getopt-option-changelog/> is equal `true`">
Capture the unstaged diff of the `CHANGELOG.md` file located by
`ase-repo-changelog` (in the current directory or one of its
parents) into <before/> via `git -C "<repo-root/>" diff --
"<changelog/>"`. Then invoke the ChangeLog updating:
<skill name="ase:ase-repo-changelog"/>
Capture the same diff again into <after/>, and stage exactly the changes which <after/> carries beyond <before/> -- the entries just added or updated for the staged selection -- by assembling, writing, and applying them as in STEP 3.2 and 3.3.
</if> - <if condition="<getopt-option-commit/> is equal `true`"> Invoke the commit message crafting for the staged selection: <skill name="ase:ase-repo-commit"/> </if>
- <if condition="<getopt-option-changelog/> is equal `true`">
Capture the unstaged diff of the `CHANGELOG.md` file located by
`ase-repo-changelog` (in the current directory or one of its
parents) into <before/> via `git -C "<repo-root/>" diff --
"<changelog/>"`. Then invoke the ChangeLog updating:
<skill name="ase:ase-repo-changelog"/>
- <step id="STEP 6: Report Result">
Give the closing hints by expanding the following (which, depending on the configured <ase-guidance-level/>, may each expand into nothing and hence emit no output at all):
<if condition="<getopt-option-commit/> is not equal `true`"> <ase-tpl-hint level="normal"> Use `/ase-repo-review` to review and `/ase-repo-commit` to craft the commit message of the staged selection. </ase-tpl-hint> </if> <ase-tpl-hint level="verbose"> Use `--merge` to keep already staged changes, `--worktree` to check the build in a temporary worktree, `--no-verify` to skip the check, and `--changelog`/`--commit` to chain into the ChangeLog and commit message skills. </ase-tpl-hint> </step>