Nf Git Workflow

nf-git-workflow

Install a project-scoped git workflow rule file that overrides the global "ask before every commit/push" safety rule for the current repo only. Stack-agnostic. The current branch at install time becomes the protected "head" that must stay safe.

Concept

• Head branch(es) = the current branch at install time by default; the user may add more protected branches during install. The first/current branch is the primary (used in command examples). All modes guarantee every head stays safe (no force-push, no hard reset, no direct unsanctioned writes).
• 3 modes of how work lands on head:
• worktree-pr — work in worktree/ → PR + auto-merge into head (safest)
• worktree-local-merge — work in worktree/ → local fast-forward merge into head → push
• direct-on-head — commit directly on head, no worktree, no PR (most permissive)
• A project may enable 1, 2, or all 3 modes. Multi-mode means the agent picks the best fit per task.

Invocation

• /nf-git-workflow — interactive multi-select picker
• /nf-git-workflow worktree-pr — install single mode
• /nf-git-workflow worktree-pr,direct-on-head — install multiple (comma or space separated)
• /nf-git-workflow all — install all 3 modes

Workflow

Phase 1: Preflight

Run scripts/install.sh preflight. Returns JSON {"ok": bool, "head_branch": "...", "error": "..."}.

• ok: false with error about not being a git repo → STOP, show error.
• ok: false with worktree error → STOP: tell user to run from the main checkout.
• ok: false with detached HEAD → STOP: ask user to check out a branch first.
• ok: true → save head_branch for use in later phases.

Phase 2: Resolve mode selection

Parse $ARGUMENTS:

• Empty → AskUserQuestion multiSelect. Present the 3 options in THIS order: direct-on-head (opt1), worktree-pr (opt2), worktree-local-merge (opt3). No default pre-selected. (This is display order only; the rendered file order is fixed by scripts/install.sh render.)
• all → all 3 modes.
• Comma-separated or space-separated names → split, trim, validate each. Unknown name → STOP with list of valid names (worktree-pr, worktree-local-merge, direct-on-head).

Save as MODES (array). Canonical ordering in the output file is enforced by scripts/install.sh render.

Phase 3: Resolve head branches

The current branch (head_branch from preflight) is the default protected head. A repo may protect MORE than one branch (e.g. both main and a long-lived develop/release).

• List local branches: git branch --format='%(refname:short)'.
• AskUserQuestion multiSelect, header "Head branches":
• Put the current branch FIRST, labelled "(Recommended)" — it becomes the primary head (used in command examples).
• Add the repo's other local branches as further options.
• Tell the user in the question text they may also use "Other" to type branch names not listed (including branches that don't exist yet, e.g. a planned release), comma-separated.
• When the repo has only the current branch (just 1 local branch), AskUserQuestion still needs ≥2 options — add a second option "Type other branch(es) via Other" whose description points the user at the "Other" free-text field.
• Collect every selected option + every typed name into HEAD_BRANCHES. Put the current/primary branch first, dedupe, preserve order.
• If $ARGUMENTS supplied modes non-interactively (Phase 2 did not open the picker), skip this question and set HEAD_BRANCHES to just the current branch — the user can re-run interactively to add more.

Join HEAD_BRANCHES with commas to form HEAD_BRANCHES_CSV for the write step.

Phase 4: Resolve output target

Do NOT ask — always write to .claude/rules/user-git-workflow.md at the repo root (created if missing). This is the fast default the user chose; no output-target question.

The user- filename prefix marks this as a personal, machine-local rule: it authorizes auto-commit/push behavior that overrides the user's global safety floor, so it must NOT be committed into the project repo. The nf-ignore convention gitignores **/.claude/rules/**/user-*, keeping this file out of the shared tree.

The ONE safety gate that remains (not friction — a data-loss guard): if .claude/rules/user-git-workflow.md already exists AND does NOT contain the install marker ``, it is a foreign hand-written file — warn it will be fully overwritten and ask to confirm or cancel. If the marker IS present, it is a prior install of this skill — overwrite silently (re-install, no question).

Phase 5: Render and write

Run scripts/install.sh write [mode2] [mode3].

Pass HEAD_BRANCHES_CSV as a single comma-separated argument (primary/current branch first). An empty string falls back to the detected current branch.

The script:

• Re-runs preflight internally to confirm state has not changed.
• Calls render to assemble assets/header.md + mode files in canonical order + assets/footer.md, substituting {{HEAD_BRANCH}} (the primary branch, used in command examples), {{HEAD_BRANCHES}} (the backticked list of all protected branches, used in prose), and {{INSTALL_DATE}}.
• Writes to `. For CLAUDE.md: wraps in ` markers; replaces existing block if present, else appends.
• Creates parent directories as needed.
• Reports written path.

Phase 6: Report

Print summary: path written, modes enabled, head branch(es) protected.

When the target was .claude/rules/user-git-workflow.md, verify the file is gitignored: run git check-ignore -q .claude/rules/user-git-workflow.md from repo root. If it is NOT ignored, warn the user that this personal auto-commit rule would otherwise be committed into the shared repo, and suggest running /nf-ignore (or adding .claude/rules/user-* to .gitignore).

Remind: reload the CC session so the new rule loads into the system prompt.

Rules

• NEVER install when cwd is inside a worktree — scripts/install.sh preflight detects this.
• NEVER install on detached HEAD — scripts/install.sh preflight detects this.
• NEVER overwrite an existing rule file silently — always confirm when the target exists without the install marker.
• NEVER fabricate mode names. Valid: worktree-pr, worktree-local-merge, direct-on-head.
• NEVER scan the project filesystem for CI/CD platform. The assets/footer.md SKIPCIBLOCK is static and platform-agnostic.
• ALWAYS use canonical mode order — scripts/install.sh render enforces this automatically.
• NEVER render a "dangerous paths" list. The philosophy is "all paths allowed, CI controlled via [skip ci]".

Resources

• scripts/install.sh — orchestrator with subcommands preflight | render | write . head_branches_csv = comma-separated protected branches, primary/current first.
• assets/header.md — HEADER block (always included; contains {{HEAD_BRANCH}}, {{HEAD_BRANCHES}}, and {{INSTALL_DATE}} placeholders)
• assets/mode-worktree-pr.md — MODE_SECTION for worktree-pr
• assets/mode-worktree-local-merge.md — MODE_SECTION for worktree-local-merge
• assets/mode-direct-on-head.md — MODE_SECTION for direct-on-head
• assets/footer.md — FOOTER block (always included; contains NOT-authorized floor + SKIPCIBLOCK). Prose references use {{HEAD_BRANCHES}}; mode command examples use {{HEAD_BRANCH}} (primary).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: llawliet11
• Source: llawliet11/claude-skills-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.