eliteforge-feature-oriented-release-flow

name	eliteforge-feature-oriented-release-flow
description	Stateful release workflow controller for EliteForge Feature-Oriented Git projects. Use for workflow boundary actions such as initializing iteration branches, publishing dev, submitting or verifying QA, deploying QA, handling QA fixes, squashing a feature branch, merging release branches, deploying snapshot or formal versions, tagging a version, or merging a release back to master. Do not use for ordinary coding, local tests, formatting, simple commits, or unrelated Git inspection.
metadata	{"version":"1.0.1"}

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.