@rse/ase 2.0.6 → 2.0.8

package/plugin/skills/ase-repo-changelog/help.md

@@ -15,7 +15,7 @@ The `ase-repo-changelog` skill helps to *complete*, *consolidate*, and
 file, based on the underlying *Git* commits and the currently staged
 changes in the Git *index*.
 
-Each entry is formatted as `<change-type> [<artifact-kind>]: <summary>`
+Each entry starts with `<change-type> [<artifact-kind>]: <summary>`
 where *change-type* is one of `FEATURE`, `IMPROVEMENT`, `BUGFIX`,
 `UPDATE`, `CLEANUP`, or `REFACTOR`, and *artifact-kind* is one or more
 comma-separated *artifact class* tags out of `spec`, `code`, `docs`,
@@ -23,6 +23,10 @@ comma-separated *artifact class* tags out of `spec`, `code`, `docs`,
 prefix. The date in the section header is also updated to the current
 date.
 
+The layout of the entries follows the style of the existing entries
+of the file (e.g. a single line, a title line plus an explaining body,
+or a wrapped sentence), and each entry is kept within about 5 lines.
+
 ##  SCENARIOS
 
 -   You want the `CHANGELOG.md` brought up to date with recent commits

package/plugin/skills/ase-repo-commit/SKILL.md

@@ -2,7 +2,10 @@
 name: ase-repo-commit
 argument-hint: "[--help|-h]"
 description: >
-    Determine commit message for staged Git changes.
+    Determine commit message for staged Git changes. Use when the user
+    asks to "give", "write", "craft", "suggest", or "propose" a "commit
+    message", or wants to know how to "describe" or "phrase" the staged
+    changes for a commit.
 user-invocable: true
 disable-model-invocation: false
 effort: medium

package/plugin/skills/ase-repo-dissect/help.md

@@ -123,4 +123,5 @@ Dissect the changes along an explicitly given axis:
 ##  SEE ALSO
 
 [`ase-task-dissect`](../ase-task-dissect/help.md), [`ase-repo-diff`](../ase-repo-diff/help.md), [`ase-repo-review`](../ase-repo-review/help.md),
-[`ase-repo-changelog`](../ase-repo-changelog/help.md), [`ase-repo-commit`](../ase-repo-commit/help.md).
+[`ase-repo-changelog`](../ase-repo-changelog/help.md), [`ase-repo-commit`](../ase-repo-commit/help.md),
+[`ase-repo-stage`](../ase-repo-stage/help.md).

package/plugin/skills/ase-repo-stage/SKILL.md

@@ -0,0 +1,459 @@
+---
+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 --others --exclude-standard`
+
+        Set <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/>"`
+
+    6.  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`
+
+        `git -C "<repo-root/>" diff --numstat`
+
+        <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>
+
+    </step>
+
+2.  <step id="STEP 2: Select Changes">
+
+    1.  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/>.
+
+        -   `entry`: the changes which realize the *last* ChangeLog
+            entry, i.e. the entry added or modified by the *uncommitted*
+            change of the `CHANGELOG.md` file 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 uncommitted `CHANGELOG.md` entry found
+            </template>
+
+        -   `turn` resp. `session`: the changes made by your *own*
+            file-modifying tool calls (like `Edit` and `Write`) 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*:
+
+            <template>
+            ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ▶ ERROR: no changes of the <mode/> found in the conversation context
+            </template>
+
+        For the modes `entry`, `turn`, and `session`, a non-empty
+        <topic/> additionally *narrows* the selected changes to those
+        which semantically belong to <topic/>.
+
+    2.  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.
+
+    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>
+
+3.  <step id="STEP 3: Stage Changes">
+
+    1.  Set <tmp-dir/> to the value of the `TMPDIR` environment variable
+        if it is known in the current session context, and to `/tmp`
+        otherwise. Do not output anything.
+
+    2.  Assemble <patch/> from <diff/>: keep the complete `diff --git`
+        file 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 of `git 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 `--recount` fixes 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.
+
+    3.  Use the `Write` tool 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):
+
+        `git -C "<repo-root/>" apply --cached --recount --whitespace=nowarn "<tmp-dir/>/ase-stage.patch"`
+
+        <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>
+
+    4.  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"`
+
+    5.  Only output the following <template/>, with one `○` line per
+        staged file and an ultra brief <summary/> of its staged changes:
+
+        <template>
+        ○   `<file/>`: <summary/>
+        [...]
+        ⧉ **ASE**: ✪ skill: **ase-repo-stage**, ✚ staged: **<n-files/>** files, **<n-hunks/>** hunks (**<n-split/>** split), ▶ status: **selection staged**
+        </template>
+
+    </step>
+
+4.  <step id="STEP 4: Verify Staged State"
+        condition="<getopt-option-no-verify/> is not equal `true`">
+
+    1.  Determine the *build command* <build/> of the project: prefer
+        the command the project-level AI guidance files (`AGENTS.md`,
+        `CLAUDE.md`, or similar) name for building, else derive it from
+        the build configuration (like the `build` script of
+        `package.json`, the default target of a `Makefile`, or the
+        native build command of the language). Prefer a *single*
+        top-level command which builds and type-checks the *entire*
+        project.
+
+        <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>
+
+    2.  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/>" HEAD`
+
+            `git -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_modules` directory, found via `find
+            "<repo-root/>" -name node_modules -type d -prune -not -path
+            "*/.ase/*"`) into the same relative location of <check-dir/>
+            via `ln -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/>"`
+
+            `rm -f "<tmp-dir/>/ase-stage-check.patch"`
+            </elseif>
+
+        -   <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/stash`
+
+            `git -C "<repo-root/>" stash push -q --keep-index --include-untracked -m "ase-repo-stage"`
+
+            `git -C "<repo-root/>" rev-parse -q --verify refs/stash`
+
+            If 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 --hard`
+
+            `git -C "<repo-root/>" stash pop -q --index`
+
+            If the `git stash pop` command fails, only output the
+            following <template/> and then immediately *STOP*:
+
+            <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>
+
+    3.  <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>
+
+5.  <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">
+
+    1.  <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>
+
+    2.  <if condition="<getopt-option-commit/> is equal `true`">
+        Invoke the commit message crafting for the staged selection:
+
+        <skill name="ase:ase-repo-commit"/>
+        </if>
+
+    </step>
+
+6.  <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>
+
+</flow>
+

package/plugin/skills/ase-repo-stage/help.md

@@ -0,0 +1,120 @@
+
+##  NAME
+
+`ase-repo-stage` - Stage a Part of the Changes
+
+##  SYNOPSIS
+
+`ase-repo-stage`
+    [`--help`|`-h`]
+    [`--entry`|`-e`]
+    [`--turn`|`-t`]
+    [`--session`|`-s`]
+    [`--merge`|`-m`]
+    [`--no-verify`|`-V`]
+    [`--worktree`|`-w`]
+    [`--changelog`|`-c`]
+    [`--commit`|`-C`]
+    [*topic*]
+
+##  DESCRIPTION
+
+The `ase-repo-stage` skill stages only the *part* of the current Git working copy changes which
+belongs to a *selection*, so a mixed change set can be committed in cohesive portions without
+hand-crafted partial patches.
+
+The selection is either a free-text *topic*, the *last* `CHANGELOG.md` entry (`--entry`), the
+changes of the *last turn* (`--turn`), or all changes of the current *session* (`--session`).
+Without an option, the selection is inferred from the *topic* text, so `stage the last turn`
+works, too. An explicitly given option overrides the inference, and a remaining *topic* narrows
+the entry, turn, and session selections.
+
+The changes are picked at the granularity of individual *lines*: hunks which belong to the
+selection only partially are *split*, and untracked files are selectable, even partially.
+Mutually dependent changes, like a use and its import, are kept together. Unless `--merge` is
+given, the selection *replaces* the current index content. Only the Git index is changed, never
+the content of a working copy file.
+
+After staging, the skill checks that the *staged state alone builds*, with the build command
+auto-detected from the project. By default, the remaining unstaged changes are temporarily
+stashed for this, or -- under `--worktree` -- the staged state is built in a temporary worktree.
+A failed build keeps the staged selection and is reported with its essential error lines.
+
+Finally, the skill optionally chains into the ChangeLog updating and the commit message
+crafting, both for the staged selection.
+
+##  OPTIONS
+
+-   `--entry`|`-e`:
+    Select the changes which realize the *last* `CHANGELOG.md` entry, i.e. the entry added or
+    modified by the uncommitted change of `CHANGELOG.md`, plus the entry itself.
+
+-   `--turn`|`-t`:
+    Select the changes made by the agent in the *last turn* before the skill invocation.
+
+-   `--session`|`-s`:
+    Select all changes made by the agent in the current *session*.
+
+-   `--merge`|`-m`:
+    Stage the selection *on top* of the already staged changes, instead of replacing them.
+
+-   `--no-verify`|`-V`:
+    Skip the check that the staged state builds on its own.
+
+-   `--worktree`|`-w`:
+    Check the build in a *temporary Git worktree* holding only the staged state, instead of
+    temporarily stashing the unstaged changes of the working copy.
+
+-   `--changelog`|`-c`:
+    Afterwards, update the `CHANGELOG.md` entries via `ase-repo-changelog` and stage exactly the
+    entries it added or updated.
+
+-   `--commit`|`-C`:
+    Afterwards, craft the commit message of the staged selection via `ase-repo-commit`.
+
+The options `--entry`, `--turn`, and `--session` are mutually exclusive.
+
+##  ARGUMENTS
+
+-   *topic*:
+    A free-text description of the changes to stage, or -- without an option -- a reference
+    like `last turn` or `last changelog entry` the selection is inferred from.
+
+##  SCENARIOS
+
+-   You want only the hunks related to a certain topic staged
+-   You want only the changes of the last turn or of the session staged
+-   You want the changes behind a `CHANGELOG.md` entry staged and committed
+-   You want to be sure the staged part builds without the rest of the changes
+
+##  EXAMPLES
+
+Stage only the hunks related to a topic:
+
+```text
+❯ /ase-repo-stage the getopt negation handling
+```
+
+Stage the changes of the last turn, checking the build in a temporary worktree:
+
+```text
+❯ /ase-repo-stage --turn --worktree
+```
+
+Stage the changes of the last ChangeLog entry and craft its commit message:
+
+```text
+❯ /ase-repo-stage --entry --commit
+```
+
+Add the session changes related to a topic to the already staged ones:
+
+```text
+❯ /ase-repo-stage --session --merge task board
+```
+
+##  SEE ALSO
+
+[`ase-repo-dissect`](../ase-repo-dissect/help.md), [`ase-repo-diff`](../ase-repo-diff/help.md),
+[`ase-repo-review`](../ase-repo-review/help.md), [`ase-repo-commit`](../ase-repo-commit/help.md),
+[`ase-repo-changelog`](../ase-repo-changelog/help.md).