Logical Commits

Commit logical repository changes

This skill changes Git state. Confirm that committing is explicitly requested by the user or required by an active ExecPlan whose execution was requested.

1. Read the active ExecPlan state first when executing an ExecPlan. Determine the current functional slice and intended paths. Follow .agent/PLANS.md when a plan is present.

2. Inspect scoped changes:

   git status --short -- <task paths>
   git diff --stat -- <task paths>
   git diff -- <task paths>

   Inspect staged changes separately. Do not run destructive cleanup and do not include unrelated modifications.

3. Split changes by behavior or contract, not by file count. Suitable commit boundaries include:

   • one shared interface plus its focused tests;
   • one platform-family migration;
   • one dependency scaffold and its documentation;
   • one release-policy change and its idempotence tests;
   • one follow-up fix discovered by validation.

   Do not create a commit for formatting-only fragments that belong to the same functional change. Do not combine architecture, unrelated cleanup, generated artifacts, and documentation for another feature.

4. Before each commit, run the validate-headers skill and the smallest validation sufficient for that slice. Always run:

   git diff --check --cached

   Save verbose build output to a log and record only a compact summary.

5. Stage only intended paths:

   git add -- <paths>

   Review:

   git diff --cached --stat
   git diff --cached -- <paths>
   

6. Write an English commit message in the repository's Conventional-Commits-inspired format:

   <type>(<scope>): imperative description
   <type>(<scope>,<platform>): imperative description
   <type>!(<scope>[,<platform>]): imperative description
   <type>(<scope>[,<platform>])!: imperative description

   Use only these types: fix, feat, refactor, perf, style, test, docs, build, ci, chore, or revert. The scope is required and may contain letters, numbers, underscores, and hyphens. The optional platform must be lowercase and is the second qualifier. Architecture is not a title qualifier; mention it in the body instead.

   The title must be English, start with a lowercase letter, use the imperative mood, contain at least three words, be at most 80 characters, and not end with a period. If there is a body, separate it from the title with one blank line. Keep every body line at 80 characters or less; the CI check ignores Markdown link URLs when measuring body lines.

   For every non-trivial change, add a body that explains:

   • why the change is needed;
   • what behavior or contract changes;
   • platform, compatibility, artifact, or release impact;
   • focused validation completed and important deferrals.

   Example:

   refactor(build): centralize native target policy
   
   Resolve Android, Linux, and Windows platform settings from the shared
   native-build configuration so workflows and explicit target wrappers no
   longer repeat toolchain values.
   
   Keep minizip on Android API 24 while the default remains API 23. Validate
   configuration resolution and the zlib build-only workflow.

   For breaking changes, put ! in the title and add a BREAKING CHANGE: footer describing the compatibility impact. For revert commits, name the reverted commit hash or hashes in the body.

7. Before creating the commit, write the exact proposed message to a temporary file and validate that file with the repository's source-of-truth validator:

   python3 .github/scripts/validate-commit-message.py \
     --message-file <message-file>

   Resolve every reported body-line warning before committing, even though CI currently reports those lines as warnings rather than failures. This avoids creating a commit that immediately requires a follow-up formatting repair.

8. Create the commit from the same validated message file:

   git commit -F <message-file>

   Do not amend or rewrite history unless explicitly requested.

9. Validate the created commit with the same repository validator:

   python3 .github/scripts/validate-commit-message.py --commit HEAD

   Do not maintain a second inline implementation of commit-message rules in this skill. The standalone validator is the source of truth shared with CI.

10. Update the active ExecPlan state after the logical commit. Update the active plan only when this commit reaches a functional-family, architecture, ABI, release-policy, or milestone checkpoint.

11. Report the commit hash, subject, paths, focused validations, and any deferred expensive validation. Do not push unless explicitly requested.