From Plan to Pull Request: A Day on Strike

Pick a small change. The example throughout this cairn is “add an opt-out flag to the ECO completion email notification — let an OSP supervisor disable the email per-tenant if they prefer pager-only.” Small, real, touches the API, the web frontend, and a projection. The exact feature does not matter. What matters is the shape of the loop around it: how the work gets framed, claimed, executed, reviewed, and shipped.

If you have read the prior twelve cairns, every one of them shows up here. That is the point. This cairn is short on new content and long on integration.

The loop, in one diagram

Before we walk it, here is the whole loop. The first time you read this cairn, the diagram will be denser than it needs to be; come back to it after the prose has named the steps, and it should look obvious.

flowchart TD
  A1[Brief / spec] --> B[bd create]
  A2[Organic discovery] --> B
  B --> C[bd worktree create]
  C --> D{Needs spec pass?}
  D -->|Yes| E[Spec pass]
  D -->|No| F[Execute]
  E --> F
  F --> G[just check-fast iterating]
  G --> H[Commit]
  H --> I[timbers log]
  I --> J[Push, gh pr create]
  J --> K[Q reviews]
  K --> L{Verdict?}
  L -->|Looks good| O[Merge]
  L -->|Concerns/Changes| M[Triage]
  M --> N[Fix, push, re-request review]
  N --> K
  O --> P[bd close]
  P --> R[Final timbers entry]

The conditional at the middle — “needs a spec pass?” — is the call most often gotten wrong. Anything more than a typo benefits from a paragraph. We will come back to that.

Where the bead comes from

Beads originate two ways. The path the example follows here is spec-first: you have a change in mind, you state it clearly, and the agent turns the brief into one or more beads. The other path is organic discovery — a bead surfaces during other work, with no prepared brief, and the agent crafts the description from context. Both paths converge at the same place (a well-formed bead in the graph); they differ in what triggers them.

Spec-first

A brief is what you say (or write) before you create the bead. It does not have to be long. For our example: “OSP tenants should be able to opt out of the per-ECO completion email. Default is opt-in. Setting lives on the OSP tenant config; UI lives in the existing tenant settings page.”

Three sentences naming the change, the default, and where the surface lives. That is enough to ask the agent to create a bead. For larger or more structured specs, the agent breaks the spec into a small set of beads with explicit dependencies, including a t-shirt size on each (see Beads, the Backbone for the sizing scale); you confirm the breakdown. Future-state, this is also where a GitHub issue could land and become beads through the same conversion step, once the bd↔GitHub bridge is wired.

If a brief takes more than a minute to articulate, the work probably wants its own design pass before it becomes a bead — see Spec pass below.

Organic discovery

While the agent is working on something else, you (or it) notice a related problem worth fixing later — a TODO that should be tracked, a flaky test, a dependency upgrade that wants attention, a cleanup the current work surfaced, an inconsistency between two files. There is no formal brief here. The agent has the context from the surrounding work and turns it into a bead description that captures the intent. “File a bead for that flaky test we just saw — describe the failure mode and link it to the dispatched-contact module.” The agent runs bd create; you confirm the body before going back to what you were doing.

This pattern fires often. It is how most of the team’s beads-as-cleanup-items get filed, and it is the second pillar (alongside spec conversion) of how the graph fills. Skipping the spec pass on organic-discovery beads is usually correct — the surrounding context the agent already has is what you would have spent the spec on anyway.

Bead created, bead claimed

You tell the agent what the work is and ask for a bead. The agent runs bd create, names the issue something searchable, drafts a body that captures the brief, and assigns a priority. The bead is claimable as soon as it lands.

For our example, the bead title might be “Opt-out flag for ECO completion email per OSP tenant.” The body restates the brief, names the touchpoints (packages/api/internal/domain/tenant, packages/api/internal/notification, packages/web/src/app/settings, the ECO completion projection), and lists the gates that must pass.

You confirm the breakdown is right; if it is not, you adjust by talking. “Split this into two beads — one for the API and projection, one for the web frontend.” The agent reshapes the graph.

When the breakdown is right, work claims itself: “let’s pick this up,” and the agent runs bd update --claim against the relevant bead. The graph now says one or two issues are in flight, owned by you.

Worktree

For anything more than a typo, work in a worktree. The pattern from Working in Parallel (Mostly):

bd worktree create .worktrees/opt-out-completion-email
cd .worktrees/opt-out-completion-email

The bd worktree create form is the only one you should use — it does the worktree creation and the surrounding setup that lets bd ready, bd close, and the rest see the project’s issue graph from inside the worktree. Plain git worktree add skips that setup and tends to leave the worktree’s beads commands blind to the project’s actual work.

Once you cd in, run the orientation ritual the agent does at every session start: confirm the branch, confirm bd ready shows what you expect, confirm AGENTS.md is the strike one. Most of this happens automatically; what is left is the spoken confirmation that you are in the right place.

Spec pass (if needed)

For anything beyond a typo, a paragraph saves a day. The spec pass is a brief structured exchange with the agent before any code gets written: what the change covers, what it explicitly does not cover, which decisions are deliberate, which are deferred. The team’s dm-work:brainstorming skill, if installed, automates the back-and-forth shape of this conversation; without it, the same exchange happens by talking.

For our example, the spec pass surfaces questions like:

• Is the flag stored on the tenant config row, or is it a new per-OSP override table? (Tenant config row, for now.)
• Does the existing notification path read the flag, or is there a new branch in the projection? (Read the flag in the projection’s notification dispatcher.)
• What happens to ECOs that completed before the flag was flipped? (No retroactive change; the flag affects future completions only.)

Ten minutes of that conversation, captured as the bead body’s amendments, is what the rest of the work runs against. Skip it on small changes; do not skip it on anything that has more than one valid implementation.

Execute

The agent does the typing. You stay at the briefing-and-judgment level. For a piece of work with two beads (one API, one web), this is where subagents earn their keep — one subagent handles the API change in parallel with one handling the web frontend, both reporting back to you. The orchestrator (your main session) integrates.

For smaller work, no subagents needed; the main session writes the code directly. The pattern is the same shape either way: brief the agent on the constraint set, watch it work, intervene when it goes off-script, accept the diff when it converges.

The trust posture from Your Box and Your Trust Model is in play here. If your auto-allow list includes just * recipes, the agent will iteratively run just check-fast against the api and web packages without interrupting you. If it does not, expect to approve those calls. The faster posture pays off most during execute; the more careful posture pays off most when the work touches infrastructure or production.

Local gates

Quality Gates is the deep read. The tactical pattern in this loop:

just check-fast    # iterate on this; it is the per-save sanity check
just check         # run before push; the umbrella across packages

If just check-fast fails, the agent reads the failure, edits, reruns. Most lint complaints fix themselves with just api fix and just web fix. The 20% that do not are the ones worth your attention. Coverage failures are real failures — they mean a code path you added is not exercised. Add the test; do not lower the threshold.

Running just check before pushing is the seatbelt. It catches the slow gates that just check-fast skips: the full web build, integration tests, audit-ci. The thirty seconds the slow run costs is cheap insurance against a CI failure that lands at 2 PM in everyone’s GitHub notifications.

Commit, then timbers

Commits are small. The pre-commit hook does the work the Quality Gates cairn described: beads JSONL flush, lint-staged Prettier on web, timbers gate. The commit message stays whatever you would have written. After the commit, the agent runs timbers log with the what / why / how it understood. You read what it wrote and adjust the why if it is shallow.

For our example, a commit and its timbers entry look like:

git commit -m "feat(api): add opt_out_completion_email flag to OSP tenant config"

timbers log "Add opt_out_completion_email flag to OSP tenant config" \
  --why "OSP supervisors using pager-first workflows do not want duplicate email noise; opt-in by default preserves existing behavior" \
  --how "New nullable column on osp_tenant_config; tenant config aggregate updated; projection reads the flag in notification dispatcher"

That --why is the part the next reviewer will appreciate most. “Why is there a flag?” is the question the diff alone cannot answer; the timbers entry is where it is settled.

Push, open the PR

git push -u origin <branch> publishes the worktree’s branch to the remote. Then gh pr create opens the pull request. Title under 70 characters; body is the bead description plus a Test plan checklist. The agent will draft both; you read and adjust.

For our example, a PR title: feat(api): opt-out flag for ECO completion email. A body that lists what changed, why, how to test it, and links the bead. The link is manual today — the bd ↔ GitHub bridge is not yet wired up — and a quick line in the PR body of the form “Closes os-pvw9” is the convention until it is.

Q reviews the PR

Within minutes of the PR opening, Q (Claude Routine) posts a verdict and inline review comments. Looks good, Concerns, or Changes required. The verdict is a first-class checkpoint, not optional polish — Q’s review catches a meaningful fraction of issues that make it past the agent’s own self-review during execute.

While Q is reviewing, do not start unrelated work that would lose PR context. Schedule a check-back: another small bead in the same area, a documentation pass, a code-reading session on an adjacent module. The point is to stay close enough to the PR that integrating Q’s feedback is cheap when it arrives.

The triage matrix

Q’s review arrives as inline comments and a top-level verdict. Not every comment is equal. The triage move:

Severity	What it is	What you do
Critical	Security, correctness, data loss, crash, regression	Fix it now. Do not push another commit until it is addressed.
Important	Architecture concern, missing test, gap that will bite later	Fix it in this PR. Reply briefly; push a fix; re-request review.
Nice-to-have	Style, minor naming, alternate approach that is also reasonable	Reply with the call you made; defer if the rationale holds.

The agent does the first pass of triage by reading the comments and proposing severity for each. You confirm or override. Critical and Important get fixed; Nice-to-have gets a reply that explains the call. Nice-to-have dismissals should be one sentence — “Keeping the existing naming for consistency with the adjacent module” is enough.

After fixes land, re-request review explicitly. The gh api invocation that does it cleanly is the one that has bitten every new agent at least once:

# CORRECT: build the JSON object with jq, pipe via --input -
jq -n --arg user "q-redshifted" \
  '{reviewers: [$user]}' \
  | gh api --input - \
    -X POST \
    "/repos/{owner}/{repo}/pulls/{number}/requested_reviewers"

The trap is using gh api -F for the array-valued field; that path silently sends a stringified blob that the API rejects with a 422 “client_payload is not an object” (or its variant). Build the JSON properly with jq -n; pipe via --input -. The agent should have this pattern internalized; if you see it reach for -F with an array, redirect.The same pattern applies to repository_dispatch events, which is where this gotcha most often lands. The Conduit publisher uses exactly this idiom in its CI; see the conduit cairns for the deeper context.

The convergence loop is capped at three exchanges. If you are on the fourth round of “fix, re-request, fix, re-request,” that is a signal: the disagreement is not converging on its own, and a human conversation (or a Codex council, per Codex as Second Opinion) is the next step.

Browser-QA, maybe

An honest section. The agent driving a browser via Playwright MCP or Chrome DevTools MCP for runtime verification is possible in our environment today, but it is not how most of the team verifies UI-touching changes. The author has experimented with both, and the experience is somewhere between interesting and worth building on but not yet a default.

For our example, the team’s pattern today is:

• Run the app locally (just dev).
• Click through the affected flow yourself.
• Add a Playwright test (just web e2e) for the regression you want to prevent.

The future pattern — agents writing, running, and evaluating end-to-end Playwright tests as part of the same loop the agent already runs lint and unit tests in — is something we are feeling our way toward but have not landed. If you experiment with it on a real feature and learn something useful, file a bead with what worked.The shape of the answer is probably: the agent runs Playwright in headed mode against a worktree-scoped local stack, takes screenshots at key points, summarizes the run as a structured artifact the next agent (or the human) can read. None of that is hard; what is hard is making it boring enough that you actually do it.

Merge

Merge only after Q has approved (or its concerns are resolved), CI is green, and — for non-trivial changes — the human in the loop has said go. Do not self-merge when the user has not signed off. This rule is one of the more frequently-tested ones; the temptation when CI is green and Q is approving is to just hit the button. Wait for the explicit go.

For our example, after Q approves and CI is green: “Looks good — merge it.” The agent runs gh pr merge --squash (or whatever the project’s merge style is — squash for Strike), and the branch lands on main.

Bead close, final timbers entry

After the merge, close the bead and record the merge commit in timbers:

bd close os-pvw9
timbers log "Merge: opt-out flag for ECO completion email" \
  --why "Brief from supervisor: pager-first workflows want to silence duplicate email" \
  --how "Squash-merged after Q approval and CI green; bead os-pvw9 closed"

The agent runs both. You confirm timbers pending is 0 — non-negotiable, per Timbers, the Ledger. The worktree can stay around for follow-up beads on the same feature, or be removed:

git worktree remove .worktrees/opt-out-completion-email
git branch -d opt-out-completion-email

That is the loop, complete. From brief to merged pull request, every prior cairn has been put to work.

Beyond the repo

A few open questions sit beyond this cairn’s scope. Naming them is more honest than pretending the loop above is finished work.

bd ↔ GitHub bridge and the Project board. Both questions that used to live here have been answered. The bridge exists in the bd CLI (bd github sync/push/pull), but Strike deliberately doesn’t auto-enable it — bidirectional sync would pollute one side or the other. The choice between mapping the beads graph onto a Project board and keeping the two complementary came down decisively on the complementary side: the manual seam, with discovered and epic/<area> labels driving bead minting at claim time, is the methodology. Where the Work Lives is the dedicated walkthrough — directly upstream of this cairn in the trail.

Agile / scrum for agent teams. Sprint cadence, story-pointing, retrospectives, planning poker — what do those rituals look like when execution is cheap and the participants include agents? We are feeling our way. Retros and planning still happen; their rhythm is different. New hires are explicitly invited to bring opinions; this is one of the genuinely undecided parts of the practice.

The Constructured-specific plugin set. Tracked as an epic on the Project board; the plugin will pull the methodology and shared steering out of per-repo .claude/rules/ files and into a packaged plugin installed once per dev. Expect a follow-up cairn that updates the loop above with the team-specific commands and skills once the plugin ships. Until then, the loop runs on the dm-work plugins where they are installed and on agent native capabilities everywhere else.

Where this trail leaves you

You have read the philosophy (How We Build Here), the tool map (The Workshop), the three required practices (Beads, Timbers, Just), the agent harness (Claude Code as Daily Driver), your machine and trust model (Your Box and Your Trust Model), the second-opinion pattern (Codex as Second Opinion), the small power tools (Quiet Power Tools), the worktree pattern (Working in Parallel (Mostly)), the gates (Quality Gates), and now the integrated loop. That is the workflow.

The companion trail, Osprey Strike — From Emergency to Resolution, is the product. Now that you know how we work, that trail is what we work on — emergency callouts in fiber operations, the architecture that supports them, and the design choices that shape the system. The first cairn (When the Fiber Goes Dark) is a good entry point.

Welcome to the team. The work is in front of you; the trail above is how it gets done.

Summary

1. One loop, twelve cairns of context. (Trigger: a brief, a claim from the GitHub Project board, or an organic find you'll tackle this session) → bead → worktree → (spec pass) → execute → gates → commit → timbers → push → Q review → triage → merge → close.
2. Beads originate two ways. Spec-first (you state the change; the agent makes one or more beads with t-shirts) or board-claim (you pick a card off the GitHub Project; the agent reads it and mints the bead at claim time). Both converge at a well-formed bead in the graph. Whichever path, a clear bead body is the first deterministic constraint on the work. Discoveries you intend to defer to a future session file as GitHub issues (label discovered or epic/<area>), not beads — the bead is for active work; see Where the Work Lives.
3. Worktrees and bd worktree create for non-typo work. The bd form does the beads-side setup that makes bd ready work inside the worktree; git worktree add skips it. Branch isolation pays off as soon as a second piece of work shows up.
4. Local gates iterate via just check-fast; just check is the seatbelt before push. Auto-fix first; treat coverage failures as real failures.
5. Q reviews are first-class. Triage matrix: critical/important/nice-to-have. jq -n | gh api --input - is the working pattern for re-requesting review.
6. Browser-QA is honestly TBD. Possible today, not yet a default. File a bead with what works if you experiment.
7. Merge requires explicit user sign-off. Self-merging on green CI is the failure mode that skips the last layer of judgment.
8. Beyond the repo: agile-for-agent-teams, the Constructured plugin set. Still open; new hires welcome to bring opinions. The bd ↔ GitHub question that used to live here is answered — the bridge exists, we don't auto-enable it, and the workflow is in Where the Work Lives.

• The "wait for the user's go before merging" rule is universal, but the test we use for "non-trivial enough to need explicit go" is implicit. How would you write that test down so an agent applies it consistently — number of files changed, package scope, presence of schema changes, something else?
• Browser-QA is the trail's biggest TBD. Pick one shape for what good looks like (agent runs Playwright headlessly, agent narrates a headed run, agent writes Playwright tests but does not run them) and argue for it. Where would you start?
• The "Beyond the repo" section names four open questions. If you had to rank them by which one will most reshape the daily loop when it lands, which goes first, and why?

1. How We Build Here — Cairn 1. The argument under everything in this loop.
2. The Workshop — Cairn 2. The tool map this loop assumes is installed and working.
3. Beads, the Backbone — Cairn 3. bd create, bd ready, bd close, the issue graph that drives the loop.
4. Timbers, the Ledger — Cairn 4. The post-commit ritual; timbers pending must be 0 before close.
5. Claude Code as Daily Driver — Cairn 5. The harness, orientation ritual, and subagent pattern this loop runs in.
6. Just: One Place to Discover — Cairn 6. just check, just check-fast, just fix — the build verbs throughout.
7. Your Box and Your Trust Model — Cairn 7. The trust posture under which the agent runs the loop's mechanics.
8. Codex as Second Opinion — Cairn 8. The escalation when Q's review and your judgment diverge, or when convergence stalls.
9. Quiet Power Tools — Cairn 9. RTK and the CLI multipliers that compound across the loop without ever showing up as a step in it.
10. Working in Parallel (Mostly) — Cairn 10. The bd worktree create rule and the branch-isolation pattern this loop relies on.
11. Quality Gates: The Contract That Lets You Move Fast — Cairn 11. The exact thresholds and the cardinal rules.
12. Osprey Strike — From Emergency to Resolution — The companion trail. The product domain you have just learned to ship into.
13. gh api — Official GitHub CLI documentation for gh api. Required reading for the --input - pattern that fixes the array-valued payload trap.