eliteforge-git-feature-oriented-lite-spec

name	eliteforge-git-feature-oriented-lite-spec
description	Git specification for feature-oriented development with necessary branch types and non multi-agent, multi-agent base, and subagent branch and worktree tree naming.
metadata	{"version":"1.0.1"}

EliteForge Git Feature-Oriented Lite Spec

Environment Variables

• ELITEFORGE_SKILL_GIT_LITE_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.

• Only use two types of branches: feature and default branch (main or master).
• Non multi-agent branch name follows template: feature/<developer>[/<taskId>]/<taskName>.
• Multi-agent base branch name follows template: feature/<developer>[/<taskId>]/<taskName>/base.
• Codex subagent branch name follows template: feature/<developer>[/<taskId>]/<taskName>/<agentId>/<subtaskName>.
  • 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/<developer>[/<taskId>]/<taskName>、feature/<developer>[/<taskId>]/<taskName>/base	create from master	development and unit testing
master	feature/<developer>/...	git rebase	always rebase master latest commits
feature/<developer>[/<taskId>]/<taskName>/base	feature/<developer>[/<taskId>]/<taskName>/<agentId>/<subtaskName>	create from multi-agent base branch	subtask implementation in isolated worktree
feature/<developer>[/<taskId>]/<taskName>/<agentId>/<subtaskName>	feature/<developer>[/<taskId>]/<taskName>/base	git merge	subtask branch must merge back to its corresponding multi-agent base branch after completion
feature/<developer>/...	master	Fast-forward only merge	after merge completed,ensure merged branches are cleaned up
master	master	git tag <version>	ensure all feature merged

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_LITE_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>/feature/<developer>[/<taskId>]/<taskName>.
• Multi-agent base worktree path follows template: <root>/<repo>/feature/<developer>[/<taskId>]/<taskName>/base.
• Subagent worktree path follows template: <root>/<repo>/feature/<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/clouds3n/add-login uses worktree <root>/<repo>/feature/clouds3n/add-login.
• multi-agent base branch feature/clouds3n/add-login/base uses worktree <root>/<repo>/feature/clouds3n/add-login/base.
• subagent branch feature/clouds3n/add-login/backend/session-token uses worktree <root>/<repo>/feature/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 branch or another release branch.
• The coordinating agent owns conflict resolution and final acceptance.

Commit Spce

Follow Conventional Commits specification.

Merge Request Spce

No need to create MR/PR.

Quality Gates

• Check branch before coding. DO NOT develop directly on default branch
• Non multi-agent branch name follows template: feature/<developer>[/<taskId>]/<taskName>
• Multi-agent base branch name follows template: feature/<developer>[/<taskId>]/<taskName>/base
• Subagent branch name follows template: feature/<developer>[/<taskId>]/<taskName>/<agentId>/<subtaskName>
• Worktree path must mirror the branch tree under ${ELITEFORGE_SKILL_GIT_LITE_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
• Commit message follows Conventional Commits