Feature Flow

---
name: feature-flow
description: Complete git workflow orchestration (GitHub/GitLab/Forgejo) - branch, issue, commit
argument-hint: "[context | #issue-number] [--skip-branch] [--skip-issue] [--skip-mr] [--squash] [--msg \"text\"] [--dry-run] [--force]"
user-invocable: true
disable-model-invocation: true
allowed-tools: Read, Write, Edit, Grep, Glob, Skill, Bash(git:*), Bash(make:*), Bash(npm:*), Bash(npx:*), Bash(go:*), Bash(python:*), Bash(cargo:*), Bash(task:*), Bash(golangci-lint:*), Bash(eslint:*), Bash(ruff:*), Bash(mypy:*), Bash(auto-mr:*), Bash(gh:*), Bash(glab:*), Bash(fgj:*), Bash(jq:*), AskUserQuestion
---

# Feature Flow

Orchestrate a complete git workflow for feature development. Two modes:

1. **Staged Changes Mode** (default): Analyze staged changes → branch → create issue → commit
2. **Issue Mode** (`#<number>`): Retrieve issue → **validate relevance** → branch → implement → lint → test → verify → commit → merge

Automates repetitive workflow setup (branching, issues, commits, quality checks, merge requests).

## Mode Detection

**Route based on `$argument`:** first positional argument matching `#<number>` or bare `<number>` → **Issue Mode**; otherwise → **Staged Changes Mode**.

Issue Mode examples: `/feature-flow #42`, `/feature-flow 42 --squash`
Staged Mode examples: `/feature-flow`, `/feature-flow add user auth`, `/feature-flow --skip-issue`

## Staged Changes Mode (5 Phases)

### Phase 1: Discovery & Validation (Automatic)

**Execute parallel git commands:** `git status` and `git diff --staged`

**Detect Repository Host**: Use the `detect-repo-host` skill to identify the hosting service (GitHub, GitLab, or Forgejo) and extract owner/repo details.

**Analysis steps:**
1. **Analyze staged changes:**
   - Extract file paths, extensions, and types
   - Determine change type: new files → `feat`, test+fixes → `fix`, docs only → `docs`, structural → `refactor`, build/config → `chore`
   - Extract primary scope from directory (e.g., `src/api/` → `api`, `internal/auth/` → `auth`)

2. **Generate proposed branch name:**
   - Format: `<type>/<scope>-<description>` (kebab-case, 2-4 words)
   - Types: feat, fix, refactor, docs, chore, test, perf, ci
   - Examples: `feat/api-user-profile`, `fix/auth-jwt-validation`, `docs/readme-update`

**Error handling:**
- No staged changes → Abort: "No staged changes found. Stage files with 'git add' first."
- Repository host detection fails → The `detect-repo-host` skill provides detailed error messages

### Phase 2: Branch Creation (User Confirmation)

**Parse flags:** `--skip-branch` or `-b` → skip this phase.

**If not skipped:**

1. Check current branch: `git rev-parse --abbrev-ref HEAD`
2. Display proposed branch name
3. Ask confirmation via AskUserQuestion: "Create branch '<proposed-name>'?" with options: "Yes, create this branch", "Use different name", "Skip branch creation"
4. Handle response:
   - "Yes, create": `git checkout -b <branch-name>`, verify
   - "Use different name": Ask for custom name, then create
   - "Skip": Continue on current branch

**Error handling:**
- Branch exists → Suggest `<name>-v2` or ask for alternative
- Git error → Display error, abort

### Phase 3: Issue Creation (User Confirmation)

**Parse flags:** `--skip-issue` or `-i` → skip this phase.

**If not skipped:**

1. **List available labels** (same pattern as `/create-issue` skill):
   - GitHub: `gh label list --repo <owner>/<repo>`
   - GitLab: `glab label list`
   - Forgejo: `fgj label list -R <owner>/<repo>`

2. **Generate issue content** following `/create-issue` conventions:
   - Title: under 80 chars, imperative mood, based on change type and scope
   - Description: Overview + Changes list + Testing section + Branch reference
   - Labels: map type to labels (`feat`→enhancement, `fix`→bug, `docs`→documentation, etc.), validate against available labels

3. Display preview, ask confirmation: "Create issue with this content?" → "Yes, create issue" / "Skip issue creation"

4. Create issue if approved:
   - GitHub: `gh issue create --repo <owner>/<repo> --title "<title>" --body "<body>" --label "<label1>" --label "<label2>" --assignee @me`
   - GitLab: `glab issue create --title "<title>" --description "<body>" --label "<label1>" --label "<label2>" --assignee "$(glab api user | jq -r '.username')"`
   - Forgejo: `fgj issue create -R <owner>/<repo> -t "<title>" -b "<body>" -l <label1> -l <label2>` (no assignee flag — `fgj` does not yet support issue assignment, so omit self-assign)
   - Parse issue number from command output; store for Phase 4

**Error handling:**
- `gh`/`glab`/`fgj` CLI not installed → Skip issue creation, warn, continue to commit
- Invalid labels → Remove silently, warn user
- Issue creation fails → Log error, continue to Phase 4 without issue reference

### Phase 4: Commit Execution (User Confirmation)

**Generate conventional commit message** following `/commit` skill format (see `commit.md` for full spec):
- Type from branch name or change analysis
- Scope from primary directory
- Description: imperative mood, lowercase, under 50 chars, no period
- Body: bullet points for multi-file changes
- Footer: `Closes #<issue-number>` (always use `Closes`, not `Refs`, when an issue was created in Phase 3)
- **CRITICAL**: NO Claude Code attribution (per the `commit` skill's no-attribution policy)

**Display preview, ask confirmation:** "Commit with this message?" → "Yes, commit now" / "Edit message" / "Cancel workflow"

**Execute:** `git commit -m "<message>"`, verify with `git log -1 --oneline`.

**Error handling:**
- Pre-commit hook fails → Display error, abort, provide recovery steps
- Commit fails → Display git error, abort

### Phase 5: Summary & Next Steps (Automatic)

Display workflow summary showing completed steps (branch created, issue created, commit hash) and next steps: push branch, create PR/MR, continue development.

## Issue Mode Process (8 Phases)

### Phase I-1: Issue Retrieval & Relevance Check

**Detect Repository Host**: Use the `detect-repo-host` skill.

**Get current branch:** `git rev-parse --abbrev-ref HEAD`

**Fetch issue details:**
- GitHub: `gh issue view <number> --repo <owner>/<repo> --json title,body,labels`
- GitLab: `glab issue view <number>`
- Forgejo: `fgj issue view <number> -R <owner>/<repo> --json`

**Extract:** Title (→ branch name, commit, MR title), Body (→ implementation spec), Labels (→ type detection)

**Validate the issue is still relevant (ESSENTIAL — never skip):**

The codebase may have changed since the issue was opened, so the issue may already be resolved or no longer applicable. Before doing any work, confirm it still holds:

1. Locate the code the issue refers to (Glob/Grep/Read for the files, symbols, or behavior named in the title/body).
2. Verify against the **current** code:
   - **Bug / fix:** does the faulty code still exist and the bug still reproduce?
   - **Feature / enhancement:** is it still missing, or already implemented?
   - **Refactor / docs / chore:** does the targeted code still exist in the form the issue describes?
3. **If still relevant →** continue to Phase I-2.
4. **If already resolved, partially done, or no longer applicable →** STOP, report the findings with evidence (`file:line`), then ask via AskUserQuestion: "Proceed anyway" / "Adjust scope to remaining work" / "Abort" (optionally comment on or close the issue).

This check is read-only and always runs, including under `--dry-run` and `--force`. In `--force` mode, run the check and auto-proceed when the issue is still valid; if it is clearly already resolved, abort with the evidence instead of implementing redundant changes.

**Error handling:**
- Issue not found → Abort: "Issue #N not found in <owner/repo>."
- `gh`/`glab`/`fgj` CLI not installed → Abort: "Cannot retrieve issue. Install `gh` (GitHub), `glab` (GitLab), or `fgj` (Forgejo) CLI first."

### Phase I-2: Branch Creation (User Confirmation)

**Parse flags:** `--skip-branch` or `-b` → skip this phase.

**If not skipped:**

1. **Derive branch type from labels:**

   | Label contains | Type |
   |----------------|------|
   | bug, bugfix, fix | `fix` |
   | enhancement, feature | `feat` |
   | documentation, docs | `docs` |
   | refactor | `refactor` |
   | test | `test` |
   | ci, ci-cd | `ci` |
   | performance | `perf` |
   | *(no match)* | `feat` |

2. **Generate branch name:** `<type>/<scope>-issue-<N>` (scope from issue title, kebab-case)

3. Ask confirmation via AskUserQuestion, handle response same as Phase 2.

**Error handling:** Same as Phase 2 (branch exists → suggest alternative, git error → abort).

### Phase I-3: AI Implementation (User Confirmation)

1. Read issue body as specification; parse requirements and target files
2. Analyze project structure using Glob/Read to find relevant files and conventions
3. Implement solution using Write/Edit; follow existing code style; include tests if module has them
4. Display change summary (files created/modified)
5. Ask confirmation: "Implementation complete. Review changes and continue?" → "Yes, continue to lint & test" / "Make adjustments" / "Cancel workflow"

### Phase I-4: Lint (Automatic)

**Use the `run-lint` skill** to auto-detect and execute the project linter. If lint fails, ask user whether to continue.

### Phase I-5: Test (Automatic)

**Use the `run-tests` skill** to auto-detect and execute the project test runner. If tests fail, ask user whether to continue.

### Phase I-6: Verification (User Confirmation)

1. Re-run lint and tests to confirm clean
2. Display `git diff --stat` summary
3. Show pass/fail gate: Lint ✓/✗, Tests ✓/✗, file stats
4. Ask confirmation: "Verification complete. Proceed to commit?" → "Yes, commit changes" / "Go back and fix issues" / "Cancel workflow"

### Phase I-7: Commit (User Confirmation)

1. Stage implementation files: `git add <files from Phase I-3>` (only created/modified files)
2. Generate conventional commit per Phase 4 format, with: type from Phase I-2, scope from issue, footer `Closes #<N>`
3. **CRITICAL**: NO Claude Code attribution
4. Display preview, ask confirmation, execute commit, verify with `git log -1 --oneline`

**Error handling:** Pre-commit hook fails → abort with recovery steps; commit fails → abort.

**On successful commit:** Immediately proceed to Phase I-8.

### Phase I-8: Merge via auto-mr (User Confirmation, Skippable)

**Parse flags:** `--skip-mr` → skip this phase.

**Build command:** `auto-mr [--msg "<message>"]`
- `auto-mr` squashes by default; there is no `--squash` flag to forward. `--squash`/`-s` is a no-op kept for backward compatibility.
- `--msg`: default `<type>(<scope>): <issue-title> (Closes #<N>)`, override with user's `--msg`

**Pre-flight (run before asking):**
- `auto-mr --version` — if `auto-mr` is not installed, skip this phase entirely and
  show `git push -u origin <branch-name>` instead.
- `git rev-parse --abbrev-ref HEAD` — if this is the default branch
  (`main`/`master`), **stop**. `auto-mr` will not refuse on its own, and merging a
  default branch into itself then deleting it is not recoverable from here.
- `git status --porcelain` — if the tree is dirty, list the uncommitted files
  and let the user decide before proceeding.

**Confirmation (required — never skip, never infer):** ask via `AskUserQuestion`:

> Run `auto-mr` on `<branch-name>`? This pushes the branch, opens the MR/PR, waits
> for CI, and then **merges it and deletes the branch automatically** if CI passes.

Options: "Yes — push, merge and delete" / "Cancel — leave the commit local"

Do not treat the Phase I-7 commit approval as covering this. Committing and
merging are different decisions with very different blast radius, and this is the
only irreversible step in the workflow.

**Execute:** Run `auto-mr` → on success display MR/PR URL → on failure warn and show manual push instructions. If the failure looks like a pipeline timeout, verify the MR/PR is still open and unmerged (`gh pr view` / `glab mr view` / `fgj pr view`) before reporting the outcome.

**Display summary** showing all completed steps (issue retrieved, branch, implementation, lint, tests, commit, MR) with URLs and hashes.

## Flag Support

**Both modes:**

| Flag | Short | Effect |
|------|-------|--------|
| `--skip-branch` | `-b` | Skip branch creation, stay on current branch |
| `--dry-run` | `-n` | Preview mode: show what would be done without executing |
| `--force` | `-f` | Skip all confirmation prompts, auto-approve all phases |

**Staged changes mode only:**

| Flag | Short | Effect |
|------|-------|--------|
| `--skip-issue` | `-i` | Skip issue creation |

**Issue mode only:**

| Flag | Short | Effect |
|------|-------|--------|
| `--squash` | `-s` | No-op — `auto-mr` squashes by default already |
| `--msg "text"` | `-m "text"` | Custom MR message for auto-mr |
| `--skip-mr` | none | Skip auto-mr phase (I-8) |

**Flag parsing:** Split `$argument` by spaces. Tokens starting with `--` or `-` are flags. `#<number>` or bare `<number>` as first positional → Issue Mode. Remaining non-flag text → context for branch/commit description.

**Dry run (`--dry-run`):** Executes discovery/retrieval phases, displays all proposed actions (branch, issue, commit, implementation plan, lint/test commands), but does NOT execute any mutations. Ends with "Dry run complete. No changes made."

**Force mode (`--force`):** Skips all AskUserQuestion calls, auto-approves all phases. Still displays progress and aborts on errors.

## Integration

Works with `/create-issue` (same CLI logic), `/commit` (same conventional format), and `/analyze-pr` (compatible output).

## Examples

### Staged Changes Mode

```bash
# Stage files, run command → branch + issue + commit
git add api/user.go api/user_test.go
/feature-flow

# Skip issue creation for trivial changes
git add docs/README.md
/feature-flow --skip-issue

# Preview without executing
git add database/schema.sql
/feature-flow --dry-run

# Minimal workflow: commit only (no branch, no issue)
git add config.yml
/feature-flow --skip-branch --skip-issue
```

### Issue Mode

```bash
# Full workflow from issue
/feature-flow #42

# With squash merge
/feature-flow #42 --squash

# Implement and commit only, no MR
/feature-flow #42 --skip-mr

# Auto-approve everything
/feature-flow #42 --force --squash
```

## Error Handling

### Staged Changes Mode Errors

| # | Error | Message / Action |
|---|-------|-----------------|
| 1 | No staged changes | "No staged changes found. Stage files with 'git add <file>' first." |
| 2 | Not a git repository | "Not a git repository. Initialize with 'git init' first." |
| 3 | Branch already exists | Suggest `<name>-v2` or ask for alternative |
| 4 | Pre-commit hook fails | Display hook output, abort, suggest fixing and retrying |
| 5 | `gh`/`glab`/`fgj` CLI not found (issue) | Skip issue creation, warn, continue to commit |
| 6 | Invalid labels | Remove invalid labels silently, warn user |
| 7 | Issue creation fails | Log error, continue to commit without issue reference |
| 8 | Commit fails | Display git error, abort |

### Issue Mode Errors

| # | Error | Message / Action |
|---|-------|-----------------|
| 9 | Issue not found | "Issue #N not found in <owner/repo>." Abort. |
| 10 | `gh`/`glab`/`fgj` CLI not found (retrieval) | "Cannot retrieve issue. Install `gh`, `glab`, or `fgj` CLI first." Abort. |
| 10b | Issue already resolved / no longer relevant | Report evidence (`file:line`); ask to proceed / adjust scope / abort |
| 11 | Lint failure | Display errors, attempt auto-fix, ask user to continue or abort |
| 12 | Test failure | Display output, attempt fix (max 2 retries), ask user |
| 13 | auto-mr not installed | Warn, show manual push: `git push -u origin <branch-name>` |
| 14 | auto-mr fails | Show error, provide manual push command and MR URL |

## Best Practices

- Stage only related files for cohesive branch/issue/commit (staged mode)
- Use `--dry-run` first to preview either mode
- Use `--skip-issue` for trivial changes (staged mode)
- Use custom context for better branch names: `/feature-flow add OAuth2 integration`
- Use `--skip-mr` to commit without creating a merge request (issue mode)
- Combine with existing skills: `/feature-flow` → work → `/commit` → `/analyze-pr`