| name | eliteforge-git-feature-oriented-spec |
| description | Git specification for feature-oriented development with full branch types, including non multi-agent, multi-agent base, and subagent branch and worktree tree naming. |
| metadata | {"version":"1.0.1"} |
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 branchcheck_merge: Check all branches for the current version are merged into the current branchdelete_local_branches: Delete all branches except the main/master.ensure all branches are pushedrename_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
