feat(git-commit): ryoppippi版のreferences/とrevertability哲学を取り込みフッターを中立化 (#154)

Author: nkoji21

.agents/skills/git-commit-ja/SKILL.md

@@ -5,6 +5,24 @@ user-invocable: true
 allowed-tools: Bash, Skill
 ---
 
-Use /git-commit to perform the commit, but write the commit message description **in Japanese**.
+Use `/git-commit` to perform the commit (granularity, revertability, `git apply`
+staging, and references all apply unchanged). It also forwards any `--path` /
+`--push` arguments. The reference docs live under
+`.agents/skills/git-commit/references/` (this skill has none of its own).
 
-Example: `fix(alacritty): 起動時警告を消すため非推奨オプションを削除`
+## Language override (this skill takes precedence)
+
+`/git-commit` instructs English commit messages. When this skill runs, **the
+following language rules override that** — re-confirm them right before writing each
+message:
+
+- **type**: English Conventional Commits type (`feat`, `fix`, `docs`, `refactor`,
+  `chore`, …).
+- **scope**: English (e.g. `alacritty`, `vim`, `git`).
+- **description**: 日本語で書く。What だけでなく Why を簡潔に。
+
+Example:
+
+```
+fix(alacritty): 起動時警告を消すため非推奨オプションを削除
+```

.agents/skills/git-commit/SKILL.md

@@ -5,7 +5,8 @@ user-invocable: true
 allowed-tools: Bash
 ---
 
-Review current changes and autonomously commit following Conventional Commits.
+Review current changes and autonomously create fine-grained, independently
+revertable commits following Conventional Commits.
 
 **Working tree status (source repo):**
 ```
@@ -19,32 +20,53 @@ Review current changes and autonomously commit following Conventional Commits.
 
 ## Arguments
 
-If a `--path <dir>` argument is provided (e.g. invoked as `git-commit --path /tmp/feat-foo`), all git commands must be run inside that directory by prepending `cd <dir> &&` to every Bash command. This overrides the current working directory.
-
-1. Run `git status`, `git diff`, and `git log --oneline -5` to understand the changes and context
-2. Decide the commit message autonomously
-3. Stage and commit using `git apply` (see below)
-
-## Principle
-- Write **Why** in the subject line itself — keep it concise but meaningful.
-- Body is optional. If you feel a body is necessary, the commit is likely too large — consider splitting it.
-- Footer (Co-Authored-By) is always required.
-- Each commit must be **independently revertable** without breaking other functionality.
+- `--path <dir>`: run every git command inside `<dir>` by prepending `cd <dir> &&`
+  to each Bash command. This overrides the current working directory (e.g. invoked
+  as `git-commit --path /tmp/feat-foo`).
+- `--push`: push to remote after all commits are complete (default: off). See the
+  **Push** section below.
+
+1. Run `git status`, `git diff HEAD`, and `git log --oneline -10` to understand the
+   changes and context
+2. Decide commit boundaries and messages autonomously
+3. Stage and commit each unit using `git apply --cached` (see below)
+
+## Core Philosophy — Revertability First
+
+Each commit must be **revertable independently** without breaking other
+functionality. Prefer smaller, granular commits over large groupings — split by
+hunks within files, not just whole files.
+
+- **Tiny commits are expected.** A single review comment, one wording correction,
+  one reference-file extraction, one symlink sync, or one formatting pass can each
+  be its own commit when independently revertable. PR branches are squash-merged
+  later, so don't worry about granularity being too fine.
+- **Tiny does not mean incomplete.** For moves, renames, or extractions, one commit
+  must include *both* sides: remove/update the old location, add the new location,
+  update references, and sync generated links. Never commit only the destination of
+  a move while leaving the source/reference cleanup for later.
+- **Don't `--amend` away review history.** PR branches are squash-merged, so keep
+  review fixes as small follow-up commits that can be reverted independently. Amend
+  only for unpublished local mistakes or when the user explicitly asks.
+
+For concrete good and bad examples, read `references/revertable-commits.md`.
 
 ## Commit Granularity
 - 1 commit = 1 logical change
 - Examine individual hunks, not entire files — split if needed
 - Separate refactoring and feature additions
 - Tests can be in the same commit as the main code
-- Formatting-only changes should be separate
+- Formatting-only changes should be separate (`chore(xxx): format` or `chore: format`)
 
 ## Staging with git apply
 
-Never use interactive commands like `git add -p`. Instead:
+Never use interactive commands like `git add -p` or `git add --interactive` —
+Claude Code cannot handle them. Instead:
 
 ```bash
-# 1. Generate patch for the target changes
-git diff > patch.diff
+# 1. Generate patch for the target changes (HEAD-relative so already-staged
+#    hunks and new files from a prior iteration are not lost)
+git diff HEAD > patch.diff
 
 # 2. Verify before applying (no file changes on failure)
 git apply --cached --check patch.diff
@@ -53,11 +75,16 @@ git apply --cached --check patch.diff
 git apply --cached patch.diff
 ```
 
+When a patch fails, needs whitespace handling, or must be staged without touching
+unrelated hunks, read `references/git-apply.md`.
+
 ## Commit Message Format
 Conventional Commits v1.0.0
 
 Format: `type(scope): description`
-- scope: optional (e.g., `alacritty`, `vim`, `git`)
+- **type**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`,
+  `ci`, `chore`, `revert`
+- **scope**: optional (e.g., `alacritty`, `vim`, `git`)
 - **description: in English** — convey Why, not just What, but keep it short
 
 Examples:
@@ -69,7 +96,31 @@ fix(git): remove deprecated option
 fix(git): remove deprecated option to prevent startup warning
 ```
 
-Required footer:
-```
-Co-Authored-By: Claude <noreply@anthropic.com>
-```
+Body is optional. Add one only to explain Why or revertability when the subject
+alone is insufficient. If a body is needed just to enumerate *what* changed, the
+commit is likely too large — consider splitting it.
+
+Do not add a `Co-Authored-By` or any agent-identifying footer. This skill is shared
+across Claude / Codex / Cursor, so hardcoding a single agent name would mislabel
+commits made by the others.
+
+## Quality Checks
+- Can this be reverted without breaking other functionality?
+- Is this the smallest logical unit?
+- Does the message clearly explain the change (Why)?
+- Does it match the project's commit patterns, scopes, and style?
+- No debugging statements or commented-out code without explanation
+
+## Push (only if `--push`)
+
+After all commits are complete, push to remote. Let repository git hooks run; if a
+pre-commit or pre-push hook runs format, sync, lint, typecheck, or tests, treat
+those as part of the normal validation path and fix any failures in a new small
+commit.
+
+Never push to `main`/`master` directly — create a feature branch first.
+
+If `--path <dir>` was also given, the push commands must run inside `<dir>` too —
+`references/push.md` shows where to prepend `cd <dir> &&`.
+
+Read `references/push.md` for the exact branch/upstream checks and push commands.

.agents/skills/git-commit/references/git-apply.md

@@ -0,0 +1,69 @@
+# Git Apply Reference
+
+This skill stages patches **without touching the worktree**, so every command here
+uses `--cached` by default. Drop `--cached` only when you deliberately want to apply
+to the working tree instead of the index.
+
+## Basic Usage
+
+```bash
+# Always verify first before staging (no changes on failure)
+git apply --cached --check patch_file.patch
+
+# Stage with verbose output for debugging
+git apply --cached -v patch_file.patch
+
+# Stage a diff generated between refs
+git diff main...HEAD -- <file> | git apply --cached -v
+```
+
+## Essential Flags
+
+- `-v, --verbose`: always use this for detailed feedback during application.
+- `--check`: verify whether a patch can be applied cleanly without making changes.
+- `--cached`: stage the patch without applying it to the worktree.
+- `--stat`: display affected files before applying.
+- `--whitespace=fix`: automatically correct trailing whitespace issues.
+- `--reject`: create `.rej` files for failed sections instead of aborting entirely.
+- `--reverse` / `-R`: revert a previously applied patch.
+
+## Troubleshooting Failed Applies
+
+Trailing whitespace:
+
+```bash
+git apply --cached --check --whitespace=fix patch_file.patch
+git apply --cached --whitespace=fix -v patch_file.patch
+```
+
+Partial failures (write `.rej` files for the hunks that don't apply):
+
+```bash
+git apply --cached --reject -v patch_file.patch
+```
+
+Context mismatch — the surrounding lines in the file no longer match the patch
+context (line offsets / fuzz). Prefer a three-way merge, which uses the blob the
+patch was based on:
+
+```bash
+git apply --cached --3way -v patch_file.patch
+```
+
+If `--3way` is not viable, loosen the required context lines with `-C<n>` (e.g.
+`-C1`). Note: `--ignore-whitespace` only helps when the *only* difference in the
+context is whitespace — it does not fix genuine line-offset mismatches.
+
+Line ending issues:
+
+```bash
+git apply --cached --ignore-space-change -v patch_file.patch
+```
+
+## Git Apply vs Git Am
+
+- `git apply`: applies or stages changes without creating commits.
+- `git am`: applies patches with commit messages and author info preserved.
+
+Use `git apply --cached -v` for this workflow to keep commit creation explicit and
+controlled.

.agents/skills/git-commit/references/push.md

@@ -0,0 +1,42 @@
+# Push Reference
+
+Run in `sh`/`zsh` (this repo's shell). Do NOT use fish syntax.
+
+When invoked with `--path <dir>`, prepend `cd <dir> &&` to every command below so
+the push targets that repository, not the current working directory.
+
+## 1. Check the current branch before any push
+
+```bash
+current_branch=$(git branch --show-current)
+if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then
+  echo "On $current_branch — stop. Create a feature branch before pushing."
+  exit 1
+fi
+```
+
+If the current branch is `main` or `master`, stop and create a feature branch
+before pushing. The `exit 1` above guarantees execution halts instead of falling
+through to the push step.
+
+## 2. Check if the branch has an upstream
+
+```bash
+git rev-parse --abbrev-ref --symbolic-full-name '@{u}'
+```
+
+- **If this succeeds** (an upstream exists), push directly:
+
+  ```bash
+  git push
+  ```
+
+- **If this fails** (no upstream), ask the user whether to set upstream and push:
+  - If yes: `git push -u origin HEAD`
+  - If no: skip pushing.
+
+## 3. Hooks
+
+Let repository git hooks run. If a pre-push hook runs format, sync, lint,
+typecheck, or tests and one fails, fix it in a new small commit and push again —
+treat hook failures as part of the normal validation path, not as errors to bypass.

.agents/skills/git-commit/references/revertable-commits.md

@@ -0,0 +1,62 @@
+# Revertable Commit Examples
+
+## Good: split independent implementation steps
+
+```text
+feat(auth): add RefreshTokenService class
+
+Added RefreshTokenService to handle token lifecycle management.
+This service generates and invalidates refresh tokens with
+configurable expiry periods.
+```
+
+```text
+feat(auth): integrate token rotation in middleware
+
+Updated auth middleware to call RefreshTokenService when validating
+tokens. This can be reverted independently without removing the
+service itself.
+```
+
+## Good: keep both sides of a move together
+
+One commit contains:
+
+- `A .agents/skills/tdd/references/vitest-examples.md`
+- `M .agents/skills/tdd/SKILL.md`
+- `D .agents/skills/tdd/vitest-example.md`
+
+The commit is still small, but it is complete: the old path is removed, the new
+path is added, and every reference points to the new path.
+
+## Bad: split one move across incomplete commits
+
+First commit:
+
+- `A .agents/skills/tdd/references/vitest-examples.md`
+
+Second commit:
+
+- `M .agents/skills/tdd/SKILL.md`
+- `D .agents/skills/tdd/vitest-example.md`
+
+The first commit is not independently revertable because it leaves duplicate or
+unreachable guidance until the second commit lands.
+
+## Good: one review comment per commit
+
+If a reviewer says "run format before typecheck/test", one commit can update only
+that workflow wording and the matching always-on reminder. Keep unrelated examples,
+source docs, and typo fixes for separate commits.
+
+## Bad: tidy broad commit
+
+Avoid a commit that mixes:
+
+- PR review workflow changes
+- TypeScript assertion guidance
+- OpenCode data-source corrections
+- Markdown fence formatting
+- Generated symlink sync
+
+Even if each change is correct, reverting one concern would revert unrelated work.