beadhive 0.1.0__tar.gz

beadhive-0.1.0/.claude/settings.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "deny": [
+      "Bash(bd remember:*)"
+    ]
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bd prime --hook-json"
+          }
+        ]
+      }
+    ]
+  }
+}

beadhive-0.1.0/.githooks/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+# ws pre-commit: ruff + markdownlint + pytest (via `just check`).
+# Enable with `just hooks` (sets core.hooksPath). Bypass once with `git commit --no-verify`.
+exec mise exec -- just check

beadhive-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: release
+
+# Publishes the built distribution to PyPI via Trusted Publishing (OIDC) — no
+# stored API token. Fires on a v* tag push; workflow_dispatch allows a manual
+# re-run. The Trusted Publisher on pypi.org must name this repo + this
+# workflow file (release.yml) + project `beadhive` (see
+# beadhive/infra manifests/trusted-publishers.yaml).
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi-prod  # approval gate; configured under repo Settings → Environments
+    permissions:
+      contents: read   # job-level perms REPLACE workflow-level — must re-list to checkout a private repo
+      id-token: write  # required for OIDC token exchange with PyPI
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Verify distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Smoke-import the built wheel
+        run: uv run --isolated --no-project --with dist/*.whl python -c "import beadhive"
+
+      # Trusted Publishing via OIDC — `always` fails loudly if the OIDC token is
+      # absent (rather than silently looking for an API token). uv everywhere.
+      # NB: uv publish does not emit PEP 740 attestations (the pypa action would);
+      # revisit if attestations become a requirement.
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

beadhive-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Secrets
+.env
+
+# Local Dolt data — issue data NEVER goes to GitHub
+.dolt-data/
+
+# Beads working copy / exports — no issue data on GitHub
+.beads/
+*.jsonl
+backup/
+
+# OS / tooling cruft
+.DS_Store
+
+# Python / bh build + tooling
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+.pytest_cache/
+
+# Beads / Dolt files (added by bd init)
+.dolt/
+*.db
+.beads-credential-key
+.beads/proxieddb/
+
+# bd agent-integration artifacts (regenerable via `bd setup`; local-only)
+.agents/
+.codex/
+
+# .claude: only shared settings.json is tracked. Agents and skills are vended via the bh
+# plugin (beadhive/claude-plugin) — no agent files or skills symlinks are committed here.
+# Local overrides (.claude/agents/<seat>.md) remain untracked and outrank the plugin.
+.claude/**/*.local.json
+.claude/agents/
+.claude/skills
+AGENTS.md
+CLAUDE.md
+
+# bv (beads viewer) local config and caches
+.bv/
+
+# Planning-plane scratch: molecule specs (bh plan file) + design notes that feed epics
+.planning/

beadhive-0.1.0/.markdownlint-cli2.jsonc

@@ -0,0 +1,19 @@
+// markdownlint-cli2 config for `just lint-md`.
+{
+  // What to lint (so `markdownlint-cli2` with no args = our docs, not .venv etc.)
+  "globs": ["README.md", "docs/**/*.md", "src/beadhive/**/*.md"],
+  // AGF-hint.md is a fragment appended into other docs (no standalone H1) — not a doc.
+  "ignores": ["src/beadhive/assets/AGF-hint.md"],
+  "config": {
+    "default": true,
+    // Our prose wraps ~92 cols by convention; 80 is needlessly strict. Cap at 100,
+    // and don't enforce length inside code blocks or tables (they legitimately run long).
+    "MD013": { "line_length": 100, "code_blocks": false, "tables": false },
+    // Each integration in INTEGRATIONS.md repeats the same subsection headings
+    // (Enabling / What it reads / What it unlocks / Scope & gating) by design; only
+    // require heading uniqueness among siblings under one parent, not document-wide.
+    "MD024": { "siblings_only": true },
+    // Compact tables (`|---|---|`) are our house style; MD060's pipe-spacing rule fights it.
+    "MD060": false
+  }
+}

beadhive-0.1.0/.mise.toml

@@ -0,0 +1,11 @@
+# Tool versions for developing beadhive. Install with: mise install
+# (colima, dolt, beads come from the Brewfile — see README for why.)
+[tools]
+python = "3.12"
+uv = "latest"
+just = "1.54.0"
+gh = "2.95.0"
+docker-cli = "29.6.1"
+docker-compose = "5.2.0"
+node = "lts"                          # for the npm-backed markdown linter
+"npm:markdownlint-cli2" = "latest"    # docs linting (just lint-md)

beadhive-0.1.0/Brewfile

@@ -0,0 +1,9 @@
+# Bootstrap + tools mise can't cleanly provide. Run: brew bundle
+#
+# Everything else (just, gh, jq, yq, docker-cli, docker-compose) is pinned in
+# .mise.toml and installed by `mise install`.
+
+brew "mise"      # tool-version manager — provides everything in .mise.toml
+brew "colima"    # Docker daemon/VM for macOS (system deps; not a plain binary)
+brew "dolt"      # Dolt CLI — backups, diagnostics, SQL shell (not in mise registry)
+brew "beads"     # the `bd` issue tracker (homebrew-core; not in mise registry)

beadhive-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format loosely follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project has not yet committed to
+a formal versioning cadence beyond [SemVer](https://semver.org/).
+
+## Unreleased
+
+Headline so far: the **ws → Beadhive (`bh`) rebrand** — same tool, same AGF process, new name
+and package identity to remove the collision with the many other CLIs named `ws`.
+
+### Rebrand: ws → Beadhive / `bh`
+
+- Python package renamed `ws` → `beadhive`; console scripts renamed `ws`/`ws-mcp` →
+  `bh`/`bh-mcp`.
+- Injected/managed asset marker and file layout migrated to the `beadhive`/`bh` naming
+  (`bh rig migrate` added to move an existing onboarded rig over in place).
+- MCP resource URI scheme renamed `ws://` → `beadhive://`.
+- Docs, skills, and agent definitions across the AGF plugin swept for the rename; the
+  abstract process is now framed as **Beadflow** (an implementation of **AGF** on beads),
+  with **Beadhive** as the umbrella product/workspace name.
+- Config/runtime state continues to live under `~/.ws/` (unchanged) — only the package,
+  command names, and resource scheme changed; on-disk data and Dolt-backed issue history
+  are unaffected.
+- See `docs/design/limn-naming-strategy-adr.md` for the naming decision record and
+  `docs/AGF.md` for the AGF/Beadflow process this tool drives.
+
+### Notes
+
+- An earlier draft of this changelog bumped the package to `1.0.0` and framed it as a first
+  public release. That was premature: the project is still under local development and has
+  not yet committed to a `1.0.0` SemVer stability promise, so the version has been reverted
+  to `0.1.0` pending an actual release decision. The rebrand work above already happened and
+  the notes are kept here as a record; only the release framing was walked back. See
+  .

beadhive-0.1.0/INSTALL.md

@@ -0,0 +1,122 @@
+---
+# yaml-language-server: $schema=https://agentguides.io/schemas/0.1/install.schema.json
+install:
+  id: beadhive
+  summary: Beadhive — the `bh` CLI, the integration-plane driver for Agentic Git Flow (AGF) and cross-repo beads issue tracking.
+  methods:
+    # Alternatives — pick ONE that fits the user's OS / package manager.
+    # Recommended primary: install the `beadhive` package from PyPI so `bh` lands on PATH.
+    - kind: package
+      manager: uv
+      os: [macos, linux]
+      command: uv tool install 'beadhive[otel]'
+    - kind: package
+      manager: homebrew
+      os: [macos, linux]
+      command: brew install beadhive/tap/beadhive
+    - kind: package
+      manager: pipx
+      command: pipx install 'beadhive[otel]'
+    - kind: package
+      manager: pip
+      command: pip install 'beadhive[otel]'
+  verify: bh --version
+  # Already installed? Report installed-vs-available and offer the upgrade (with consent).
+  upgrade: ask
+  configure:
+    # Sequential — run in order, asking permission at each step.
+    # 1. Scaffold ~/.beadhive (config.yaml + templates). Required, one-time per machine.
+    - kind: script
+      command: bh config init
+    # 2. Claude Code only — register the bh MCP server at user scope
+    #    (shells out to: claude mcp add bh --scope user -- bh mcp serve).
+    - kind: script
+      command: bh mcp install
+    # 3. Optional, Claude Code only — the bh claude-plugin (AGF seat defs, role skills).
+    - kind: plugin
+      harness: claude-code
+      ref: bh@beadhive
+---
+
+# Install Beadhive
+
+> This is the repo's real `INSTALL.md`, following the
+> [INSTALL.md convention](https://github.com/agentguides/agentguides). Paste its
+> link into any agent to install Beadhive. A convention-aware agent reads the
+> `install:` frontmatter above; every other agent — and you — can follow the
+> prose below and reach the same result with the same permission prompts.
+
+Beadhive is the `bh` CLI (Python package `beadhive`). Installing it is two
+things — a **package install** (puts `bh` on your PATH) and a one-time
+**configure** step (`bh config init`), plus optional Claude Code wiring.
+Whoever is installing (agent or human) should **ask before running each
+command**.
+
+## 1. Install `bh` (pick ONE)
+
+These are alternatives. Choose the one that matches your setup; you only need one.
+
+- **`uv` (recommended, macOS/Linux):**
+
+  ```sh
+  uv tool install 'beadhive[otel]'   # puts `bh` on PATH (~/.local/bin)
+  ```
+
+- **Homebrew:**
+
+  ```sh
+  brew install beadhive/tap/beadhive
+  ```
+
+- **`pipx` / `pip`:**
+
+  ```sh
+  pipx install 'beadhive[otel]'      # or: pip install 'beadhive[otel]'
+  ```
+
+The `[otel]` extra enables OpenTelemetry signals out of the box; drop it if you
+don't want them. The MCP server ships in the core install.
+
+## 2. Verify
+
+```sh
+bh --version
+```
+
+This should print a version. If it does not, `bh` is not on your PATH —
+`uv tool` and `pipx` install to `~/.local/bin`; add it to your shell profile:
+
+```sh
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+## 3. Configure
+
+Run these in order.
+
+1. **Scaffold the config home** (required, one-time per machine). Writes
+   `config.yaml` and templates into `~/.beadhive/`:
+
+   ```sh
+   bh config init
+   ```
+
+2. **Claude Code only — wire the MCP server** at user scope, so planning, work,
+   rig, and config tools are available in every session:
+
+   ```sh
+   bh mcp install     # runs: claude mcp add bh --scope user -- bh mcp serve
+   ```
+
+3. **Optional, Claude Code only — the `bh` claude-plugin.** Vends the AGF seat
+   agent defs and role skills (dispatcher / developer / merger / …):
+
+   ```sh
+   claude plugin marketplace add beadhive/claude-plugin
+   claude plugin install bh@beadhive
+   ```
+
+That's it. `bh` is installed, verified, and configured. Next steps:
+[`docs/ONBOARDING.md`](docs/ONBOARDING.md) walks from here to a fully
+configured AGF workspace with registered rigs; [`README.md`](README.md) has the
+overview and docs map.

beadhive-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: beadhive
+Version: 0.1.0
+Summary: Beadhive CLI
+Requires-Python: >=3.11
+Requires-Dist: fastmcp<4,>=3.4
+Requires-Dist: pydantic-settings>=2.11
+Requires-Dist: ruamel-yaml>=0.18
+Requires-Dist: structlog>=24
+Requires-Dist: typer>=0.12
+Provides-Extra: mcp
+Provides-Extra: otel
+Requires-Dist: opentelemetry-exporter-otlp>=1.27; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.27; extra == 'otel'
+Requires-Dist: structlog>=24; extra == 'otel'
+Description-Content-Type: text/markdown
+
+# Beadhive (`bh`)
+
+`bh` is a single CLI for managing **beads** issue tracking across many repositories. Each
+repo is its own beads database (a **rig**) with a short, stable prefix; `bh` onboards them,
+keeps their labels consistent, runs `bd`/`git` across one or all of them, and aggregates
+every rig into one cross-repo view — even rigs whose code isn't checked out.
+
+It's a thin orchestrator over `bd`, `git`, `git-workspace`, `dolt`, and `docker`: `bh`
+encodes the conventions, the registry, validation, and routing. Config and runtime state live
+under `~/.beadhive/`; **no issue data lives there** — each rig's issues live in its own Dolt
+DB under `refs/dolt/data` on that repo's own git remote.
+
+`bh` is the **Beadhive** umbrella's workspace CLI — the integration-plane driver for **AGF**
+(Agentic Git Flow), the abstract, tracker-independent process. **Beadflow** is that process
+implemented on beads: this repo's concrete implementation, unchanged behavior under a naming
+layer. See [docs/AGF.md](docs/AGF.md) for the process and
+[docs/design/limn-naming-strategy-adr.md](docs/design/limn-naming-strategy-adr.md) for the
+naming decision record.
+
+This repo is the CLI's source (Python package `beadhive` on PyPI, command `bh`).
+
+## Install
+
+**Agents:** point your agent at [`INSTALL.md`](INSTALL.md) — the preferred install path. It
+carries a structured `install:` frontmatter block (the agent reads it, discloses the plan,
+and asks before each command) plus a prose fallback any agent or human can follow.
+
+**Manual** (pick one):
+
+```sh
+uv tool install 'beadhive[otel]'     # PyPI (recommended)
+brew install beadhive/tap/beadhive   # Homebrew
+```
+
+Then scaffold the config home:
+
+```sh
+bh config init      # writes config.yaml + templates into ~/.beadhive/
+```
+
+**Optional (Claude Code):** the `bh` claude-plugin vends the AGF seat agent defs and role
+skills; `bh mcp install` wires the MCP server at user scope:
+
+```sh
+claude plugin marketplace add beadhive/claude-plugin
+claude plugin install bh@beadhive
+bh mcp install
+```
+
+## Docs
+
+New to bh? Start at [`**docs/ONBOARDING.md**`](docs/ONBOARDING.md) — the end-to-end guide
+from fresh Mac to a configured AGF workspace with registered rigs.
+
+Everything else — the design and reasoning, configuration, the full command surface, and each
+component — starts at [`**docs/OVERVIEW.md**`](docs/OVERVIEW.md).
+
+## Develop
+
+```sh
+just bootstrap   # brew bundle + mise install + uv sync   (once per machine)
+just install     # uv tool install --force '.[otel]' → ~/.local/bin/bh
+just lint        # ruff check
+just fmt         # ruff format
+just test        # pytest
+just build       # uv build
+```

beadhive-0.1.0/README.md

@@ -0,0 +1,67 @@
+# Beadhive (`bh`)
+
+`bh` is a single CLI for managing **beads** issue tracking across many repositories. Each
+repo is its own beads database (a **rig**) with a short, stable prefix; `bh` onboards them,
+keeps their labels consistent, runs `bd`/`git` across one or all of them, and aggregates
+every rig into one cross-repo view — even rigs whose code isn't checked out.
+
+It's a thin orchestrator over `bd`, `git`, `git-workspace`, `dolt`, and `docker`: `bh`
+encodes the conventions, the registry, validation, and routing. Config and runtime state live
+under `~/.beadhive/`; **no issue data lives there** — each rig's issues live in its own Dolt
+DB under `refs/dolt/data` on that repo's own git remote.
+
+`bh` is the **Beadhive** umbrella's workspace CLI — the integration-plane driver for **AGF**
+(Agentic Git Flow), the abstract, tracker-independent process. **Beadflow** is that process
+implemented on beads: this repo's concrete implementation, unchanged behavior under a naming
+layer. See [docs/AGF.md](docs/AGF.md) for the process and
+[docs/design/limn-naming-strategy-adr.md](docs/design/limn-naming-strategy-adr.md) for the
+naming decision record.
+
+This repo is the CLI's source (Python package `beadhive` on PyPI, command `bh`).
+
+## Install
+
+**Agents:** point your agent at [`INSTALL.md`](INSTALL.md) — the preferred install path. It
+carries a structured `install:` frontmatter block (the agent reads it, discloses the plan,
+and asks before each command) plus a prose fallback any agent or human can follow.
+
+**Manual** (pick one):
+
+```sh
+uv tool install 'beadhive[otel]'     # PyPI (recommended)
+brew install beadhive/tap/beadhive   # Homebrew
+```
+
+Then scaffold the config home:
+
+```sh
+bh config init      # writes config.yaml + templates into ~/.beadhive/
+```
+
+**Optional (Claude Code):** the `bh` claude-plugin vends the AGF seat agent defs and role
+skills; `bh mcp install` wires the MCP server at user scope:
+
+```sh
+claude plugin marketplace add beadhive/claude-plugin
+claude plugin install bh@beadhive
+bh mcp install
+```
+
+## Docs
+
+New to bh? Start at [`**docs/ONBOARDING.md**`](docs/ONBOARDING.md) — the end-to-end guide
+from fresh Mac to a configured AGF workspace with registered rigs.
+
+Everything else — the design and reasoning, configuration, the full command surface, and each
+component — starts at [`**docs/OVERVIEW.md**`](docs/OVERVIEW.md).
+
+## Develop
+
+```sh
+just bootstrap   # brew bundle + mise install + uv sync   (once per machine)
+just install     # uv tool install --force '.[otel]' → ~/.local/bin/bh
+just lint        # ruff check
+just fmt         # ruff format
+just test        # pytest
+just build       # uv build
+```