eliteforge-feature-oriented-release-flow

What this skill does

# EliteForge Feature-Oriented Release Flow

## Overview

Advance one release workflow state at a time for the full EliteForge Feature-Oriented Git process. Keep the state machine strict at release boundaries, but leave normal development work outside this skill.

## Invocation Boundary

Always follow the EliteForge Git Feature-Oriented Spec.
Use this skill only for workflow boundary actions:

- Initialize iteration branches.
- Publish feature work to dev through `nightly`.
- Submit, verify, or deploy QA through `qa/<version>`.
- Return from failed QA to feature fixes.
- Squash the feature branch after QA passes.
- Merge approved feature branches into `release/<version>`.
- Rebase/push release, deploy snapshot, tag, deploy formal version, and merge back to `master`.

Do not use this skill for ordinary feature coding, routine commits, local tests, linting, formatting, dependency bumps, or generic Git questions.

## Inputs

- `version`: required release version, for example `1.0.0`.
- `developer`: required developer segment, for example `clouds3n`.
- `taskName`: required branch-safe task name, for example `demo`.
- `taskId`: optional task identifier, for example `#123`.
- `multiAgent`: optional mode. Use it only when the task has entered the EliteForge Git Feature-Oriented Spec multi-agent workflow.

When `taskId` exists, derive non multi-agent branch `feature/<version>/<developer>/<taskId>/<taskName>` and state file `docs/tasks/release-flow/<version>/<taskId>-<taskName>.json`.

When `taskId` is absent, derive non multi-agent branch `feature/<version>/<developer>/<taskName>` and state file `docs/tasks/release-flow/<version>/<taskName>.json`.

When `multiAgent` is active, the release-flow `feature_branch` is the matching multi-agent base branch: `feature/<version>/<developer>[/<taskId>]/<taskName>/base`. Subagent branches must already be merged into this `/base` branch before release-flow promotion states run.

## Operating Rules

- Execute exactly one state transition per user request unless the user explicitly asks for a larger run.
- Before risky transitions, run `scripts/release_flow_state.sh --version <version> --developer <developer> --task-name <taskName>` from the target repository; add `--task-id <taskId>` only when a task ID exists, and add `--multi-agent` only when the release-flow feature branch must be `.../<taskName>/base`.
- Use `references/release-flow-state-machine.md` when command details, transition guards, or failure handling are needed.
- Persist workflow state in `docs/tasks/release-flow/<version>/<taskId>-<taskName>.json`. This state file is required, not optional.
- `taskId` is optional. If `taskId` is absent, persist workflow state in `docs/tasks/release-flow/<version>/<taskName>.json`.
- Use the literal `taskId` and `taskName` in the state file name. Do not strip `#` from task IDs such as `#123`; quote the path in shell commands. Do not add a leading hyphen when `taskId` is absent.
- Stop if `version`, `taskId` when present, or `taskName` contains `/`, because each value must remain one path segment.
- Do not use `/base` for non multi-agent release flows. If a task starts non multi-agent and later enters multi-agent mode, rename the existing feature branch to the matching `/base` branch before creating or promoting subagent work.
- Update the state file only after the command sequence and guard checks for the new state have succeeded. Use `scripts/persist_release_flow_state.py` for the write.

## Invariants

- Stop if `git status --porcelain` contains non-state-file changes before switching, merging, rebasing, tagging, deploying, or pushing, except when intentionally committing user changes.
- Never skip MR approval before QA deployment.
- Never force push except after feature squash or release rebase.
- Never deploy from an ambiguous or wrong branch.
- Never continue automatically through merge conflicts, rebase conflicts, missing remote branches, existing tags, failed deploys, or unclear protected-branch rules.
- Treat `master` and `main` as equivalent only for branch policy; follow the repository's actual default branch in commands. If this release flow names `master`, verify whether the repo uses `master` or `main` before executing.

## Compact State Table

| State | Expected branch | Boundary action | Next |
| --- | --- | --- | --- |
| `READY` | any clean branch | Fetch, prune, verify default branch | `INIT_BRANCHES` |
| `INIT_BRANCHES` | default branch refs | Create `feature`, `qa`, and `release` from default | `FEATURE_DEV` |
| `FEATURE_DEV` | `feature/...` or `feature/.../base` | Commit normal feature or fix work | `DEV_PUBLISH` |
| `DEV_PUBLISH` | `nightly`, then feature | Merge feature into `nightly`, push, deploy dev, push feature | `QA_MR` |
| `QA_MR` | GitLab | Create or verify MR from feature to `qa/<version>` | `QA_DEPLOY` |
| `QA_DEPLOY` | `qa/<version>` | Pull QA, deploy `VERSION=<version>-SNAPSHOT` | `FEATURE_FIX` or `SQUASH` |
| `FEATURE_FIX` | `feature/...` or `feature/.../base` | Commit QA fix | `DEV_PUBLISH` |
| `SQUASH` | `feature/...` or `feature/.../base` | Interactive rebase from merge-base, force push feature | `RELEASE_MERGE` |
| `RELEASE_MERGE` | `release/<version>` | Merge approved squashed feature branches | `RELEASE_REBASE` |
| `RELEASE_REBASE` | `release/<version>` | Rebase onto default remote, force push release | `SNAPSHOT_DEPLOY` |
| `SNAPSHOT_DEPLOY` | `release/<version>` | Deploy `VERSION=<version>-SNAPSHOT` | `TAG` |
| `TAG` | `release/<version>` | Create and push tag `<version>` | `PROD_DEPLOY` |
| `PROD_DEPLOY` | `release/<version>` | Deploy `VERSION=<version>` | `MASTER_BACKMERGE` |
| `MASTER_BACKMERGE` | default branch | Fast-forward merge `release/<version>` or create protected-branch MR | `DONE` |

## Resources

- `references/release-flow-state-machine.md`: Complete state machine, command templates, guards, and blocked states.
- `scripts/release_flow_state.sh`: Read-only Git diagnostic helper for current branch, cleanliness, derived branches, state file path, upstreams, remote refs, local tag existence, optional remote tag existence, and state hints.
- `scripts/persist_release_flow_state.py`: Deterministically create or update the required state JSON after a successful state transition.