agex-cli 0.25.0__tar.gz → 0.26.1__tar.gz

{agex_cli-0.25.0 → agex_cli-0.26.1}/.github/workflows/publish.yml

@@ -73,8 +73,9 @@ jobs:
   # because it needs to rewrite the version before building.
   #
   # The matrix exists so we can publish the same code under three PyPI
-  # distribution names: `agex-cli` (canonical) plus the `agent-devex` and
-  # `devex-cli` aliases. Each leg rewrites `[project].name` in pyproject.toml
+  # distribution names: `devex-cli` (canonical) plus the `agent-devex` and
+  # `agex-cli` aliases (`agex-cli` is the legacy canonical name, still
+  # published for back-compat). Each leg rewrites `[project].name` in pyproject.toml
   # before building so each wheel is uploaded under its own Trusted Publishing
   # project.
   # --------------------------------------------------------------------------
@@ -97,9 +98,9 @@ jobs:
       - run: uv venv
       - run: uv pip install build
 
-      # Rewrite `[project].name` to the matrix dist name. For `agex-cli`
+      # Rewrite `[project].name` to the matrix dist name. For `devex-cli`
       # (the canonical dist) the regex still has to match so we re-emit
-      # the line; for `agent-devex` / `devex-cli` it produces an alias dist
+      # the line; for `agent-devex` / `agex-cli` it produces an alias dist
       # with identical contents. The post-rewrite re-parse is a fail-closed
       # check: if a future formatting change breaks the regex match (or
       # `[project].name` ends up wrong for any reason), the job aborts

{agex_cli-0.25.0 → agex_cli-0.26.1}/.github/workflows/test.yml

@@ -23,6 +23,47 @@ jobs:
       - run: uv pip install -e ".[dev]"
       - run: uv run pytest
 
+  # --------------------------------------------------------------------------
+  # SonarCloud CI-based analysis + coverage. SonarCloud is no longer in
+  # Automatic Analysis mode (the two modes are mutually exclusive), so this job
+  # is the sole analysis path: it generates coverage.xml (with repo-relative
+  # paths via pyproject [tool.coverage.run] so Sonar can match files) and runs
+  # the scanner, which
+  # reads sonar-project.properties (projectKey / organization / reportPaths)
+  # and the SONAR_TOKEN repo secret. Runs on PRs (new-code decoration) and on
+  # pushes to main (baseline). fetch-depth: 0 gives Sonar the full history it
+  # needs for accurate new-code / blame attribution.
+  # --------------------------------------------------------------------------
+  sonarcloud:
+    name: SonarCloud
+    runs-on: ubuntu-latest
+    # Promote a *presence flag* (not the secret) to job env so the scan step
+    # can gate on it — `secrets.*` isn't allowed in `if:`. Lets forks /
+    # token-less runs skip the scan rather than hard-fail. (Pattern from the
+    # sibling agentfront repo, whose CI-based SonarCloud scan is green.)
+    env:
+      SONAR_TOKEN_PRESENT: ${{ secrets.SONAR_TOKEN != '' }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39  # v3
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: "3.12"
+      - run: uv venv
+      - run: uv pip install -e ".[dev]"
+      - run: uv run pytest --cov=src/devex --cov-report=xml --cov-report=term
+      # Pinned to v6 to match the sibling agentfront repo's working scan.
+      # The v7+/v8 scanner engine 404s on `api.sonarcloud.io/analysis/analyses`
+      # against SonarQube Cloud; v6 posts to sonarcloud.io directly.
+      - name: SonarCloud Scan
+        if: env.SONAR_TOKEN_PRESENT == 'true'
+        uses: SonarSource/sonarqube-scan-action@fd88b7d7ccbaefd23d8f36f73b59db7a3d246602  # v6
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+          SONAR_HOST_URL: https://sonarcloud.io
+
   # --------------------------------------------------------------------------
   # Enforces that every PR touching code (src/, tests/, pyproject.toml) also
   # bumps the version in pyproject.toml. Without this, a merge to main that

{agex_cli-0.25.0 → agex_cli-0.26.1}/.gitignore

@@ -208,6 +208,7 @@ marimo/_lsp/
 __marimo__/
 
 # Project
+.devex/data/
 .agex/data/
 
 # Worktrees

{agex_cli-0.25.0 → agex_cli-0.26.1}/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.26.1] - 2026-05-29
+
+### Added
+
+- SonarCloud CI-based analysis + coverage upload: a `sonarcloud` job in test.yml runs `pytest --cov` and the SHA-pinned `sonarqube-scan-action` (v6), reading `sonar-project.properties` + the `SONAR_TOKEN` secret. Coverage config lives in `pyproject.toml [tool.coverage.run]` (`relative_files` so coverage.xml paths map to `sonar.sources=src`).
+
+### Changed
+
+- SonarCloud moved from Automatic Analysis to CI-based analysis (the two are mutually exclusive); project now under the `agentculture` org. Updated CLAUDE.md / sonar-project.properties notes accordingly.
+
+## [0.26.0] - 2026-05-29
+
+### Added
+
+- **`devex pr await <PR> --detach` / `--check`** — non-blocking await (#64). `--detach` forks a detached background poller that runs the same readiness → CI → Sonar-gate → thread-tally logic, writes the verdict to a marker (`.devex/data/pr/<PR>/await.json`, atomic `os.replace`), and returns immediately — taking the in-session `time.sleep` (and the prompt-cache re-read tax past the ~5-min TTL) out of the agent's context. `--check` reads that marker back without sleeping or re-polling: the stored briefing + the same non-zero-on-blocked exit code when done, a "still polling (started Ns ago)" notice while running, and a clear notice (never a crash or false "clean") when no run exists or the marker schema is incompatible. The detached worker always leaves a marker — even on `gh` failure, and even if the spawn itself fails — so `--check` is never left hanging. The two flags are mutually exclusive. New per-backend footer keys (`await_detached`, `await_check_pending`, `await_check_missing`, `await_check_incompatible`) ship for all four backends.
+- **`devex pr open --detached-await`** — auto-wait at open time: after creating the PR (and posting the Qodo trigger), fork the detached `pr await` poller and return immediately, so "open → walk away → `pr await <PR> --check`" is one command. The non-blocking counterpart to `--delayed-read` (the two are mutually exclusive).
+
+### Changed
+
+- **Renamed the tool from `agex` to `devex` end to end** — `devex` is now the canonical command, `devex-cli` the canonical PyPI distribution, and the Python module is `devex` (was `agent_experience`). The on-disk state directory is `.devex/` (was `.agex/`), with a transparent read-fallback to a pre-existing `.agex/` and a one-time migration on first write. **`agex` stays a fully working, non-breaking alias**: the `agex` console script and `agex-cli` distribution are still published, `agex` is still recognized as an invoked name, and `devex explain agex` resolves to the overview page. Kept stable for back-compat: the `agex_version` config-file key, the `agex:` gamify hook-fragment IDs, and the `agex hook write` command in the shipped hook asset.
+
 ## [0.25.0] - 2026-05-29
 
 ### Added

{agex_cli-0.25.0 → agex_cli-0.26.1}/CLAUDE.md

@@ -4,24 +4,24 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project
 
-`agex` — non-agentic Python CLI that emits deterministic per-backend markdown briefings for autonomous agents. Published on PyPI under three distribution names: `agex-cli` (canonical), `agent-devex`, and `devex-cli` — the same wheel each time. CLI entry points: `agex` and `devex` (both invoke the same tool; emitted output reflects whichever name was typed). GitHub repo: `agentculture/devex`. Python module (unchanged): `agent_experience`.
+`devex` — non-agentic Python CLI that emits deterministic per-backend markdown briefings for autonomous agents. Published on PyPI under three distribution names: `devex-cli` (canonical), `agent-devex`, and `agex-cli` (the legacy canonical name, still published) — the same wheel each time. CLI entry points: `devex` (canonical) and `agex` (legacy alias) — both invoke the same tool; emitted output reflects whichever name was typed. GitHub repo: `agentculture/devex`. Python module: `devex` (renamed from `agent_experience`).
 
 **Source-of-truth documents:**
 
 - Spec: `docs/superpowers/specs/2026-04-18-agex-design.md`
 - Implementation plan: `docs/superpowers/plans/2026-04-18-agex-v0.1.md` — 33 tasks across 12 phases.
-- Status: PR #1 merged Phases 1–3 (scaffolding, core, `agex explain`). Phases 4–12 (`overview`, `learn`, `gamify`, `hook`, backends, docs site, tester) remain.
+- Status: PR #1 merged Phases 1–3 (scaffolding, core, `devex explain`). Phases 4–12 (`overview`, `learn`, `gamify`, `hook`, backends, docs site, tester) remain.
 
 Read the spec before any non-trivial change — the design invariants below are derived from it.
 
 ## Design invariants (non-negotiable)
 
-1. **Zero LLM calls inside agex.** All output is deterministic markdown from Jinja templates + Python.
+1. **Zero LLM calls inside devex.** All output is deterministic markdown from Jinja templates + Python.
 2. **Markdown is the only output format.** No `--json` flag.
 3. **`--agent <backend>` is required** on backend-sensitive commands. The CLI never auto-detects.
-4. **Side effects only in** `gamify`, `gamify --uninstall`, `hook write`, `pr open`, `pr reply`, `pr review`, `pr read` (journal writes), and first-run `.agex/` init. Everything else is read-only. The `agex pr` namespace allows scoped network I/O (via `gh`) and bounded `--wait` sleep — a deliberate carve-out from the no-network/no-sleep invariants.
+4. **Side effects only in** `gamify`, `gamify --uninstall`, `hook write`, `pr open`, `pr reply`, `pr review`, `pr read` (journal writes), `pr await` (journal + `--detach` marker writes under `.devex/data/pr/<pr>/` and the detached poller subprocess), and first-run `.devex/` init. Everything else is read-only. The `devex pr` namespace allows scoped network I/O (via `gh`), bounded `--wait` sleep, and — for `pr await --detach` — a detached background process that pays that sleep outside the agent session; a deliberate carve-out from the no-network/no-sleep invariants.
 5. **"Unsupported" is success** — exit 0 with a markdown notice that links to the issue tracker, not a non-zero exit.
-6. **Skills are authored by the agent, not shipped by agex.** `agex learn <topic>` teaches; `agex explain <topic>` describes; agex never writes a user skill file on the agent's behalf in v0.1.
+6. **Skills are authored by the agent, not shipped by devex.** `devex learn <topic>` teaches; `devex explain <topic>` describes; devex never writes a user skill file on the agent's behalf in v0.1.
 
 ## Architecture (3-stage pipeline)
 
@@ -36,17 +36,18 @@ cli.py ──► commands/<name>/scripts/<name>.py ──► core/render.py
                   (supported / unsupported)
 ```
 
-- `cli.py` (Typer) routes `agex <command> [args] --agent X`. No business logic.
-- Each `commands/<name>/` is a **skill-folder**: `SKILL.md` + `scripts/` + `assets/` + `references/`. The `SKILL.md` doubles as the content emitted by `agex explain <command>`.
-- `core/` is shared plumbing — backend enum, `.agex/` paths, Jinja renderer (`StrictUndefined`), TOML config, SKILL.md frontmatter parser, capability matrix loader, hook JSON I/O. Command- and content-agnostic.
+- `cli.py` (Typer) routes `devex <command> [args] --agent X`. No business logic.
+- Each `commands/<name>/` is a **skill-folder**: `SKILL.md` + `scripts/` + `assets/` + `references/`. The `SKILL.md` doubles as the content emitted by `devex explain <command>`.
+- `core/` is shared plumbing — backend enum, `.devex/` paths, Jinja renderer (`StrictUndefined`), TOML config, SKILL.md frontmatter parser, capability matrix loader, hook JSON I/O. Command- and content-agnostic.
 - A backend lives in three places: `core/backend.Backend` (enum entry), `backends/<name>/probe.py` (optional Python probe), and one YAML per relevant command under `commands/*/assets/backends/<name>.yaml`. Adding a backend touches only those locations.
 
-## `agex pr` namespace (v0.17.0+)
+## `devex pr` namespace (v0.17.0+)
 
-`lint`, `open`, `read`, `reply`, `review`, `await`, `delta`. Each command ends with a deterministic "Next step:" footer. The `pr` namespace allows scoped network I/O (via `gh`) and bounded `--wait` sleep — a deliberate carve-out from the no-network/no-sleep invariants. `pr open` (non-draft, new PR) and `pr review` post the Qodo `/agentic_review` trigger comment; the legacy `/improve` is deprecated and never emitted. The trigger string lives in one place: `commands/pr/scripts/review.QODO_REVIEW_TRIGGER`. Key modules:
+`lint`, `open`, `read`, `reply`, `review`, `await`, `delta`. Each command ends with a deterministic "Next step:" footer. The `pr` namespace allows scoped network I/O (via `gh`) and bounded `--wait` sleep — a deliberate carve-out from the no-network/no-sleep invariants. `pr open` (non-draft, new PR) and `pr review` post the Qodo `/agentic_review` trigger comment; the legacy `/improve` is deprecated and never emitted. The trigger string lives in one place: `commands/pr/scripts/review.QODO_REVIEW_TRIGGER`. `pr await --detach` / `--check` (issue #64) move the bounded poll out of the agent session: `--detach` forks a detached worker (`commands/pr/scripts/_await_worker.py`) that writes the verdict to a marker (`commands/pr/scripts/_detach.py`, atomic `os.replace`), and `--check` reads it back without sleeping. Key modules:
 
 - `core/github.py` — thin `gh` shellout wrapper; future zero-trust httpx swap touches only this file.
-- `core/journal.py` — nested-stream JSONL append/load for `.agex/data/<dir>/<stream>.jsonl`.
+- `commands/pr/scripts/_detach.py` — await-marker read/write (atomic) + the detached-subprocess spawn helper.
+- `core/journal.py` — nested-stream JSONL append/load for `.devex/data/<dir>/<stream>.jsonl`.
 - `core/backend.resolve_backend()` — `--agent` resolution with `culture.yaml` fallback.
 - `commands/pr/assets/rules/next_step_rules.py` — "Next step:" footer decision logic, per-backend phrasing under `commands/pr/assets/backends/<backend>.yaml`.
 
@@ -57,8 +58,8 @@ Spec: `docs/superpowers/specs/2026-05-10-agex-pr-design.md`. Plan: `docs/superpo
 - **Resource loading: use `importlib.resources.files(...)` and treat the result as a `Traversable`.** Call `.joinpath()` / `.is_file()` / `.read_text(encoding="utf-8")` directly. Wrap with `importlib.resources.as_file()` only when a third-party API needs a real `pathlib.Path`. Do NOT do `Path(str(files(...)))` — it's not zipapp/PEX safe.
 - **File locking: use `portalocker.lock` / `portalocker.unlock`.** Reaching for `fcntl.flock` / `msvcrt.locking` directly is a known foot-gun on Windows (see commit `923f639`).
 - **Always pass `encoding="utf-8"` to `read_text` / `write_text`.** Default locale on Windows corrupts non-ASCII output.
-- **Validate user-controlled CLI args before joining into paths.** `agex explain <topic>` rejects anything that doesn't match `^[a-z][a-z0-9-]*$` to block path traversal (commit `5ac796e`, test `test_explain_rejects_path_traversal`).
-- **Single source of truth for the version:** `pyproject.toml`. `agent_experience.__version__` derives from installed distribution metadata via `importlib.metadata.version("agex-cli")`, and `Config.agex_version` derives from `__version__` via `field(default_factory=...)`. Bumping the version means editing `pyproject.toml` only — no `__init__.py` edit needed.
+- **Validate user-controlled CLI args before joining into paths.** `devex explain <topic>` rejects anything that doesn't match `^[a-z][a-z0-9-]*$` to block path traversal (commit `5ac796e`, test `test_explain_rejects_path_traversal`).
+- **Single source of truth for the version:** `pyproject.toml`. `devex.__version__` derives from installed distribution metadata via `importlib.metadata.version("devex-cli")` (falling back to the `agent-devex` / `agex-cli` alias dists, then pyproject), and `Config.agex_version` derives from `__version__` via `field(default_factory=...)`. (The `agex_version` config-file key name is kept for back-compat with existing `.devex/config.toml` / `.agex/config.toml` files.) Bumping the version means editing `pyproject.toml` only — no `__init__.py` edit needed.
 
 ## Common commands
 
@@ -73,24 +74,24 @@ uv run pytest
 uv run pytest tests/core/test_paths.py::test_ensure_init_creates_dir_and_gitignore -v
 
 # Run the CLI
-uv run agex --version
-uv run agex explain agex
-uv run agex explain explain
+uv run devex --version
+uv run devex explain devex
+uv run devex explain explain
 
-# Coverage (matches what build.yml runs; SonarCloud reads this file)
-uv run pytest --cov=src/agent_experience --cov-report=xml --cov-report=term
+# Coverage (matches the `sonarcloud` job in test.yml; SonarCloud reads coverage.xml)
+uv run pytest --cov=src/devex --cov-report=xml --cov-report=term
 ```
 
 ## CI surface
 
-- `.github/workflows/test.yml` — matrix: 3 OS × 4 Python (3.10–3.13) running `uv run pytest`. Also runs a `version-check` job on PRs that fails (with a sticky `<!-- version-check -->` comment) when `pyproject.toml`'s version on the PR matches the one on `main` and any code file under `src/` / `tests/` / `pyproject.toml` changed. Docs-only PRs skip the check.
+- `.github/workflows/test.yml` — matrix: 3 OS × 4 Python (3.10–3.13) running `uv run pytest`. Also runs (1) a `sonarcloud` job that generates `coverage.xml` (`pytest --cov`, repo-relative paths via `pyproject [tool.coverage.run]`) and runs the SHA-pinned `sonarqube-scan-action` (needs the `SONAR_TOKEN` repo secret); and (2) a `version-check` job on PRs that fails (with a sticky `<!-- version-check -->` comment) when `pyproject.toml`'s version on the PR matches the one on `main` and any code file under `src/` / `tests/` / `pyproject.toml` changed. Docs-only PRs skip the version check.
 - `.github/workflows/publish.yml` — builds sdist + wheel. PRs publish a per-PR dev version to TestPyPI (sticky install-command comment); pushes to `main` publish the stable version to TestPyPI (canary), then an `autotag` job pushes `v<version>` if missing, which gates the inline `publish-pypi` + `github-release` jobs. No manual tagging — bumping `pyproject.toml` is the release signal.
-- SonarCloud is configured as **Automatic Analysis** on the repo (no CI workflow). Coverage and quality are read by SonarCloud directly.
+- SonarCloud runs in **CI-based analysis** mode (Automatic Analysis is off — the two are mutually exclusive). The `sonarcloud` job in `test.yml` uploads coverage + triggers the scan via `sonarqube-scan-action`, reading `sonar-project.properties` and the `SONAR_TOKEN` secret. The quality gate decorates PRs and gates merges.
 - All third-party actions are **pinned to full commit SHAs** with trailing `# vN` comments (rule `githubactions:S7637`). Keep new actions pinned the same way.
 
 ## SonarCloud notes
 
-- `python:S5496` is **narrowly suppressed** for `src/agent_experience/core/render.py` only via `sonar.issue.ignore.multicriteria` in `sonar-project.properties`. Reason: `render_string()` renders Jinja templates that are always package-shipped; output is markdown, never HTML in a browser. See the comment in `render.py` above `render_string` for the rationale. Do not widen the suppression to other files.
+- `python:S5496` is **narrowly suppressed** for `src/devex/core/render.py` only via `sonar.issue.ignore.multicriteria` in `sonar-project.properties`. Reason: `render_string()` renders Jinja templates that are always package-shipped; output is markdown, never HTML in a browser. See the comment in `render.py` above `render_string` for the rationale. Do not widen the suppression to other files.
 - The `render.py` autoescape decision is explicit (`autoescape=select_autoescape([])`). Don't change it.
 
 ## Git workflow
@@ -100,6 +101,6 @@ uv run pytest --cov=src/agent_experience --cov-report=xml --cov-report=term
 - Push, open a PR, let CI + SonarCloud + Qodo + Copilot run. Address inline comments + resolve threads before merge.
 - Merging to `main` publishes to PyPI automatically (via `autotag` → `publish-pypi` → `github-release` in `publish.yml`). No manual tagging.
 - When posting on GitHub on the user's behalf (PR descriptions, issue replies, review-thread replies), sign so it's clear the message came from an AI. Three conventions, in priority order:
-  - **`agex pr open` / `agex pr reply`** — auto-append `- agex-cli (Claude)` (the nick is resolved from `culture.yaml` via `core.github.resolve_nick`, falling back to the repo basename). Don't sign manually.
+  - **`devex pr open` / `devex pr reply`** — auto-append `- devex-cli (Claude)` (the nick is resolved from `culture.yaml` via `core.github.resolve_nick`, falling back to the repo basename). Don't sign manually.
   - **Inside `communicate` workflow scripts** (`post-issue.sh`, `post-comment.sh`) — `agtag` resolves the same nick from `culture.yaml`. Don't sign manually.
-  - **Manual posts the scripts didn't author** (a hand-typed `gh pr create --body …`, a one-off review reply) — sign explicitly as `- agex-cli (Claude)`.
+  - **Manual posts the scripts didn't author** (a hand-typed `gh pr create --body …`, a one-off review reply) — sign explicitly as `- devex-cli (Claude)`.

{agex_cli-0.25.0 → agex_cli-0.26.1}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: agex-cli
-Version: 0.25.0
+Version: 0.26.1
 Summary: Agent-operated developer-experience CLI — deterministic per-backend markdown briefings for autonomous agents.
-Project-URL: Homepage, https://culture.dev/agex/
+Project-URL: Homepage, https://culture.dev/devex/
 Project-URL: Repository, https://github.com/agentculture/devex
 Project-URL: Issues, https://github.com/agentculture/devex/issues
 Author: Ori Nachum
@@ -24,29 +24,29 @@ Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: syrupy>=4.6; extra == 'dev'
 Description-Content-Type: text/markdown
 
-# agex
+# devex
 
-Agent-operated developer-experience CLI. Non-agentic, deterministic, markdown-first. The same wheel is published on PyPI under three distribution names — `agex-cli` (canonical), `agent-devex`, and `devex-cli` — and installs two equivalent commands, `agex` and `devex` (emitted output reflects whichever name you invoke).
+Agent-operated developer-experience CLI. Non-agentic, deterministic, markdown-first. The same wheel is published on PyPI under three distribution names — `devex-cli` (canonical), `agent-devex`, and `agex-cli` (the legacy canonical name, still published) — and installs two equivalent commands, `devex` (canonical) and `agex` (legacy alias) (emitted output reflects whichever name you invoke).
 
 ## Install
 
 ```bash
-uv tool install agex-cli      # or: devex-cli
+uv tool install devex-cli      # or: agex-cli
 # or
-pipx install agex-cli         # or: pipx install devex-cli
+pipx install devex-cli         # or: pipx install agex-cli
 ```
 
 ## Quick start
 
 ```bash
-agex explain agex
-agex overview --agent claude-code
-agex learn --agent claude-code
+devex explain devex
+devex overview --agent claude-code
+devex learn --agent claude-code
 ```
 
 ## Docs
 
-[culture.dev/agex](https://culture.dev/agex/).
+[culture.dev/devex](https://culture.dev/devex/).
 
 Spec: `docs/superpowers/specs/2026-04-18-agex-design.md`.
 

agex_cli-0.26.1/README.md

@@ -0,0 +1,29 @@
+# devex
+
+Agent-operated developer-experience CLI. Non-agentic, deterministic, markdown-first. The same wheel is published on PyPI under three distribution names — `devex-cli` (canonical), `agent-devex`, and `agex-cli` (the legacy canonical name, still published) — and installs two equivalent commands, `devex` (canonical) and `agex` (legacy alias) (emitted output reflects whichever name you invoke).
+
+## Install
+
+```bash
+uv tool install devex-cli      # or: agex-cli
+# or
+pipx install devex-cli         # or: pipx install agex-cli
+```
+
+## Quick start
+
+```bash
+devex explain devex
+devex overview --agent claude-code
+devex learn --agent claude-code
+```
+
+## Docs
+
+[culture.dev/devex](https://culture.dev/devex/).
+
+Spec: `docs/superpowers/specs/2026-04-18-agex-design.md`.
+
+## License
+
+MIT.

{agex_cli-0.25.0 → agex_cli-0.26.1}/culture.yaml

@@ -1,3 +1,3 @@
 agents:
-- suffix: agex-cli
+- suffix: devex-cli
   backend: claude

{agex_cli-0.25.0 → agex_cli-0.26.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agex-cli"
-version = "0.25.0"
+version = "0.26.1"
 description = "Agent-operated developer-experience CLI — deterministic per-backend markdown briefings for autonomous agents."
 authors = [{name = "Ori Nachum"}]
 license = {text = "MIT"}
@@ -26,11 +26,11 @@ dev = [
 ]
 
 [project.scripts]
-agex = "agent_experience.cli:_main_entrypoint"
-devex = "agent_experience.cli:_main_entrypoint"
+devex = "devex.cli:_main_entrypoint"
+agex = "devex.cli:_main_entrypoint"
 
 [project.urls]
-Homepage = "https://culture.dev/agex/"
+Homepage = "https://culture.dev/devex/"
 Repository = "https://github.com/agentculture/devex"
 Issues = "https://github.com/agentculture/devex/issues"
 
@@ -39,12 +39,27 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/agent_experience"]
+packages = ["src/devex"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-n auto -v"
 
+[tool.coverage.run]
+source = ["src/devex"]
+# Emit repo-relative paths in coverage.xml so SonarCloud maps them to
+# sonar.sources=src (absolute / .venv paths fail to map → empty coverage).
+relative_files = true
+
+[tool.coverage.report]
+show_missing = true
+fail_under = 60
+exclude_lines = [
+    "pragma: no cover",
+    "if __name__ == .__main__.",
+    "if TYPE_CHECKING:",
+]
+
 [tool.black]
 line-length = 100
 
@@ -54,7 +69,7 @@ line_length = 100
 
 [tool.bandit]
 # B311 flags any `random.*` usage as potentially unsafe for crypto purposes.
-# `core/hook_io._acquire_lock_with_retry` uses `random.uniform` purely for
+# `core/_jsonl.acquire_lock_with_retry` uses `random.uniform` purely for
 # backoff jitter between bounded retries -- not a security context, so the
 # standard `random` module is the right choice (secrets would be misuse).
 skips = ["B311"]

{agex_cli-0.25.0 → agex_cli-0.26.1}/sonar-project.properties

@@ -1,5 +1,5 @@
 sonar.projectKey=agentculture_devex
-sonar.organization=orinachum
+sonar.organization=agentculture
 
 # Displayed in SonarCloud UI
 sonar.projectName=devex
@@ -12,12 +12,11 @@ sonar.sourceEncoding=UTF-8
 # Python: target versions (matches CI matrix)
 sonar.python.version=3.10, 3.11, 3.12, 3.13
 
-# Coverage report path. SonarCloud runs in Automatic Analysis mode (no
-# CI-based scan — see PR #20). Automatic Analysis doesn't upload
-# pytest-cov output; this key remains so that if/when we ever revisit
-# coverage delivery, the file path is already declared. The bugs /
-# vulnerabilities / code-smells portion of the analysis works without
-# coverage and is what gates the PR quality gate today.
+# Coverage report path. SonarCloud now runs in CI-based analysis mode
+# (Automatic Analysis is OFF — the two are mutually exclusive). The `sonarcloud`
+# job in .github/workflows/test.yml runs `pytest --cov` (repo-relative paths
+# via pyproject [tool.coverage.run], so Sonar can match files) and the
+# sonarqube-scan-action uploads this report. Requires the SONAR_TOKEN repo secret.
 sonar.python.coverage.reportPaths=coverage.xml
 
 # S5496 triggers on render_string() because it renders a Jinja template with a
@@ -30,17 +29,17 @@ sonar.python.coverage.reportPaths=coverage.xml
 # S2083 (path injection) fires in commands/gamify/scripts/install.py because
 # the hooks file path is `Path.cwd() / ".claude" / "hooks.json"`. `Path.cwd()`
 # is the process's working directory (set by the user's shell before invoking
-# agex); `.claude` and `hooks.json` are hardcoded literals. No HTTP body, CLI
+# devex); `.claude` and `hooks.json` are hardcoded literals. No HTTP body, CLI
 # string argument, or other network/request input is ever joined into this
 # path — the backend name is enum-validated by `parse_backend()` before reaching
 # install.py and does not itself flow into the path. S2083 is designed for
 # web contexts where a request-body filename taints a filesystem call; that
 # threat model does not apply here. Writing `.claude/hooks.json` is the
-# documented contract of `agex gamify` (design spec invariant #4: "Side
+# documented contract of `devex gamify` (design spec invariant #4: "Side
 # effects only in gamify, gamify --uninstall, hook write, and first-run
-# `.agex/` init"). Rule is disabled only for this one file.
+# `.devex/` init"). Rule is disabled only for this one file.
 sonar.issue.ignore.multicriteria=e1,e2
 sonar.issue.ignore.multicriteria.e1.ruleKey=pythonsecurity:S5496
-sonar.issue.ignore.multicriteria.e1.resourceKey=src/agent_experience/core/render.py
+sonar.issue.ignore.multicriteria.e1.resourceKey=src/devex/core/render.py
 sonar.issue.ignore.multicriteria.e2.ruleKey=pythonsecurity:S2083
-sonar.issue.ignore.multicriteria.e2.resourceKey=src/agent_experience/commands/gamify/scripts/install.py
+sonar.issue.ignore.multicriteria.e2.resourceKey=src/devex/commands/gamify/scripts/install.py

{agex_cli-0.25.0/src/agent_experience → agex_cli-0.26.1/src/devex}/__init__.py

@@ -2,14 +2,15 @@ from importlib.metadata import PackageNotFoundError, version
 
 
 def _resolve_version() -> str:
-    # `agex-cli` is the canonical PyPI distribution name; `agent-devex` and
-    # `devex-cli` are alias distributions that ship the identical wheel under
-    # different names. Whichever one is installed, surface its metadata
+    # `devex-cli` is the canonical PyPI distribution name; `agent-devex` and
+    # `agex-cli` are alias distributions that ship the identical wheel under
+    # different names (`agex-cli` is the legacy canonical name, kept published
+    # for back-compat). Whichever one is installed, surface its metadata
     # version. As a final fallback for unbuilt source checkouts (no installed
     # dist metadata), read the version directly from the repo's pyproject.toml
     # so the version stays single-sourced from pyproject.toml in every
     # reachable code path.
-    for dist in ("agex-cli", "agent-devex", "devex-cli"):
+    for dist in ("devex-cli", "agent-devex", "agex-cli"):
         try:
             return version(dist)
         except PackageNotFoundError:

{agex_cli-0.25.0/src/agent_experience → agex_cli-0.26.1/src/devex}/__main__.py

@@ -1,4 +1,4 @@
-from agent_experience.cli import _main_entrypoint
+from devex.cli import _main_entrypoint
 
 if __name__ == "__main__":
     _main_entrypoint()

{agex_cli-0.25.0/src/agent_experience → agex_cli-0.26.1/src/devex}/backends/acp/probe.py

@@ -1,6 +1,6 @@
 from pathlib import Path
 
-from agent_experience.backends.claude_code.probe import ProbeResult
+from devex.backends.claude_code.probe import ProbeResult
 
 
 def probe(project_dir: Path) -> ProbeResult:

{agex_cli-0.25.0/src/agent_experience → agex_cli-0.26.1/src/devex}/backends/capabilities/codex.yaml

@@ -1,7 +1,7 @@
 hooks: false
 hooks_alternative: |
   Codex does not expose a hook interface. Wrap your Codex invocation in a shell
-  script that calls `agex hook write` before/after each turn as a workaround.
+  script that calls `devex hook write` before/after each turn as a workaround.
 mcp: true
 skills: false
 agents: false

{agex_cli-0.25.0/src/agent_experience → agex_cli-0.26.1/src/devex}/backends/capabilities/copilot.yaml

@@ -1,7 +1,7 @@
 hooks: false
 hooks_alternative: |
   GitHub Copilot CLI does not expose a hook interface in v0.1-era versions.
-  Track usage via a shell wrapper that calls `agex hook write`.
+  Track usage via a shell wrapper that calls `devex hook write`.
 mcp: false
 skills: false
 agents: false

{agex_cli-0.25.0/src/agent_experience → agex_cli-0.26.1/src/devex}/backends/claude_code/probe.py

@@ -5,7 +5,7 @@ from typing import Any
 
 import yaml
 
-from agent_experience.core.skill_loader import load_skill
+from devex.core.skill_loader import load_skill
 
 _CLAUDE_DIR = ".claude"
 

{agex_cli-0.25.0/src/agent_experience → agex_cli-0.26.1/src/devex}/backends/codex/probe.py

@@ -1,6 +1,6 @@
 from pathlib import Path
 
-from agent_experience.backends.claude_code.probe import ProbeResult
+from devex.backends.claude_code.probe import ProbeResult
 
 
 def probe(project_dir: Path) -> ProbeResult:

{agex_cli-0.25.0/src/agent_experience → agex_cli-0.26.1/src/devex}/backends/copilot/probe.py

@@ -1,6 +1,6 @@
 from pathlib import Path
 
-from agent_experience.backends.claude_code.probe import ProbeResult
+from devex.backends.claude_code.probe import ProbeResult
 
 
 def probe(project_dir: Path) -> ProbeResult: