Challenge

Challenge: Unify BFDev Authoring for Agent-Led and Parallel Product Development¶

How might we make bf-dev the one authoritative BetterFleet authoring repository, so contributors and agents can work across services as one product surface, run side-by-side worktree-based comparisons safely, and reduce the Git friction that currently blocks holistic testing and delivery?

Motivation¶

The current bf-dev model is a local orchestration harness around many separately cloned service repositories, which means one product change often becomes several repository-specific authoring tasks.
That split is especially costly for agents, because branch management, review context, and change tracking are fragmented across multiple Git roots instead of one coherent workspace.
The immediate pressure is not only contributor convenience. BetterFleet also needs a practical stepping stone toward side-by-side validation workflows such as blue/green-style local comparisons, backwards-compatibility checks, and current-vs-upcoming version testing using separate worktrees.
In the current model, those experiments are awkward because one comparable environment may require several repositories to be branched, aligned, and checked out consistently.
Until the authoring surface becomes product-oriented rather than repo-oriented, full-stack testing, parallel experimentation, and small vertical slices will keep carrying unnecessary coordination overhead.

Context¶

Today bf-dev bootstraps and orchestrates downstream BetterFleet repositories, but it does not act as the primary authoring repository for the code those repos contain.
Full-stack work regularly crosses service boundaries even when the user-visible outcome is one coherent product change.
The current repository topology exposes service and repository boundaries directly to contributors and agents during authoring, even when those boundaries are not helpful to the work being done.
BetterFleet wants to improve the authoring model without silently changing runtime/service boundaries. ADR 0014 - Service Granularity still governs service architecture separately from repository topology.
The intended change is therefore a Git-authoring and workflow challenge: make product-oriented change easier while preserving the current delivery-repository model during transition.

Domain Modelling¶

Domain: BFDev repository topology and contributor authoring workflow.
Core entities:
Authoring repository
Imported project directory
Upstream repository binding
Branch
Worktree
Vertical slice
Comparison environment
Downstream sync path
This challenge sits between developer ergonomics, agent operating constraints, local testing workflows, and release continuity for the current service repos.

High-Level Use Cases / JTBD (Required)¶

As a contributor, I want to work across BetterFleet services from one repository so I can deliver one product slice without repeating branch, commit, and review setup in every downstream repo.
As an agent, I want one coherent Git workspace so I can reason about, change, and validate a cross-service slice without reconstructing intent across multiple repository histories.
As a developer validating a risky change, I want one worktree for the current version and another for an upcoming version so I can compare behavior, verify backwards compatibility, and inspect regressions side by side.
As an engineering lead or reviewer, I want one review surface for a multi-service product change so I can assess the whole slice end to end rather than as several disconnected merge requests.
As a platform maintainer, I want contributors to stop caring about downstream repository mechanics during day-to-day authoring while still preserving safe synchronization to the current delivery repositories during transition.

Current State -> Desired State¶

Current State (Pain/Gain)	Desired Outcome	Success Measure
Pain: one product-facing change often requires repeated branch, commit, push, and merge-request handling across several downstream repositories	One product-facing slice can be authored and reviewed from one authoritative repository	A contributor can complete a cross-service slice with one branch/worktree and one contributor-facing MR
Pain: agents must operate across several Git roots, which fragments context, increases coordination overhead, and makes automation less reliable	Agents can work against one coherent authoring surface	Agent-driven tasks can inspect, edit, and validate a cross-service change from one workspace without per-repo orchestration
Pain: side-by-side testing of current versus upcoming versions is awkward because multi-repo alignment across worktrees is cumbersome	Parallel worktrees become a practical way to compare versions and behaviors safely	A developer can stand up two comparable worktrees for the same slice and use them for blue/green-style local validation or backwards-compatibility checks
Pain: the current repo topology keeps service/repository boundaries front-and-center even when the user outcome is one product change	Contributors experience BetterFleet authoring as one product surface rather than many repo surfaces	Normal authoring flow no longer requires contributors to think in per-service Git steps
Gain to protect: service-level delivery pipelines and repository ownership already exist and should keep working during transition	Authoring becomes simpler without breaking current downstream delivery continuity	Downstream repositories remain synchronizable and deployable while the new authoring model is adopted

Assumptions & Open Questions¶

Key assumptions:
The immediate problem is authoring topology, not runtime consolidation.
Better agent ergonomics is a primary business and engineering driver, not a side benefit.
Worktree-based comparison workflows are valuable enough to justify topology changes even before any larger BetterFleet-wide repo strategy is decided.
Contributors should usually experience downstream repositories as an implementation detail rather than a primary workspace concern.
Trunk-friendly small vertical slices remain the preferred delivery shape, consistent with ADR 0006 - Trunk-Based Development.
Open questions:
Which comparison workflows matter most in the first release: blue/green local validation, backwards-compatibility checks, regression comparison, or parallel exploratory spikes?
What degree of environment parity is needed for side-by-side worktree validation to be trusted by teams?
Which downstream repositories, if any, may still need temporary exceptions during migration because of size, sensitivity, or ownership complexity?
At what point does downstream sync remain a transition concern versus a longer-term permanent model?
Validation plans (who/what/when):
Validate with contributors and agents that the dominant friction is the authoring/review surface rather than only bootstrap tooling.
Validate with engineering that two-worktree comparison flows become materially easier under the proposed authoring model.
Validate with platform/release stakeholders that any transition approach preserves current downstream delivery safety.

Constraints & Out of Scope¶

Constraints:
The challenge must stay scoped to bf-dev-monolithic-git, not a broader BetterFleet-wide repository strategy.
Repository-topology consolidation must remain explicitly separate from runtime or service consolidation.
Any automation introduced for downstream synchronization must satisfy ADR 0007 - Generalised principle for automation: safe, worthwhile, and observable.
Existing downstream repositories must continue supporting current CI, deployment, and infrastructure ownership during transition.
Out of scope:
Redesigning BetterFleet service boundaries.
Collapsing services into one runtime monolith.
Designing every implementation detail of subtree sync, bootstrap scripts, or CI execution in the challenge itself.
Solving the full BetterFleet-wide product-engineering repository model in this pass.

Evaluation¶

User value:
Contributors spend less time on repository mechanics and more time on the product slice they are changing.
Agents get a workspace that is easier to reason about and safer to operate within.
Developers can run more realistic side-by-side comparisons between current and upcoming versions without reconstructing several repos in lockstep.
Business value & strategic alignment:
Better agent ergonomics improves the quality and speed of assisted delivery work.
Easier parallel experimentation and compatibility checking reduces risk around larger cross-service changes.
A product-oriented authoring surface supports the BetterFleet preference for small, trunk-friendly vertical slices rather than fragmented multi-repo batches.

Risks & Opportunities¶

Risks:
The initiative gets mistaken for a runtime-monolith proposal and widens into service-architecture debate.
The workflow simplifies authoring but leaves comparison/testing ergonomics too vague to produce the intended blue/green-style benefits.
Downstream synchronization becomes opaque or brittle, which would trade one form of friction for another.
Contributors keep falling back to per-repo habits if the new authoring model is only partially coherent.
Opportunities:
Make agent-led cross-service work materially more reliable.
Turn worktrees into a normal tool for comparison, validation, and parallel experimentation rather than a niche workaround.
Shift BetterFleet authoring from repo-fragmented thinking toward product-oriented delivery without prematurely changing runtime architecture.

Relationships¶

Related projects:
BFDev Monolithic Git specification
BFDev Monolithic Git stories
Platform Architecture
Upstream/downstream dependencies:
This challenge feeds the existing bf-dev-monolithic-git specification and story set.
The active specification should remain aligned to this challenge rather than broadening into runtime/service consolidation.
The eventual canonical governed challenge should live in Index even though this repo-local working artifact supports the current BFDev documentation set.

Solution Ideas & Tradeoffs¶

Idea A (Preferred): make bf-dev the primary authoring repository while keeping downstream repositories in place for delivery continuity during transition.
Best for reducing contributor and agent friction quickly without forcing an all-at-once delivery-platform rewrite.
Idea B: keep the current multi-repo topology and improve it only with better scripts and conventions.
Lower immediate migration cost, but likely preserves the core problem that authoring and testing context stay fragmented across repositories.
Idea C: delay authoring-topology change until a broader BetterFleet-wide repository strategy is ready.
More globally coherent, but blocks the immediate need for better agent ergonomics and side-by-side worktree testing.
Tradeoffs to compare:
immediate workflow gain versus migration complexity
authoring simplicity versus downstream sync complexity
faster experimentation versus transition risk
local comparison power versus additional workspace/tooling expectations
Preferred direction:
Idea A, because it addresses the immediate friction directly and creates a practical stepping stone toward worktree-based comparison workflows without requiring a full platform-wide restructuring first.

Release Sequencing¶

Natural or value-based order:
First establish one authoritative authoring surface in bf-dev.
Then preserve or automate safe downstream synchronization for delivery continuity.
Then prove the workflow through real cross-service slices and side-by-side comparison use cases.
Later, decide whether broader BetterFleet-wide repository consolidation is still justified.
Smaller parts to solve first:
Remove per-repo authoring friction.
Make worktree-based parallel comparison practical.
Keep downstream delivery continuity explicit and safe.
Potential slices/releases:
Slice 1: unified bf-dev authoring surface and operating model
Slice 2: safe downstream synchronization and contributor/reviewer workflow hardening
Slice 3: explicit side-by-side validation patterns for current-versus-upcoming comparisons