qodo-cli 0.3.2__tar.gz → 0.5.0__tar.gz

qodo_cli-0.5.0/.devague/current

@@ -0,0 +1 @@
+qodo-cli-now-does-qodo-s-two-core-jobs-natively-fr

qodo_cli-0.5.0/.devague/frames/qodo-cli-now-does-qodo-s-two-core-jobs-natively-fr.json

@@ -0,0 +1,168 @@
+{
+  "slug": "qodo-cli-now-does-qodo-s-two-core-jobs-natively-fr",
+  "title": "qodo-cli now does Qodo's two core jobs natively from your terminal, in zero-dependency Python: 'qodo rules' surfaces your org's coding rules by semantic search (reading your existing ~/.qodo/config.json API key), and 'qodo review' (a.k.a. 'qodo pr') triages and resolves the Qodo bot's PR review comments through your existing provider CLIs (gh/glab/az). Each verb cites the official qodo-ai/qodo-skills as its behavioral source of truth \u2014 we point at the skills as the spec; we do not fork, vendor, or npx-install them. A dedicated auth/config verb and repos/agents commands are explicit follow-ups.",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-06-16T17:43:44Z",
+  "updated": "2026-06-16T17:44:57Z",
+  "claims": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "qodo-cli now does Qodo's two core jobs natively from your terminal, in zero-dependency Python: 'qodo rules' surfaces your org's coding rules by semantic search (reading your existing ~/.qodo/config.json API key), and 'qodo review' (a.k.a. 'qodo pr') triages and resolves the Qodo bot's PR review comments through your existing provider CLIs (gh/glab/az). Each verb cites the official qodo-ai/qodo-skills as its behavioral source of truth \u2014 we point at the skills as the spec; we do not fork, vendor, or npx-install them. A dedicated auth/config verb and repos/agents commands are explicit follow-ups.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h1",
+          "text": "Behavioral parity is verifiable: for a given input, 'qodo rules'/'qodo review' make equivalent API/provider-CLI calls and apply the same severity mapping as the cited upstream skill.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "Developers and AI coding agents with a Qodo subscription who want one terminal-native, zero-dependency CLI for Qodo's domain \u2014 rules and PR review \u2014 instead of juggling per-agent skill installs (npx skills add) and the Qodo web app.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h5",
+          "text": "Audience is reachable: a Qodo subscriber can run 'qodo rules' / 'qodo review' on a machine that already has ~/.qodo/config.json (rules) and gh/glab/az (review), with no Qodo-side setup beyond what the skills already require.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c3",
+      "kind": "before_state",
+      "text": "Qodo's capabilities are reachable today only through (a) the per-agent skills in qodo-ai/qodo-skills, installed ad-hoc via 'npx skills add' / the Claude marketplace, and (b) the Qodo web app. qodo-cli has no Qodo surface yet \u2014 it is still the agent-first introspection scaffold (whoami/learn/explain/doctor).",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h6",
+          "text": "Before-state is checkable: 'git grep' in qodo-cli finds no rules/review command surface today, and the only ways to reach these Qodo behaviors are the upstream skills (npx skills add) and the Qodo web app.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c4",
+      "kind": "why_it_matters",
+      "text": "qodo-cli's stated domain is managing Qodo. Reimplementing the skills' behavior as native zero-dep commands \u2014 while citing qodo-ai/qodo-skills as the canonical spec \u2014 gives one consistent CLI across agents, removes Node/npx + per-agent-install friction, and keeps upstream as the source of truth we point at rather than a fork that drifts.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h7",
+          "text": "Benefit is observable: a user gets identical Qodo behavior from 'qodo ...' with no Node/npx or per-agent skill install, and upstream qodo-ai/qodo-skills stays the single cited source (no forked copy lives in this repo).",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c5",
+      "kind": "after_state",
+      "text": "'qodo' exposes two Qodo verbs as native command groups \u2014 'rules' (get) and 'review'/'pr' (list, resolve) \u2014 each documenting which upstream skill it derives from. 'rules' calls the Qodo API using the API key already in ~/.qodo/config.json; 'review' drives the user's existing provider CLIs (gh/glab/az) to read and resolve the Qodo bot's PR comments. There is no meta 'skills' verb; a dedicated auth/config verb is deferred to follow-up.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h2",
+          "text": "Every native verb's --help/docs names the upstream skill it cites (qodo-get-rules / qodo-pr-resolver) and the API endpoint or provider CLI it uses.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c6",
+      "kind": "boundary",
+      "text": "Non-goals: no 'qodo skills' verb and no npx-skills wrapper (skills are cited as spec, not shipped/installed/forked); no dedicated auth/config or repos/agents verbs in this slice (follow-ups); no reimplementation of Qodo's server-side analysis; not a general Agent-Skills package manager. 'qodo rules' requires a pre-existing ~/.qodo/config.json and does not implement an interactive login.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h8",
+          "text": "Non-goals are enforceable: the shipped CLI has no 'skills' verb and no npx invocation, 'qodo rules' errors (not prompts) when ~/.qodo/config.json is absent, and nothing in the repo vendors or forks upstream skill content.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c7",
+      "kind": "success_signal",
+      "text": "With a valid ~/.qodo/config.json, 'qodo rules get \"<task>\"' returns the same severity-ranked rules qodo-get-rules would; and on a repo with open Qodo PR comments, 'qodo review' lists and resolves the same comments qodo-pr-resolver would \u2014 behavioral parity with both cited skills from one zero-dep CLI.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h9",
+          "text": "Parity is demonstrable on a fixture: for a known task input 'qodo rules get' returns the same severity-ranked rules qodo-get-rules yields from the same API response; for a PR with known Qodo comments 'qodo review list' enumerates the same comments qodo-pr-resolver would.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c8",
+      "kind": "requirement",
+      "text": "qodo-cli reuses the skills' existing credentials as-is \u2014 ~/.qodo/config.json (API key + environment) for 'rules' and the user's already-working provider-CLI auth (gh/glab/az) for 'review' \u2014 introducing no new config format or auth flow.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h3",
+          "text": "On a machine where the skills already work, 'qodo rules' reads the same ~/.qodo/config.json keys with no migration, and 'qodo review' reuses the existing provider-CLI auth \u2014 neither prompts for new credentials.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c9",
+      "kind": "requirement",
+      "text": "Each verb maps 1:1 to a cited upstream skill: 'qodo rules' <- qodo-get-rules (POST /rules/search, severity ERROR/WARNING/RECOMMENDATION); 'qodo review'/'pr' <- qodo-pr-resolver (provider-CLI fetch of Qodo bot comments, dedup, fix, reply, resolve threads, push).",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h4",
+          "text": "The 1:1 verb<-skill mapping is checkable against the upstream SKILL.md scripts: the endpoints, severity labels, and provider-CLI calls match what those scripts do.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    }
+  ],
+  "open_vagueness": [
+    {
+      "id": "v1",
+      "text": "Exact Qodo API surface (endpoints, auth header, base URL per environment), the ~/.qodo/config.json schema, and which provider-comment APIs expose the Qodo bot's threads must be confirmed by reading the upstream skill scripts / Qodo API docs during planning.",
+      "kind": "unknown_nonblocking",
+      "claim_id": null
+    },
+    {
+      "id": "v2",
+      "text": "Dedicated 'qodo auth'/'qodo config' verb, repos-level commands, and Qodo agents management are future scope ('and more'), not built in this first slice.",
+      "kind": "follow_up",
+      "claim_id": null
+    }
+  ]
+}

{qodo_cli-0.3.2 → qodo_cli-0.5.0}/.gitignore

@@ -228,3 +228,6 @@ __marimo__/
 
 # Per-machine skills config (copy from skills.local.yaml.example)
 skills.local.yaml
+
+# devague working state (not committed by default)
+.devague/questions/

{qodo_cli-0.3.2 → qodo_cli-0.5.0}/.markdownlint-cli2.yaml

@@ -21,3 +21,6 @@ ignores:
   - ".teken/**"
   # Vendored skills are cited verbatim from guildmaster — do not reformat them.
   - ".claude/skills/**"
+  # devague-exported specs are generated artifacts (the H1 is the verbatim
+  # announcement; bodies carry literal "<placeholders>") — do not reformat them.
+  - "docs/specs/**"

qodo_cli-0.5.0/.pr_agent.toml

@@ -0,0 +1,26 @@
+# Qodo Merge / PR-Agent configuration for qodo-cli.
+# Docs: https://docs.qodo.ai/qodo-documentation/qodo-merge/configuration/configuration-file
+#
+# Kept minimal on purpose (per Qodo's guidance: only override what you need).
+# The repo's coding conventions live in best_practices.md at the root, which the
+# reviewer auto-references; this file just reinforces a few intentional patterns
+# that an earlier review flagged as false positives.
+
+[pr_reviewer]
+extra_instructions = """
+qodo-cli is an unofficial, community CLI to manage Qodo, built as a
+zero-runtime-dependency, stdlib-only Python package. Intentional patterns (do
+not flag these as issues):
+- Command handlers return a bare 0/1/None for the exit code. The EXIT_* constants
+  in qodo/cli/_errors.py are for CliError codes (the failure path), not for
+  handler return values. `return 0` in a handler is intentional and consistent
+  across every command.
+- Nested argparse subparsers inherit the structured-error parser class via
+  `add_subparsers(parser_class=type(p))` (see qodo/cli/_commands/cli.py). Passing
+  `type(p)` is the established idiom and is equivalent to naming
+  `_CliArgumentParser` directly — it is not a missing parser_class.
+- `qodo review resolve --reply` drives the user's own `gh` with their own auth;
+  the reply text belongs to the caller, so the tool must not auto-append an agent
+  signature.
+See best_practices.md at the repo root for the full conventions.
+"""

{qodo_cli-0.3.2 → qodo_cli-0.5.0}/CHANGELOG.md

@@ -5,6 +5,77 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-06-17
+
+### Added
+
+- `.pr_agent.toml` + `best_practices.md` at the repo root — the Qodo Merge
+  reviewer config (cite, don't fork). They codify this repo's intentional
+  patterns (bare `return 0` handlers, `parser_class=type(p)` subparser nesting,
+  the mechanics-only `review resolve --reply`) so Qodo reviews accurately and
+  stops raising them as violations.
+- `qodo doctor` now also checks **Qodo setup**, against the current git repo:
+  `.pr_agent.toml` present, `best_practices.md` present, and whether a usable
+  Qodo API key is resolvable for `qodo rules` — `QODO_API_KEY`, else a non-empty
+  `API_KEY` in `~/.qodo/config.json` (a present-but-keyless or malformed file
+  fails the check with guidance, and never throws). These are advisory and each
+  carries a `remediation` that guides an agent through setup. Runs in any repo
+  (not just a source checkout). (Addresses #7.)
+
+### Changed
+
+- `qodo doctor` `healthy` now depends on **error**-severity checks only;
+  `warning`/`info` checks surface guidance without flipping `healthy` or the
+  exit code. Fixes the `claude → CLAUDE.md` drift in the `doctor` explain entry
+  (this repo's backend is `colleague` → `AGENTS.colleague.md`).
+- `learn` now describes `doctor` as "agent-identity invariants + Qodo setup" in
+  both its text and JSON payload, matching `overview` and the explain catalog
+  (self-description stays consistent across the introspection surfaces).
+
+## [0.4.0] - 2026-06-17
+
+### Added
+
+- First real Qodo-management surface — two native, zero-dependency noun groups,
+  each citing `qodo-ai/qodo-skills` as its behavioral source of truth (cite,
+  don't fork/vendor/npx):
+  - `qodo rules get "<query>"` — semantic-search your org's Qodo coding rules.
+    Reimplements `qodo-get-rules` over the stdlib (`urllib`): reads the API key
+    already in `~/.qodo/config.json` (env `QODO_API_KEY`/`QODO_ENVIRONMENT_NAME`/
+    `QODO_API_URL` win), POSTs `{base}/rules/search`, and prints the
+    relevance-ranked rules with `ERROR`/`WARNING`/`RECOMMENDATION` severity.
+    Errors (never prompts) when no credentials are present.
+  - `qodo review` (alias `qodo pr`) — `list` and `resolve` the Qodo bot's PR
+    review comments. Reimplements `qodo-pr-resolver` by driving the user's
+    existing provider CLI (`gh`): detect provider, find the open PR for the
+    branch, fetch and filter the Qodo bot's comments (`qodo-code-review`,
+    `qodo-merge`, `qodo-ai`, `pr-agent-pro(-staging)` — matched as base names so
+    both gh `[bot]`-suffix spellings hit), dedup by stable comment identity
+    (id/url) so distinct same-badge inline comments never collapse, reply, and
+    acknowledge (`+1`). GitHub is wired — including GitHub Enterprise, recognised
+    via your `gh` host config (`gh auth status --hostname`) rather than hostname
+    guessing (implemented but not live-tested against a real GHE instance);
+    GitLab/Azure/Bitbucket/Gerrit are recognised but raise a clear "not wired
+    yet" error.
+- `qodo/cli/_qodo_api.py` and `qodo/cli/_providers.py` — the zero-dep mechanics
+  behind the two verbs (stdlib `urllib` / `subprocess` only).
+- `docs/qodo-skills-sources.md` — the Qodo-skills citation ledger: verb↔skill
+  map, the resolved API/provider contract, follow-up providers, and a re-sync
+  procedure.
+- `docs/specs/…-qodo-cli-now-does-qodo-s-two-core-jobs-natively-fr.md` — the
+  converged `/think` spec this slice was built from.
+
+### Changed
+
+- `learn`, `overview`, the explain catalog root, and the parser description now
+  describe the real Qodo surface instead of self-describing as "a clonable
+  template" (the drift CLAUDE.md flagged); `overview`'s artifact list now names
+  `AGENTS.colleague.md` (the colleague-backend prompt file) rather than
+  `CLAUDE.md`.
+- `.markdownlint-cli2.yaml` ignores `docs/specs/**` — devague-exported specs are
+  generated artifacts (verbatim-announcement H1, literal `<placeholders>`) and
+  are not reformatted, mirroring the vendored-skills exclusion.
+
 ## [0.3.2] - 2026-06-16
 
 ### Fixed

{qodo_cli-0.3.2 → qodo_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qodo-cli
-Version: 0.3.2
+Version: 0.5.0
 Summary: Community CLI and agent to manage Qodo — the AI code reviewer and Qodo's other agents (requires a Qodo subscription). Unofficial: not affiliated with, authorized, or endorsed by Qodo; the Qodo name and trademark belong to Qodo Ltd.
 Project-URL: Homepage, https://github.com/agentculture/qodo-cli
 Project-URL: Issues, https://github.com/agentculture/qodo-cli/issues

qodo_cli-0.5.0/best_practices.md

@@ -0,0 +1,59 @@
+# Best practices for qodo-cli
+
+Repository-specific coding standards for the Qodo reviewer — and for any agent
+working in this repo. `qodo-cli` is an unofficial, community CLI to manage Qodo,
+built as a **zero-runtime-dependency, stdlib-only** Python package.
+
+These conventions are pinned by the test suite and the agent-first rubric
+(`teken cli doctor . --strict`); please review against them rather than against
+generic defaults.
+
+## Dependencies
+
+- Runtime dependencies must stay empty (`dependencies = []` in `pyproject.toml`).
+  Use only the Python standard library at runtime, and flag any new third-party
+  runtime import. `teken` and the lint/test tools are dev-only.
+
+## Exit codes
+
+- Command handlers return a bare `0` / `1` / `None` for their exit code (`0` is
+  success). The `EXIT_*` constants in `qodo/cli/_errors.py` are for `CliError`
+  codes on the failure path, **not** for handler return values. A bare
+  `return 0` in a handler is intentional and consistent across every command —
+  do not flag it as a magic number.
+
+## Errors and output
+
+- Every failure raises `CliError(code, message, remediation)`; no Python
+  traceback may leak to stderr. Text-mode errors render `error: <msg>` then
+  `hint: <remediation>` (the `hint:` prefix is required).
+- Results go to stdout; errors and diagnostics go to stderr. Never mix the two,
+  in text or `--json` mode. Every command supports `--json`.
+
+## argparse
+
+- Build subparsers with the structured-error parser class. Nested subparsers
+  inherit it via `add_subparsers(parser_class=type(p))` (see
+  `qodo/cli/_commands/cli.py`); passing `type(p)` is the established idiom and is
+  equivalent to naming `_CliArgumentParser` directly — it is not a missing
+  `parser_class`.
+- Add the standard `--json` flag with `add_json_flag()` from `qodo.cli._output`
+  rather than re-declaring the literal.
+
+## The CLI is mechanics-only
+
+- `qodo review resolve --reply` drives the user's own `gh` with their own auth;
+  the reply text belongs to the caller. The tool must not auto-append an agent
+  signature — that would mis-attribute human-authored replies. Signing is the
+  caller's responsibility (an opt-in flag may be added later).
+
+## Cite, don't import
+
+- Behavior derived from `qodo-ai/qodo-skills` and the vendored `.claude/skills/`
+  kit is cited as the source of truth, not forked or vendored into runtime code.
+  Keep `docs/qodo-skills-sources.md` in sync when the upstream contract changes.
+
+## Keep the self-description in sync
+
+- When adding a command, update `learn`, `overview`, and the explain catalog so
+  the rubric and the self-describing text stay consistent.

qodo_cli-0.5.0/docs/qodo-skills-sources.md

@@ -0,0 +1,117 @@
+# Qodo-skills citation ledger
+
+`qodo rules` and `qodo review` are **native reimplementations** of the two
+official skills in [`qodo-ai/qodo-skills`](https://github.com/qodo-ai/qodo-skills).
+We **cite, don't import**: those skills are the behavioral source of truth that
+this CLI points at — we do **not** fork, vendor, or `npx skills add` them, and no
+copy of their content lives in this repo. This ledger records what each native
+verb derives from, what we reimplement versus what stays the calling agent's job,
+and the resolved API/provider contract.
+
+If upstream changes, this is the file to re-check the contract against.
+
+## Verb ↔ skill map
+
+| qodo-cli verb | Upstream skill | Upstream reference |
+| --- | --- | --- |
+| `qodo rules get` | `qodo-get-rules` | `skills/qodo-get-rules/SKILL.md`, `references/search-endpoint.md`, `references/output-format.md` |
+| `qodo review list` / `resolve` (alias `qodo pr`) | `qodo-pr-resolver` | `skills/qodo-pr-resolver/SKILL.md`, `resources/providers.md` |
+
+## What we reimplement vs. what stays agent-side
+
+The skills are agent harnesses: they mix deterministic API/provider mechanics
+with LLM-driven steps (generating search queries, reading code, writing fixes).
+This CLI owns **only the deterministic mechanics**. The LLM steps stay with the
+calling agent — which keeps the CLI zero-dependency and model-agnostic.
+
+- **`qodo rules`** — we own: read `~/.qodo/config.json`, build the base URL,
+  POST `/rules/search`, return relevance-ranked rules with severity. The agent
+  owns: turning a task into the two structured queries `qodo-get-rules`
+  generates (call `rules get` once per query and merge).
+- **`qodo review`** — we own: detect the provider, find the open PR, fetch and
+  filter the Qodo bot's comments, dedup by stable comment identity (id/url),
+  reply, acknowledge. The agent owns: reading the flagged files, generating a
+  fix, editing, and committing.
+
+## Resolved contract — `qodo-get-rules`
+
+- **Config:** `~/.qodo/config.json`. Keys: `API_KEY` (env `QODO_API_KEY` wins),
+  `ENVIRONMENT_NAME` (env `QODO_ENVIRONMENT_NAME` wins), `QODO_API_URL` (optional
+  override). Absent config is not fatal if `QODO_API_KEY` is set; otherwise it is
+  an environment error — the CLI never prompts for credentials.
+- **Base URL:** `QODO_API_URL` → `{url}/rules/v1`. Otherwise by environment:
+  empty → `https://qodo-platform.qodo.ai/rules/v1`, else
+  `https://qodo-platform.<env>.qodo.ai/rules/v1` (e.g. `staging`, `qodost.st`).
+- **Endpoint:** `POST {base}/rules/search`.
+- **Headers:** `Authorization: Bearer <API_KEY>`, `request-id` (a per-call UUID),
+  `qodo-client-type` (telemetry; we send `qodo-cli`), optional `trace_id` (from
+  `TRACE_ID`).
+- **Request body:** `{"query": <str>, "top_k": <int>, "scopes": [<str>]}`.
+  `scopes` is omitted entirely when empty (never `null` / `[]`). `top_k`
+  defaults to `20`.
+- **Response:** `{"rules": [{"id", "name", "content", "severity"}]}`, ranked by
+  relevance (most relevant first). Severity is one of `ERROR`, `WARNING`,
+  `RECOMMENDATION`.
+
+## Resolved contract — `qodo-pr-resolver`
+
+- **Qodo bot logins:** `qodo-merge`, `qodo-ai`, `pr-agent-pro`,
+  `pr-agent-pro-staging` (from the skill), plus `qodo-code-review` (observed
+  live on GitHub — the login the current Qodo reviewer posts under). Matched as
+  base names: `gh pr view --json comments` returns the login **without** `[bot]`
+  while `gh api` returns it **with** `[bot]`, so the suffix is normalised before
+  matching. (Gerrit: comments tagged `autogenerated:qodo`.)
+- **Comment surfaces:** the summary arrives as PR-level **issue comments**
+  (`gh pr view --json comments`) and per-issue **inline review comments**
+  (`gh api .../pulls/<pr>/comments`). We deliberately do **not** fetch
+  `pulls/<pr>/reviews` — the skill documents only the two surfaces above, and
+  the reviews endpoint was empty on a live Qodo-reviewed PR.
+- **Provider detection:** `git remote get-url origin`, matched against the host.
+- **Provider detection upgrade (GitHub Enterprise):** `github.com` classifies as
+  GitHub directly. Any other host that is *unknown* to the well-known-host map is
+  re-checked against `gh auth status --hostname <host>` — if `gh` is
+  authenticated to it, it is treated as a GitHub Enterprise host (we don't guess
+  GHE hostnames). **Implemented but NOT live-tested** against a real GHE instance
+  (we have none); covered by mocked tests only.
+- **GitHub (wired now), via `gh`:**
+  - find PR: `gh pr list --head <branch> --state open --json number,title,url`
+  - summary comments: `gh pr view <pr> --json comments`
+  - inline comments: `gh api repos/{owner}/{repo}/pulls/<pr>/comments --paginate`
+  - reply: `gh api repos/{owner}/{repo}/pulls/<pr>/comments/<id>/replies -X POST -f body=<text>`
+  - acknowledge: `gh api repos/{owner}/{repo}/pulls/comments/<id>/reactions -X POST -f content='+1'`
+
+### Follow-up providers (recognised, not yet wired)
+
+These are captured from `resources/providers.md` so wiring them is a lookup, not
+a re-investigation. Today the CLI raises a clear "not wired yet" error for them.
+
+- **GitLab (`glab`):** find `glab mr list --source-branch <branch>`; fetch
+  `glab mr view <iid> --comments`; reply / resolve via
+  `glab api /projects/:id/merge_requests/<iid>/discussions/...`.
+- **Azure DevOps (`az`):** find `az repos pr list --source-branch <branch> --status active`;
+  fetch / reply / resolve via `az devops invoke --resource pullRequestThreads`.
+- **Bitbucket (`curl`):** REST under
+  `api.bitbucket.org/2.0/repositories/<ws>/<repo>/pullrequests/<id>/comments`.
+- **Gerrit:** detect via `.gitreview` / port `29418` / `googlesource.com`; push
+  `git push origin HEAD:refs/for/<branch>`.
+
+True GitHub review-thread resolution (the GraphQL `resolveReviewThread`
+mutation) is also a follow-up; today `resolve` posts the `+1` reaction the
+upstream skill uses as a lightweight acknowledgement.
+
+## Non-goals (enforced)
+
+- No `qodo skills` verb and no `npx skills add` wrapper — skills are cited as a
+  spec, never shipped, installed, or forked.
+- No reimplementation of Qodo's server-side analysis.
+- `qodo rules` does not implement an interactive login — it reuses existing
+  credentials and errors when they are absent.
+
+## Re-sync procedure
+
+1. Re-fetch the upstream `SKILL.md` and the `references/` / `resources/` files
+   listed in the verb↔skill map above.
+2. Diff the resolved contract in this file against them (endpoint, headers,
+   request/response schema, bot logins, provider commands).
+3. Update `qodo/cli/_qodo_api.py` / `qodo/cli/_providers.py` and this ledger
+   together, then bump the version.

qodo_cli-0.5.0/docs/specs/2026-06-16-qodo-cli-now-does-qodo-s-two-core-jobs-natively-fr.md

@@ -0,0 +1,45 @@
+# qodo-cli now does Qodo's two core jobs natively from your terminal, in zero-dependency Python: 'qodo rules' surfaces your org's coding rules by semantic search (reading your existing ~/.qodo/config.json API key), and 'qodo review' (a.k.a. 'qodo pr') triages and resolves the Qodo bot's PR review comments through your existing provider CLIs (gh/glab/az). Each verb cites the official qodo-ai/qodo-skills as its behavioral source of truth — we point at the skills as the spec; we do not fork, vendor, or npx-install them. A dedicated auth/config verb and repos/agents commands are explicit follow-ups.
+
+> qodo-cli now does Qodo's two core jobs natively from your terminal, in zero-dependency Python: 'qodo rules' surfaces your org's coding rules by semantic search (reading your existing ~/.qodo/config.json API key), and 'qodo review' (a.k.a. 'qodo pr') triages and resolves the Qodo bot's PR review comments through your existing provider CLIs (gh/glab/az). Each verb cites the official qodo-ai/qodo-skills as its behavioral source of truth — we point at the skills as the spec; we do not fork, vendor, or npx-install them. A dedicated auth/config verb and repos/agents commands are explicit follow-ups.
+
+## Audience
+
+- Developers and AI coding agents with a Qodo subscription who want one terminal-native, zero-dependency CLI for Qodo's domain — rules and PR review — instead of juggling per-agent skill installs (npx skills add) and the Qodo web app.
+
+## Before → After
+
+- Before: Qodo's capabilities are reachable today only through (a) the per-agent skills in qodo-ai/qodo-skills, installed ad-hoc via 'npx skills add' / the Claude marketplace, and (b) the Qodo web app. qodo-cli has no Qodo surface yet — it is still the agent-first introspection scaffold (whoami/learn/explain/doctor).
+- After: 'qodo' exposes two Qodo verbs as native command groups — 'rules' (get) and 'review'/'pr' (list, resolve) — each documenting which upstream skill it derives from. 'rules' calls the Qodo API using the API key already in ~/.qodo/config.json; 'review' drives the user's existing provider CLIs (gh/glab/az) to read and resolve the Qodo bot's PR comments. There is no meta 'skills' verb; a dedicated auth/config verb is deferred to follow-up.
+
+## Why it matters
+
+- qodo-cli's stated domain is managing Qodo. Reimplementing the skills' behavior as native zero-dep commands — while citing qodo-ai/qodo-skills as the canonical spec — gives one consistent CLI across agents, removes Node/npx + per-agent-install friction, and keeps upstream as the source of truth we point at rather than a fork that drifts.
+
+## Requirements
+
+- qodo-cli reuses the skills' existing credentials as-is — ~/.qodo/config.json (API key + environment) for 'rules' and the user's already-working provider-CLI auth (gh/glab/az) for 'review' — introducing no new config format or auth flow.
+  - honesty: On a machine where the skills already work, 'qodo rules' reads the same ~/.qodo/config.json keys with no migration, and 'qodo review' reuses the existing provider-CLI auth — neither prompts for new credentials.
+- Each verb maps 1:1 to a cited upstream skill: 'qodo rules' <- qodo-get-rules (POST /rules/search, severity ERROR/WARNING/RECOMMENDATION); 'qodo review'/'pr' <- qodo-pr-resolver (provider-CLI fetch of Qodo bot comments, dedup, fix, reply, resolve threads, push).
+  - honesty: The 1:1 verb<-skill mapping is checkable against the upstream SKILL.md scripts: the endpoints, severity labels, and provider-CLI calls match what those scripts do.
+
+## Honesty conditions
+
+- Behavioral parity is verifiable: for a given input, 'qodo rules'/'qodo review' make equivalent API/provider-CLI calls and apply the same severity mapping as the cited upstream skill.
+- Audience is reachable: a Qodo subscriber can run 'qodo rules' / 'qodo review' on a machine that already has ~/.qodo/config.json (rules) and gh/glab/az (review), with no Qodo-side setup beyond what the skills already require.
+- Before-state is checkable: 'git grep' in qodo-cli finds no rules/review command surface today, and the only ways to reach these Qodo behaviors are the upstream skills (npx skills add) and the Qodo web app.
+- Benefit is observable: a user gets identical Qodo behavior from 'qodo ...' with no Node/npx or per-agent skill install, and upstream qodo-ai/qodo-skills stays the single cited source (no forked copy lives in this repo).
+- Every native verb's --help/docs names the upstream skill it cites (qodo-get-rules / qodo-pr-resolver) and the API endpoint or provider CLI it uses.
+- Non-goals are enforceable: the shipped CLI has no 'skills' verb and no npx invocation, 'qodo rules' errors (not prompts) when ~/.qodo/config.json is absent, and nothing in the repo vendors or forks upstream skill content.
+- Parity is demonstrable on a fixture: for a known task input 'qodo rules get' returns the same severity-ranked rules qodo-get-rules yields from the same API response; for a PR with known Qodo comments 'qodo review list' enumerates the same comments qodo-pr-resolver would.
+
+## Success signals
+
+- With a valid ~/.qodo/config.json, 'qodo rules get "<task>"' returns the same severity-ranked rules qodo-get-rules would; and on a repo with open Qodo PR comments, 'qodo review' lists and resolves the same comments qodo-pr-resolver would — behavioral parity with both cited skills from one zero-dep CLI.
+
+## Scope / boundaries
+
+- Non-goals: no 'qodo skills' verb and no npx-skills wrapper (skills are cited as spec, not shipped/installed/forked); no dedicated auth/config or repos/agents verbs in this slice (follow-ups); no reimplementation of Qodo's server-side analysis; not a general Agent-Skills package manager. 'qodo rules' requires a pre-existing ~/.qodo/config.json and does not implement an interactive login.
+
+## Open / follow-up
+
+- Dedicated 'qodo auth'/'qodo config' verb, repos-level commands, and Qodo agents management are future scope ('and more'), not built in this first slice.

{qodo_cli-0.3.2 → qodo_cli-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qodo-cli"
-version = "0.3.2"
+version = "0.5.0"
 description = "Community CLI and agent to manage Qodo — the AI code reviewer and Qodo's other agents (requires a Qodo subscription). Unofficial: not affiliated with, authorized, or endorsed by Qodo; the Qodo name and trademark belong to Qodo Ltd."
 readme = "README.md"
 license = "MIT"

{qodo_cli-0.3.2 → qodo_cli-0.5.0}/qodo/cli/__init__.py

@@ -67,11 +67,13 @@ def _build_parser() -> argparse.ArgumentParser:
     from qodo.cli._commands import explain as _explain_cmd
     from qodo.cli._commands import learn as _learn_cmd
     from qodo.cli._commands import overview as _overview_cmd
+    from qodo.cli._commands import review as _review_group
+    from qodo.cli._commands import rules as _rules_group
     from qodo.cli._commands import whoami as _whoami_cmd
 
     parser = _CliArgumentParser(
         prog="qodo-cli",
-        description="qodo-cli — a clonable template for AgentCulture mesh agents.",
+        description="qodo-cli — an unofficial community CLI to manage Qodo (rules + PR review).",
     )
     parser.add_argument(
         "--version",
@@ -82,13 +84,17 @@ def _build_parser() -> argparse.ArgumentParser:
     # through _CliArgumentParser too.
     sub = parser.add_subparsers(dest="command", parser_class=_CliArgumentParser)
 
+    # Qodo domain noun groups (the real surface):
+    _rules_group.register(sub)
+    _review_group.register(sub)
+    # Agent-first introspection verbs:
     _whoami_cmd.register(sub)
     _learn_cmd.register(sub)
     _explain_cmd.register(sub)
     _overview_cmd.register(sub)
     _doctor_cmd.register(sub)
     _cli_group.register(sub)
-    # Register your own noun groups here:
+    # Register further noun groups here, following the rules/review pattern:
     #   from qodo.cli._commands import my_noun as _my_noun_group
     #   _my_noun_group.register(sub)
 

{qodo_cli-0.3.2 → qodo_cli-0.5.0}/qodo/cli/_commands/cli.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 import argparse
 
 from qodo.cli._commands.overview import cli_sections, emit_overview
+from qodo.cli._output import add_json_flag
 
 
 def cmd_cli_overview(args: argparse.Namespace) -> int:
@@ -32,12 +33,12 @@ def register(sub: argparse._SubParsersAction) -> None:
         "cli",
         help="CLI-surface introspection (see 'qodo-cli cli overview').",
     )
-    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    add_json_flag(p)
     p.set_defaults(func=_no_verb, json=False)
     # `p` is a _CliArgumentParser (the top-level subparsers were built with that
     # parser_class); propagate it so `cli overview` parse errors route through
     # the structured error contract instead of argparse's default stderr/exit 2.
     noun_sub = p.add_subparsers(dest="cli_command", parser_class=type(p))
     ov = noun_sub.add_parser("overview", help="Describe the qodo-cli CLI surface.")
-    ov.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    add_json_flag(ov)
     ov.set_defaults(func=cmd_cli_overview)