devex-cli 0.24.0__py3-none-any.whl

agent_experience/commands/learn/assets/topics/visualize/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: visualize
+description: Build a skill that renders a compact visual of your agent setup.
+type: lesson
+---
+
+# Lesson — build a `visualize` skill for {{ backend }}
+
+Same shape as introspect, but the output optimizes for *at-a-glance* rather than recommendations. The skill runs `agex overview --agent {{ backend }}`, compresses it into a tight markdown block (counts only, with a token target of < 500 output tokens), and echoes it for situational awareness.
+
+## Step 1 — understand the goal
+
+Run `agex overview --agent {{ backend }}` now. Note the counts of skills, hooks, MCP integrations, and CLAUDE.md status. The visualize skill will display these as a one-liner for quick reference.
+
+## Step 2 — create the skill file
+
+Write the file shown below to the path noted above its fence. This skill is intentionally minimal — no prose, no recommendations.
+
+### Skill template — `.claude/skills/visualize/SKILL.md`
+
+```markdown
+{{ skill_template_body }}
+```
+
+## Step 3 — invoke it
+
+Say "what do I have" or "show the setup" and invoke `/visualize` (or equivalent). You'll get a compact status bar.

agent_experience/commands/learn/assets/topics/visualize/assets/skill-template/claude-code/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: visualize
+description: At-a-glance snapshot of the project's agent setup — counts only, compact.
+type: command
+---
+
+# Visualize
+
+When the user says "what do I have", "show the setup", or similar.
+
+## Process
+
+1. `agex overview --agent claude-code`
+2. Emit a compact block: `Skills: N · Hooks: M · MCP: K · CLAUDE.md: ✓/✗`
+3. Stop. No recommendations, no prose paragraphs.
+
+## Rule
+
+Target < 500 output tokens. If you can't fit the summary, trim further.

agent_experience/commands/learn/scripts/learn.py

@@ -0,0 +1,73 @@
+import re
+from importlib.resources import as_file, files
+from importlib.resources.abc import Traversable
+
+from agent_experience.core.backend import Backend
+from agent_experience.core.prog import error_prefix
+from agent_experience.core.render import render_string
+from agent_experience.core.skill_loader import Skill, load_skill
+
+_TOPIC_RE = re.compile(r"^[a-z][a-z0-9-]*$")
+_SKILL_FILENAME = "SKILL.md"
+
+
+def _learn_assets() -> Traversable:
+    # Anchor on the `commands` package (which has __init__.py) and navigate in.
+    # Avoids relying on namespace-package semantics for `assets/`, which is a
+    # data directory, not a package. Matches explain.py / overview.py pattern.
+    return files("agent_experience.commands").joinpath("learn", "assets")
+
+
+def _load_skill_from_traversable(trav: Traversable) -> Skill:
+    # load_skill expects a pathlib.Path; resolve via as_file when needed.
+    with as_file(trav) as path:
+        return load_skill(path)
+
+
+def _list_topics() -> list[dict]:
+    topics: list[dict] = []
+    topics_root = _learn_assets().joinpath("topics")
+    for topic_dir in sorted(topics_root.iterdir(), key=lambda p: p.name):
+        if topic_dir.is_file():
+            continue
+        skill_md = topic_dir.joinpath(_SKILL_FILENAME)
+        if not skill_md.is_file():
+            continue
+        skill = _load_skill_from_traversable(skill_md)
+        # Use the directory name as the canonical slug — `run_topic` looks up
+        # by directory, so the menu's `agex learn <name>` invocation must
+        # match. Frontmatter `skill.name` is still available for drift checks.
+        topics.append(
+            {"name": topic_dir.name, "description": skill.description, "unsupported": None}
+        )
+    return topics
+
+
+def run_menu(backend: Backend) -> tuple[str, int, str]:
+    """Return (stdout, exit_code, stderr) for the topic menu."""
+    topics = _list_topics()
+    template_text = _learn_assets().joinpath("menu.md.j2").read_text(encoding="utf-8")
+    out = render_string(template_text, {"backend": backend.value, "topics": topics})
+    return (out, 0, "")
+
+
+def run_topic(topic: str, backend: Backend) -> tuple[str, int, str]:
+    """Return (stdout, exit_code, stderr) for a specific lesson topic."""
+    if not _TOPIC_RE.match(topic):
+        menu_out, _, _ = run_menu(backend)
+        return (menu_out, 2, error_prefix(f"unknown topic '{topic}'"))
+
+    topic_dir = _learn_assets().joinpath("topics", topic)
+    skill_md = topic_dir.joinpath(_SKILL_FILENAME)
+    if not skill_md.is_file():
+        menu_out, _, _ = run_menu(backend)
+        return (menu_out, 2, error_prefix(f"unknown topic '{topic}'"))
+
+    skill = _load_skill_from_traversable(skill_md)
+    template_path = topic_dir.joinpath("assets", "skill-template", backend.value, _SKILL_FILENAME)
+    template_body = template_path.read_text(encoding="utf-8") if template_path.is_file() else ""
+    rendered = render_string(
+        skill.body,
+        {"backend": backend.value, "skill_template_body": template_body},
+    )
+    return (rendered, 0, "")

agent_experience/commands/overview/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: overview
+description: Render a descriptive markdown snapshot of the project's current agent setup.
+type: command
+---
+
+# `agex overview --agent <backend>`
+
+Call this to get a read-only markdown snapshot of what's configured in the
+current project for a given backend — skills, hooks, agents, MCP servers,
+and relevant config files. Descriptive, not diagnostic. Read it before you
+act.
+
+## From your shell tool
+
+```bash
+agex overview --agent claude-code
+agex overview --agent codex
+```
+
+## What you get
+
+Markdown sections: Project root, `CLAUDE.md`/`AGENTS.md` presence, Skills,
+Hooks, MCP servers, Settings.
+
+## Notes
+
+- Malformed files are skipped with a `> ⚠️` inline warning.
+- Read-only except first-run `.agex/` init.
+- Build diagnostic logic (gaps, recommendations) into an agent-authored skill:
+  `agex learn introspect --agent <backend>`.

agent_experience/commands/overview/assets/backends/acp.yaml

@@ -0,0 +1,7 @@
+sections:
+  - project_memory
+  - skills
+  - hooks
+  - mcp
+  - settings
+probe: acp

agent_experience/commands/overview/assets/backends/claude-code.yaml

@@ -0,0 +1,7 @@
+sections:
+  - project_memory
+  - skills
+  - hooks
+  - mcp
+  - settings
+probe: claude_code

agent_experience/commands/overview/assets/backends/codex.yaml

@@ -0,0 +1,7 @@
+sections:
+  - project_memory
+  - skills
+  - hooks
+  - mcp
+  - settings
+probe: codex

agent_experience/commands/overview/assets/backends/copilot.yaml

@@ -0,0 +1,7 @@
+sections:
+  - project_memory
+  - skills
+  - hooks
+  - mcp
+  - settings
+probe: copilot

agent_experience/commands/overview/assets/sections.md.j2

@@ -0,0 +1,52 @@
+# Overview — {{ backend }}
+
+**Project:** `{{ project_dir }}`
+{% if probe.warnings %}
+{% for w in probe.warnings -%}
+> ⚠️ {{ w }}
+{% endfor %}
+{%- endif %}
+## Project memory
+{% if probe.claude_md -%}
+- `{{ probe.claude_md.name }}` present at `{{ probe.claude_md }}`
+{%- else -%}
+- _no CLAUDE.md / AGENTS.md equivalent found_
+{%- endif %}
+
+## Skills ({{ probe.skills|length }})
+{% if probe.skills -%}
+| name | description |
+|---|---|
+{% for s in probe.skills -%}
+| `{{ s.name }}` | {{ s.description }} |
+{% endfor %}
+{%- else -%}
+_none_
+{%- endif %}
+
+## Hooks ({{ probe.hooks|length }})
+{% if probe.hooks -%}
+{% for h in probe.hooks -%}
+- `{{ h.event }}` — {{ h.entries|length }} entry(s)
+{% endfor %}
+{%- else -%}
+_none_
+{%- endif %}
+
+## MCP servers ({{ probe.mcp_servers|length }})
+{% if probe.mcp_servers -%}
+{% for m in probe.mcp_servers -%}
+- `{{ m.name }}`
+{% endfor %}
+{%- else -%}
+_none_
+{%- endif %}
+
+## Settings
+{% if probe.settings -%}
+```json
+{{ probe.settings | tojson(indent=2) }}
+```
+{%- else -%}
+_no settings file found_
+{%- endif %}

agent_experience/commands/overview/scripts/overview.py

@@ -0,0 +1,40 @@
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+from agent_experience.backends.acp.probe import probe as acp_probe
+from agent_experience.backends.claude_code.probe import probe as claude_code_probe
+from agent_experience.backends.codex.probe import probe as codex_probe
+from agent_experience.backends.copilot.probe import probe as copilot_probe
+from agent_experience.core.backend import Backend
+from agent_experience.core.paths import ensure_init
+from agent_experience.core.render import render_string
+
+_PROBES = {
+    Backend.CLAUDE_CODE: claude_code_probe,
+    Backend.CODEX: codex_probe,
+    Backend.COPILOT: copilot_probe,
+    Backend.ACP: acp_probe,
+}
+
+
+def _assets_root() -> Traversable:
+    # Anchor on the `commands` package (which has __init__.py) and navigate in,
+    # matching explain.py's pattern. Avoids relying on namespace-package
+    # semantics for `assets/`, which is a data directory, not a package.
+    return files("agent_experience.commands").joinpath("overview", "assets")
+
+
+def run(backend: Backend) -> tuple[str, int, str]:
+    """Return (stdout, exit_code, stderr)."""
+    ensure_init()
+    project_dir = Path.cwd()
+
+    probe_result = _PROBES[backend](project_dir)
+
+    template_text = _assets_root().joinpath("sections.md.j2").read_text(encoding="utf-8")
+    out = render_string(
+        template_text,
+        {"backend": backend.value, "project_dir": project_dir, "probe": probe_result},
+    )
+    return (out, 0, "")

agent_experience/commands/pr/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: pr
+description: GitHub PR lifecycle commands for agents — lint, open, read, reply, review, await, delta. Each command ends with a deterministic "Next step:" footer so the agent never has to guess what to chain.
+type: command
+---
+
+# `agex pr` — PR lifecycle for agents
+
+Seven verbs, in roughly the order an agent uses them on a PR:
+
+| Verb | Purpose |
+|---|---|
+| `agex pr lint` | Portability + alignment-trigger lint on the working diff. |
+| `agex pr open --title T [--body-file F] [--draft] [--delayed-read]` | `gh pr create` with auto-signed body; with `--delayed-read` chains to `read --wait 180`. |
+| `agex pr read [<PR>] [--wait SECS]` | Unified briefing: CI checks, SonarCloud quality gate, all comments, reviewer readiness. With `--wait`, polls until required reviewers are ready or timeout. Always exits 0. |
+| `agex pr reply <PR>` | Read JSONL replies on stdin, post each, resolve threads. |
+| `agex pr review [<PR>]` | Post the Qodo agentic-review trigger (`/agentic_review`) on a PR. Re-triggers on an already-open PR; `pr open` posts it automatically for a new non-draft PR. |
+| `agex pr await [<PR>] [--max-wait SECS]` | "Wake me when this is triage-able" — polls readiness, runs CI + Sonar gate, dumps briefing. **Exits 1 on quality-gate `ERROR`, unresolved threads, or failing CI checks**, 0 on clean state or timeout. Default `--max-wait 1800` (30 min). |
+| `agex pr delta` | Dump sibling-project `CLAUDE.md` heads + `culture.yaml` for alignment review. |
+
+`pr read --wait` and `pr await` share the same readiness-polling loop; the
+difference is the exit code. Use `read` when you want the briefing
+unconditionally; use `await` when you want to **gate** the next step on
+PR health (e.g., in scripts that should fail if Sonar errors).
+
+## Readiness and `--wait` semantics
+
+- **`--wait` / `--max-wait` is an upper bound, not a minimum sleep.** It's the
+  *maximum* time to poll (60s interval). The loop returns as soon as the
+  readiness predicate holds — including **immediately** (`waited=0s`) if it
+  already held on entry. When that happens the stderr heartbeat appends
+  `(readiness already satisfied on entry; not polling)`, so a fast return on a
+  large `--wait` is expected, not a bug.
+- **What "ready" means.** `ready=True` when every reviewer in
+  `[pr].required_reviewers` (default `["qodo"]`) has posted a non-empty comment.
+  This is **review-feedback-present**, *not* merge-ready: it says nothing about
+  unresolved review threads, CI checks, or the SonarCloud quality gate. Widen
+  the predicate by adding reviewers to `[pr].required_reviewers` in
+  `.agex/config.toml`.
+- **Need merge-gating?** Use `agex pr await`, which adds the CI + Sonar + thread
+  gates on top of the same readiness loop and **exits non-zero** when the PR
+  isn't clean.
+
+## Qodo agentic review
+
+When a PR is opened, Qodo runs an agentic code review on demand when it sees a
+trigger comment. The current command is **`/agentic_review`**. The legacy
+`/improve` command is **deprecated** (Qodo replies with a deprecation banner and
+no committed removal date), so agex never posts `/improve`.
+
+- `agex pr open` posts `/agentic_review` **automatically** for a freshly created,
+  non-draft PR — out of the box, no flag. Drafts are skipped (not review-ready)
+  and already-open PRs are skipped (idempotent re-opens shouldn't spam the
+  thread).
+- `agex pr review [<PR>]` posts the same trigger on demand — use it to re-trigger
+  a review on an existing PR (e.g. after pushing fixes) or to trigger a draft
+  once it's ready.
+
+The command string lives in one place (`scripts/review.QODO_REVIEW_TRIGGER`), so
+a future Qodo rename is a one-line change for every consumer of `agex pr`.
+
+## SonarCloud project key
+
+`pr read` and `pr await` query the SonarCloud quality gate for the current
+PR. The project key is resolved in order:
+
+1. `SONAR_PROJECT_KEY` env var (override for non-standard naming).
+2. `[pr] sonar_project_key` in `.agex/config.toml`.
+3. `<owner>_<repo>` (SonarCloud GitHub-import default).
+
+When the project isn't on SonarCloud the API 404s and agex silently
+skips the section, so the verbs stay safe for non-Sonar repos.
+
+Every command ends with a `**Next step:**` footer — chase the chain without guessing.
+
+## Side effects
+
+Network: every command except `lint` and `delta` talks to GitHub via `gh`.
+`pr open` (non-draft, new PR) and `pr review` post the `/agentic_review` trigger
+comment.
+Disk: `pr open`, `pr read`, `pr reply`, and `pr review` append events to
+`.agex/data/pr/events.jsonl`.
+
+## Prerequisites
+
+- `gh` (GitHub CLI) on PATH and authenticated (`gh auth login`).
+- `--agent` flag, or first agent's `backend:` set in `culture.yaml`.
+
+For each verb's full behavior, error modes, and exit codes, see
+`docs/superpowers/specs/2026-05-10-agex-pr-design.md`.

agent_experience/commands/pr/assets/backends/acp.yaml

@@ -0,0 +1,21 @@
+hints:
+  lint_clean: "Commit, push, then `{{ prog }} pr open --title \"...\"`."
+  lint_clean_with_alignment: "Run `{{ prog }} pr delta` (this PR touches alignment files), then commit, push, and `{{ prog }} pr open --title \"...\"`."
+  lint_violations: "Fix the {{ violation_count }} violation(s) above and rerun `{{ prog }} pr lint`."
+  open_recommend_read: "`{{ prog }} pr read {{ pr }} --wait 180` (recommended) or `{{ prog }} pr read {{ pr }}` in ~3 min."
+  open_already_exists: "PR already open as #{{ pr }} — `{{ prog }} pr read {{ pr }} --wait 180` to fetch the briefing."
+  read_unresolved_after_commits: "Push fixes, then `{{ prog }} pr read {{ pr }} --wait 180`."
+  read_unresolved_no_commits: "Triage and prepare `replies.jsonl`, then `{{ prog }} pr reply {{ pr }} < replies.jsonl`."
+  read_ci_red: "Fix CI before requesting re-review (see failing checks above)."
+  read_clean: "Wait for human merge."
+  read_wait_timeout: "Still waiting on: {{ reviewers }}. Rerun `{{ prog }} pr read {{ pr }} --wait 180` to continue."
+  reply_with_failures: "Resubmit the failed lines (see table above) to `{{ prog }} pr reply {{ pr }}`."
+  reply_clean: "Push fixes (if any), then `{{ prog }} pr read {{ pr }} --wait 180`."
+  delta_done: "Triage each sibling — open follow-up PRs where alignment drifted; mention them in your reply."
+  review_posted: "Posted `/agentic_review` — `{{ prog }} pr read {{ pr }} --wait 180` once Qodo responds."
+  await_clean: "PR #{{ pr }} is ready — wait for human merge."
+  await_gate_error: "SonarCloud quality gate is ERROR — fix the new issues above, push, then `{{ prog }} pr await {{ pr }}` again."
+  await_gate_unknown: "SonarCloud quality gate is UNKNOWN — analysis is pending or the project isn't analyzed yet; wait and re-run `{{ prog }} pr await {{ pr }}`."
+  await_unresolved_threads: "Triage and prepare `replies.jsonl`, then `{{ prog }} pr reply {{ pr }} < replies.jsonl`."
+  await_ci_red: "Fix CI before requesting re-review (see failing checks above)."
+  await_wait_timeout: "Still waiting on: {{ reviewers }}. Rerun `{{ prog }} pr await {{ pr }}` to keep waiting."

agent_experience/commands/pr/assets/backends/claude-code.yaml

@@ -0,0 +1,21 @@
+hints:
+  lint_clean: "Commit, push, then `{{ prog }} pr open --title \"...\"`."
+  lint_clean_with_alignment: "Run `{{ prog }} pr delta` (this PR touches alignment files), then commit, push, and `{{ prog }} pr open --title \"...\"`."
+  lint_violations: "Fix the {{ violation_count }} violation(s) above and rerun `{{ prog }} pr lint`."
+  open_recommend_read: "`{{ prog }} pr read {{ pr }} --wait 180` (recommended) or `{{ prog }} pr read {{ pr }}` in ~3 min."
+  open_already_exists: "PR already open as #{{ pr }} — `{{ prog }} pr read {{ pr }} --wait 180` to fetch the briefing."
+  read_unresolved_after_commits: "Push fixes, then `{{ prog }} pr read {{ pr }} --wait 180`."
+  read_unresolved_no_commits: "Triage and prepare `replies.jsonl`, then `{{ prog }} pr reply {{ pr }} < replies.jsonl`."
+  read_ci_red: "Fix CI before requesting re-review (see failing checks above)."
+  read_clean: "Wait for human merge."
+  read_wait_timeout: "Still waiting on: {{ reviewers }}. Rerun `{{ prog }} pr read {{ pr }} --wait 180` to continue."
+  reply_with_failures: "Resubmit the failed lines (see table above) to `{{ prog }} pr reply {{ pr }}`."
+  reply_clean: "Push fixes (if any), then `{{ prog }} pr read {{ pr }} --wait 180`."
+  delta_done: "Triage each sibling — open follow-up PRs where alignment drifted; mention them in your reply."
+  review_posted: "Posted `/agentic_review` — `{{ prog }} pr read {{ pr }} --wait 180` once Qodo responds."
+  await_clean: "PR #{{ pr }} is ready — wait for human merge."
+  await_gate_error: "SonarCloud quality gate is ERROR — fix the new issues above, push, then `{{ prog }} pr await {{ pr }}` again."
+  await_gate_unknown: "SonarCloud quality gate is UNKNOWN — analysis is pending or the project isn't analyzed yet; wait and re-run `{{ prog }} pr await {{ pr }}`."
+  await_unresolved_threads: "Triage and prepare `replies.jsonl`, then `{{ prog }} pr reply {{ pr }} < replies.jsonl`."
+  await_ci_red: "Fix CI before requesting re-review (see failing checks above)."
+  await_wait_timeout: "Still waiting on: {{ reviewers }}. Rerun `{{ prog }} pr await {{ pr }}` to keep waiting."

agent_experience/commands/pr/assets/backends/codex.yaml

@@ -0,0 +1,21 @@
+hints:
+  lint_clean: "Commit, push, then `{{ prog }} pr open --title \"...\"`."
+  lint_clean_with_alignment: "Run `{{ prog }} pr delta` (this PR touches alignment files), then commit, push, and `{{ prog }} pr open --title \"...\"`."
+  lint_violations: "Fix the {{ violation_count }} violation(s) above and rerun `{{ prog }} pr lint`."
+  open_recommend_read: "`{{ prog }} pr read {{ pr }} --wait 180` (recommended) or `{{ prog }} pr read {{ pr }}` in ~3 min."
+  open_already_exists: "PR already open as #{{ pr }} — `{{ prog }} pr read {{ pr }} --wait 180` to fetch the briefing."
+  read_unresolved_after_commits: "Push fixes, then `{{ prog }} pr read {{ pr }} --wait 180`."
+  read_unresolved_no_commits: "Triage and prepare `replies.jsonl`, then `{{ prog }} pr reply {{ pr }} < replies.jsonl`."
+  read_ci_red: "Fix CI before requesting re-review (see failing checks above)."
+  read_clean: "Wait for human merge."
+  read_wait_timeout: "Still waiting on: {{ reviewers }}. Rerun `{{ prog }} pr read {{ pr }} --wait 180` to continue."
+  reply_with_failures: "Resubmit the failed lines (see table above) to `{{ prog }} pr reply {{ pr }}`."
+  reply_clean: "Push fixes (if any), then `{{ prog }} pr read {{ pr }} --wait 180`."
+  delta_done: "Triage each sibling — open follow-up PRs where alignment drifted; mention them in your reply."
+  review_posted: "Posted `/agentic_review` — `{{ prog }} pr read {{ pr }} --wait 180` once Qodo responds."
+  await_clean: "PR #{{ pr }} is ready — wait for human merge."
+  await_gate_error: "SonarCloud quality gate is ERROR — fix the new issues above, push, then `{{ prog }} pr await {{ pr }}` again."
+  await_gate_unknown: "SonarCloud quality gate is UNKNOWN — analysis is pending or the project isn't analyzed yet; wait and re-run `{{ prog }} pr await {{ pr }}`."
+  await_unresolved_threads: "Triage and prepare `replies.jsonl`, then `{{ prog }} pr reply {{ pr }} < replies.jsonl`."
+  await_ci_red: "Fix CI before requesting re-review (see failing checks above)."
+  await_wait_timeout: "Still waiting on: {{ reviewers }}. Rerun `{{ prog }} pr await {{ pr }}` to keep waiting."

agent_experience/commands/pr/assets/backends/copilot.yaml

@@ -0,0 +1,21 @@
+hints:
+  lint_clean: "Commit, push, then `{{ prog }} pr open --title \"...\"`."
+  lint_clean_with_alignment: "Run `{{ prog }} pr delta` (this PR touches alignment files), then commit, push, and `{{ prog }} pr open --title \"...\"`."
+  lint_violations: "Fix the {{ violation_count }} violation(s) above and rerun `{{ prog }} pr lint`."
+  open_recommend_read: "`{{ prog }} pr read {{ pr }} --wait 180` (recommended) or `{{ prog }} pr read {{ pr }}` in ~3 min."
+  open_already_exists: "PR already open as #{{ pr }} — `{{ prog }} pr read {{ pr }} --wait 180` to fetch the briefing."
+  read_unresolved_after_commits: "Push fixes, then `{{ prog }} pr read {{ pr }} --wait 180`."
+  read_unresolved_no_commits: "Triage and prepare `replies.jsonl`, then `{{ prog }} pr reply {{ pr }} < replies.jsonl`."
+  read_ci_red: "Fix CI before requesting re-review (see failing checks above)."
+  read_clean: "Wait for human merge."
+  read_wait_timeout: "Still waiting on: {{ reviewers }}. Rerun `{{ prog }} pr read {{ pr }} --wait 180` to continue."
+  reply_with_failures: "Resubmit the failed lines (see table above) to `{{ prog }} pr reply {{ pr }}`."
+  reply_clean: "Push fixes (if any), then `{{ prog }} pr read {{ pr }} --wait 180`."
+  delta_done: "Triage each sibling — open follow-up PRs where alignment drifted; mention them in your reply."
+  review_posted: "Posted `/agentic_review` — `{{ prog }} pr read {{ pr }} --wait 180` once Qodo responds."
+  await_clean: "PR #{{ pr }} is ready — wait for human merge."
+  await_gate_error: "SonarCloud quality gate is ERROR — fix the new issues above, push, then `{{ prog }} pr await {{ pr }}` again."
+  await_gate_unknown: "SonarCloud quality gate is UNKNOWN — analysis is pending or the project isn't analyzed yet; wait and re-run `{{ prog }} pr await {{ pr }}`."
+  await_unresolved_threads: "Triage and prepare `replies.jsonl`, then `{{ prog }} pr reply {{ pr }} < replies.jsonl`."
+  await_ci_red: "Fix CI before requesting re-review (see failing checks above)."
+  await_wait_timeout: "Still waiting on: {{ reviewers }}. Rerun `{{ prog }} pr await {{ pr }}` to keep waiting."

agent_experience/commands/pr/assets/rules/lint_rules.py

@@ -0,0 +1,79 @@
+"""Portability and alignment rules for `agex pr lint`.
+
+Pure functions over (file_path, file_content) tuples so they can be
+unit-tested without git.  The CLI driver in `commands/pr/scripts/lint.py`
+collects the diff and feeds it in.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_HOME_PATH_RE = re.compile(r"/home/[a-zA-Z0-9_-]+/")
+_DOTFILE_RE = re.compile(r"~/\.[a-zA-Z][a-zA-Z0-9_-]*/")
+_DOC_EXTS = (".md", ".rst", ".txt")
+_ALIGNMENT_PATHS = ("CLAUDE.md", "culture.yaml")
+_ALIGNMENT_PREFIXES = (".claude/skills/",)
+
+
+@dataclass
+class Violation:
+    rule: str
+    file: str
+    line: int
+    evidence: str
+
+
+def _check_absolute_home(path: str, content: str) -> list[Violation]:
+    out: list[Violation] = []
+    for lineno, line in enumerate(content.splitlines(), start=1):
+        m = _HOME_PATH_RE.search(line)
+        if m:
+            out.append(
+                Violation(
+                    rule="absolute-home-path",
+                    file=path,
+                    line=lineno,
+                    evidence=line.strip(),
+                )
+            )
+    return out
+
+
+def _check_dotfile_in_doc(path: str, content: str) -> list[Violation]:
+    if not path.lower().endswith(_DOC_EXTS):
+        return []
+    out: list[Violation] = []
+    for lineno, line in enumerate(content.splitlines(), start=1):
+        if _DOTFILE_RE.search(line):
+            out.append(
+                Violation(
+                    rule="user-dotfile-reference",
+                    file=path,
+                    line=lineno,
+                    evidence=line.strip(),
+                )
+            )
+    return out
+
+
+def check_files(files: list[tuple[str, str]]) -> list[Violation]:
+    """Run all portability rules over (path, content) tuples."""
+    out: list[Violation] = []
+    for path, content in files:
+        out.extend(_check_absolute_home(path, content))
+        out.extend(_check_dotfile_in_doc(path, content))
+    return out
+
+
+def check_alignment_trigger(file_paths: list[str]) -> bool:
+    """Return True if the changed file list touches any alignment-relevant
+    file (CLAUDE.md, culture.yaml, .claude/skills/**)."""
+    for p in file_paths:
+        if p in _ALIGNMENT_PATHS:
+            return True
+        for prefix in _ALIGNMENT_PREFIXES:
+            if p.startswith(prefix):
+                return True
+    return False

agent_experience/commands/pr/assets/rules/next_step_rules.py

@@ -0,0 +1,78 @@
+"""Prioritized 'Next step:' rule keys for `agex pr` commands.
+
+Each function takes the data the command already gathered and returns the
+footer rule key + a context dict for variable substitution.  First match
+wins.  Per-backend phrasing lives in `assets/backends/*.yaml`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def lint_next_step(violations: list[Any], alignment_triggered: bool) -> tuple[str, dict[str, Any]]:
+    if violations:
+        return "lint_violations", {"violation_count": len(violations)}
+    if alignment_triggered:
+        return "lint_clean_with_alignment", {}
+    return "lint_clean", {}
+
+
+def open_next_step(pr: int, was_already_open: bool) -> tuple[str, dict[str, Any]]:
+    key = "open_already_exists" if was_already_open else "open_recommend_read"
+    return key, {"pr": pr}
+
+
+def read_next_step(
+    pr: int,
+    threads_unresolved: int,
+    has_recent_local_commits: bool,
+    ci_red: bool,
+) -> tuple[str, dict[str, Any]]:
+    if ci_red:
+        return "read_ci_red", {"pr": pr}
+    if threads_unresolved > 0:
+        if has_recent_local_commits:
+            return "read_unresolved_after_commits", {"pr": pr}
+        return "read_unresolved_no_commits", {"pr": pr}
+    return "read_clean", {"pr": pr}
+
+
+def read_wait_timeout_step(pr: int, reviewers: list[str]) -> tuple[str, dict[str, Any]]:
+    return "read_wait_timeout", {"pr": pr, "reviewers": ", ".join(reviewers)}
+
+
+def await_next_step(
+    pr: int,
+    gate_error: bool,
+    threads_unresolved: int,
+    ci_red: bool,
+    gate_unknown: bool = False,
+) -> tuple[str, dict[str, Any]]:
+    if gate_error:
+        return "await_gate_error", {"pr": pr}
+    if gate_unknown:
+        return "await_gate_unknown", {"pr": pr}
+    if threads_unresolved > 0:
+        return "await_unresolved_threads", {"pr": pr}
+    if ci_red:
+        return "await_ci_red", {"pr": pr}
+    return "await_clean", {"pr": pr}
+
+
+def await_wait_timeout_step(pr: int, reviewers: list[str]) -> tuple[str, dict[str, Any]]:
+    return "await_wait_timeout", {"pr": pr, "reviewers": ", ".join(reviewers)}
+
+
+def reply_next_step(pr: int, failure_count: int) -> tuple[str, dict[str, Any]]:
+    if failure_count > 0:
+        return "reply_with_failures", {"pr": pr}
+    return "reply_clean", {"pr": pr}
+
+
+def review_next_step(pr: int) -> tuple[str, dict[str, Any]]:
+    return "review_posted", {"pr": pr}
+
+
+def delta_next_step() -> tuple[str, dict[str, Any]]:
+    return "delta_done", {}