diff --git a/.agents/skills/git-commit-ja/SKILL.md b/.agents/skills/git-commit-ja/SKILL.md index 92fd77e..4174fe0 100644 --- a/.agents/skills/git-commit-ja/SKILL.md +++ b/.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): 起動時警告を消すため非推奨オプションを削除 +``` diff --git a/.agents/skills/git-commit/SKILL.md b/.agents/skills/git-commit/SKILL.md index 7999417..526fc08 100644 --- a/.agents/skills/git-commit/SKILL.md +++ b/.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 ` 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 &&` 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 `: run every git command inside `` by prepending `cd &&` + 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 -``` +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 ` was also given, the push commands must run inside `` too — +`references/push.md` shows where to prepend `cd &&`. + +Read `references/push.md` for the exact branch/upstream checks and push commands. diff --git a/.agents/skills/git-commit/references/git-apply.md b/.agents/skills/git-commit/references/git-apply.md new file mode 100644 index 0000000..b0000e3 --- /dev/null +++ b/.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 -- | 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` (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. diff --git a/.agents/skills/git-commit/references/push.md b/.agents/skills/git-commit/references/push.md new file mode 100644 index 0000000..08f67d6 --- /dev/null +++ b/.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 `, prepend `cd &&` 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. diff --git a/.agents/skills/git-commit/references/revertable-commits.md b/.agents/skills/git-commit/references/revertable-commits.md new file mode 100644 index 0000000..538221b --- /dev/null +++ b/.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.