When to Use and When Not to Use
This skill is not intended to replace CodeGuard quality, platform protection, or deployment acceptance. It can be installed on its own; without the GitFlow plugin, use read-only Git observation and rule-by-rule verification. It does not depend on adjacent skill files or assume that the host automatically loads other skills.
Prerequisites and Authorization
- Git is available, and the project directory is clear. First confirm the real root of the parent repository and the project instructions, and preserve user modifications.
- Existing specifications take precedence; no Git, no specifications, detached, shallow history, and unknown origins must be explicitly reported.
- Read-only observation and preview may be performed; Git initialization, branch creation/switching, committing, pushing, integration, cleanup, Hook installation, and rule activation are performed within the scope of the user's existing authorization.
- Project Rules and Evidence is a self-contained reference for this skill;authoritative directory used for model and source verification.
Execution Steps
Step 1
Read the activated policy and discover the current repository/branch/HEAD and remote names; avoid outputting URLs containing credentials.
Step 2
Clarify the action, single source/target/ref, remote, and merge method. In fork mode, confirm the personal origin and authoritative upstream separately; the name itself does not authorize pushing.
Step 3
fetch also modifies tracking refs; default to preview; after clarifying the source, pull performs fetch+ff-only, and non-fast-forward is handed over to an explicit integration plan.
Step 4
For merge, check that the source's merge_into includes the current target role; for rebase, check create_from, and refuse to rewrite commits already contained in remote references.
Step 5
push is limited to same-name mappings and a single branch; force-push, deletion, mirror, and multi-ref operations are not automatically permitted and require a separate plan.
Step 6
Execute after obtaining authorization within scope; record Git identity before and after. Network timeouts may have already caused remote side effects; query the actual ref before deciding on recovery.
Step 7
Preserve the scene of conflicts and provide the actual branch and interruption markers. Clearly distinguish local refs, ls-remote observations, CI, and production.
Standalone Tool and Plugin Paths
First locate this skill's scripts/inspect_repository.py, and read the status according to the commands in the contract . Python 3.11+ standard library, read-only and no initialization. The actual command uses the directory where the current skill is located; a mount example is:
python3 /mnt/skills/user/git-sync/scripts/inspect_repository.py /absolute/project
When the GitFlow plugin is available, call the command corresponding to its actual path; see operation examples. Do not treat the name of a CLI that is not installed as an existing command.
Verification and Output
Pull defaults to ff-only; squash requires separate commit review, and the first version of the plugin refuses automatic squash integration rather than fabricating an approval.
Output must distinguish: facts, rule sources, recommendations, user authorization, and unverified items. After write operations, verify the current refs/HEAD/status; plans and previews are not evidence of completion. Security boundaries: do not leak credentials, do not upload the working tree; do not expose credentials, entire working tree contents, or sensitive remote URLs in logs.
Positive Examples
feature merged into develop: after switching to develop, clarify the source, preview, then merge; push origin develop is authorized separately.
Counterexamples
Omitting the target and then automatically pushing according to an untrusted upstream, or treating --force-with-lease as the default safe synchronization.
Gotchas (situations prone to misjudgment)
.gitWhen it is a file, it may still be a valid worktree; query Git/common-dir first.- Matching the branch pattern does not prove the source is correct; manually created but undocumented entries should be listed separately as unknown.
- Remote tracking and protection configuration text cannot prove that the live remote has implemented it.
- For a new project with empty history, do not pre-create false long-term refs; the initial commit must have a clear bootstrap plan.
- Before changing definitions, re-check the active revision; passing quality checks does not exempt branch rules.
- Do not blindly replay steps that have already completed due to a timeout with no response; check Git status and operation logs first.
Exception handling
Missing/drifted/corrupted rules, unknown identity, interrupted operations, or insufficient source evidence: stop the related write actions, report unverified and the specific information needed, and continue with read-only work that can be completed independently. Clear naming/flow violations: deny and provide a preservation-oriented fix direction. Git unavailable or network failure: do not auto-install, and do not treat failure as success. For conflicts, preserve the real state and handle them according to the recovery steps.
Optional handoff
When other responsibilities are needed, invoke them by name; do not assume that the skill is installed. For example, workflow selection can be handed off to git-workflow；Install: npx skills add full-stack-skills/git-skills --skill git-workflow. Any handoff must not expand the user's authorization.