cloudsen/eliteforge-git-feature-oriented-spec

EliteForge Git Feature-Oriented Spec

Environment Variables

• ELITEFORGE_SKILL_GIT_WORKTREE_ROOT [optional] Root directory for generated git worktrees; defaults to ${CODEX_HOME:-$HOME/.codex}/worktrees.

Branch Spec

main and master are equivalent

Follow the feature-oriented branching model. Continuously develop and test features.

Release-flow branches keep their project convention, such as nightly, qa/<version>, and release/<version>. Working branches only use feature, bugfix, or hotfix as <type>.

Non multi-agent branch name follows template: <type>/<version>/<developer>[/<taskId>]/<taskName>.

Multi-agent base branch name follows template: <type>/<version>/<developer>[/<taskId>]/<taskName>/base.

Codex subagent branch name follows template: <type>/<version>/<developer>[/<taskId>]/<taskName>/<agentId>/<subtaskName>.

• the type attribute only belongs to:
  • feature: new requirements
  • bugfix: bugs does not stuck the main process
  • hotfix: serious bugs requiring urgent fix
• the version attribute follows SemVer Spec x.y.z
• developer is the name of the developer from git config, use email prefix if the name is not set.
• agentId is not used in non multi-agent branches and is required for Codex subagents or parallel agents.
• Subagent agentId must use the role name only, for example backend, frontend, test, review, or docs.
• Put scope and target details in taskName or subtaskName, not in agentId.
• Do not use pure numbers, weak semantic names, numbered variants, or role-plus-target names such as agent-01, backend-01, frontend-02, worker-a, tmp, work, backend-login-api, frontend-login-page, or test-auth-flow.
• taskId is optional, only used for non multi-agent branches when the project has task management system and the task can be easily linked to the branch name.
• taskName and subtaskName should be concise and descriptive, use hyphen to separate words, avoid using special characters.
• Normalize each branch segment to lowercase filesystem-safe text using only a-z, 0-9, ., _, and -.
• Do not use /base for non multi-agent workflows. Use /base only as the integration branch leaf after a task enters multi-agent workflow.
• If a task starts on a non multi-agent branch and later needs subagents, rename the existing branch to the matching /base branch before creating subagent branches. Do not keep both forms for the same task.

| origin branch | target branch | ops | notes | | :--- | :--- | :--- | :--- | | master | feature/<version>/<developer>[/<taskId>]/<taskName>、feature/<version>/<developer>[/<taskId>]/<taskName>/base、qa/<version>、release/<version> | create from master | development and unit testing | | master | feature/<version>/...、qa/<version>、release/<version> | git rebase | always rebase master latest commits | | <type>/<version>/<developer>[/<taskId>]/<taskName>/base | <type>/<version>/<developer>[/<taskId>]/<taskName>/<agentId>/<subtaskName> | create from multi-agent base branch | subtask implementation in isolated worktree | | <type>/<version>/<developer>[/<taskId>]/<taskName>/<agentId>/<subtaskName> | <type>/<version>/<developer>[/<taskId>]/<taskName>/base | git merge | subtask branch must merge back to its corresponding multi-agent base branch after completion | | feature | nightly | git merge | coding complete,no compilation errors | | feature | qa | create merge request | submit to testing, ensure version consistency | | feature | feature | git rebase -i (squash commits) && git push -f | squash mutiple commits of one feature | | feature（squashed） | release | git merge | ensure completed testing | | release | release | git tag <version> | ensure no snapshot/dev dependencies | | release | master | Fast-forward only merge | after merge completed,ensure all other branches for the current version are cleaned up |

Worktree Spec

When using git worktree, the worktree path must mirror the branch tree and have a one-to-one relationship with the checked-out branch.

Worktree root is resolved dynamically:

worktree_root="${ELITEFORGE_SKILL_GIT_WORKTREE_ROOT:-${CODEX_HOME:-$HOME/.codex}/worktrees}"

• One worktree checks out exactly one spec-compliant branch.
• One spec-compliant branch must not be reused by multiple worktrees at the same time.
• Non multi-agent worktrees follow the non multi-agent branch tree: <root>/<repo>/<type>/<version>/<developer>[/<taskId>]/<taskName>.
• Multi-agent base worktree path follows template: <root>/<repo>/<type>/<version>/<developer>[/<taskId>]/<taskName>/base.
• Subagent worktree path follows template: <root>/<repo>/<type>/<version>/<developer>[/<taskId>]/<taskName>/<agentId>/<subtaskName>.
• Use the same semantic fields as the branch name; do not flatten path separators into a basename.
• Do not use project-ambiguous or weak worktree names such as temp, new, work, scratch, or feature-clouds3n-add-login.
• If converting an existing non multi-agent worktree to multi-agent mode, move or recreate the worktree at the /base path before adding subagent worktrees. Do not create subagent worktrees inside an existing non multi-agent worktree.

Examples:

• non multi-agent branch feature/1.2.0/clouds3n/add-login uses worktree <root>/<repo>/feature/1.2.0/clouds3n/add-login.
• multi-agent base branch feature/1.2.0/clouds3n/add-login/base uses worktree <root>/<repo>/feature/1.2.0/clouds3n/add-login/base.
• subagent branch feature/1.2.0/clouds3n/add-login/backend/session-token uses worktree <root>/<repo>/feature/1.2.0/clouds3n/add-login/backend/session-token.

Subagent Merge Spec

• The multi-agent /base branch is the integration branch for the task.
• A subagent branch must merge back into its corresponding /base branch after the subtask is complete.
• A subagent branch must not bypass the /base branch and merge directly into default, nightly, qa, release, or another release-flow branch.
• The coordinating agent owns conflict resolution, final acceptance, and release-flow promotion.

Commit Spce

Follow Conventional Commits specification.

Merge Request Spce

Always use the default MR/PR template from current project.

Useful CLI Commands

Learn more from the scripts/ directory in this skil

• auto_merge: Merge the current version branches into the current branch
• check_merge: Check all branches for the current version are merged into the current branch
• delete_local_branches: Delete all branches except the main/master.ensure all branches are pushed
• rename_git_branch: Rename the branch both locally and remotely

Quality Gates

• Check branch before coding. DO NOT develop directly on master,main,nightly,qa,release branch
• Non multi-agent branch name follows template: <type>/<version>/<developer>[/<taskId>]/<taskName>
• Multi-agent base branch name follows template: <type>/<version>/<developer>[/<taskId>]/<taskName>/base
• Subagent branch name follows template: <type>/<version>/<developer>[/<taskId>]/<taskName>/<agentId>/<subtaskName>
• Worktree path must mirror the branch tree under ${ELITEFORGE_SKILL_GIT_WORKTREE_ROOT:-${CODEX_HOME:-$HOME/.codex}/worktrees}
• Worktree and branch must have a one-to-one relationship
• Subagent branches must merge back to the corresponding /base branch
• Subagent agentId must use a role name and must not include numeric suffixes, scope, or target details
• Version follows SemVer
• Commit message follows Conventional Commits