git-workflow

Workflow identification, selection, and definition

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; when the GitFlow plugin is absent, use read-only Git observation and rule-by-rule verification. It does not depend on neighboring skill files or assume the host automatically loads other skills.

Prerequisites and authorization

• Git is available and the project directory is clear. First confirm the parent repository's true root and project instructions, and preserve user modifications.
• Existing specifications take precedence; no Git, no specification, detached, shallow history, and unknown origin must be explicitly reported.
• Read-only observation and preview may be performed; Git initialization, branch creation/switching, commits, pushes, integration, cleanup, hook installation, and rule activation are performed within the user's existing scope of authorization.
• Project rules and evidence is a self-contained reference for this skill;authoritative directory is used for model and source verification.

Execution steps

Step 1

First run read-only discovery, read existing contribution and release specifications; distinguish empty repository, existing history, and established team specifications.

Step 2

Ask about release methods, version maintenance, and PR/direct commit policies that materially affect the selection; naming conventions that can be inferred must be annotated as assumptions.

Step 3

Select one branch model based on the authoritative directory, then separately determine the shared/fork collaboration mapping; do not mechanically combine all models.

Step 4

Form a candidate JSON: roles with fixed name or pattern, required, allow_commit, create_from, merge_into, primary remote, and merge/message policy.

Step 5

Read the profiles templates within this skill; the template mainline defaults to main, protection policies and prefixes are project extensions, and adjust according to the confirmed contract.

Step 6

Provide the differences between old rules and new rules and incompatibilities with existing branches, prioritize preserving history and planning the transition, and do not migrate silently.

Step 7

When the plugin is available, init/activate default to preview; activate only after explicit authorization from the current user, then audit and gate. When the plugin is absent, state that the candidate has not yet been activated.

Standalone tools and plugin paths

First locate this skill's scripts/inspect_repository.py, and follow the contract to read status using the commands in it. Python 3.11+ standard library, read-only and does not initialize. Actual commands use the directory where this skill currently resides; a mount example is:

python3 /mnt/skills/user/git-workflow/scripts/inspect_repository.py /absolute/project

When the GitFlow plugin is available, invoke the command corresponding to its actual path; see operation examples. Do not treat a CLI name that is not installed as an existing command.

Verification and output

Output candidate rules, sources, differences, applicable scenarios, exceptions, and authorization boundaries. The closing fields of the profile JSON are described in this skill's references/policy.md.

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

An existing main+feature team selects github-flow, records that develop is unnecessary; selects a message format among candidates, then reviews and activates it.

Counterexamples

In a project with GitHub Flow history, defaulting to switching to develop, or directly editing allow_commit and then claiming it has been allowed.

Gotchas (situations prone to misjudgment)

• .git Even when it is a file, it may still be a valid work tree; first query Git/common-dir.
• Matching branch patterns does not prove correct provenance; manually created but lacking records should be listed separately as unknown.
• Remote tracking and protection configuration text cannot prove that the live remote has implemented it.
• Empty history for a new project does not pre-create false long-term refs; the initial commit must have an explicit bootstrap plan.
• For definition changes, review the active revision first; passing quality checks does not exempt branch rules.
• Steps already completed should not be blindly replayed due to timeout or no response; check Git status and operation logs first.

Exception Handling

Missing/drifted/corrupted rules, unclear identity, interrupted operations, or insufficient source evidence: stop the relevant write actions, report unverified and the specific information required, and continue with read-only work that can be completed independently. Clear naming/flow violations: deny and provide a preservative repair direction. Git unavailable or network failure: do not auto-install, and do not treat failure as success. Preserve the real state of conflicts and handle them according to recovery steps.

Optional Handoff

When other responsibilities are needed, call them by name; do not assume that 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.