Add branching-strategy skill with next and create actions

Version-aware branch naming (X.Y.Z.Q/{TASK_CODE}-{FEATURE}-{SEQ}), branch creation from origin/test with origin/main fallback, and the PR-into-test merge rule. Ships a TypeScript CLI (next, create) plus shell modules (loggers, base, cli) run via Taskfile. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-24 13:48:13 +03:00
parent 823baf8302
commit c32c55cb4d
46 changed files with 1426 additions and 0 deletions
@@ -0,0 +1,104 @@
+---
+name: 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/branching-strategy.git
+  origin-path: $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:
+
+```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).