gitflow-workflow

Purpose

All detailed command manuals live under ./references/ and should be consulted when you need exact flags/options.

Required invariants (used by the 6 instruction-type skills)

Preflight

Before any start/finish operation:

• Confirm working tree is clean (use git status to verify).
• Identify current branch and verify the branch type matches the operation (feature/*, hotfix/*, release/*).
• Determine the active workflow preset (Classic GitFlow vs GitHub Flow vs GitLab Flow) to identify correct base/target branches.

Branch naming

• Use kebab-case and a strict prefix: <type>/<kebab-case> (e.g. feature/user-authentication).

Finish behavior

• Prefer non-fast-forward merges when finishing (e.g. --no-ff) to preserve a visible integration history, unless the repo workflow config says otherwise.
• Run tests if available before finishing; fix failures before merging.
• After finishing hotfix/release, ensure the integration branch receives the changes (often merging back into develop).
• Delete topic branches locally and remotely after finishing when policy allows.

Changelog generation

When updating CHANGELOG.md during finish-release or finish-hotfix operations, follow these principles:

Core principle: Include all commits that represent user-facing changes since the previous version tag. Exclude internal-only changes (build, CI, tooling) and administrative commits (merges, releases).

Note: The finish-feature operation updates the [Unreleased] section without filtering, as features are already user-facing by nature.

Commit collection process for releases and hotfixes:

1. Identify the previous version tag (e.g., v1.5.0)
2. Collect commits: git log --oneline <previous-tag>..HEAD
3. Filter commits using conventional commit format, applying the user-facing principle:
   • Include: Commits that affect end users, API consumers, or documented behavior (e.g., feat, fix, refactor, docs, perf, deprecate, remove, security)
   • Exclude: Internal tooling (chore, build, ci), test-only changes (test), merge commits, release commits
4. Map commit types to appropriate Keep a Changelog sections (Added, Changed, Deprecated, Removed, Fixed, Security)
5. Format entries using present/imperative tense and user-facing language
6. Merge repetitive items and include sufficient context to understand impact

See ${CLAUDE_PLUGIN_ROOT}/examples/changelog.md for the standard format.

Minimal templates (what the 6 skills assume)

The operation-specific templates have been moved into the corresponding start-* / finish-* skills to keep those tasks self-contained.

Reference index

• ./references/context-gathering.md
• ./references/naming-rules.md
• ./references/workflow-presets.md
• ./references/versioning-and-tags.md
• ./references/commands-core.md
• ./references/commands-topic.md

External References

• git-flow-next Documentation
• git-flow-next Commands
• git-flow-next Cheat Sheet