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

README.md

@@ -319,9 +319,9 @@ claude mcp add --scope user bitbucket-work \
 
 ### Optional: install the bundled `bitbucket` agent for delegated use
 
-The MCP server exposes the *tools*; the bundled **agent** (`agents/bitbucket.md` in this repo) is the *behavioral layer* that makes a Claude Code session use those tools intelligently — propose-first protocol for destructive ops (`pr_merge`, `pr_decline`, `pipeline_stop`, `pr_unapprove`), resolve-git-context-first before any Bitbucket call, show-diffs-before-merge discipline, bash/Python parity rule for delegated CLI maintenance, and the project-conventions checklist for tracking per-workspace defaults.
+The MCP server exposes the *tools*; the bundled **agent** (`agents/bitbucket.md` in this repo) is the *behavioral layer* that makes a Claude Code session use those tools intelligently — propose-first protocol for destructive ops (`pr_merge`, `pr_decline`, `pipeline_stop`, `pr_unapprove`), resolve-git-context-first before any Bitbucket call, show-diffs-before-merge discipline, bash/Python parity rule for delegated CLI maintenance, and the per-workspace conventions block for tracking each workspace's defaults.
 
-The bundled `agents/bitbucket.md` is a **deliberately-generic template** — it ships with placeholder examples (`acme/widget-service`, fictional reviewers, generic custom-pipeline patterns like `deploy-prod`) and an explicitly-blank "Project-specific conventions" section at the bottom. After copying it to `~/.claude/agents/bitbucket.md`, personalize your local copy with your default workspace, required reviewers, custom pipeline patterns, branch naming conventions, and any other non-generic context. **Anything you contribute back to this repo via PR should be re-genericized first** — real workspace slugs, real ticket titles, real reviewer handles, and project-specific custom-pipeline patterns belong only in your personal `~/.claude/agents/` copy, never in the upstream-tracked version.
+The bundled `agents/bitbucket.md` is a **deliberately-generic template** — it ships with placeholder examples (`acme/widget-service`, fictional reviewers, generic custom-pipeline patterns like `deploy-prod`) and an explicitly-blank "Per-workspace conventions" section at the bottom. After copying it to `~/.claude/agents/bitbucket.md`, personalize your local copy with your default workspace, required reviewers, custom pipeline patterns, branch naming conventions, and any other non-generic context. **Anything you contribute back to this repo via PR should be re-genericized first** — real workspace slugs, real ticket titles, real reviewer handles, and project-specific custom-pipeline patterns belong only in your personal `~/.claude/agents/` copy, never in the upstream-tracked version.
 
 The agent is a single Markdown file with frontmatter. To install:
 
@@ -330,10 +330,16 @@ The agent is a single Markdown file with frontmatter. To install:
 mkdir -p ~/.claude/agents
 cp agents/bitbucket.md ~/.claude/agents/bitbucket.md
 
-# 2. Customize the "Project-specific conventions" section near the bottom
-#    for your project(s) — default workspace, required reviewers, custom
-#    pipeline patterns, sensitive variable names. The file ships with a
-#    checklist of what to capture per project.
+# 2. Populate the "Per-workspace conventions" section using bb itself —
+#    don't type defaults from memory, let the CLI discover them:
+#      bb workspaces                # which workspaces you belong to
+#      bb -w <ws> repos             # what's in each
+#      bb repo <ws>/<repo>          # → Main branch (verify PR base; GitFlow repos target develop)
+#      bb pipelines <ws>/<repo>     # → TRIGGER column = custom pipelines
+#      bb branches <ws>/<repo>      # → branch-naming convention
+#      bb vars <ws>/<repo>          # → SECURED=true = sensitive vars to mask
+#    Add one block per workspace (the template at the bottom of the agent
+#    file shows the shape). The bundled agent can run this survey for you.
 
 # 3. Newly-started Claude Code sessions pick up the agent automatically.
 #    Existing sessions need a restart. In any new session you can then
@@ -356,7 +362,7 @@ The MCP tools already do per-call auto-detection on their own (source-branch aut
 | **Pipeline failure investigation** | Caller must navigate `pipeline_show` → `pipeline_steps` → `pipeline_logs` manually | Triages in that order, surfaces the relevant log tail (last ~50 lines around the failure) instead of dumping the whole stream |
 | **Avoiding redundant probes** | Caller may re-fetch `git_current_branch` / `git_remote_repo` per call even when the tool would auto-detect | Lets tool-level auto-detect carry the call (passes `repo=""` and omits `source_branch=` instead of pre-fetching git context just to echo it back) |
 | **`bb`-CLI maintenance** (delegated) | Re-discovers the parity rule, naming conventions, redaction patterns per session | Owns the design → implement → test → docs → PR cycle with the rules already baked in |
-| **Project conventions** | Re-discovered each session | Read from the agent file's "Project-specific conventions" section (your local copy) before any write op |
+| **Per-workspace conventions** | Re-discovered each session | Reads (or bb-discovers and proposes) the agent file's "Per-workspace conventions" block for the active workspace before any write op |
 
 ### Security
 
@@ -365,7 +371,7 @@ The MCP tools already do per-call auto-detection on their own (source-branch aut
 - Cross-host `Authorization` headers are stripped on redirect so the Bitbucket Basic header never reaches S3 when fetching pipeline logs.
 - Pipeline variable values are masked as `KEY=***` when echoed back.
 
-The agent file is genuinely portable — strip the example "Project-specific conventions" section and you have a clean template that works for any Bitbucket Cloud workspace.
+The agent file is genuinely portable — strip the example "Per-workspace conventions" section and you have a clean template that works for any Bitbucket Cloud workspace.
 
 ## License
 

VERSION

@@ -1 +1 @@
-1.2.0
+1.2.1

agents/bitbucket.md

@@ -142,6 +142,24 @@ When the user says "open a PR for this branch," call `pr_create(title="...")` wi
 
 When invoking `pr_merge`, `pr_decline`, `pipeline_stop`, or `pr_unapprove` from a delegated context, surface the what / why / new-state to the user first when there's any ambiguity. `pr_approve` and `pr_comment_add` are reversible enough to fire without a propose step in normal flow.
 
+### 6. Populating conventions from `bb` (don't ask the user to recite them)
+
+When you're delegated work in a workspace that has no block yet under
+"Per-workspace conventions," don't interrogate the user for defaults — run the
+read-only discovery survey and propose a filled-in block for them to confirm:
+
+- `bb workspaces` → which workspaces exist
+- `bb -w <ws> repos` → what's in each workspace (+ recency)
+- `bb repo <ws>/<repo>` → default destination branch (the "Main branch" field — but verify the actual PR base; GitFlow repos take PRs against `develop`, not the `mainbranch`)
+- `bb pipelines <ws>/<repo>` → custom pipeline patterns (the TRIGGER column; filter out plain branch names)
+- `bb branches <ws>/<repo>` → branch-naming / ticket-key convention
+- `bb vars <ws>/<repo>` → sensitive variables (rows with `SECURED=true`)
+- `bb pr <ws>/<repo> <id>` on a recent PR → reviewer/author patterns
+
+These are all read-only — gather first, then show the user the proposed block
+and write it only on confirmation. Real values go in the user's local
+`~/.claude/agents/bitbucket.md`, never the upstream template.
+
 ---
 
 ## Operating examples (generic)
@@ -234,16 +252,45 @@ The CLI is two parallel implementations:
 
 ---
 
-## Project-specific conventions (placeholder — fill this in per project)
+## Per-workspace conventions (placeholder — fill this in per workspace)
+
+Capture each workspace's conventions here so they survive across sessions.
+Add one block per workspace you work in (the workspace slug is the heading);
+a top-level default covers repo-less commands run outside a checkout.
+
+**Don't type these from memory — let `bb` discover them.** Every field below
+is derivable from a read-only `bb` command, so populating this section is a
+mechanical survey rather than a guess:
+
+```bash
+bb workspaces                      # enumerate the workspaces you belong to
+bb -w <ws> repos                   # what's in each one (+ recency)
+bb repo <ws>/<repo>                # → "Main branch" (but verify the PR base — GitFlow
+                                   #   repos take PRs against develop, not the mainbranch)
+bb pipelines <ws>/<repo>           # → TRIGGER column = custom pipeline patterns in use
+bb branches <ws>/<repo>            # → branch-name prefixes / ticket-key convention
+bb vars <ws>/<repo>                # → SECURED=true rows = sensitive variables to mask
+bb pr <ws>/<repo> <id>             # → reviewers / author on a recent PR
+```
+
+The bundled agent can run this survey for you — see "Populating conventions
+from `bb`" under Operating principles.
 
-When this agent is delegated work in a specific project, capture the project's conventions here so they survive across sessions:
+Template — copy per workspace:
 
-- **Default workspace:** _(e.g. `acme`)_
-- **Default destination branch:** _(e.g. `develop`)_
-- **Required reviewers:** _(e.g. team-lead handle)_
-- **Custom pipeline patterns:** _(e.g. `deploy-staging`, `deploy-prod`, `nightly-integration`)_
-- **PR title conventions:** _(e.g. `[TICKET-123] Add X` / `feat: …`)_
-- **Branch naming:** _(e.g. `feat/`, `fix/`, `chore/`)_
-- **Pipeline variables that are sensitive:** _(list so they aren't echoed in plaintext when surfacing trigger results)_
+```markdown
+**Default workspace** (repo-less commands outside a checkout): `<slug>`
+
+### Workspace: `<slug>`
+- **Default destination branch:** _(from `bb repo` → Main branch)_
+- **Custom pipeline patterns:** _(from `bb pipelines` TRIGGER column; e.g. `deploy-prod`, `v*`)_
+- **Branch naming:** _(from `bb branches`; e.g. `feature/TICKET-NNN-…`)_
+- **PR / commit conventions:** _(e.g. Conventional Commits, ticket-key in scope, milestone tags)_
+- **Reviewers:** _(confirm per-PR via `bb pr` — reviewer arrays aren't a stable default)_
+- **Sensitive pipeline variables:** _(from `bb vars`, SECURED=true rows — so they aren't echoed on trigger)_
+```
 
-The fields above are intentionally blank in the bundled template — fill them in your own private copy after installing, never in the upstream-tracked version.
+These fields are intentionally blank in the bundled template. Fill them in
+your own private copy (`~/.claude/agents/bitbucket.md`) after installing —
+real workspace slugs, repo names, reviewer handles, and pipeline patterns
+belong only there, **never in the upstream-tracked version**.