claude-dev-env 1.29.3 → 1.30.0

package/scripts/test_groq_bugteam_spec.py

@@ -0,0 +1,346 @@
+"""Coherence tests for groq_bugteam_spec module import surface.
+
+The behavioral contract for apply_fix_from_spec lives in
+test_groq_bugteam_apply_fix_from_spec.py; those tests pass whether the
+function is defined in groq_bugteam.py directly or re-exported from the
+spec module. This file exists solely so the spec module has a
+same-named test companion for filename-based test pairing.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import pathlib
+import sys
+import types
+
+import pytest
+
+
+def _load_spec_module():
+    scripts_directory = pathlib.Path(__file__).parent
+    sys.path.insert(0, str(scripts_directory))
+    sys.modules.pop("groq_bugteam_spec", None)
+    module_path = scripts_directory / "groq_bugteam_spec.py"
+    module_spec = importlib.util.spec_from_file_location(
+        "groq_bugteam_spec", module_path
+    )
+    loaded_module = importlib.util.module_from_spec(module_spec)
+    sys.modules["groq_bugteam_spec"] = loaded_module
+    module_spec.loader.exec_module(loaded_module)
+    return loaded_module
+
+
+groq_bugteam_spec = _load_spec_module()
+
+
+def test_apply_fix_from_spec_is_callable():
+    assert callable(groq_bugteam_spec.apply_fix_from_spec)
+
+
+def test_run_spec_mode_main_is_callable():
+    assert callable(groq_bugteam_spec.run_spec_mode_main)
+
+
+def test_is_spec_mode_invocation_detects_flag_value_pair():
+    assert groq_bugteam_spec.is_spec_mode_invocation(["--mode", "spec"]) is True
+    assert groq_bugteam_spec.is_spec_mode_invocation(["--mode", "pipeline"]) is False
+    assert groq_bugteam_spec.is_spec_mode_invocation([]) is False
+
+
+def _attach_required_groq_attributes(target_module: types.ModuleType) -> None:
+    target_module.call_groq_with_fallback = lambda *args, **kwargs: None
+    target_module.parse_json_object = lambda text: {}
+    target_module.preserve_trailing_newline = lambda original, updated: updated
+
+
+def test_resolver_prefers_registered_groq_bugteam_over_main(monkeypatch):
+    fake_groq_bugteam = types.ModuleType("groq_bugteam")
+    _attach_required_groq_attributes(fake_groq_bugteam)
+    monkeypatch.setitem(sys.modules, "groq_bugteam", fake_groq_bugteam)
+
+    resolved_module = groq_bugteam_spec.resolve_groq_bugteam_module()
+
+    assert resolved_module is fake_groq_bugteam
+
+
+def test_resolver_falls_back_to_main_when_groq_bugteam_absent(monkeypatch):
+    monkeypatch.delitem(sys.modules, "groq_bugteam", raising=False)
+    fake_main = types.ModuleType("__main__")
+    _attach_required_groq_attributes(fake_main)
+    monkeypatch.setitem(sys.modules, "__main__", fake_main)
+
+    resolved_module = groq_bugteam_spec.resolve_groq_bugteam_module()
+
+    assert resolved_module is fake_main
+
+
+def test_resolver_falls_back_to_main_when_registered_module_is_stub(monkeypatch):
+    stub_groq_bugteam = types.ModuleType("groq_bugteam")
+    stub_groq_bugteam.call_groq_with_fallback = lambda *args, **kwargs: None
+    monkeypatch.setitem(sys.modules, "groq_bugteam", stub_groq_bugteam)
+    complete_main = types.ModuleType("__main__")
+    _attach_required_groq_attributes(complete_main)
+    monkeypatch.setitem(sys.modules, "__main__", complete_main)
+
+    resolved_module = groq_bugteam_spec.resolve_groq_bugteam_module()
+
+    assert resolved_module is complete_main
+
+
+def test_resolver_raises_when_registered_module_missing_required_attributes(
+    monkeypatch,
+):
+    stub_groq_bugteam = types.ModuleType("groq_bugteam")
+    stub_groq_bugteam.call_groq_with_fallback = lambda *args, **kwargs: None
+    monkeypatch.setitem(sys.modules, "groq_bugteam", stub_groq_bugteam)
+    monkeypatch.delitem(sys.modules, "__main__", raising=False)
+
+    try:
+        groq_bugteam_spec.resolve_groq_bugteam_module()
+    except RuntimeError as resolver_error:
+        resolver_error_text = str(resolver_error)
+        assert "parse_json_object" in resolver_error_text
+        assert "preserve_trailing_newline" in resolver_error_text
+    else:
+        raise AssertionError("resolver should have raised RuntimeError")
+
+
+def test_resolver_raises_when_neither_module_available(monkeypatch):
+    monkeypatch.delitem(sys.modules, "groq_bugteam", raising=False)
+    placeholder_main = types.ModuleType("__main__")
+    monkeypatch.setitem(sys.modules, "__main__", placeholder_main)
+
+    try:
+        groq_bugteam_spec.resolve_groq_bugteam_module()
+    except RuntimeError as resolver_error:
+        resolver_error_text = str(resolver_error)
+        assert "groq_bugteam" in resolver_error_text
+    else:
+        raise AssertionError("resolver should have raised RuntimeError")
+
+
+FAKE_API_KEY = "gsk_test_placeholder_value"
+
+
+def _install_fake_groq_bugteam_module(monkeypatch, response_object):
+    """Register a minimal fake groq_bugteam module for resolver lookup."""
+
+    fake_module = types.ModuleType("groq_bugteam")
+
+    def fake_call(api_key, messages, temperature, max_completion_tokens):
+        return types.SimpleNamespace(
+            content=json.dumps(response_object),
+            model="fake-model",
+        )
+
+    def fake_parse_json_object(text):
+        return json.loads(text)
+
+    def fake_preserve_trailing_newline(original, updated):
+        if original.endswith("\n") and not updated.endswith("\n"):
+            return updated + "\n"
+        if not original.endswith("\n") and updated.endswith("\n"):
+            return updated[:-1]
+        return updated
+
+    fake_module.call_groq_with_fallback = fake_call
+    fake_module.parse_json_object = fake_parse_json_object
+    fake_module.preserve_trailing_newline = fake_preserve_trailing_newline
+    monkeypatch.setitem(sys.modules, "groq_bugteam", fake_module)
+    monkeypatch.setenv("GROQ_API_KEY", FAKE_API_KEY)
+
+
+def test_skipped_entry_missing_finding_index_does_not_crash(monkeypatch):
+    original_file = "alpha\nbeta\n"
+    spec_list = [
+        {
+            "finding_index": 4,
+            "severity": "P1",
+            "category": "J",
+            "file": "sample.py",
+            "target_line_start": 1,
+            "target_line_end": 1,
+            "intended_change": "rename alpha",
+            "replacement_code": "alpha_fixed",
+            "acceptance_criteria": ["alpha_fixed appears on line 1"],
+        }
+    ]
+    patched_file = "alpha_fixed\nbeta\n"
+    fake_response = {
+        "updated_content": patched_file,
+        "applied_finding_indexes": [4],
+        "skipped": [{"reason": "malformed entry without finding_index"}],
+        "acceptance_checks": [
+            {
+                "finding_index": 4,
+                "criterion": "alpha_fixed appears on line 1",
+                "met": True,
+            }
+        ],
+    }
+    _install_fake_groq_bugteam_module(monkeypatch, fake_response)
+
+    outcome = groq_bugteam_spec.apply_fix_from_spec(spec_list, original_file)
+
+    assert outcome["updated_content"] == patched_file
+    assert outcome["applied_finding_indexes"] == [4]
+
+
+def test_null_updated_content_falls_back_to_current_content(monkeypatch):
+    original_file = "alpha\nbeta\n"
+    spec_list = [
+        {
+            "finding_index": 0,
+            "severity": "P2",
+            "category": "E",
+            "file": "sample.py",
+            "target_line_start": 1,
+            "target_line_end": 1,
+            "intended_change": "no-op fallback",
+            "replacement_code": "alpha",
+            "acceptance_criteria": ["alpha remains on line 1"],
+        }
+    ]
+    fake_response = {
+        "updated_content": None,
+        "applied_finding_indexes": [],
+        "skipped": [
+            {
+                "finding_index": 0,
+                "reason": "Groq returned null updated_content",
+            }
+        ],
+        "acceptance_checks": [],
+    }
+    _install_fake_groq_bugteam_module(monkeypatch, fake_response)
+
+    outcome = groq_bugteam_spec.apply_fix_from_spec(spec_list, original_file)
+
+    assert outcome["updated_content"] == original_file
+
+
+def test_null_collection_fields_coerce_to_empty_lists(monkeypatch):
+    original_file = "alpha\n"
+    spec_list = [
+        {
+            "finding_index": 1,
+            "severity": "P2",
+            "category": "E",
+            "file": "sample.py",
+            "target_line_start": 1,
+            "target_line_end": 1,
+            "intended_change": "no-op",
+            "replacement_code": "alpha",
+            "acceptance_criteria": ["alpha remains"],
+        }
+    ]
+    fake_response = {
+        "updated_content": original_file,
+        "applied_finding_indexes": None,
+        "skipped": None,
+        "acceptance_checks": None,
+    }
+    _install_fake_groq_bugteam_module(monkeypatch, fake_response)
+
+    outcome = groq_bugteam_spec.apply_fix_from_spec(spec_list, original_file)
+
+    assert outcome["applied_finding_indexes"] == []
+    assert outcome["skipped"] == []
+    assert outcome["acceptance_checks"] == []
+
+
+def test_dict_collection_fields_coerce_to_empty_lists(monkeypatch):
+    original_file = "alpha\n"
+    spec_list = [
+        {
+            "finding_index": 2,
+            "severity": "P2",
+            "category": "E",
+            "file": "sample.py",
+            "target_line_start": 1,
+            "target_line_end": 1,
+            "intended_change": "no-op",
+            "replacement_code": "alpha",
+            "acceptance_criteria": ["alpha remains"],
+        }
+    ]
+    fake_response = {
+        "updated_content": original_file,
+        "applied_finding_indexes": {"not": "a list"},
+        "skipped": {"0": "not a list either"},
+        "acceptance_checks": {"also": "a dict"},
+    }
+    _install_fake_groq_bugteam_module(monkeypatch, fake_response)
+
+    outcome = groq_bugteam_spec.apply_fix_from_spec(spec_list, original_file)
+
+    assert outcome["applied_finding_indexes"] == []
+    assert outcome["skipped"] == []
+    assert outcome["acceptance_checks"] == []
+
+
+def test_non_string_updated_content_falls_back_to_current_content(monkeypatch):
+    original_file = "alpha\nbeta\n"
+    spec_list = [
+        {
+            "finding_index": 0,
+            "severity": "P2",
+            "category": "E",
+            "file": "sample.py",
+            "target_line_start": 1,
+            "target_line_end": 1,
+            "intended_change": "no-op fallback",
+            "replacement_code": "alpha",
+            "acceptance_criteria": ["alpha remains on line 1"],
+        }
+    ]
+    fake_response = {
+        "updated_content": {"unexpected": "dict instead of str"},
+        "applied_finding_indexes": [],
+        "skipped": [],
+        "acceptance_checks": [],
+    }
+    _install_fake_groq_bugteam_module(monkeypatch, fake_response)
+
+    outcome = groq_bugteam_spec.apply_fix_from_spec(spec_list, original_file)
+
+    assert outcome["updated_content"] == original_file
+
+
+def test_run_spec_mode_main_emits_error_json_on_missing_api_key(
+    monkeypatch, capsys
+):
+    monkeypatch.delenv("GROQ_API_KEY", raising=False)
+    monkeypatch.setattr(
+        "groq_bugteam_dotenv.load_claude_dev_env_dotenv_file",
+        lambda: None,
+    )
+    spec_payload = {
+        "spec": [
+            {
+                "finding_index": 0,
+                "severity": "P1",
+                "category": "J",
+                "file": "sample.py",
+                "target_line_start": 1,
+                "target_line_end": 1,
+                "intended_change": "noop",
+                "replacement_code": "noop",
+                "acceptance_criteria": ["noop"],
+            }
+        ],
+        "current_content": "noop\n",
+    }
+    monkeypatch.setattr("sys.stdin", io.StringIO(json.dumps(spec_payload)))
+
+    with pytest.raises(SystemExit) as exit_info:
+        groq_bugteam_spec.run_spec_mode_main()
+
+    captured = capsys.readouterr()
+    emitted_outcome = json.loads(captured.out)
+    assert "error" in emitted_outcome
+    assert "GROQ_API_KEY" in emitted_outcome["error"]
+    assert exit_info.value.code != 0

package/skills/bugteam/SKILL.md

@@ -124,6 +124,10 @@ TeamCreate(
 
 **Roles (spawned per loop, not here):** bugfind → `code-quality-agent` opus (4.7) at xhigh effort; bugfix → `clean-coder` opus (4.7) at xhigh effort. `model="opus"` resolves to Opus 4.7 on the Anthropic API and runs at the model's default `xhigh` effort level — see [`CONSTRAINTS.md`](CONSTRAINTS.md) § **Opus 4.7 at xhigh effort for both teammates** for rationale. **Display:** inherit `teammateMode` from `~/.claude.json`. Reference subagent types by name when spawning teammates ([`sources.md`](sources.md) § Referencing subagent types when spawning teammates).
 
+**Optional Groq-backed FIX path (explicit opt-in only):** the default flow above always uses Opus teammates. A separate optional path exists only when the user explicitly sets `BUGTEAM_FIX_IMPLEMENTER=groq-coder` before invocation: spawn the FIX teammate with `subagent_type="groq-coder"`. Before Step 3, `groq_bugteam.py` loads `packages/claude-dev-env/.env` when that file exists (gitignored; start from `packages/claude-dev-env/.env.example`). If `GROQ_API_KEY` is still unset after that load, stop and prompt the user to create `packages/claude-dev-env/.env` from the example path above—do not continue the Groq path without a key. Any other `BUGTEAM_FIX_IMPLEMENTER` value (or unset) keeps `clean-coder` on Opus. The FIX spawn XML in [`PROMPTS.md`](PROMPTS.md) is identical for both implementers.
+
+**`--bugbot-retrigger` flag:** when present on the `/bugteam` invocation, after every successful FIX push in Step 3, post an additional `bugbot run` issue comment via the Step 2.5 issue-comments fallback endpoint (`POST .../issues/{issue}/comments`) to re-trigger Cursor's bugbot on the new commit. Omit when the flag is absent.
+
 **Loop state (lead; not a single script):**
 
 ```bash

package/skills/bugteam/reference/README.md

@@ -11,3 +11,19 @@ Expanded material that used to live inline in `SKILL.md`. Load a file when the o
 | [`teardown-publish-permissions.md`](teardown-publish-permissions.md) | Utility scripts note, teardown, PR description rewrite, revoke, final report |
 
 Canonical documentation quotes: [`../sources.md`](../sources.md).
+
+## Retired: pre-push-review skill
+
+The `pre-push-review` skill was retired. Its mechanical checks are now covered automatically by the expanded code-rules enforcer and the git hooks installed via `npx claude-dev-env`.
+
+**What replaced what:**
+
+- **Mechanical pre-push checks** (magic values, boolean naming, imports, constants location, and other CODE_RULES checks) — handled by the `code_rules_enforcer.py` PreToolUse hook (blocks at write time) and by the git pre-push hook installed via `npx claude-dev-env`. The git pre-push hook is the gate that runs at `git push` time; no manual invocation is needed.
+
+- **`/qbug`** — a full PR audit-fix cycle that spawns subagents, runs multiple audit loops, and produces a structured report. It is NOT a lightweight pre-push gate. Do not use `/qbug` as a substitute for `git push` (the hook fires automatically). Use `/qbug` when you want a thorough multi-loop review of a PR before requesting human review.
+
+References updated:
+- `skills/pr-review-responder/SKILL.md` — Rule 6 and checklist item updated to reference the git pre-push hook
+- `commands/plan.md` — Phase 5 step 10 updated to reference the git pre-push hook
+- `hooks/github-action/pre-push-review.yml` — deleted (workflow no longer needed)
+- `hooks/github-action/test_workflow.py` — deleted alongside the workflow

package/skills/bugteam/test_skill_additions.py

@@ -0,0 +1,30 @@
+"""Markdown assertion tests for bugteam SKILL.md additive options."""
+
+from __future__ import annotations
+
+import pathlib
+
+
+def _read_skill_text() -> str:
+    skill_path = pathlib.Path(__file__).parent / "SKILL.md"
+    return skill_path.read_text(encoding="utf-8")
+
+
+def test_skill_references_fix_implementer_env_var():
+    skill_text = _read_skill_text()
+    assert "BUGTEAM_FIX_IMPLEMENTER" in skill_text
+
+
+def test_skill_names_default_implementer_subagent_type():
+    skill_text = _read_skill_text()
+    assert "clean-coder" in skill_text
+
+
+def test_skill_names_optional_groq_implementer_subagent_type():
+    skill_text = _read_skill_text()
+    assert "groq-coder" in skill_text
+
+
+def test_skill_documents_bugbot_retrigger_flag():
+    skill_text = _read_skill_text()
+    assert "--bugbot-retrigger" in skill_text

package/skills/monitor-open-prs/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: monitor-open-prs
+description: >-
+  Discover every open pull request across the jl-cmd/* and JonEcho/*
+  owner scopes, spawn /bugteam on each in parallel with the Groq-backed
+  FIX implementer (BUGTEAM_FIX_IMPLEMENTER=groq-coder) and the bugbot
+  re-trigger flag (--bugbot-retrigger), wrap the session in `bws run`
+  to inject GROQ_API_KEY, and poll Cursor's bugbot replies after
+  convergence so any post-Groq findings loop back through /bugteam.
+  Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Triggers:
+  '/monitor-open-prs', 'sweep the open PRs', 'groq-bugteam the backlog'.
+---
+
+# Monitor Open PRs
+
+**Core principle:** One sweep covers every open PR across both owner scopes. Claude discovers PRs live via `gh search prs`, dispatches `/bugteam` per PR with `BUGTEAM_FIX_IMPLEMENTER=groq-coder` and `--bugbot-retrigger`, then polls Cursor's bugbot replies until each PR is quiet for a full backoff cycle.
+
+## Contents
+
+- When this skill applies — refusal cases and trigger conditions
+- Discovery — live `gh search prs` across both owner scopes
+- Wrapping — `bws run` for GROQ_API_KEY injection
+- Dispatch — `/bugteam <numbers...>` with groq-coder + retrigger
+- Post-convergence polling — bugbot replies and re-invocation
+- `scripts/discover_open_prs.py` — the discovery helper
+
+## When this skill applies
+
+`/monitor-open-prs` authorizes one full sweep over all open PRs in both owner scopes.
+
+Refusals — first match wins; respond with the quoted line exactly and stop:
+
+- **Agent teams not enabled.** Check `claude config get env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` and `~/.claude/settings.json`. If neither is `"1"`: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 not set. /monitor-open-prs requires the agent teams feature.`
+- **bws not on PATH.** `bws not installed. /monitor-open-prs injects GROQ_API_KEY via Bitwarden Secrets Manager.`
+- **gh not authenticated.** `gh auth status failed. /monitor-open-prs relies on existing gh credentials.`
+- **Dirty tree on the caller's repo.** `Uncommitted changes detected. Stash, commit, or revert before /monitor-open-prs.`
+- **Required subagents missing.** Confirm `code-quality-agent`, `clean-coder`, and `groq-coder` exist. Else: `Required subagent type <name> not installed.`
+
+## Discovery
+
+Call `scripts/discover_open_prs.discover_open_prs(all_owners=["jl-cmd", "JonEcho"])` to merge the live open-PR list across both scopes. The helper runs `gh search prs --owner <owner> --state open --json number,repository,url,headRefName,baseRefName` once per owner and flattens the result to a uniform dict shape with keys `number`, `owner`, `repo`, `head_ref`, `base_ref`, `url`. Empty scopes contribute empty lists; an entirely empty sweep returns `[]` and exits cleanly.
+
+## Secret Wrapping
+
+Every `/bugteam` dispatch runs inside `bws run` so `GROQ_API_KEY` is injected from Bitwarden Secrets Manager without touching the filesystem. The project and secret UUIDs are fixed for this skill:
+
+```bash
+bws run \
+  --project-id c69cedc5-aea1-4aa8-b350-b4300145d978 \
+  -- \
+  env BUGTEAM_FIX_IMPLEMENTER=groq-coder \
+  /bugteam --bugbot-retrigger <pr_numbers...>
+```
+
+The `bws run` subshell resolves the project's secrets and exports them for the wrapped command. The `GROQ_API_KEY` secret's UUID inside that project is `b7e99a7f-2ecc-42b3-99a5-b434010622f9`. GitHub auth is not sourced through `bws` — existing `gh auth` credentials carry the session.
+
+## Dispatch
+
+For each discovered PR:
+
+1. Resolve the PR's repo checkout (existing worktree or fresh `git clone`).
+2. From that checkout, invoke `/bugteam <pr_number>` under the `bws run` wrapper above.
+3. The `BUGTEAM_FIX_IMPLEMENTER=groq-coder` env var routes the FIX role to the `groq-coder` subagent. The `--bugbot-retrigger` flag tells bugteam to post `bugbot run` as an issue comment after every successful FIX push so Cursor's bugbot re-evaluates the new commit.
+4. Bugteam runs its own 10-loop audit/fix cycle per PR; this skill waits for each bugteam invocation to return before dispatching the next (or fanning out — see below).
+
+**Fan-out (optional):** when the discovered list has more than one PR, the skill may spawn `/bugteam` dispatches in parallel by issuing multiple `Agent` calls in a single assistant message. Each dispatch operates in its own per-PR worktree (bugteam Step 1.1). Serialize when the caller sets an explicit `--serial` flag.
+
+## Post-Convergence Polling
+
+After a `/bugteam` invocation returns (converged, cap reached, stuck, or error), the PR may accumulate new Cursor bugbot comments within minutes. Poll for them:
+
+1. Baseline: capture `since_timestamp` as the PR's last commit timestamp.
+2. Every 60 seconds, run `gh pr view <pr_number> --json comments --jq '.comments[] | select(.createdAt > "<since_timestamp>") | select(.author.login | test("bugbot|cursor";"i"))'`.
+3. Back off: 60s → 120s → 240s → 480s → 960s. If five successive polls return empty, exit polling for this PR.
+4. If bugbot posts a new finding in any poll, re-invoke `/bugteam <pr_number>` via the same `bws run` wrapper with the bugbot finding text seeded into the invocation's `bugs_to_fix` preamble. Reset the backoff.
+
+### Polling Cost and Cadence
+
+The five-step backoff sums to `60 + 120 + 240 + 480 + 960 = 1860` seconds (~31 minutes) of idle polling per PR before the skill declares bugbot quiet. A sweep over ten open PRs therefore retains up to ~5 wall-clock hours of bugbot-watch time beyond the active `/bugteam` work. Callers who need faster turnaround should pass `--serial` to disable fan-out (so polling starts only after the previous PR finishes) or accept the tradeoff: the backoff exists specifically to catch late bugbot analyses that can take several minutes to appear after a push.
+
+## Final Report
+
+After every PR has exited polling, emit:
+
+```
+/monitor-open-prs sweep summary
+PRs discovered: <N>
+  jl-cmd/*: <count>
+  JonEcho/*: <count>
+PRs converged clean: <count>
+PRs hit 10-loop cap: <count>
+PRs stuck: <count>
+PRs errored: <count>
+Bugbot re-triggers fired: <count>
+Total Groq tokens consumed: <approx from /bugteam outcome summaries>
+```
+
+## Non-Negotiable Guardrails
+
+- Never run `/bugteam` without `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` active.
+- Never source secrets outside `bws run` — no `.env` files, no shell history, no logs.
+- Never pass `--no-verify` or `--no-gpg-sign` to git in any dispatched bugteam run.
+- Never open a PR from this skill; only comment on existing ones.
+- Never merge or close PRs; the skill is read + audit + patch only.

package/skills/monitor-open-prs/scripts/discover_open_prs.py

@@ -0,0 +1,69 @@
+"""Discover every open pull request across a list of owner scopes.
+
+Shells out to ``gh search prs --owner <owner> --state open --json ...`` once per
+owner, parses the JSON output, and flattens each entry to a uniform dict shape.
+The module is stateless, takes no filesystem side effects, and exposes a single
+``discover_open_prs`` entry point consumed by the monitor-open-prs skill.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+
+
+def build_gh_search_argv(owner: str) -> list[str]:
+    gh_command_name = "gh"
+    search_subcommand = ("search", "prs")
+    owner_flag = "--owner"
+    state_flag = "--state"
+    state_open_value = "open"
+    json_fields_flag = "--json"
+    json_fields_value = "number,repository,url,headRefName,baseRefName"
+    return [
+        gh_command_name,
+        *search_subcommand,
+        owner_flag,
+        owner,
+        state_flag,
+        state_open_value,
+        json_fields_flag,
+        json_fields_value,
+    ]
+
+
+def split_repository_name(name_with_owner: str) -> tuple[str, str]:
+    repo_separator = "/"
+    if repo_separator not in name_with_owner:
+        return "", name_with_owner
+    owner_segment, repository_segment = name_with_owner.split(repo_separator, 1)
+    return owner_segment, repository_segment
+
+
+def flatten_pr_entry(raw_pr_entry: dict) -> dict:
+    name_with_owner = raw_pr_entry.get("repository", {}).get("nameWithOwner", "")
+    owner_segment, repository_segment = split_repository_name(name_with_owner)
+    return {
+        "number": raw_pr_entry.get("number"),
+        "owner": owner_segment,
+        "repo": repository_segment,
+        "head_ref": raw_pr_entry.get("headRefName", ""),
+        "base_ref": raw_pr_entry.get("baseRefName", ""),
+        "url": raw_pr_entry.get("url", ""),
+    }
+
+
+def fetch_open_prs_for_owner(owner: str) -> list[dict]:
+    search_argv = build_gh_search_argv(owner)
+    completed_process = subprocess.run(
+        search_argv, check=True, capture_output=True, text=True
+    )
+    raw_pr_entries = json.loads(completed_process.stdout)
+    return [flatten_pr_entry(each_entry) for each_entry in raw_pr_entries]
+
+
+def discover_open_prs(all_owners: list[str]) -> list[dict]:
+    all_discovered: list[dict] = []
+    for each_owner in all_owners:
+        all_discovered.extend(fetch_open_prs_for_owner(each_owner))
+    return all_discovered