/bootstrap-workflow
The fourth and final phase of project setup — activates the full agent workflow by initializing the beads tracker, configuring branch protection, and seeding the backlog from the PRD.
v1.6.0+ — Phase 4 is beads-native. No GitHub project board is created. The tracker is
bd; the board is a read-only HTML projection at.gembaflow-boards/. New forks never see GitHub Projects.
When to use it
Run this last in the bootstrap sequence, after the three earlier
phases (/bootstrap-product, /bootstrap-architecture,
/bootstrap-agents) have all shipped. The command reads the PRD
and roadmap, runs ./scripts/init-beads.sh to initialize the beads
tracker with the right prefix, configures branch protection on
main, and seeds the backlog with one bead per Phase 1 feature from
the roadmap. After this runs, /work-ticket
has somewhere to pick from.
This is the moment the project becomes operational. Before this,
you’ve been planning and configuring; after this, you can
/drain the ready queue overnight.
Don’t run this before earlier phases have shipped — the seeded backlog quality depends on the PRD and architecture documents being in good shape. A backlog seeded from a half-baked PRD produces beads that will need re-grooming.
How it fits
After this lands, the project is workflow-active: the operator can
/groom-backlog to complete DoR on the seeded
beads so they surface in bd ready, then start executing.
What it does
- Verifies all three earlier bootstrap phases have shipped (pre-flight)
- Initializes the beads tracker via
./scripts/init-beads.sh -p <prefix> - Seeds the GitHub-side
safety:*PR-label registry (bash scripts/setup-safety-labels.sh) - Configures branch protection on
main— no direct commits, PRs required, agent-merge gate honored - Seeds the backlog with one bead per Phase 1 feature from the roadmap, each pre-populated with the 4 Power Sections drafted from the PRD
- Verifies readiness:
bd ready --jsonsurfaces the intended MVP tasks
PAT scopes required
| Scope | Required |
|---|---|
repo | Yes |
workflow | Yes |
project | No — beads needs none |
What does NOT happen
- No GitHub project board is created
- No project board columns are configured
- No
project-scope PAT is read, checked, or required
The visual board (.gembaflow-boards/kanban.html) is generated locally
by hooks whenever a bd command mutates tracker state. You can force a
re-render with /board-refresh.
Ready is computed, not curated
After the backlog is seeded, readiness is computed — there is no
“move to Ready” action. bd ready mechanically surfaces every open,
unblocked bead that has completed its Definition of Ready.
Run /groom-backlog to complete DoR on the seeded beads, wire
dependencies, and confirm the intended 2-5 MVP tasks surface in
bd ready --json.
Migrating an existing fork?
This phase is for standing up a NEW workflow. An existing fork with
open GitHub Issues runs scripts/migrate-issues-to-beads.sh instead
(idempotent, safe to re-run; see docs/BEADS.md § “Migrating an existing
fork”).
If you need to stay on GitHub Projects temporarily (one release only),
set legacy.githubProjects: true in .gembaflow-config.json and the
GEMBAFLOW_LEGACY_GITHUB_PROJECTS=true Actions variable. The flag
defaults to false, warns on every read, and is removed next release
(vibeacademy/gembaflow#587). The project PAT scope is only required
while this flag is on.
Related commands
/bootstrap-agents— predecessor; agents must be specialized before they can participate in the workflow this command activates/groom-backlog— the natural first command to run after this lands; completes DoR so beads surface inbd ready/work-ticket— the everyday command oncebd readyis populated/board-refresh— force-regenerate.gembaflow-boards/if the hooks didn’t fire
Canonical spec: .claude/commands/bootstrap-workflow.md