oxFlow Wiki

ADR-0003 — BMAD outputs sync one-way from the codebase repo into docs/bmad/

3 min read

Context

When implementation on the oxFlow codebase starts (in a separate repo, tentatively 361-coders-nz/oxflow-app), it will run BMAD-METHOD. BMAD produces a structured set of planning artefacts in the codebase’s docs/ directory:

  • docs/product-brief-*.md
  • docs/prd-*.md, docs/tech-spec-*.md
  • docs/architecture-*.md
  • docs/stories/{epic}.{story}.story.md
  • docs/prd/, docs/architecture/ — sharded per-epic fragments
  • docs/bmm-workflow-status.yaml, docs/sprint-status.yaml

These artefacts are planning output of the code, but they are input to the team’s shared knowledge base. Readers of this monorepo need to see them alongside ADRs, research, and meeting notes — otherwise the wiki isn’t the single source of truth.

We want to pull BMAD output into this monorepo automatically, without letting it trample hand-written content, and without the wiki becoming a write-back path to the codebase. Three sync patterns were evaluated:

PatternVerdict
git submoduleRejected — agents forget --init --recursive; pointer-not-content confuses every Markdown tool.
git subtreeWorks, but pulls every codebase commit into this repo. Noisy. Re-sync is manual (git subtree pull).
CI auto-PR (rsync + GitHub Action)Recommended — decouples deploy cadences, gives a review gate, one-way flow only.

We will use a GitHub Action in the codebase repo that rsyncs its docs/ to this monorepo’s docs/bmad/ and opens an auto-PR on every push to main where docs/** changed.

Decision

Producer (codebase repo):

  • BMAD writes to the codebase’s docs/ per its v6 convention.
  • A GitHub Action on push: branches: [main] + paths: ['docs/**'] checks out this monorepo, runs meta/bmad-sync/sync.sh --from <codebase>/docs --to docs/bmad, and opens a PR.

Consumer (this monorepo, docs/bmad/):

  • All files under docs/bmad/ are owned by the sync PR. Humans do not edit them.
  • Each synced file gets a frontmatter stamp: bmad_source: <codebase-commit-sha> plus type: bmad.
  • Subfolders mirror the producer: docs/bmad/prd/, docs/bmad/architecture/, docs/bmad/stories/, etc.
  • docs/bmad/bmm-workflow-status.yaml (YAML, not markdown) is copied verbatim; docs/progress.md can render it for the birds-eye view.

Ownership rules:

  • Companion thoughts, deltas, discussions about a BMAD doc go in research/YYYY-MM-DD-<slug>.md or docs/decisions/NNNN-<slug>.md. They wikilink inward to the docs/bmad/... file.
  • Hand-editing a file under docs/bmad/ will be overwritten by the next sync. CI will flag it in the PR diff.

Conflict handling:

  • Additions (new BMAD files) → PR auto-merges if no conflicts.
  • Modifications / deletions of existing synced files → human review required.
  • The action’s auto-PR has a fixed branch name (bmad-sync/<codebase-sha>) so subsequent pushes update the same PR.

Alternatives considered

  • Submodule — ergonomic trap for agents; a submodule is a pointer, not content, so grep across docs misses it unless you init it.
  • Subtree — couples codebase and wiki histories. Every BMAD change becomes a wiki commit.
  • Manual copy — won’t survive first week of real sprint output.
  • Bidirectional sync — explicitly rejected. Bidirectional sync + multi-agent writes = merge conflict hell. Wiki is consumer only.

Consequences

Positive

  • BMAD output shows up in the wiki automatically, same graph/backlinks treatment as the rest.
  • Review gate on every sync — a human sees what changed before it lands on main.
  • Codebase and wiki deploy independently.

Negative

  • Needs the codebase repo to exist before wiring the Action. Phase 1 commits the contract spec and skeleton script; Phase 2 wires the Action.
  • Failing to register bmad_source means false positives in “hand-edited” checks; sync script must always set it.

Follow-up

  • Phase 2: wire the GitHub Action once the codebase repo is up.
  • Phase 2: add an apps/wiki/ component that surfaces docs/bmad/bmm-workflow-status.yaml on docs/progress.md.
  • Phase 2: add a CI check in this monorepo that fails PRs touching docs/bmad/** unless the actor is the sync bot.

References

Graph View

Backlinks