cloudsen/eliteforge-feature-oriented-release-flow

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.