development-branching-strategy-3darch/SKILL.md

name, description, license, metadata

name	description	license	metadata
branching-strategy	Principles and tooling for git branching in any repository — version-aware branch naming, branch creation from origin/test, and the PR-into-test merge rule. Use this skill whenever a new git branch must be named or created, or when committing, pushing, or merging in any repository — even if the user only says "new branch", "commit this", "push it", or "merge". Enforces the convention X.Y.Z.Q/{TASK_MANAGEMENT_CODE}-{FEATURE_X}-{SEQ} with the version read from git tags only. Also use when deciding what an agent may do autonomously in a repository versus what requires explicit human approval.	Proprietary	author version spec origin-repository origin-path workspace-swiss-knife 2.0 agentskills.io/specification git@github.ibm.com:CTOTools-skills-code-agent/branching-strategy.git $HOME/projects-ibm/cognitive-architect/workspace-skills-code-agent/branching-strategy

Branching Strategy

Git branching principles and tooling, for any repository.

Main rules

Rule 1 — All local work happens on a branch created from origin/test

• Working locally with any repository always requires a branch — never commit on the base branch itself.
• The branch is created from origin/test; if the remote has no test, fall back to origin/main; if the remote has neither, ask the user which base to use — never guess.
• Fetch first (git fetch --prune) so the branch is cut from the current remote state.
• Before creating the branch, present the computed branch name to the user and get their confirmation — run the next action, show the name, create only after a yes.

Rule 2 — Branch naming convention

X.Y.Z.Q/{TASK_MANAGEMENT_CODE}-{FEATURE_X}-{SEQ}

Example: 4.0.0.0/IIAA-123-api-cleanup-001

Segment	Meaning	Source
X.Y.Z.Q	Version	Git tags only — latest semver tag of the target repo (v prefix allowed; 3-part tags get Q=0). No tags → stop and ask which version to tag, never guess.
TASK_MANAGEMENT_CODE	Task/ticket identifier, e.g. IIAA-123	Provided per task (--task-key)
FEATURE_X	Kebab-case feature/focus topic	Provided per task (--topic)
SEQ	3-digit sequence, 001-based	Auto-incremented by scanning existing local + remote branches with the same prefix

The version is never taken from package.json, VERSION files, or guessed.

Rule 3 — Merging into test is via Pull Request, by the user, always

• Every branch is merged into test through a Pull Request — never by direct merge + push.
• Merging always happens manually by the user. The agent may prepare and push the branch and hand over the PR compare URL; it never creates the merge.

Supporting principles

• Commit only when the user asks; push only when the user asks, and only branches.
• Never delete or force-push branches without an explicit request.
• Git runs over SSH with the user's existing key — never install or configure API tokens (gh auth login, PATs); real enforcement is server-side branch protection on test.
• Commits: imperative subject ≤ 72 chars; agent-generated commits carry Co-Authored-By: <agent name> <noreply@anthropic.com>; never commit gitignored artifacts.
• Versions are marked with git tags — tags are the single source of truth.

Available scripts

All commands run via task from the scripts/ directory of this skill:

# Compute the next branch name + detected base (no changes made) — show this to the user
task next -- --task-key="IIAA-123" --topic="api-cleanup" --repo-dir="/path/to/repo"

# After user confirmation: fetch, then create the branch from origin/test (or origin/main)
task create -- --task-key="IIAA-123" --topic="api-cleanup" --repo-dir="/path/to/repo"

# Build TypeScript to dist/
task build

TypeScript CLI actions (run via cli module → src/):

• next (src/actions/next/action.ts) — resolves version, sequence, and base branch; outputs the branch name and its parts as YAML
• create (src/actions/create/action.ts) — same resolution, then git fetch --prune + git checkout -b <branch> <base>; errors out if neither origin/test nor origin/main exists and no --base was given; never pushes

Workflow

1. Confirm the target repo has at least one semver tag (git tag --list). If not, stop and ask which version to tag — do not invent one.
2. Run task next — it prints the computed branch name and the detected base branch.
3. Show the branch name to the user and wait for confirmation.
4. Run task create only after the user confirms. If it reports no test/main on the remote, ask the user and re-run with --base.
5. Pushing and the PR into test are the user's decision — hand over the compare URL, never merge.

Gotchas

• Tags are compared with --sort=-v:refname; a malformed tag (e.g. release-1) is ignored, not an error.
• SEQ scans both local and origin/ branches — create fetches first, but if using next alone on a stale repo, run git fetch --prune or the sequence can collide with an unseen remote branch.
• task-key must match PROJECT-ID shape (^[A-Z][A-Z0-9]*-[A-Za-z0-9]+$); topic must be kebab-case.
• create falls back to branching from the local ref when offline (fetch failure is non-fatal).