Framework SDLC
How Gemba Flow itself is developed, tested, and released. Written from the perspective of a contributor to the framework — not a user building on it.
Framework vs. downstream
Gemba Flow is a framework product. Its consumers are downstream variants — cloud-specific forks, workshop forks, and user repositories provisioned from those variants. The framework owns: agent definitions, slash commands, validation scripts, CI workflow structure, doc templates, and starter projects.
A PR against Gemba Flow is not a product change — it is a framework change. Every such change propagates to all downstream variants. That carries obligations no other PR type does.
Sync paths
| Path | When used | Mechanism |
|---|---|---|
pull-upstream.sh | Routine updates — new agents, improved scripts | File-level diff against syncDirectories; skips .gembaflow-overrides |
upgrade.sh | Major version changes or restructuring | Three-way merge with conflict resolution modes |
Version significance
| Change type | Bump | Changelog |
|---|---|---|
| Bug fix, doc correction | Patch | Yes |
| New agent, command, script, workflow | Minor | Yes |
| Renamed/removed agent, restructured dirs, changed bootstrap | Major | Yes + migration guide |
Protecting downstream customizations
Downstream forks maintain .gembaflow-overrides — one path per line.
Both sync paths skip files listed there. The override mechanism works
by exact file path, which is why renaming any file in syncDirectories
is a breaking change requiring a major version bump and a migration
guide.
Historical: agile-flow → Gemba Flow rebrand
The framework was renamed from agile-flow to gembaflow in 2026-Q2
across six phases. Downstream forks running /upgrade against framework
version 1.1.0 or later get the rename transparently via redirect-aware
sync.
The rebrand phases for reference (no action required):
- Phase 0.5 (v1.1.0) —
/upgrade(template-sync.sh) made redirect-safe; canonical PAT scope set documented - Phase 1 — GitHub repo rename (operational, not a PR)
- Phases 2a–2c — URL rewrites in scripts, env var dual-read shim, package metadata rename
- Phase 3 — variant fork
.agile-flow-versionfiles updated to point at their own forks - Phase 4 (v1.2.0) — dotfile renames (
.agile-flow-*→.gembaflow-*); sync branch prefix rename - Phase 5 — GCP resource naming forward-only update
Where this shows up
/upgraderunspull-upstream.sh(the routine sync path) and respects.gembaflow-overrides./report-issuefiles defects against the framework from a downstream fork, closing the contributor feedback loop./doctorflags stale framework versions and recommends/upgradewhen the gap matters.