Smart Flow Tool

Intelligent Git Flow manager that auto-detects the appropriate workflow action based on repository state.

When to Use This Command

Run this command when you need to:

• Execute Git Flow operations without remembering specific sub-commands for each branch type
• Let the tool detect your current branch type and suggest the logical next action
• Manage complex Git Flow workflows with automatic state detection and guidance

Consider alternatives when:

• You want explicit control over every Git Flow step and prefer individual commands
• Your repository does not follow Git Flow conventions and uses a simpler branching model

Quick Start

Configuration

Copy
name: smart-flow-tool
type: command
category: git

Example Invocation

Copy
claude command:run smart-flow-tool --action auto

Example Output

Analyzing repository state...
  Current branch: feature/payment-gateway
  Branch type: feature
  Base: develop
  Commits ahead: 7
  Working tree: clean
  Tests: passing

Recommended action: FINISH
  This feature branch has 7 commits and all tests pass.
  Ready to merge back into develop.

Proceed with finish? [Y/n]
Merging feature/payment-gateway into develop... done.
Branch cleaned up successfully.

Core Concepts

Smart Detection Overview

Aspect	Details
Branch Detection	Identifies feature, release, hotfix, develop, or main from branch name prefix
State Analysis	Checks commit count, test status, merge readiness, and upstream sync state
Action Mapping	Maps branch type plus state to recommended action (start, finish, publish)
Interactive	Prompts for confirmation before executing destructive or merge operations
Fallback	Falls back to manual selection when auto-detection is ambiguous

Decision Workflow

Detect Branch Type
       |
       +-- feature/* --> Check tests + commits
       |                    |
       |              ready? --> FINISH
       |              not ready? --> CONTINUE
       |
       +-- release/* --> Check changelog + version
       |                    |
       |              tagged? --> FINISH
       |              not tagged? --> BUMP VERSION
       |
       +-- develop --> Suggest START feature or release
       |
       +-- main --> Suggest START hotfix if needed

Configuration

Parameter	Type	Default	Description
action	string	auto	Force action: start, finish, publish, or auto for detection
type	string	auto	Force branch type: feature, release, hotfix, or auto
name	string	(none)	Name for new branches when action is start
skip-tests	boolean	false	Skip test execution during state analysis
verbose	boolean	false	Show detailed reasoning for recommended action

Best Practices

1. Let auto-detection guide you - The tool is most valuable when you trust its recommendations. It analyzes repository state comprehensively and provides accurate suggestions based on branch conventions.

2. Use verbose mode for learning - When onboarding new team members, enable verbose mode so they can see why the tool recommends each action, building their Git Flow understanding organically.

3. Configure branch prefixes consistently - The auto-detection relies on conventional prefixes. Ensure your team uses feature/, release/, and hotfix/ consistently across all repositories.

4. Integrate with CI status - The tool checks local test results by default but configuring it to query your CI pipeline status provides more reliable readiness assessments.

5. Review before confirming - Always review the proposed action especially for finish operations that merge and delete branches. A moment of review prevents accidental data loss.

Common Issues

1. Branch type not detected - Non-standard branch names like wip/experiment are not recognized. Rename the branch to use a standard prefix or specify the type parameter manually.

2. Multiple actions seem appropriate - When the tool cannot decide between actions it prompts for manual selection. This typically happens on a feature branch with both merge-ready commits and uncommitted work.

3. Stale branch state after network changes - Run git fetch --all before invoking the tool to ensure branch tracking information is current for accurate recommendations.