Eliteforge Git Feature Oriented Lite Spec

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.

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