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.