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

---
name: development-branching-strategy
description: >
  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.
license: Proprietary
metadata:
  author: workspace-swiss-knife
  version: "2.0"
  spec: agentskills.io/specification
  origin-repository: git@github.ibm.com:CTOTools-skills-code-agent/development-branching-strategy.git
  origin-path: $HOME/projects-ibm/cognitive-architect/workspace-skills-code-agent/development-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:

```bash
# 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).