Software work at Constructured shows up in two surfaces. One is a GitHub Project where humans coordinate, plan, triage, and report. The other is bd — a CLI issue tracker that holds the in-flight execution units that an agent or engineer is actively building from. Most teams pick one of these and force the other to live in its shadow: either everything happens in a SaaS tracker that engineers wrestle with all day, or everything happens in the IDE and the rest of the company is left guessing.

We use both. And the seam between them — when work lifts from beads into GitHub, when it descends from GitHub back into beads — is where the workflow actually lives. This cairn is a tour of that seam.

There are two natural audiences for that tour. People who plan, track, and report on the work want to know what they’ll see on the GitHub Project and how it relates to the conversation happening in code. People who build the work want to know how to file a discovery so a teammate can pick it up tomorrow, and how to claim something off the board to start on it today. The rest of this cairn alternates between those two views, with a shared opening on what the surface looks like.

The three categories

Before talking about either surface, it helps to name the three categories of work that flow through the system. The categorization is encoded in coordination-and-tracking.md inside the osprey-strike repo; here is the plain-English version.

Auto-review findings are issues filed by nightly review routines — small, scoped concerns about specific code that the routines spotted (a missing nil check, an unused export, a comment that contradicts the code beneath it). They live on the GitHub Project, labeled auto-review/<vertical>, and a separate routine triages them. The smallest of them get auto-fixed as draft PRs; the larger ones get dished out to people during planning.

Epics are multi-day, cross-cutting pieces of human-coordinated work — usually some combination of customer commitment, technical investment, or compliance concern. They live on the GitHub Project, labeled epic/<area>, and humans pick them up during planning sessions. They decompose into execution units when somebody is about to do the work, not before.

Discoveries are everything else — sub-day or few-day work an engineer noticed during a session but isn’t going to tackle in that session. The team’s prior pattern filed these as beads, then mined bd ready to figure out what to do next. The newer pattern hoists them to the GitHub Project at file time, labeled discovered, so casual coordination has a visible surface instead of a private one. The execution unit (the bead) comes into existence only when somebody is about to start work on it.

Key Takeaway

The shape: most work has a coordination form (a GitHub Issue) and a built form (a bead). The first surfaces it for the people deciding what to do. The second is the thing somebody is actively building from. They are not the same record.

The shared surface: Osprey Product Development

The board lives at https://github.com/orgs/Constructured/projects/1. It’s named Osprey Product Development — a deliberately broad title that covers product, ops, dev, and dev-adjacent work, with room for more repos to share it as the fleet grows. The Project has five named views, each tuned for a different audience or moment. None of them are sprint boards in a ceremonial sense; they are lenses on the same data.

All work is the default landing. A board layout, columns by Status (Triage → Ready → In progress → Blocked → In review → Done), sorted by Priority. It is everything in flight at any granularity — the auto-review queue, the epics, the discoveries — without any filter. Useful when the question is “what is going on right now?”

By priority is the same items, swimlaned by the Priority field. P1 critical items sit in their own row, then P2, then P3, then P4, then unset. Useful in planning when the question is “where are the high-priority items stuck, and on what?”

By assignee is a table grouped by Status and sliced by Assignees. You see who has what, and you see the unassigned-but-Ready pool — the candidate pool for the next person to pick something up.

Roadmap is a timeline. It filters to epic/* items only and plots them along their Start and Target dates. It is the only view that filters; everything else is unfiltered because the categories already separate themselves visually via labels and titles.

My work is assignee:@me. Each person’s daily landing.

Tip

Views are cheap to add and easy to delete. If the team finds itself filtering manually three times in a row, that filter wants to be a view. Don’t over-engineer the set upfront — it grows as the team finds gaps.

The Status field has six options. Triage is the default and the inbox. Ready means committed and pickable. In progress means someone is actively building. Blocked means stalled on something external. In review means a PR is open. Done means it closed. Items move between columns as the team works; agents and engineers are encouraged to keep Status current, and a quick scan during any sync catches drift.

Priority is P1 through P4, matching the existing bd convention. P1 is critical or blocking. P2 is important and soon. P3 is ordinary. P4 is backlog. The two systems share the scheme so an engineer never has to mentally translate priority numbers between the board and the CLI.

For people who plan, track, and report

If you are not writing code on a given day but you are responsible for keeping the team oriented — planning sessions, status conversations, weekly check-ins, customer communications — the board is most of what you’ll touch.

The natural rhythm has four moments, none of which require a formal ceremony.

Triage glance. Items land in the Triage column when they arrive — auto-review findings the routines just filed, epics someone wrote up between sessions, discoveries an engineer hoisted during yesterday’s work. Triage is the inbox. The question to ask of each one is what does this need to move forward? Sometimes that’s “nothing, this should be picked up next” → move to Ready. Sometimes “we need to talk about whether to do this at all” → leave in Triage with a Priority bump or a comment. Sometimes “this is unclear” → comment with a clarifying question and let it sit until the right person answers.

Capacity scan. Open By assignee. Each row is one person’s queue. Unassigned items in Ready are the candidate pool for whoever picks next. Items in In progress are the cards under the team’s collective hand. If someone is stretched, you’ll see it visually. If someone is unloaded, you’ll see that too. The view is a conversation prompt, not a verdict — capacity isn’t always what the columns suggest, but the columns are a useful starting point.

Roadmap check. Open Roadmap. Epics with Start and Target dates plot themselves as bars. Without dates they appear as flat rows, which is itself useful — those are epics the team has committed to doing but not to a timeframe for. The conversation the Roadmap supports is “are these the right things in roughly the right order, and is there anything we’re surprised by?”

Status touch-ups. Things move between columns as the team works. Ready → In progress when someone claims a card. In progress → Blocked when an external dependency stalls it. Blocked → Ready or In progress when the block clears. In progress → In review when a PR opens. In review → Done on merge. You don’t need to enforce these transitions; the team is encouraged to keep them current, and a planning-session scan catches any drift.

Key Takeaway

The board exists to keep coordination visible. It does not exist to track time spent, predict completion, or enforce a methodology. Use it the way you’d use a whiteboard — to see where things are, not to grade where they should be.

Reporting outward

When you need to tell a customer or a stakeholder what’s happening, the board is the source. Pick the Roadmap view for “what’s next and roughly when”; pick All work for “what’s in flight right now”; pick By priority for “where the urgent things are.” The advantage over a bespoke status doc is that the board is always current — engineers update Status as they work, and the views recompute automatically. The disadvantage is that the board is internal-facing; for external communications you will usually want to filter or rewrite for the audience.

A note on methodology

This cairn deliberately doesn’t prescribe scrum, kanban, or any of the other named methodologies. The team’s planning rhythm is for the team to decide. What this surface supports well: a regular cadence (weekly is a reasonable starting point) for triaging the inbox column, scanning capacity, and revisiting the Roadmap. What it does not support: ceremonial overhead that exists for its own sake. If a ritual is helping the team see and decide together, keep it. If a ritual exists because somebody read a book once, drop it.

For people who build

If you spend most of your day in code, the board still matters — it is the surface where work arrives and departs — but most of your interaction with the system is through bd and Claude Code, with the board as a periodic reference.

The mental model has three parts.

Discovery hoists to the board, not to beads. When you find something mid-session that you’re not going to tackle in that session — a brittle pattern adjacent to what you’re touching, a missing test, a doc inconsistency — file it on the board with the discovered label. The old pattern of filing a bead for it and trusting bd ready to surface it later is on its way out; it worked when the team was small and tightly coupled, but headless coordination doesn’t scale to new contributors or to people who don’t run bd locally. The board is the visible surface.

The filing recipe is in coordination-and-tracking.md. In practice it is a short gh api POST invocation, or — if you are talking to Claude Code — a one-line request like “file a discovered issue for the brittle thing in Foo.tsx:42 — I won’t get to it today.” The agent knows the recipe and produces a well-formed issue.The discovered-vs-bead choice is small enough that it can feel like premature ceremony for a one-line fix. The shift in habit is the point: the board is where the team coordinates, and the cost of a one-line GitHub issue is roughly the cost of a one-line bead, while the visibility gain is meaningful.

Beads come into existence at claim time. A bead is an active unit of execution — something somebody is in the middle of building. It is not the place a discovery lives until someone claims it. When you claim a card off the board, that’s the moment a bead gets minted.

Two flows for the claim, both documented in the rule:

Flow A — UI-first
@dev [Assigns #N to self in GitHub, moves to In progress]
@dev Let's tackle #N — please mint the beads and set me up.
@Claude Read #N. Filing one bead since it's labeled discovered and looks like a single-session fix. Bead os-aaaa carries the GH URL in its design field. Ready when you are.
Flow B — Claude-first
@dev Let's work on #N.
@Claude Read #N. It's an epic with three acceptance criteria — decomposing into three beads. Assigned you on GitHub, moved Status to In progress. Beads os-aaaa, os-bbbb, os-cccc, sequenced. Starting on os-aaaa.

Neither flow is more correct than the other. Pick whichever matches what you’re already doing. The artifact at the end is identical: a GitHub issue assigned to a human with Status=In progress, plus one or more beads carrying the GH URL in their design field.

The bead carries the GH URL; the GH issue references the bead(s). This is the back-reference that makes the seam navigable. Anyone reading the bead in isolation finds the parent context one click away. Anyone reading the GH issue sees which beads it decomposed into in the issue body’s Beads section. When a PR merges with Closes #N in the body, GitHub closes the issue automatically; for epics, you close the parent issue after all child beads are done, with a wrap-up comment.

Tip

The –design field on the bead is the single most important link in this system. If a bead doesn’t carry the GH URL, the bead is orphaned — anyone picking it up later has no context for why the work matters. Make the link non-negotiable.

Why the round-trip

The bead-from-GH pattern feels heavier than just bd create until you’ve worked alongside a teammate who picked something off the board you had already started in beads. The board is the dedupe mechanism, the social coordination layer, the place a manager or product partner can scan to know what is happening. Beads-as-discovery silently strips all of that.

About targets

A note on time before any further operational detail. The Roadmap view has a Start date and a Target date. Both are optional. Both are targets, not commitments measured against velocity — because we don’t have a velocity. A part-time three-person team with heavy agent assist is not the kind of team that has produced enough work in enough cycles for “we’ll ship X by Y” to be a math-supported claim. Pretending otherwise would be theatre.

What targets are useful for is sequencing and forecasting at a coarse grain. If we say “we’d like to ship the multi-replica work before customer X scales their installation,” that’s a target — a useful one for prioritization and external planning, but soft. If the work takes longer (it usually does, even with agents), the target moves. The Roadmap is a forecast, not a contract.

Warning

Velocity numbers will appear at some point — beads tracks closure rates, GitHub tracks merge rates, the patterns will eventually be measurable. Until then, resist the temptation to set targets as if they were measured commitments. Honesty is cheaper than recovery from a missed promise.

The deeper principle: an agile mindset means treating the plan as the thing we update when we learn, not the thing we defend. Both the board and the beads support that. Moving an item from Ready back to Triage because of new information is a feature, not a failure. So is moving a Target date forward because we underestimated, or backward because we overestimated. The board is a tool for seeing reality, not a record for grading it.

What auto-review is doing on the same board

If you scroll the board on any given morning, you’ll see auto-review items in among the human-filed work. These come from nightly routines that read the codebase, identify concerns, and file structured GitHub issues — small ones the routines may auto-fix as draft PRs (an XS or S finding becomes a small PR with a banner saying humans should still review this), larger ones that get dished out to people during planning.

For the planning audience, auto-review items are the team’s technical-debt drip-feed. They surface real issues we would want to address but probably wouldn’t have noticed on our own. A triager routine filters them — items deemed not-a-bug or already-fixed get closed, the rest get a triaged label and rejoin the pool. Items larger than the auto-fixer can handle land back in front of humans the same way any epic or discovery does.

For the engineering audience, auto-review items are a steady stream of work you can pick from when you have an hour between bigger things. Many of them are 10-line fixes with citations to a specific file and line. They are a low-friction way to get familiar with parts of the codebase you don’t work in often.

The important thing is that the auto-review pipeline and the human-discovery pipeline use different label namespaces (auto-review/* versus discovered, with epic/* as the third namespace). That separation means the auto-review routines never confuse a human-filed issue for one of their own (and vice versa), and views can filter by namespace when you want a focused lens.

Where the bridge fits, and doesn’t

A bidirectional sync between beads and GitHub Issues exists — bd github sync/push/pull will round-trip records between the two. We don’t use it by default, and the rule is explicit about why: bidirectional auto-sync would either pollute the beads ready queue with auto-review noise or flood the Project board with sub-day bead churn. Either failure mode is worse than the manual seam.

The bridge does have two legitimate uses, both rare:

  • An epic that originated as a bead (because you thought it was small) and now needs human visibility on the board → push the bead and its descendants in one command.
  • A GitHub issue you specifically want bead dependency graphs on → pull it into beads selectively.

Outside those cases, the seam is intentional. The two surfaces have different purposes, different rhythms, and different audiences. Forcing them to be mirrors of each other costs more than the asymmetry does.

Where this is heading

The methodology lives in this repo’s .claude/rules/coordination-and-tracking.md today. As more Constructured repos join the fleet, that per-repo file is going to drift between copies — each repo would carry its own version, and the versions would age independently. The next step on this thread is a Constructured Claude Code plugin (tracked as epic #192 on the same board) that pulls the steering into a shared package. Install once per developer; applies uniformly across repos. The board, the labels, and the workflows all stay; the rule file becomes a published artifact rather than a repo-resident one.

Until then, the rule is the source of truth. The board is the live surface. The beads are where the work actually gets built. The seam between them is the workflow.

  1. Two surfaces, one workflow. The GitHub Project is the coordination surface; beads is the execution surface. Both exist on purpose, and the movement between them is the workflow itself.
  2. Discoveries hoist to the board. Items found during a session but not tackled in it get filed as GitHub issues with the discovered label, not as beads. Beads come into existence at claim time.
  3. Five views, one Project. All work, By priority, By assignee, Roadmap, My work. Each is a lens for a different audience or moment. Add more as gaps emerge; delete any that go unused.
  4. Targets, not commitments. The Roadmap dates are forecasts. We don't have a measured velocity yet; until we do, dates exist for sequencing and external coordination, not for grading the team.
  5. Disjoint label namespaces. auto-review/*, epic/*, and discovered never overlap. The routines and the humans share a surface without conflicting on records.
  6. The bead carries the GH URL. The --design field's first line is the GitHub issue link. Without it, the bead is orphaned from its context.
  • Where does your team currently coordinate work that doesn't live in code yet? Is that surface visible to everyone who needs it, or is it private to whoever runs the tool?
  • When a new contributor joins, how do they discover the existing in-flight work? Is the path the same as the path their teammates use, or is it parallel?
  • What's your team's current relationship to dates on planning artifacts — forecasts you update when you learn, or commitments you defend? What would change if you treated them as the other?
  1. coordination-and-tracking.md — The methodology file inside the osprey-strike repo. The rule this cairn is the long-form companion to.
  2. Osprey Product Development project — The live board. Five views, one Project, fed by labels.
  3. Beads, the Backbone — The companion cairn on beads itself. Read this for the execution-side substrate.
  4. How We Build Here — The trail opener on Strike's overall engineering culture. Sets the scaffolding-for-agents framing.
  5. Beads on GitHub — The CLI tracker source, install instructions, and changelog.