FAQ

The questions everyone asks in their first week.

Why can’t I push to main?

The main branch is protected. Nobody — not even you — can push directly. This is a safety net. All changes go through a pull request so they can be reviewed and tested before they reach the live codebase. Think of main as the published version of your project.


# Create a branch for your change
git checkout -b feature/my-change
git add -A
git commit -m "feat: describe what you changed"
git push -u origin feature/my-change
# Then open a PR on GitHub.

Why three GitHub accounts?

Solo developers do not need three. For teams, Gemba Flow uses three identities for a clear audit trail: a personal account for final decisions, a worker bot that writes code and opens PRs, and a reviewer bot that reviews them. No single account can both write and approve.

What if CI fails?

CI runs every time you push or open a PR. A red X means something failed — formatting, tests, or invalid files. Click “Details” next to the failed check to read the error.


# Common fixes
npx markdownlint --fix **/*.md
npx eslint . --fix
uv run ruff check . --fix
 
# Re-run tests locally
npm test
uv run pytest

How do I add a dependency?


# Node.js
npm install package-name
 
# Python (FastAPI starter)
uv add package-name
 
# Then commit
git add -A
git commit -m "build: add package-name dependency"

What does the pre-push hook do?

It runs your linter and test suite automatically every time you push. If something fails, the push is blocked so broken code never reaches GitHub. Think of it as a spell-checker that runs before you hit send.

Can I skip the hooks?

You can — git push --no-verify bypasses pre-push, and pre-commit hooks have a similar flag — but if you find yourself skipping them, the hook is wrong or the change is too big. Fix the cause, not the hook.

Beads tracker (v1.6.0+)

The following questions cover the beads-era tracker introduced in gembaflow v1.6.0. New forks are beads-native from bootstrap. Existing forks have a migration path — see “What happens to my existing issues?” below.

Where did the project board go?

The GitHub Projects board was retired in gembaflow v1.6.0. The tracker is now beads (bd CLI) — a local, git-committed issue store that ships with the framework. Ready work is computed (bd ready = open + unblocked + DoR complete), not a column anyone moves tickets into. The board you see on GitHub is no longer the canonical view.


# The commands you used to run against the board
bd ready --json           # open, unblocked, DoR-complete beads
bd show <id> --json       # read a bead
bd update <id> --claim    # claim a bead (atomic — no races)

Do I still need the `project` PAT scope?

No. The project PAT scope is retired entirely. No framework script, workflow, or agent command reads or writes GitHub Projects data anymore. If you see it in a personal access token you already created, it is harmless but unnecessary. Remove it on renewal.

How do I see the board now?

Two read-only HTML projections live in .gembaflow-boards/ in your repo root:


.gembaflow-boards/kanban.html       # the headline board — use this one
.gembaflow-boards/techtree.html     # experimental dependency tree

They are regenerated automatically by the Stop and SessionStart hooks, so they stay current as long as you are using Claude Code. You can also regenerate manually at any time:


/board-refresh

Open either file in your browser. They render in under a second with no network calls — the data comes from the local .beads/issues.jsonl mirror.

Can humans edit the board?

No. The board projections are read-only. They are rendered output, not an editable surface.

All mutations go through the operator terminal via the bd CLI:


bd update <id> --claim              # claim a bead
bd comment <id> "progress note"     # add a comment
bd update <id> --add-label in-review  # label state transitions
bd close <id> --reason "merged"     # close after a verified merge

This is an honest architectural limit, not a marketing softening. There is no click-to-edit UI; the terminal is the mutation surface.

What happens to my existing issues?

You have two paths. Choose one — one-release window only.

The flag that keeps the legacy GitHub Projects path reachable will be removed in the next release (removal ticket gembaflow#587 ). Do not defer this decision past that release.

Path A: Migrate now (recommended)

Run the idempotent migrator to import your GitHub Issues into beads:


# Dry-run first — creates nothing, reports what it would do
bash scripts/migrate-issues-to-beads.sh
 
# Execute when satisfied with the dry-run output
bash scripts/migrate-issues-to-beads.sh --execute
 
# Optionally close the source GitHub Issues with pointer comments
bash scripts/migrate-issues-to-beads.sh --execute --close-github

Key properties of the migrator:

Idempotent by --external-ref — safe to re-run; a completed run reports created 0 and exits clean.
Epics first — dependency wiring is resolved in the right order.
GitHub Issues can stay open as the public inbox. You do not have to pass --close-github. Many forks keep GitHub Issues open for public intake and use beads as the working queue. The two coexist.

After a successful migration, sync the tracker state:


bd dolt push

Path B: Legacy flag (one release only)

If you are not ready to migrate, set the flag in both locations:


# 1. In .gembaflow-config.json (local tooling reads this)
#    Add the following key:
#    "legacy": { "githubProjects": true }


# 2. In your repo's Actions variables (GitHub Actions reads this)
gh variable set GEMBAFLOW_LEGACY_GITHUB_PROJECTS --body true

Critical: you must set BOTH surfaces. The .gembaflow-config.json key controls local bootstrap tooling. The Actions variable controls auto-board-status.yml in CI. Setting one but not the other causes a silent partial failure:

Legacy flag OFF (default) + no Actions variable set: auto-board-status.yml skips with a loud notice. This is correct behavior for beads-native forks.
Legacy flag ON + Actions variable missing: auto-board-status.yml silently no-ops — it receives the default (false/unset) and skips without warning. Your board sync appears to run but does nothing. This is the easiest thing for an existing-fork operator to miss.

Every read of the legacy path prints a deprecation warning. Treat each warning as a reminder that the window closes at the next release.

What about the agent-merge gate?

The agent-merge gate (agent-merge.yml) is opt-in — it ships with the framework but you install it manually on your fork, so every fork makes an explicit decision.

The gate is also configurable, not doctrinal:

REVIEWER_APPROVAL_LOGIN — set to your reviewer bot’s login (upstream default: va-reviewer) to require a second-identity approval on every autonomous merge. The gate checks that the approval was made against the current head commit — a stale approval on an earlier commit is refused.
Empty REVIEWER_APPROVAL_LOGIN — deliberately accepted by “never-approve” forks. The gate still enforces citation, safety label, and green CI checks; it warns loudly on every run that second-identity approval is not required.

Forks staying on GitHub Projects do not install the workflow. Forks wanting the autonomous drain path install the workflow copies manually — workflows are not in syncDirectories, so each fork controls its own copy.

FAQ