Ship Your First PR

You have a configured beads tracker, seven agents, and bd ready populated with tickets. This page covers the next 10 minutes — picking up a bead, watching the worker ship it, and merging the result.

1. Groom the backlog

The bootstrap seeded your backlog with Phase 1 beads. They’re open but not yet ready — grooming completes the Definition of Ready so they surface in bd ready.

Open Claude Code in the project directory and run:

/groom-backlog

The grooming agent reads your PRD and roadmap, scores backlog candidates by Cost-of-Delay ÷ Duration, checks the top few against Definition of Ready, and completes DoR on the strongest 2-5. You can watch the progress in the Claude chat; bd ready --json is the outcome.

There is no board to watch — Ready is computed by bd ready. The .gembaflow-boards/kanban.html board projection updates automatically whenever a bd command runs.

If your backlog is empty (you skipped seeding, or you want to start with a hand-written bead), use /create-ticket first to file one. The grooming agent will pick it up on the next pass.

2. Run /work-ticket

With bd ready stocked, type:

/work-ticket

The Ticket Worker agent picks the top-priority bead from bd ready, claims it atomically (bd update <id> --claim), creates a feature branch (feature/<bead-id>-{slug}), implements the change, runs lint and tests locally, and pushes to origin. It opens a pull request with a body line Bead: <id> linking to the bead.

You watch this happen. The bead is claimed; the PR lands; CI starts. If something looks wrong, interrupt — typing simpler — just edit the existing function is a valid correction; the worker resumes from your feedback. You are the supervisor; the worker is the line operator.

3. CI auto-fix loop

When CI runs, one of three things happens:

• CI green on first try. The worker auto-launches /review-pr next. Go to step 4.
• CI fails with a fixable issue (lint, format, test). The worker reads the failure, applies the fix, pushes, and waits for CI again. Up to 3 attempts.
• CI fails irrecoverably. The worker stops, leaves the bead claimed, and escalates to you. Investigate the failure manually.

The standard case is green-on-first-try for small tickets; green-after-one-fix for medium tickets.

4. Watch /review-pr run

Once CI is green, the worker chains /review-pr automatically. The reviewer agent reads every changed file (not just the diff summary), applies red-flag detection (hardcoded secrets, failing checks, missing tests, security issues), and posts a structured review comment with a recommendation:

• GO + all CI checks green → the reviewer also sets the GitHub APPROVED state. Move to step 5.
• GO + any CI check pending or failing → comment only (no approval). Resolve the CI issue; re-run review if needed.
• NO-GO with required changes → the reviewer names what blocks merge. Read the comment, decide whether to push a fix yourself or hand the change list back to the worker.

5. Merge the PR

Only humans merge. This is the framework’s hard line. Click the Merge pull request button in the GitHub UI yourself.

When you click merge, the post-merge audit picks up: the merge commit lands on main, the deployment runs (Render by default), and validation kicks in. If the deployment fails, the rollback workflow auto-fires. If it succeeds, the bead is closed with a provenance trail — the SHA, merged timestamp, and deploy ID recorded in the close reason.

What just happened

In about 10 minutes you:

• Completed Definition of Ready on backlog beads (/groom-backlog)
• Watched a worker agent claim, implement, test, and PR a bead (/work-ticket)
• Watched a reviewer agent verify it (/review-pr)
• Merged it yourself
• Saw the deployment land and the bead close with provenance

That is the gemba walk in operation. You supervised; the agents implemented. The framework’s contract is that you stay at the merge boundary and the reviewer boundary; everything in between runs without you.

Where to go next

• If you want to drain the whole ready queue overnight: /drain loops /work-ticket → /review-pr → agent-merge → post-merge validation across every safely-classified bead while you sleep.
• If a bead comes back with the wrong shape: rewrite it with /create-ticket, which enforces the Ticket Format’s four Power Sections.
• If you want to understand what just happened conceptually: Structured Handoffs covers the agent roster and the handoff contracts you just watched in action.
• If something went wrong and you don’t know why: FAQ covers the most common first-week stumbles. /doctor surfaces environment issues if the framework feels broken.