feat(gitflow): universal gitflow model — lib + skill + orchestrator wiring
lib core (start/finish/init, transactional bootstrap) + migrate + 57-test suite + aiguillage; skills/gitflow + gitignore template; CLAUDE.md gitflow rule; wiring init-project (5f/8/11), onboard (2.6), ship-feature (0/4/9), feat/bugfix/hotfix aiguillage.
This commit is contained in:
Bastien Chanot
@@ -0,0 +1,81 @@
|
||||
---
|
||||
name: gitflow
|
||||
description: Use when a project needs gitflow branch operations — bootstrapping main+develop, starting a typed branch (feature/bugfix/release/hotfix), or integrating finished work by directed merge — or when an orchestrator must branch or merge under the gitflow model. Use when about to merge any branch into develop or main.
|
||||
---
|
||||
|
||||
# gitflow
|
||||
|
||||
## Overview
|
||||
|
||||
The one place gitflow branch logic lives. The mechanics — branch, merge, hotfix
|
||||
fan-out, init, `.gitignore` reconcile, the protected-base predicate — are in
|
||||
`~/.claude/lib/gitflow.sh` (tested, deterministic). This skill governs **when**,
|
||||
and bulletproofs the single judgment call: **`finish` merges only on an explicit
|
||||
human signal.**
|
||||
|
||||
Replaces `finishing-a-development-branch` for gitflow flows — that skill is
|
||||
single-target and cannot do the directed / fan-out merges below.
|
||||
|
||||
## When to Use
|
||||
|
||||
- An orchestrator (`ship-feature`) or an assistance skill (`feat`/`bugfix`/`hotfix`) must branch or merge.
|
||||
- Bootstrapping a repo's branch model (`init-project`, `onboard`).
|
||||
- You are about to integrate a finished branch into `develop` or `main`.
|
||||
|
||||
## Branch model
|
||||
|
||||
`main` (prod) · `develop` (integration, off main) · `feature/*` and `bugfix/*`
|
||||
(off develop → develop) · `release/*` (off develop → main + back-merge develop)
|
||||
· `hotfix/*` (off main → main + develop [+ any open release/*]).
|
||||
|
||||
## Operations — all via the lib
|
||||
|
||||
```
|
||||
bash ~/.claude/lib/gitflow.sh init [msg] # main+develop; root-commit (fresh) or ensure (existing); reconcile .gitignore; install hook
|
||||
bash ~/.claude/lib/gitflow.sh start <type> <name> # branch from the correct base
|
||||
bash ~/.claude/lib/gitflow.sh finish # directed merge of the CURRENT branch — HUMAN-GATED (below)
|
||||
bash ~/.claude/lib/gitflow.sh protected-base [br] # rc 0 on main/develop — the shared predicate
|
||||
```
|
||||
|
||||
`finish` merges by the current branch's type:
|
||||
|
||||
| Current branch | Merges into | then |
|
||||
|---|---|---|
|
||||
| `feature/*` · `bugfix/*` | develop | delete |
|
||||
| `release/*` | main + develop | delete |
|
||||
| `hotfix/*` | main + develop + any open `release/*` | delete |
|
||||
|
||||
## The finish gate — merge ONLY on an explicit human signal
|
||||
|
||||
`finish` writes to shared branches (`develop`, `main`). Run it ONLY when the user
|
||||
gives a **real-time, explicit go for THIS merge** — "merge it", "feature OK",
|
||||
"finish it". Dev and testing happen out of git; finish never auto-fires.
|
||||
|
||||
**Violating the letter of this gate violates its spirit.**
|
||||
|
||||
| Rationalization | Reality |
|
||||
|---|---|
|
||||
| "Tests pass, so I'll merge." | Green = *ready to* merge, not *authorized*. Present "ready — merge?" and wait. |
|
||||
| "The user said 'ship' / 'implement and ship'." | "Ship" ends at ready-to-merge **and ask**. The verb is not a merge signal. Pushing or opening a PR is still initiating integration — ask first. |
|
||||
| "The plan's next step says 'merge into develop'." | A step written *before* the work cannot consent to integrating it. Stop at that step and ask. |
|
||||
| "finish is the last pipeline step — I'll chain it." | The orchestrator STOPS at the finish gate and asks. Reaching it ≠ permission. |
|
||||
|
||||
### Red flags — STOP, do not finish
|
||||
|
||||
- About to run `gitflow finish` / `git merge` into develop or main, and the user has not, in THIS exchange, explicitly said to merge.
|
||||
- The authorization you're leaning on is a plan step, a task description, or the word "ship" — not a live "merge it".
|
||||
- "It's obviously done — surely they want it merged."
|
||||
|
||||
All of these mean: present the merge as a question, then wait for the explicit go.
|
||||
|
||||
## Aiguillage (assistance skills)
|
||||
|
||||
On a protected base, assistance skills (`feat`/`bugfix`/`hotfix`) call
|
||||
`start <type>` to branch first; on a working branch they commit in place. Same
|
||||
`protected-base` predicate the out-of-skill hook uses.
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
- Using `finishing-a-development-branch` for a gitflow merge → it can't do directed/fan-out merges. Use `gitflow finish`.
|
||||
- Hand-writing `git merge` instead of `gitflow finish` → loses fan-out, branch delete, base sync.
|
||||
- Calling `finish` because the work *looks* done → see the gate.
|
||||
@@ -129,6 +129,18 @@ Rules:
|
||||
- React Native, Flutter, backend, embedded, static HTML → skipped.
|
||||
- If another animation lib (gsap, lottie-react, react-spring, …) is already present → skipped.
|
||||
|
||||
## STEP 5f — GITFLOW INIT
|
||||
After every scaffold file exists (STEP 5–5e have run), establish the gitflow
|
||||
layout and the deterministic root commit:
|
||||
```bash
|
||||
bash "$HOME/.claude/lib/gitflow.sh" init "chore: scaffold <project-name>"
|
||||
```
|
||||
Creates `main`+`develop`, root-commits the FULL scaffold (CLAUDE.md, README,
|
||||
config, `.gitignore`, deps), reconciles the `.gitignore` socle, and installs the
|
||||
versioned pre-commit hook — all embedded in the root commit, working tree clean.
|
||||
This is the deterministic scaffold commit owner (closes BLK-010). The MVP is
|
||||
implemented on a `feature/*` branch off `develop` (STEP 8).
|
||||
|
||||
## STEP 6 — PLAN
|
||||
Invoke `superpowers:writing-plans` with BRIEF + skeleton.
|
||||
Granular tasks (2-5 min each), exact file paths, TDD: tests before code.
|
||||
@@ -144,7 +156,15 @@ Approve and start? (yes / request changes)
|
||||
Changes → back to STEP 6. Approved → continue.
|
||||
|
||||
## STEP 8 — IMPLEMENT
|
||||
Invoke `superpowers:subagent-driven-development`. Isolated subagents, TDD, 2-stage review per task.
|
||||
Start the MVP feature branch off develop, then implement on it:
|
||||
```bash
|
||||
bash "$HOME/.claude/lib/gitflow.sh" start feature mvp
|
||||
```
|
||||
Invoke `superpowers:subagent-driven-development` for the per-task implement loop
|
||||
**and** the final whole-branch review **only**. Do NOT run its terminal
|
||||
`finishing-a-development-branch` step — this orchestrator owns integration via
|
||||
`gitflow finish` (STEP 11). When SDD's flow reaches "Use
|
||||
finishing-a-development-branch", stop and return.
|
||||
|
||||
## STEP 8b — GRAPHIFY FULL (after implementation)
|
||||
If `graphify` CLI is installed AND complexity >= 30%:
|
||||
@@ -214,7 +234,7 @@ nothing was capitalized, the helper no-ops — no commit.
|
||||
|
||||
## STEP 10c — DOC SYNC
|
||||
Run BEFORE STEP 11 FINISH (moved here from post-FINISH). doc-syncer PATCHES public docs but
|
||||
does NOT commit them, and `finishing-a-development-branch` integrates only COMMITTED history
|
||||
does NOT commit them, and `gitflow finish` integrates only COMMITTED history
|
||||
— so a patch left uncommitted never reaches the merge/PR. Same PR-stranding class as the
|
||||
STEP 10b capitalize fix (BDR-034).
|
||||
|
||||
@@ -226,14 +246,17 @@ ONLY the files doc-syncer patched (its `PATCHED_FILES` output, one path per line
|
||||
arg each), never `git add -A`, never `.claude/`/`CLAUDE.md`, and no-ops if nothing was
|
||||
patched. Report per its rc table — rc 4 = a LOUD upstream BDR-022 anomaly, not a silent skip.
|
||||
|
||||
> **Partial fix (conscious).** This commits the docs doc-sync patched, so they reach the
|
||||
> merge/PR. It does NOT fix the scaffold (STEP 5) + bootstrap-README (STEP 5b) commit gap
|
||||
> (BLK-010: no deterministic commit owner; `git worktree add -b` on an unborn HEAD) — a
|
||||
> separate chantier. After this, init-project's doc-sync is fixed but the scaffold/bootstrap
|
||||
> commit gap stays open; GSD STEP 12 still creates ROADMAP.md post-FINISH (BLK-011) — also separate.
|
||||
> **Scaffold commit owner = STEP 5f `gitflow init`** (root commit embeds scaffold + README +
|
||||
> `.gitignore` socle + hook, tree clean — BLK-010 closed). This doc-sync commit lands the
|
||||
> patched docs on the MVP feature branch so they reach the merge. GSD STEP 12 still creates
|
||||
> ROADMAP.md post-FINISH (BLK-011) — separate.
|
||||
|
||||
## STEP 11 — FINISH
|
||||
Invoke `superpowers:finishing-a-development-branch`. Tests pass, build clean, no placeholders, initial commit ready.
|
||||
Tests pass, build clean, no placeholders. Integrate the MVP feature into develop
|
||||
— **only on the user's explicit go** (the `gitflow` finish gate):
|
||||
```bash
|
||||
bash "$HOME/.claude/lib/gitflow.sh" finish # feature/mvp → develop
|
||||
```
|
||||
|
||||
## STEP 12 — GSD v2 INIT (optional)
|
||||
If `multi-session` signal was detected in STEP 0 OR the project has >3 planned milestones:
|
||||
|
||||
@@ -134,6 +134,26 @@ Cas :
|
||||
|
||||
---
|
||||
|
||||
## STEP 2.6 — GITFLOW INIT
|
||||
|
||||
Adopter le modèle gitflow sur ce repo existant :
|
||||
```bash
|
||||
bash "$HOME/.claude/lib/gitflow.sh" init
|
||||
```
|
||||
Sur un repo existant, cela : renomme `master`→`main` si besoin (LOCAL), crée
|
||||
`develop` depuis main, réconcilie le socle `.gitignore` (additif — n'écrase
|
||||
jamais les règles du projet), installe le hook pre-commit versionné, et fait UN
|
||||
commit `chore: adopt gitflow socle + hook` sur main (pendant que le hook est
|
||||
inactif → jamais auto-bloqué). Idempotent — un re-run est un no-op.
|
||||
|
||||
**Annoncer le renommage master→main** s'il a lieu. Le renommage est LOCAL ;
|
||||
repointer la branche par défaut du remote vers `main` + la protection de branche
|
||||
sur `main`/`develop` est une étape de migration séparée (sous-chantier B) — pas
|
||||
faite ici. Pré-condition : working tree raisonnablement propre (le commit
|
||||
d'adoption ne stage que `.gitignore` + `.githooks`).
|
||||
|
||||
---
|
||||
|
||||
## STEP 3 — DEEP INTERVIEW
|
||||
|
||||
L'orchestrateur pilote directement l'interview (l'agent `interviewer.md` est laissé pour `/init-project` où le BRIEF format est attendu ; ici on reste en markdown libre dans la CLAUDE.md).
|
||||
|
||||
@@ -121,7 +121,15 @@ assert a check not performed). No RELATED MEMORY from 0d → omit the block.
|
||||
Changes → back to STEP 2. Approved → continue.
|
||||
|
||||
## STEP 4 — IMPLEMENT
|
||||
Invoke `superpowers:subagent-driven-development`. Isolated subagents. 2-stage review per task: spec compliance → code quality.
|
||||
Start the feature branch off develop, then implement on it:
|
||||
```bash
|
||||
bash "$HOME/.claude/lib/gitflow.sh" start feature <name>
|
||||
```
|
||||
Invoke `superpowers:subagent-driven-development` for the per-task implement loop
|
||||
**and** the final whole-branch review **only**. Do NOT run its terminal
|
||||
`finishing-a-development-branch` step — this orchestrator owns integration via
|
||||
`gitflow finish` (STEP 9). When SDD's flow reaches "Use
|
||||
finishing-a-development-branch", stop and return.
|
||||
|
||||
## STEP 4b — ERROR RECOVERY (if STEP 4 fails)
|
||||
If a subagent returns a build error, failing test, or type error:
|
||||
@@ -191,7 +199,7 @@ memory is integrated with the branch, not stranded outside the PR.
|
||||
|
||||
## STEP 8 — DOC SYNC
|
||||
Run BEFORE STEP 9 FINISH. doc-syncer PATCHES public docs but does NOT commit them, and
|
||||
`finishing-a-development-branch` integrates only COMMITTED history — so a patch left
|
||||
`gitflow finish` integrates only COMMITTED history — so a patch left
|
||||
uncommitted (or committed after) never reaches the merge/PR. Same PR-stranding class as the
|
||||
STEP 7 capitalize fix (BDR-034).
|
||||
|
||||
@@ -206,7 +214,11 @@ surfaced a forbidden path), not a silent skip. It runs BEFORE FINISH so the doc
|
||||
on the branch FINISH integrates.
|
||||
|
||||
## STEP 9 — FINISH
|
||||
Invoke `superpowers:finishing-a-development-branch`. Tests pass, build clean, ready to merge.
|
||||
Tests pass, build clean. Integrate the feature into develop — **only on the
|
||||
user's explicit go** (the `gitflow` finish gate):
|
||||
```bash
|
||||
bash "$HOME/.claude/lib/gitflow.sh" finish # feature/<name> → develop
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user