Release v1.2.1: documentation updates (bb-driven agent conventions)

[daniel-pittman]

v1.2.1 — documentation release

Patch release to get the v1.2.0-era documentation onto main and into a published release. v1.2.0 shipped the multi-workspace code; this carries the docs that landed on develop afterward (PR #20 / #25 part B) but never made it into a tagged release.

What's included (docs-only — no code changes since v1.2.0)

• agents/bitbucket.md: "Project-specific conventions" → "Per-workspace conventions" restructure (per-workspace blocks keyed by slug), the read-only bb discovery survey for populating them, new operating-principle Phase 4.5: git_ops — git-context wrappers for the MCP agent #6 ("the agent runs the survey and proposes a block rather than asking the user to recite defaults"), and a GitFlow PR-base caveat.
• README.md: agent-install step now shows the bb discovery commands; "Per-workspace conventions" rename throughout; GitFlow PR-base caveat.
• VERSION → 1.2.1.

Test plan

• No code changed since v1.2.0 (388 pytest tests already green on that tree)
• develop is strictly ahead of main (clean ancestry — no false-conflict this time)
• v1.2.0 MCP + bash surface re-smoke-tested post-restart (workspaces_list, slim prs_list, auto-detect, state heuristic all ✅)

[claude]

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

---

Code Review — PR #21 (Release v1.2.1, docs-only)

• Gather context (diff, changed files)
• Review agents/bitbucket.md changes
• Review README.md changes
• Review VERSION bump
• Post review feedback

Scope note: this PR is already MERGED and the branch I'm on is a shallow checkout of develop, so I reviewed the merged content of the three changed files rather than a reconstructed pre-merge diff (network fetch/deepen requires approval here). Findings below are non-blocking; where useful I've flagged them as candidates for a tiny follow-up PR to develop.

---

Verdict

Solid docs-only patch release. The "Project-specific conventions" → "Per-workspace conventions" rename is complete — I grepped the repo and found no stale section-name references (the lone project-specific hit at README.md:324 is the unrelated adjective "project-specific custom-pipeline patterns"). The GitFlow PR-base caveat is worded consistently across all three places it appears (agents/bitbucket.md:153, :268, README.md:337). The read-only discovery survey and new operating-principle #6 read clearly and are internally consistent with the conventions template.

Findings (minor)

1. README.md:374 contradicts the "ships blank" framing. Line 374 says:

strip the example "Per-workspace conventions" section and you have a clean template

But README.md:324 describes that section as "explicitly-blank", and the actual agents/bitbucket.md:255-296 template ships with placeholders only (no filled example to strip). After this PR's restructure, "strip the example … section" is stale wording — there's nothing to strip. Suggest rewording to match the "ships blank" framing. Fix this →

2. README survey omits the bb pr reviewer-discovery step. The agent file's principle #6 (agents/bitbucket.md:145-161) and the conventions template (:265-273) list 7 survey commands, including bb pr <ws>/<repo> <id> for reviewer/author patterns. The README agent-install survey (README.md:335-340) lists only 6 — it drops the bb pr step. It's a condensed quick-start so this is forgivable, but adding the one line keeps the two doc surfaces in parity (and parity is this repo's stated default). Fix this →

3. VERSION lags on develop (GitFlow back-merge). The bump to 1.2.1 landed on the release branch → main, but VERSION on develop still reads 1.2.0 (confirmed: git diff origin/main..HEAD shows only VERSION). That's expected for the release-branch bump, but worth a back-merge of main into develop so develop doesn't sit behind the tagged release indefinitely — otherwise the next feature branch cut from develop carries a stale version string. Process follow-up, not a change to this PR.

Nits (optional, non-blocking)

• No CHANGELOG exists in the repo, so touching only VERSION + docs for this release is consistent with the project's current conventions — nothing missing there.
• Tool-count claims ("31 tools", README.md:23/:239) still reconcile with the tool-surface table — no drift introduced by this PR.

Nothing here blocks the release; the rename, survey, and GitFlow caveat all land cleanly. Items 1 and 2 are quick wins for a follow-up to develop, and item 3 is a GitFlow housekeeping reminder.