SDLC Standards

Every project runs the same six phases, and they’re the columns on every project board: Backlog → Plan → Design → Build → Test → Done. A card’s column is its phase. Moving a card means it has passed that phase’s gate.

Claude does the work; a person holds the gates. Each phase ends in two things:

• an artifact, a committed file the next phase reads
• a gate, a decision that has to be made before the card moves on

Gates are either human (accept, sign off, approve, merge) or automatic (checks pass). A card never skips a gate, but the work scales to the change. A typo or a one-line fix goes from Backlog straight to Build with a one-line plan, while anything new or touching several files starts at Plan.

The card id is the common key. Every card gets an id from its project key and a number that’s never reused, for example bb-07. That id ties everything together:

Where	Convention
Board	the card, BB-07
Product docs	folder bb-07-<slug>/ holding intent.md, spec.md, plan.md and mockups
Decisions	ADR frontmatter cards: [bb-07]
Code	branch bb-07-<slug>, commits bb-07: …, PR title [bb-07] …

With that, git log --grep bb-07 in either repository gives the card’s full history.

Principles

• Written before built. Intent, spec and plan exist before code, and they’re short.
• Small batches. One card = one branch = one pull request.
• Evidence over assertion. Nothing is “done” without fresh output: tests, type check, build, and a real run.
• Product documents and code live apart, linked by the card id. See Where documents live.
• The loop closes. Review findings and maintenance sweeps become new Backlog cards.

Two kinds of files come out of every card.

Product documents are the why and the what:

• intents, specs and plans
• UI mockups
• architectural decision records (ADRs)
• PRDs, research and notes

Code is the how:

• source and tests
• build and CI config
• the repository’s CLAUDE.md

The standard is that both live in git repositories, apart from each other, joined by the card id. Product documents shouldn’t clutter the code’s history or reviews, and code shouldn’t be the only place a decision is recorded. Below are three ways to arrange that, a recommendation, and a decision for you to make.

Decision needed. Pick one, then record the choice as the first ADR. Until then, cards keep their documents where they are today (docs/work/<date>-<slug>/ inside the code repository).

Shared conventions (all three approaches)

• Docs folder: bb-07-<slug>/ holds intent.md, spec.md, plan.md and mockups/, and is never renamed once created.
• ADRs: adr/NNNN-<title>.md, numbered per project. Frontmatter: status (proposed / accepted / superseded by NNNN), date, cards: [bb-07].
• Code side: branch bb-07-<slug>, commit prefix bb-07:, PR title [bb-07] …. The PR body links the docs folder.
• Mockups and images: stored with Git LFS so binary history doesn’t bloat clones.

A. A paired docs repository per project

fiddlers-fancy (code) sits next to fiddlers-fancy-docs (product), and every project gets its own pair.

Pros

• Clean separation, with one docs repository per codebase that’s easy to reason about.
• Access can differ: share the docs with a collaborator, designer or client without giving them the code.
• Each repository stays small, and LFS is only needed on the docs side.

Cons

• Repositories multiply: two per project.
• There’s nowhere to see across projects (“what’s in Design everywhere?”).
• Every card touches two repositories, and the docs and code changes can’t be committed together.
• Claude needs both checked out side by side (claude --add-dir ../fiddlers-fancy-docs) to read the spec while building.
• Links between the two rot unless CI checks them.

B. One central product repository for every project ★ recommended

A single hub repository holds every project’s documents:

• projects/<project>/work/bb-07-<slug>/
• projects/<project>/adr/
• projects/<project>/research/

Code repositories hold only code plus a CLAUDE.md that names the hub and the card-id convention. Build Buddy’s own repository is the natural hub, since it already holds every project’s board, and the board’s card ids are created in the same place as their docs folders.

Pros

• One place to read and search all product knowledge, across every project.
• The board and the docs live together: a card and its docs folder can be created in one commit, and Build Buddy can show a card’s intent, spec and plan right beside it.
• Portfolio views come cheaply (“every card in Design”, “every ADR this quarter”).
• One set of templates and skills, and one review habit, for every project.

Cons

• Each change still spans two repositories (hub for docs, code repository for code), so they can’t be committed together.
• Access is all-or-nothing: anyone who can read one project’s docs can read them all. If a project needs privacy, it gets its own hub, or approach A.
• The hub grows with every project, which LFS and occasional archiving keep in check.
• Claude, working in a code repository, has to reach the hub. Fix that once: an --add-dir alias, plus a small skill or hook that resolves bb-07 to the hub folder.
• While the hub is also Build Buddy’s app code, app changes and document changes share one history. The fix, when it matters, is to split the documents into their own product-hub repository that Build Buddy reads. The layout doesn’t change.

C. A docs repository mounted inside the code repository (git submodule)

Product documents live in their own repository (as in A), mounted read-write at /product in the code repository as a git submodule.

Pros

• Separate repository and history, so the separation is real.
• One checkout holds everything: Claude sees the spec and the code in the same tree, with no extra setup.
• Each code commit records the exact docs revision it was built against, the strongest traceability of the three.

Cons

• Submodules are easy to get wrong:
  • forgotten git submodule update
  • detached HEADs
  • clone --recursive
  • CI auth for a private submodule
• Every docs change needs two commits (inside the submodule, then the pointer bump), and pointer bumps add noise to code PRs.
• It gives the least cross-project visibility of the three, since every project’s docs repository is separate.

The recommendation

B, a central hub, because it matches how Build Buddy already works: files are the database, card ids are minted here, and the board is where the documents get read. Its two real weaknesses have known fixes:

• Reaching the hub from a code repository: an --add-dir alias and a card-id resolver skill.
• All-or-nothing access: a separate hub only for projects that need privacy.

Choose A instead if outside collaborators should see some projects’ documents but not others. Choose C only if pinning each commit to an exact spec revision matters more than everyday ergonomics.

Making it tractable whichever you pick:

• A commit-msg hook rejects commits without a card prefix.
• A PR template asks for the docs-folder link and the test evidence.
• A CI check fails a PR whose title has no card id, or whose card has no docs folder in the docs repository.

The goal is a main that’s always releasable, and a history where every change can be traced to a card and its documents. That means short-lived branches, one per card, and as few long-lived branches as possible.

Code repositories: trunk-based, one card per branch

main is protected:

• required status checks (tests, type check, build)
• linear history
• no direct pushes, and no force-push

On a solo project: GitHub never lets you approve your own pull request, so don’t require an approval. Allow the owner to bypass that rule, and treat the /code-review report in the PR as the review evidence.

Branch per card. bb-07-<slug>, from the latest main. Branches live for days, not weeks. If one is outgrowing that, the card was too big: split it.

Keep up by rebasing. git rebase main before review, not merging main into the branch. The PR then shows only the card’s own changes.

Commits: small and readable, prefixed bb-07:, with the Claude co-author trailer when Claude wrote them.

Pull requests:

• title [bb-07] <outcome>
• body: the docs-folder link, a summary of the change, test evidence and review findings
• open as a draft early if feedback helps

Squash-merge, then delete the branch. One commit per card on main keeps git log readable, and git revert <sha> undoes a whole card cleanly.

Stacked pull requests, only when a card truly depends on an unmerged one.

1. Base the child branch on the parent branch.
2. When the parent merges, rebase the child onto main. GitHub retargets the PR.
3. Keep stacks to two. Deeper stacks mean the cards were split the wrong way.

Releases:

• main deploys continuously, or from tags (v2026.10.2 for apps, semver for libraries).
• Hotfixes follow the same flow, just faster: a Backlog card marked #hotfix goes straight to Build with a one-line plan, then its own branch, the same checks and a patch tag. There’s no separate hotfix branch model.

Never:

• a long-lived develop branch
• merging with red checks
• “WIP” commits on main
• reusing a branch for a second card

Product documents: merge at the gates

Documents follow the same card branch name (bb-07-<slug>) in the docs repository, and merge as each gate passes rather than all at the end:

Gate passed	What merges to the docs main
Plan accepted	intent.md (status: accepted), or shelved with its reason
Design signed off	spec.md, mockups and any new ADRs (status: accepted)
Build plan approved	plan.md
Done (code merged)	the plan’s Deviations and the final status, alongside the code PR

That way the docs main always reflects decisions actually made. A half-written spec never reads as the plan of record.

After Done, documents are a record.

• Changes go in a dated Revisions section at the bottom.
• ADRs are superseded by a new ADR, never edited.
• Shelved intents stay, with their reason.

Keeping it tractable over time

• One join key. git log --grep bb-07 in the code repository, and the bb-07-* folder in the docs repository, give a card’s whole history from idea to merge.
• Automate the conventions so nobody has to remember them:
  • a commit-msg hook for the card prefix
  • a PR template
  • a CI check that the PR’s card exists and has a docs folder
• Small batches are the bug-prevention strategy. Smaller diffs get real reviews, rebase cleanly and revert cleanly.