docs(agent): bb-driven per-workspace convention discovery (#25)

[daniel-pittman]

Summary

Part B of #25 — documents the pattern for populating the agent's per-workspace conventions using bb itself. (Part A — populating the maintainer's local ~/.claude/agents/bitbucket.md from real workspace discovery — is machine-local and not in this repo.)

Now that v1.2.0 ships bb workspaces + workspace auto-detect, the agent's conventions section can be a mechanical bb-driven survey instead of a from-memory guess.

agents/bitbucket.md (generic template)

• Rename "Project-specific conventions" → "Per-workspace conventions" and restructure from one flat block to a per-workspace template (one block per workspace slug + a top-level default for repo-less commands), matching the v1.2.0 multi-workspace resolution model.
• Add the read-only discovery survey (bb workspaces / bb repo / bb pipelines / bb branches / bb vars / bb pr) that derives every field, with a copy-per-workspace markdown template.
• New operating principle Phase 4.5: git_ops — git-context wrappers for the MCP agent #6 "Populating conventions from bb": when delegated work in a workspace with no block yet, the agent runs the survey and proposes a filled-in block for confirmation rather than interrogating the user. Real values → local copy only.

README.md (agent-install section)

• Install step 2 now shows the bb discovery commands to populate the per-workspace blocks.
• Renamed all "Project-specific conventions" references; updated the with-agent comparison-table row to "reads (or bb-discovers and proposes)" the block.

Stays fully generic — placeholders only, with the standard "real values belong in your local ~/.claude/agents/ copy, never upstream" guardrail reinforced.

Test plan

• pytest — 388 tests pass (docs-only; no code touched)
• Reviewer: confirm the template + survey commands are accurate against the v1.2.0 CLI surface and contain no real workspace data

Closes #25.

[claude]

Claude finished @daniel-pittman's task in 3m 56s —— View job

---

Code Review — PR #20 (docs(agent): bb-driven per-workspace convention discovery)

• Gather context (read changed files + diff vs origin/develop)
• Verify survey commands against the v1.2.0 CLI surface
• Check for accidental real workspace data
• Post review feedback

I reviewed this docs-only PR with the reviewer's explicit ask in mind: are the survey commands accurate against the v1.2.0 CLI, and is there any real workspace data? I verified every documented command and output-label citation against bb itself.

Verification — all survey commands check out ✅

Doc claim	Verified against bb
bb workspaces enumerates workspaces	cmd_workspaces exists (bb:1243, case workspaces|ws)
bb -w <ws> repos	global -w/--workspace flag parsed pre-dispatch (bb:1589-1609) + cmd_repos (bb:1312)
bb repos shows recency	sorts -updated_on, UPDATED column (bb:1318-1320) — "(+ recency)" accurate
bb repo → "Main branch" field	literal label " Main branch: " (bb:1349) ✅
bb pipelines → TRIGGER column	TRIGGER header (bb:355); value is selector.pattern // trigger.name — "filter out plain branch names" caveat is correct
bb branches → branch naming	cmd_branches exists (bb:1145)
bb vars → SECURED=true rows	SECURED column renders .secured | tostring → true/false (bb:1407-1418) ✅
bb pr <id> → reviewers / author	cmd_pr_view prints Author, Reviewers, Approvals (bb:828, 840-845) ✅

No real workspace data. Only generic placeholders appear (acme/widget-service, deploy-prod, <slug>, <ws>, <repo>). The "real values → local copy only" guardrail is reinforced in both files.

The restructure into per-workspace blocks + the new operating principle #6 are internally consistent (the cross-reference "see 'Populating conventions from bb' under Operating principles" matches the new ### 6. heading).

Minor findings (terminology drift — non-blocking)

The PR renames "Project-specific conventions" → "Per-workspace conventions" everywhere except two spots in README.md that the rename missed:

1. README.md:322 — still reads "…and the project-conventions checklist for tracking per-workspace defaults." This line is doubly stale: the section is no longer a flat checklist (it's now a per-workspace template), and the name no longer matches. Consider: "…and the per-workspace conventions block for tracking each workspace's defaults."
   Fix this →

2. README.md:365 — the comparison-table row label is still **Project conventions** though its value cell was updated to reference the "Per-workspace conventions" block. Minor; arguably fine as a generic category name, but inconsistent with the PR's rename intent.

Neither is a correctness bug — both are cosmetic consistency nits. The substance (commands, labels, guardrails) is accurate and ships-ready.

Note: --comment was requested, but inline PR-review comments aren't available in this mode (I can only update this single comment), so findings are consolidated here.

[claude]

Claude finished @daniel-pittman's task in 3m 7s —— View job

---

Code Review — PR #20 (docs(agent): bb-driven per-workspace convention discovery)

• Gather context (read changed files + diff vs origin/develop)
• Verify survey commands against the v1.2.0 CLI surface
• Check for accidental real workspace data
• Confirm prior review findings (README rename) were addressed
• Post review feedback

Re-reviewed after the synchronize. This is a clean docs-only change (README.md, agents/bitbucket.md); no code touched. I re-verified every survey command against bb and confirmed the two terminology nits from the earlier review are now fixed.

Survey commands — all accurate against the CLI ✅

Doc claim	Verified
bb workspaces enumerates workspaces	cmd_workspaces (bb:1243), case workspaces|ws (bb:1652)
bb -w <ws> repos	-w/--workspace parsed pre-dispatch (bb:1591-1595); cmd_repos (bb:1312)
bb repos "(+ recency)"	sorts sort=-updated_on, UPDATED column (bb:1318-1320)
bb repo → "Main branch"	literal label (bb:1349)
bb pipelines → TRIGGER col	header (bb:355); value .target.selector.pattern // .trigger.name // "-" (bb:365) — "filter out plain branch names" caveat is correct
bb branches → naming convention	cmd_branches prints BRANCH sorted -target.date (bb:1145-1167)
bb vars → SECURED=true rows	SECURED column (bb:1407)
bb pr <ws>/<repo> <id> → reviewers/author	cmd_pr_view prints Reviewers/Approvals (bb:811, 840, 852), case pr|pr-view (bb:1638)

Prior findings — resolved by cfcd6da ✅

• README.md:322 now reads "…the per-workspace conventions block for tracking each workspace's defaults."
• README.md:365 table row relabeled to Per-workspace conventions.
• grep for Project-specific / Project conventions across both files returns zero hits — rename is complete.

No real workspace data ✅

Only generic placeholders (acme/widget-service, deploy-prod, <slug>, <ws>, <repo>). The "real values → local copy only" guardrail is reinforced in both files. Operating principle #6 is numbered correctly after 1–5 (agents/bitbucket.md:145) and its cross-reference at line 274 matches the heading.

Minor (non-blocking)

1. "Main branch = default destination branch" is imperfect for GitFlow repos. bb repo surfaces the repo's mainbranch (bb:1349), but a GitFlow workspace — like this very repo, where PRs target develop while mainbranch is main — takes PRs against a different branch than the survey would suggest. The template field is a placeholder hint and principle Phase 4.5: git_ops — git-context wrappers for the MCP agent #6 is propose-and-confirm, so this self-corrects in practice; consider a one-line caveat (e.g. "verify against the team's PR base — GitFlow repos often target develop, not mainbranch").
   Fix this →

2. Survey list differs slightly between the two locations. The conventions-section survey (agents/bitbucket.md:258-266) includes bb -w <ws> repos, but principle Phase 4.5: git_ops — git-context wrappers for the MCP agent #6 (bb:147-153) omits it. Harmless — Phase 4.5: git_ops — git-context wrappers for the MCP agent #6 is about deriving fields, not enumerating repos — but worth aligning if you want them identical.

Neither affects correctness. Substance (commands, labels, guardrails, rename) is accurate and ship-ready.

Note on --comment: inline PR-review comments aren't available in this mode — I can only update this single comment, so findings are consolidated here.

[claude]

Claude finished @daniel-pittman's task in 3m 15s —— View job

---

Code Review — PR #20 (docs(agent): bb-driven per-workspace convention discovery)

• Gather context (read changed files + diff vs origin/develop)
• Re-verify survey commands against the v1.2.0 CLI surface
• Review the new commit (692da2a — GitFlow caveat + survey alignment)
• Check for accidental real workspace data
• Post review feedback

Re-reviewed after the synchronize that added 692da2a (the round-2 nits). Still a clean docs-only change (README.md, agents/bitbucket.md); no code touched. I re-verified the survey commands against bb directly and confirmed both round-2 findings are addressed.

692da2a — round-2 nits resolved ✅

• GitFlow PR-base caveat added in both spots:
  • Principle Phase 4.5: git_ops — git-context wrappers for the MCP agent #6 (agents/bitbucket.md:153): "…the 'Main branch' field — but verify the actual PR base; GitFlow repos take PRs against develop, not the mainbranch".
  • Survey block (agents/bitbucket.md:268-269): same caveat inline.
  • This is accurate — this very repo is the example: the PR targets develop while mainbranch is main.
• Survey lists now aligned: principle Phase 4.5: git_ops — git-context wrappers for the MCP agent #6 (bb:152) now includes bb -w <ws> repos, matching the conventions-section survey (bb:267). The earlier divergence is gone.

Survey commands — re-verified against the CLI ✅

Doc claim	Verified
bb repo → "Main branch" field	literal label " Main branch: " → .mainbranch.name (bb:1349)
bb pipelines → TRIGGER column	header (bb:355); value .target.selector.pattern // .trigger.name // "-" (bb:365) — "filter out plain branch names" caveat correct (branch is the separate BRANCH/ref_name column)
bb vars → SECURED=true rows	SECURED column → .secured | tostring (bb:1407,1414)
bb workspaces / bb -w <ws> repos / bb branches / bb pr <ws>/<repo> <id>	confirmed in the two prior reviews; unchanged by this commit

Internal consistency ✅

Principle #6 is numbered correctly after 1–5 (bb:145); its cross-reference (bb:276-277, "see 'Populating conventions from bb' under Operating principles") matches the heading. README round-1 nits stay resolved (README:322 reads "per-workspace conventions block…"; comparison-table row relabeled).

No real workspace data ✅

Placeholders only (acme/widget-service, deploy-prod, v*, feature/TICKET-NNN-…, <slug>, <ws>, <repo>). The "real values → local copy only" guardrail is reinforced in both files.

Minor (non-blocking, optional)

1. The GitFlow caveat doesn't travel with the copy-per-workspace template. The template field that users actually paste (agents/bitbucket.md:285) still reads "Default destination branch: (from bb repo → Main branch)" — i.e. it reintroduces the exact mainbranch = destination-branch conflation that the caveat at :268-269 / principle Phase 4.5: git_ops — git-context wrappers for the MCP agent #6 just warned against. A reader who copies only the template block loses the warning. Consider appending "— but confirm the actual PR base" to that field so it's self-contained.
   Fix this →

2. The "copy per workspace" block bundles a once-only field. The block at agents/bitbucket.md:281-291 is introduced as "Template — copy per workspace" but begins with the top-level **Default workspace** line (:282), which is not per-workspace. Copying the block verbatim for each workspace would produce N duplicate "Default workspace" lines. Minor — splitting the top-level default out of the per-workspace ### Workspace: block would make the "copy per workspace" instruction literally correct.
   Fix this →

Neither affects correctness. The substance — commands, output labels, GitFlow caveat, survey alignment, rename, guardrails — is accurate and ship-ready.

Note on --comment: inline PR-review comments aren't available in this mode, so findings are consolidated in this single comment rather than posted inline.

[claude]

Claude finished @daniel-pittman's task in 3m 27s —— View job

---

Code Review — PR #20 (docs(agent): bb-driven per-workspace convention discovery)

• Gather context (read changed files + current merged state)
• Review the new commit (1ca1bd8 — README GitFlow PR-base caveat)
• Re-verify survey commands against the v1.2.0 CLI surface
• Check for accidental real workspace data
• Post review feedback

Re-reviewed after the latest synchronize. This PR is now merged into develop, so this pass is confirmatory — I verified the final state of both files (README.md, agents/bitbucket.md) against bb itself. Still docs-only; no code touched.

Survey commands — all accurate against the CLI ✅

Doc claim	Verified against bb
bb workspaces enumerates workspaces	cmd_workspaces (bb:1243), case workspaces|ws (bb:1652)
bb -w <ws> repos	-w/--workspace parsed pre-dispatch (bb:1591)
bb repo → "Main branch"	literal label " Main branch: " + (.mainbranch.name // "n/a") (bb:1349)
bb pipelines → TRIGGER col	header (bb:355); value .target.selector.pattern // .trigger.name // "-" (bb:365) — "filter out plain branch names" caveat is correct (branch-triggered runs surface the branch name here)
bb branches → naming convention	cmd_branches (bb:1145), case branches|br (bb:1648)
bb vars → SECURED=true rows	SECURED column (bb:1407)
bb pr <ws>/<repo> <id> → reviewers/author	cmd_pr_view prints Author/Reviewers/Approvals (bb:828, 840, 852), case pr|pr-view (bb:1638)

Prior review findings — all resolved ✅

1. GitFlow "Main branch" caveat (round-2 finding Add OSS hardening: CI, Claude reviews, CODEOWNERS, SECURITY, CONTRIBUTING #1) — now present in all three survey locations:

   • agents/bitbucket.md:153 (principle Phase 4.5: git_ops — git-context wrappers for the MCP agent #6) and :268-269 (conventions section): "verify the actual PR base; GitFlow repos take PRs against develop, not the mainbranch"
   • README.md:337 (this PR's new commit 1ca1bd8): "Main branch (verify PR base; GitFlow repos target develop)"

   The caveat is well-motivated and self-referential: this very repo surfaces mainbranch=main via bb repo (bb:1349) yet takes PRs against develop. Combined with principle Phase 4.5: git_ops — git-context wrappers for the MCP agent #6 being propose-and-confirm, the placeholder hint self-corrects in practice.

2. Survey-list alignment (round-2 finding Phase 4.1: bb_api.py + Python test infrastructure (MCP foundation) #2) — principle Phase 4.5: git_ops — git-context wrappers for the MCP agent #6 (agents/bitbucket.md:151-157) and the conventions section (:266-273) now list the same seven commands, including bb -w <ws> repos and bb pr. Aligned.

3. Cross-reference at agents/bitbucket.md:276 ("see 'Populating conventions from bb' under Operating principles") matches the ### 6. heading at :145. ✅

No real workspace data ✅

Only generic placeholders (acme/widget-service, deploy-prod, <slug>, <ws>, <repo>). The "real values → local ~/.claude/agents/ copy only, never upstream" guardrail is reinforced in both files (agents/bitbucket.md:293-296, README.md:324).

Minor (non-blocking, already merged)

• README install survey omits bb pr. The condensed survey in README.md:333-342 stops at bb vars and doesn't list bb pr <ws>/<repo> <id>, whereas the agent file's two surveys both include it. This is defensible — the README step explicitly defers to "the template at the bottom of the agent file" — but since round 2 aligned the two in-agent lists, you may want the README to match for consistency. Purely cosmetic; the substance is complete.

Substance — commands, output labels, guardrails, the rename, and the GitFlow caveat — is accurate and consistent. Clean docs-only change; nothing blocking.

Note on --comment: inline PR-review comments aren't available in this mode, so findings are consolidated in this single comment.