# Stage

> Smart staging with auto-detected file blocks and interactive override. Use before /commit.

- Skill: `majiayu000/stage-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/stage-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/stage-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/stage-2

---


# Smart Stage

Stage files for commit using auto-detected logical blocks. The user picks which blocks to stage via interactive selection.

## Workflow

```
/stage -> /commit
```

## Step 1: Scan unstaged/untracked files

Run `git status` (never use `-uall` flag) to get the full picture of modified, deleted, and untracked files.

If there are no unstaged or untracked changes, inform the user and stop.

## Step 2: Auto-detect file blocks

Group related files into logical blocks based on these rules (applied in order of priority):

### The Commit Trio rule

Any block that contains a `.py` file under `swanki/` or `tests/` MUST also include:

1. The paired dendron note (`notes/<dendron-path>.md`) -- if it exists in the changed file list
2. The paired test file (`tests/.../<test_file>.py`) or source file -- if it exists in the changed file list
3. The current weekly note (`notes/user.mjvolk3.swanki.tasks.weekly.*.md`) -- always pulled into any block containing Python files

The weekly note appears in the FIRST Python block only (not duplicated across blocks). This enforces the project's atomic commit rule: source + note + weekly travel together.

### Block detection rules (in priority order)

1. **Python trio**: a `.py` source file + its `notes/<dendron-path>.md` + its `tests/` counterpart + the weekly note. Multiple related `.py` files in the same package can be grouped into one block (e.g., all files under `swanki/processing/`).
2. **Skill bundles**: all files under a `.claude/skills/<name>/` directory grouped together
3. **Config clusters**: related config files (e.g., `.pre-commit-config.yaml` + `pyproject.toml` when both have lint-related changes)
4. **Shell scripts + notes**: `.sh` files paired with their `notes/scripts.<name>.md` counterpart
5. **Standalone notes**: `notes/*.md` files not already paired with Python or shell files
6. **Other files**: anything not covered above (configs, docs, etc.)

A file should only appear in one block. If a file could fit multiple blocks, use the highest-priority rule.

## Step 3: Present blocks to user

Display numbered blocks with file lists. Mark the weekly note explicitly so the user sees it:

```
Detected file blocks:
[1] Processing package (4 files):
    swanki/processing/pdf_processor.py
    swanki/processing/image_processor.py
    notes/swanki.processing.pdf_processor.md
    notes/user.mjvolk3.swanki.tasks.weekly.2026.08.md  (weekly)
[2] Scripts: scripts/dendron-tree.sh
[3] Standalone notes: notes/scratch.2026.02.11.*.md (3 files)
```

## Step 4: User picks blocks

Use `AskUserQuestion` with `multiSelect: true` to let the user choose which blocks to stage. Options:

- Each detected block as a selectable option
- "All" to stage everything

## Step 5: Pre-stage reminders

Print reminders as informational text (not blocking):

- If selected files include `.py` under `swanki/` or `tests/`: "Python files detected. Consider running `/update-py-notes` and `/ruff` first."

## Step 6: Stage selected blocks

- Run `git add <files>` for chosen blocks (explicit file paths, never `git add -A` or `git add .`)
- Use `git rm` for deleted files
- Never stage `.env`, credentials, or secrets -- warn the user if detected

## Step 7: Confirm

Run `git diff --cached --name-status` to show what is now staged.

## Important Rules

- NEVER run `git add -A` or `git add .`
- NEVER stage `.env`, credentials, secrets, or similar sensitive files -- warn the user
- Use `git rm` for deleted files
- The user's tool approval prompt is the gate -- do NOT ask extra confirmation questions
- A file appears in exactly one block
- Do NOT ask extra approval questions -- tool approval prompts are the gates
- The weekly note is always included with the first Python block -- never staged alone as a separate block when Python files are present

## Example Invocations

- `/stage` -- interactive staging of all changes
- "stage my changes"
- "stage files for commit"