agentirc-cli 6.2.2__tar.gz → 6.2.3__tar.gz

agentirc_cli-6.2.3/.claude/agents/doc-test-alignment.md

@@ -0,0 +1,154 @@
+---
+name: doc-test-alignment
+description: Audits a staged/branch diff for new public API surface (exceptions, classes, public functions, CLI commands, IRC protocol verbs, backend config fields) and reports whether `docs/` and `protocol/extensions/` mention them. Use at the end of a plan, before the first push, or when the user says "doc audit", "doc-test alignment", "check docs coverage".
+tools: Read, Grep, Glob, Bash
+model: sonnet
+color: cyan
+---
+
+# Doc-Test Alignment Auditor
+
+You audit a code change for **doc drift**: new public API surface that
+`docs/` doesn't mention. Run at the end of a plan (after tests pass, before
+push). Your job is to surface omissions, not to write docs.
+
+## Step 1 — Determine the diff
+
+If the caller passed a specific ref or file list, use that. Otherwise, audit
+the current branch against `main`:
+
+```bash
+git diff --name-only main...HEAD
+git diff main...HEAD -- '*.py' 'culture/cli/*' 'culture/agentirc/*'
+```
+
+If the branch has no commits ahead of `main`, fall back to staged changes:
+
+```bash
+git diff --cached --name-only
+git diff --cached -- '*.py'
+```
+
+If neither yields a diff, report "no changes to audit" and stop.
+
+## Step 2 — Extract new public API surface
+
+Run the patterns via the **Grep tool** (ripgrep / Rust regex engine — the
+Claude Code default). Patterns below are written in the Rust regex flavor
+that ripgrep accepts without any extra flags: `\s`, `(?:...)`, and character
+classes all work as written. Do **not** pipe these into POSIX `grep` / BRE
+— they will silently fail to match.
+
+Save the diff first, then search it:
+
+```bash
+git diff main...HEAD -- '*.py' 'culture/cli/*' 'culture/agentirc/*' > /tmp/branch-diff.patch
+```
+
+Then feed `/tmp/branch-diff.patch` to the Grep tool with each pattern below.
+
+| Surface type | Ripgrep pattern |
+|--------------|-----------------|
+| New exception class | `^\+class [A-Z][A-Za-z0-9_]*(\(.*(?:Error\|Exception).*\))?:` |
+| New public class | `^\+class [A-Z][A-Za-z0-9_]*` (exclude leading `_`) |
+| New public function | `^\+(async )?def [a-z][a-z0-9_]*\(` (exclude leading `_`) |
+| New CLI command | `^\+.*add_parser\(['"]` in `culture/cli/` |
+| New IRC verb | `^\+.*(_msg_handlers\[['"]\|commands\s*=).*['"][A-Z0-9]+['"]` |
+| New config field | `^\+.*@dataclass` or `^\+\s+[a-z_]+:\s+[A-Z].*=` in config modules |
+
+Ignore private symbols (leading `_`), test helpers (inside `tests/`), and
+internal-only classes (docstring contains "internal" or "private").
+
+List every match with:
+
+- symbol name
+- file path + starting line
+- kind (exception / class / function / CLI command / IRC verb / config field)
+
+## Step 3 — Check doc coverage
+
+For each extracted symbol, grep the documentation tree for a mention:
+
+```bash
+grep -r -l '<symbol>' docs/ protocol/extensions/ 2>/dev/null
+```
+
+Match rules:
+
+- **Exception**: must be referenced in at least one `docs/**/*.md` page. If
+  it's a new public exception raised across module boundaries, that's a
+  stronger obligation — flag loudly.
+- **CLI command**: must appear in `docs/` (user-facing command reference)
+  AND in the command's own module docstring.
+- **IRC verb / protocol extension**: MUST have a page under
+  `protocol/extensions/` (per the repository-root `CLAUDE.md`: "Extensions
+  use new verbs (never redefine existing commands), documented in
+  `protocol/extensions/`").
+- **Config field**: must appear in the relevant backend's `culture.yaml`
+  reference under `packages/agent-harness/culture.yaml` or
+  `docs/configuration.md`.
+- **Public function/class**: soft obligation — flag if the symbol is
+  imported from outside its module, skip if it's used only within its
+  package.
+
+## Step 4 — Check test coverage (light)
+
+For each public surface symbol, grep `tests/` for at least one reference:
+
+```bash
+grep -r -l '<symbol>' tests/ 2>/dev/null
+```
+
+If zero test files reference the symbol, flag it. This is a weak signal —
+the caller may have tested behavior without naming the symbol directly.
+Report as "likely untested" rather than "untested".
+
+## Step 5 — All-backends check (culture-specific)
+
+If the diff touches `culture/clients/<backend>/` OR `packages/agent-harness/`,
+list the other backends (`claude`, `codex`, `copilot`, `acp`) and report
+whether the same change appears in each. This enforces the project's
+"all-backends rule" (per the repository-root `CLAUDE.md`). A change in
+only one backend is a bug.
+
+## Step 6 — Report
+
+Output a concise table. Factual only: what symbols, what's missing,
+what's drifted. Do **not** write prose narration and do **not** suggest
+what the docs should say — leave doc wording to the caller. A brief
+counts-only summary line at the end is fine; skip it if everything is
+clean.
+
+```text
+## Doc-Test Alignment — <branch> vs main
+
+### New public API surface
+| Symbol | Kind | Location | Docs | Tests |
+|--------|------|----------|------|-------|
+| ConsoleConnectionLost | exception | culture/console/client.py:42 | MISSING | test_console_client.py |
+| _handle_reconnect | private | culture/console/app.py:412 | (skip — private) | — |
+
+### Protocol extensions
+(none in this diff)
+
+### All-backends drift
+Change touches `packages/agent-harness/irc_transport.py`:
+- claude: ✓ updated
+- codex: ✓ updated
+- copilot: ✗ NOT updated (divergent)
+- acp: ✗ NOT updated (divergent)
+
+### Summary
+Doc gaps: 1 · Likely untested: 0 · Backend drift: 2
+```
+
+If nothing is missing, output one line: `Doc-test alignment clean — no gaps detected.`
+
+## What NOT to do
+
+- Do not write documentation. Report gaps only.
+- Do not modify code or tests.
+- Do not fail loudly on borderline cases (internal-only helpers, test
+  utilities) — the caller is smarter than the heuristics; your value is in
+  catching the obvious omissions.
+- Do not re-run the test suite — `/run-tests` is the tool for that.

{agentirc_cli-6.2.2 → agentirc_cli-6.2.3}/.claude/skills/pr-review/SKILL.md

@@ -171,7 +171,15 @@ bash ~/.claude/skills/pr-review/scripts/pr-reply.sh --resolve <PR_NUMBER> <COMME
 - Always use `--resolve` to resolve the thread after replying
 - Every comment must get a reply — no silent fixes
 
-## Step 9 — Wait for merge
+## Step 9 — Check SonarCloud before declaring ready
+
+After CI is green and all inline threads are resolved, query SonarCloud
+for the branch via the `/sonarclaude` skill. SonarCloud findings do not
+always arrive as inline PR comments — a fully-resolved thread list plus an
+all-green `gh pr checks` is **not** sufficient evidence that the PR is
+clean. If `/sonarclaude` surfaces new findings, loop back to Step 7.
+
+## Step 10 — Wait for merge
 
 **Never merge the PR yourself.** The PR is merged manually on the GitHub site.
 

{agentirc_cli-6.2.2 → agentirc_cli-6.2.3}/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [6.2.3] - 2026-04-15
+
+
+### Changed
+
+- docs: post-#231 retrospective — CLAUDE.md guidance for pre-branch checklist, format-before-commit, pre-push code review, SonarCloud pre-ready; new doc-test-alignment subagent; /pr-review skill step for SonarCloud query
+
 ## [6.2.2] - 2026-04-14
 
 

{agentirc_cli-6.2.2 → agentirc_cli-6.2.3}/CLAUDE.md

@@ -49,13 +49,18 @@ Each backend has its own `culture.yaml` in `culture/clients/<backend>/`.
 
 When implementing features, write a corresponding markdown doc in `docs/` describing the feature — its purpose, usage, and any protocol details. Keep `docs/` as the living reference for the project.
 
+Before the first push on a branch that adds public API surface (new exceptions, CLI commands, IRC verbs, backend config fields), invoke the `doc-test-alignment` subagent to surface doc gaps: `Agent(subagent_type="doc-test-alignment", ...)`. It reads the branch diff and reports missing `docs/` coverage, missing protocol extension pages, and all-backends drift — it does not write docs, only flags omissions.
+
 ## Git Workflow
 
+- **Before branching, run `git status`.** If `CHANGELOG.md`, any `CLAUDE.md`, or other files carry pre-existing unstaged changes on `main`, decide up front whether to stash, commit separately, or hand-split. `/version-bump` inserts a new section at the top of `CHANGELOG.md` and will interleave awkwardly with an existing `[Unreleased]` block if you don't.
 - Branch out for all changes
-- **Bump the version before creating a PR** — use `/version-bump patch` (bug fix), `minor` (new feature), or `major` (breaking change). This updates `pyproject.toml`, `culture/__init__.py`, and `CHANGELOG.md` in one step. Forgetting will fail the version-check CI job.
+- **Bump the version before creating a PR** — use `/version-bump patch` (bug fix), `minor` (new feature), or `major` (breaking change). This updates `pyproject.toml` and `CHANGELOG.md` (and `uv.lock` when applicable) in one step. Forgetting will fail the version-check CI job.
+- **Pre-push review for library/protocol code.** When the diff touches shared choke points (transport, `_send_raw`-style I/O, protocol parsers, anything in `packages/` or `culture/agentirc/`), invoke a code reviewer on the staged diff before the first push — typed exceptions and new error paths routinely create caller cleanup obligations that Qodo/human reviewers otherwise surface in the first review round. Use `Agent(subagent_type="superpowers:code-reviewer", ...)` or `/review-and-fix`.
 - Push to GitHub for agentic code review
 - Pull review comments, address feedback, push fixes
 - Reply to comments after pushing, resolve threads
+- **Before declaring the PR ready**, check SonarCloud for the branch via the `/sonarclaude` skill. SonarCloud findings do not always arrive as inline PR comments, so an all-green `gh pr checks` + all-resolved threads is not sufficient.
 
 ## Testing
 
@@ -64,6 +69,10 @@ When implementing features, write a corresponding markdown doc in `docs/` descri
 - No mocks for the server — tests spin up real server instances on random ports with real TCP connections
 - Validate each layer with real IRC clients (weechat/irssi)
 
+## Format Before Commit
+
+Pre-commit runs `black`, `isort`, `flake8`, `pylint`, `bandit`. `black`/`isort` failures reformat the file and reject the commit — you then have to `git add` the reformatted file and commit again. To avoid the re-commit loop, run `uv run black <files>` and `uv run isort <files>` on staged Python files **before** `git commit`.
+
 ## Nick Format
 
 `<server>-<agent>` (e.g., `thor-claude`, `spark-ori`). Globally unique by construction.

{agentirc_cli-6.2.2 → agentirc_cli-6.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentirc-cli
-Version: 6.2.2
+Version: 6.2.3
 Summary: Legacy alias for culture — install culture instead
 Project-URL: Homepage, https://github.com/OriNachum/culture
 Author: Ori Nachum

{agentirc_cli-6.2.2 → agentirc_cli-6.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentirc-cli"
-version = "6.2.2"
+version = "6.2.3"
 description = "Legacy alias for culture — install culture instead"
 readme = "README.md"
 license = "MIT"

{agentirc_cli-6.2.2 → agentirc_cli-6.2.3}/uv.lock

@@ -561,7 +561,7 @@ wheels = [
 
 [[package]]
 name = "culture"
-version = "6.2.2"
+version = "6.2.3"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },