Generated by task docs:export-adr-index from the records in this directory. Do not edit.¶
Decision Records¶
How this project is built and worked on, one rule to a record. Each record says what holds and why, and the alternatives it turned down.
- ADR-001: Go as primary implementation language
- ADR-002: Taskfile for development automation
- ADR-003: AI agents as first-class developers
- ADR-004: Live integration tests as primary correctness gate
- ADR-006: Conventional Commits, and git hooks run by lefthook
- ADR-008: Layered Go architecture and package boundaries
- ADR-009: Transport policy for Bitbucket API calls
- ADR-010: Go model validation and schema export
- ADR-011: Error taxonomy and CLI exit contract
- ADR-013: The command tree has gh's shape, one package per top-level group
- ADR-016: Test classification and execution policy
- ADR-019: Configuration and secret handling policy
- ADR-020: bb runs git through one backend, which runs the git binary
- ADR-021: Persistent auth configuration and keyring storage
- ADR-022: Auth mode priority and token-first policy
- ADR-023: Long-term planning via GitHub issues
- ADR-024: Use .tmp directory for agent temporary files
- ADR-025: Git discipline and branch management
- ADR-026: PR readiness and auto-merge criteria
- ADR-028: A live test pins what Bitbucket does, and fixes.yaml records where bb works around its specification
- ADR-029: Network Isolation during Unit Testing
- ADR-033: Automated Conventional Commit release on main
- ADR-034: Unified dry-run planning engine for server mutating commands
- ADR-036: CLI identity bb and BB namespace
- ADR-037: Versioned docs via MkDocs Material and mike
- ADR-038: bb ai subcommand as AI-first tooling namespace
- ADR-039: Built-in MCP server with explicit host scoping and token capability restriction
- ADR-040: Agent skill distribution through npx and the copy embedded in bb
- ADR-041: Host aliases and clone URL discovery for server contexts
- ADR-042: Track the newest containerisable Bitbucket version
- ADR-043: Provision the live test instance with the Atlassian Plugin SDK
- ADR-044: Supply git credentials through a credential helper rather than persisting them
- ADR-045: Compute coverage measurements, commit only verifiable baselines
- ADR-046: Emit a JSON error envelope on the failure path
- ADR-047: Credential input paths and enforceable keyring storage
- ADR-048: Documented commands are validated against the command tree
- ADR-049: Build tooling stays outside the coverage gate but not outside testing
- ADR-050: Frequently used commands get a second spelling, and one path stays canonical
- ADR-051: bb does not manage server-side hooks
- ADR-053: Raw API escape hatch for uncovered endpoints and version gaps
- ADR-056: Pull request reviewer automation, default reviewers, and CODEOWNERS
- ADR-057: Documented release version is injected at build time
- ADR-058: System-wide configuration and administrative policy enforcement
- ADR-059: Enterprise update controls and release mirror support
- ADR-060: Mutual TLS (mTLS) client certificate authentication
- ADR-061: The MCP surface runs on the official SDK and every tool names its payload
- ADR-062: The MCP server can be confined to a workspace, and records what agents attempt there
- ADR-063: Offline release signature verification and update trust policy
- ADR-064: Machine output carries no contract version; breaking payload changes ride the release major
- ADR-065: What the quality apparatus measures, and why each part exists
- ADR-066: Every change integrates on next, and only main releases
- ADR-067: Governance tests are verified by breaking them
- ADR-068: The vendored API reference is derived from the harness release
- ADR-069: Dependabot updates merge themselves, except where held for a person
- ADR-070: Every command is explicitly classified for dry-run, and unknown means refuse
- ADR-071: Tests must not reconfigure the repository they run in
- ADR-072: Interactivity is decided in one place, and the escape hatch costs nothing per call
- ADR-073: Interactive when a person is there, explicit when not
- ADR-074: A service takes a cap, never a page size
- ADR-075: A machine-mode command emits one document, and what a caller acts on is in error.details
- ADR-076: Machine output field names are camelCase, matching the Bitbucket API
- ADR-077: Comment endpoints are views, not collections
- ADR-078: A dry run's tier is the weakest of its checks, not a label the author writes
- ADR-079: Unit tests do not simulate Bitbucket
- ADR-080: Bitbucket resolves CODEOWNERS, not bb
- ADR-081: An issue closes when its fix ships, not when it merges
- ADR-082: A unit test process inherits nothing
- ADR-083: No flag carries a secret
- ADR-084: A removed flag warns for one major before it stops working
- ADR-085: A live test seeds and owns its fixtures, and names them at random
- ADR-086: bb doctor reports the configuration without loading it
- ADR-087: Quoted messages are checked against the source that prints them
- ADR-088: Every Bitbucket release Atlassian supports is served, and none is dropped
- ADR-089: Shell completion is declared by the argument's name, and resolved by the command's own code
- ADR-090: A package sets up what every user shares, and bb sets up what is one user's
- ADR-091: A command may report the state it read through its exit status
- ADR-092: bb update installs the new binary itself, before it exits
- ADR-093: Binary and large downloads go through one downloader
- ADR-094: MCP tools pass content to the model in a format it can ingest
- ADR-095: Machine output is the whole envelope, as JSON or YAML, and not gh's field lists
- ADR-096: The flags choose a document's member, and --dry-run answers with a verdict
- ADR-097: --describe describes a command's output in every mode
- ADR-099: The MCP server serves Bitbucket content as resources, prompts and completions
- ADR-100: Administrative policy can switch bb off, switch its MCP server off, or make it read-only
- ADR-101: The MCP server adopts MCP Apps, and shows its views through one tool
- ADR-102: A value read from where a command runs may stand in for its flag
- ADR-103: MCP tools ask the person only on a server that opts in
- ADR-104: What passes for the person's own is marked as the agent's, or left to them
- ADR-105: Text an agent writes through MCP says an AI agent wrote it