/ase-repo-stage

name: ase-repo-stage
argument-hint: "[--help|-h] [--entry|-e] [--turn|-t] [--session|-s] [--merge|-m] [--no-verify|-V] [--worktree|-w] [--changelog|-c] [--commit|-C] [<topic>]"
description: >
    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,
    splitting hunks, check that the staged state builds on its own,
    and optionally chain into ChangeLog updating and commit message
    crafting. Use when the user calls to "stage" only a part of the
    changes, like "the hunks related to" a topic or "the last turn".
user-invocable: true
disable-model-invocation: false
effort: high
allowed-tools:
    - "Bash(git *)"
    - "Bash(find *)"
    - "Bash(ln -s *)"
    - "Bash(rm -f *)"
    - "Write"
    - "Read"
    - "Skill"

@${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/>"`.

<flow>

1. <step id="STEP 1: Determine Selection and Change Set">

1. 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 `true`, only output the following <template/> and then immediately *STOP*:

<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: options `--entry`, `--turn`, and `--session` are mutually exclusive </template>

2. Determine the *selection mode* <mode/>: set it to `entry`, `turn`, or `session` if the corresponding option is equal `true`. Otherwise, *infer* it from <topic/>: set it to `turn` if <topic/> refers to the changes of the last (or previous) turn, to `session` if it refers to all changes of the current session, to `entry` if it refers to the last ChangeLog entry, and in all these cases strip the referring words from <topic/>. Otherwise, set it to `topic`. An explicitly given option always *overrides* the inference, and a remaining non-empty <topic/> always *narrows* the modes `entry`, `turn`, and `session`.

If <mode/> is `topic` and <topic/> is empty, only output the following <template/> and then immediately *STOP*:

<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: no selection given -- neither a topic nor `--entry`, `--turn`, or `--session` </template>

Otherwise, set <selection/> to a brief rendering of <mode/> and <topic/> (like `topic "<topic/>"`, `last ChangeLog entry`, `last turn`, or `session, narrowed to "<topic/>"`) and only output the following <template/>:

<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ⇌ selection: **<selection/>** </template>

3. 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*:

`git rev-parse --show-toplevel`

<template> ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: no Git repository </template>

4. <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-only`

`git -C "<repo-root/>" -c core.quotepath=off diff --name-only`

If 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:

`git -C "<repo-root/>" reset -q` </if> <else> The selection is staged *on top* of the current index content, which hence stays untouched. Do not output anything. </else>

5. 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