devex-cli 0.24.0__py3-none-any.whl

agent_experience/commands/gamify/scripts/install.py

@@ -0,0 +1,203 @@
+import json
+from datetime import datetime, timezone
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+from agent_experience.core.backend import Backend
+from agent_experience.core.config import load as load_config
+from agent_experience.core.config import save as save_config
+from agent_experience.core.paths import ensure_init
+from agent_experience.core.prog import error_prefix, prog_name
+
+
+def _fragments_file() -> Traversable:
+    return files("agent_experience.commands.gamify").joinpath("assets", "hooks", "claude-code.json")
+
+
+def _fragments_for(backend: Backend) -> list[dict]:
+    if backend != Backend.CLAUDE_CODE:
+        return []
+    data = json.loads(_fragments_file().read_text(encoding="utf-8"))
+    return data["fragments"]
+
+
+def _hooks_file_for(backend: Backend, project_dir: Path) -> Path | None:
+    if backend == Backend.CLAUDE_CODE:
+        return project_dir / ".claude" / "hooks.json"
+    return None
+
+
+def _refuse(path: Path, reason: str) -> ValueError:
+    return ValueError(
+        f"{path} {reason}; refusing to overwrite. " "Fix or remove the file before re-running."
+    )
+
+
+def _load_hooks_file(path: Path) -> dict:
+    # Malformed or unexpectedly-shaped files are NEVER silently overwritten —
+    # the caller gets a ValueError, surfaces it as exit 2, and the user's file
+    # stays on disk untouched.
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise _refuse(path, f"is not valid JSON ({e})") from e
+    if not isinstance(data, dict):
+        raise _refuse(path, "is not a JSON object at the top level")
+    for entries in data.values():
+        if not isinstance(entries, list) or not all(isinstance(e, dict) for e in entries):
+            raise _refuse(path, "is not a mapping of event → list of hook objects")
+    return data
+
+
+def _write_hooks_file(path: Path, data: dict) -> None:
+    # Sonar pythonsecurity:S2083: `path` derives from
+    # Path.cwd()/".claude/hooks.json"; the backend is enum-validated by
+    # parse_backend() before reaching here. Full rationale lives in
+    # sonar-project.properties. The suppression tag below is the
+    # load-bearing one under SonarCloud Automatic Analysis.
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")  # NOSONAR
+
+
+def _merge_fragments(hooks: dict, fragments: list[dict]) -> tuple[list[str], int]:
+    """Append each fragment's {id, hook} under its event if the id isn't already
+    there. Returns (all_fragment_ids_in_insertion_order, added_count)."""
+    written_ids: list[str] = []
+    added = 0
+    for frag in fragments:
+        event = frag["event"]
+        entry = {"id": frag["id"], "hook": frag["hook"]}
+        hooks.setdefault(event, [])
+        if not any(e.get("id") == frag["id"] for e in hooks[event]):
+            hooks[event].append(entry)
+            added += 1
+        written_ids.append(frag["id"])
+    return written_ids, added
+
+
+def _remove_ids_from_hooks(hooks: dict, ids_to_remove: set[str]) -> int:
+    """Filter entries matching ids_to_remove out of each event. Event keys whose
+    arrays become empty as a result of removal are deleted. Pre-existing empty
+    event arrays are left intact. Returns total entries removed."""
+    removed = 0
+    for event in list(hooks.keys()):
+        original = hooks[event]
+        filtered = [e for e in original if e.get("id") not in ids_to_remove]
+        event_removed = len(original) - len(filtered)
+        if event_removed == 0:
+            continue
+        removed += event_removed
+        if filtered:
+            hooks[event] = filtered
+        else:
+            del hooks[event]
+    return removed
+
+
+def install(backend: Backend) -> tuple[str, int, str]:
+    ensure_init()
+    project_dir = Path.cwd()
+    hooks_file = _hooks_file_for(backend, project_dir)
+    if hooks_file is None:
+        return (_unsupported_notice(backend), 0, "")
+
+    fragments = _fragments_for(backend)
+    if not fragments:
+        return (_unsupported_notice(backend), 0, "")
+
+    try:
+        hooks = _load_hooks_file(hooks_file)
+    except ValueError as e:
+        return ("", 2, error_prefix(str(e)))
+
+    written_ids, added_count = _merge_fragments(hooks, fragments)
+    if added_count:
+        _write_hooks_file(hooks_file, hooks)
+
+    cfg = load_config()
+    previous = cfg.installed.get("gamify", {})
+    if previous.get("hook_fragment_ids") != written_ids:
+        cfg.installed["gamify"] = {
+            "at": datetime.now(tz=timezone.utc).isoformat(),
+            "hook_fragment_ids": written_ids,
+        }
+        save_config(cfg)
+
+    rel = hooks_file.relative_to(project_dir)
+    if added_count:
+        status_line = (
+            f"- Added {added_count} hook fragment(s); "
+            f"ensured {len(written_ids)} present in `{rel}`."
+        )
+    else:
+        status_line = (
+            f"- Ensured {len(written_ids)} hook fragment(s) already present "
+            f"in `{rel}` (no changes)."
+        )
+    lines = [
+        f"# Gamify installed — {backend.value}",
+        "",
+        status_line,
+        "- Fragment IDs: " + ", ".join(f"`{i}`" for i in written_ids),
+        "",
+        f"Next: run `{prog_name()} learn gamify --agent {backend.value}`"
+        " to set up the levelup skill.",
+        "",
+    ]
+    return ("\n".join(lines), 0, "")
+
+
+def uninstall(backend: Backend) -> tuple[str, int, str]:
+    ensure_init()
+    project_dir = Path.cwd()
+    hooks_file = _hooks_file_for(backend, project_dir)
+    if hooks_file is None:
+        return (_unsupported_notice(backend), 0, "")
+
+    cfg = load_config()
+    installed = cfg.installed.get("gamify", {})
+    ids_to_remove = set(installed.get("hook_fragment_ids", []))
+    if not ids_to_remove:
+        return (f"# Gamify uninstalled — nothing to remove on {backend.value}.\n", 0, "")
+
+    rel = hooks_file.relative_to(project_dir)
+    # If the user already removed the hooks file, just drop the config record.
+    # Don't re-create the file with an empty object.
+    if not hooks_file.exists():
+        cfg.installed.pop("gamify", None)
+        save_config(cfg)
+        return (
+            f"# Gamify uninstalled — `{rel}` was already gone; " "cleared config record.\n",
+            0,
+            "",
+        )
+
+    try:
+        hooks = _load_hooks_file(hooks_file)
+    except ValueError as e:
+        return ("", 2, error_prefix(str(e)))
+
+    removed_count = _remove_ids_from_hooks(hooks, ids_to_remove)
+    if removed_count:
+        _write_hooks_file(hooks_file, hooks)
+
+    cfg.installed.pop("gamify", None)
+    save_config(cfg)
+
+    return (
+        f"# Gamify uninstalled — removed {removed_count} fragment(s) from `{rel}`.\n",
+        0,
+        "",
+    )
+
+
+def _unsupported_notice(backend: Backend) -> str:
+    return (
+        f"## `gamify` is not supported on {backend.value}\n\n"
+        f"Hooks are required to track usage events, and {backend.value} does not expose "
+        f"a hook interface {prog_name()} can write to.\n\n"
+        "Want this supported? Open an issue: <https://github.com/agentculture/devex/issues>\n"
+    )

agent_experience/commands/hook/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: hook
+description: Write and read agex tracking events.
+type: command
+---
+
+# `agex hook write <event> [key=value ...]` / `agex hook read --agent <backend>`
+
+## `write`
+
+Called by installed hooks (see `agex gamify`, Phase 7). Appends a JSON line to `.agex/data/<event>.json`. Silent. Safe for concurrent invocation (file locking via `portalocker`).
+
+```bash
+agex hook write post-tool-use tool=Read
+```
+
+## `read`
+
+Renders tracked events as a markdown table. Prints the source JSON path for deeper inspection.
+
+```bash
+agex hook read --agent claude-code
+```
+
+## Notes
+
+- Event names are free-form; conventional names: `post-tool-use`, `user-prompt`, `stop`, `sessions`.
+- Extra positional `key=value` pairs are captured into the payload. Empty keys (e.g., `=foo`) are dropped.
+- Timestamp (`ts`) is attached automatically; a positional `ts=<value>` overrides it (useful for replays).
+- The positional `<event>` name is authoritative — it always wins over any `event=...` pair in args.
+- Malformed JSON lines in `.agex/data/*.json` (e.g., from a partial write) are skipped with a warning on `hook read`, not raised.

agent_experience/commands/hook/assets/table.md.j2

@@ -0,0 +1,17 @@
+# Hook events — {{ backend }}
+
+**Source:** `{{ source }}`
+
+{% for stream in streams %}
+## `{{ stream.name }}` ({{ stream.events|length }})
+
+{% if stream.events -%}
+| ts | event | details |
+|---|---|---|
+{% for e in stream.events -%}
+| {{ e.ts }} | {{ stream.name }} | {{ e.details }} |
+{% endfor %}
+{%- else -%}
+_no events_
+{%- endif %}
+{% endfor %}

agent_experience/commands/hook/scripts/read.py

@@ -0,0 +1,53 @@
+from importlib.resources import files
+from importlib.resources.abc import Traversable
+
+from agent_experience.core.backend import Backend
+from agent_experience.core.hook_io import load_events
+from agent_experience.core import journal as _journal
+from agent_experience.core.paths import data_dir, ensure_init
+from agent_experience.core.render import render_string
+
+KNOWN_STREAMS = ["post-tool-use", "user-prompt", "stop", "sessions"]
+
+
+def _assets_root() -> 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 overview.py / learn.py pattern.
+    return files("agent_experience.commands").joinpath("hook", "assets")
+
+
+def _summarize(events):
+    return [
+        {
+            "ts": e.get("ts", ""),
+            "details": ", ".join(f"{k}={v}" for k, v in e.items() if k not in ("ts", "event")),
+        }
+        for e in events
+    ]
+
+
+def run(backend: Backend) -> tuple[str, int, str]:
+    ensure_init()
+    streams = []
+
+    # Flat streams: data/<name>.json
+    for name in KNOWN_STREAMS:
+        events = load_events(name)
+        streams.append({"name": name, "events": _summarize(events)})
+
+    # Nested streams: data/<subdir>/<name>.jsonl
+    root = data_dir()
+    if root.exists():
+        for subdir in sorted(p for p in root.iterdir() if p.is_dir()):
+            for jsonl_file in sorted(subdir.glob("*.jsonl")):
+                stream_name = f"{subdir.name}/{jsonl_file.stem}"
+                events = _journal.load_events(stream_name)
+                streams.append({"name": stream_name, "events": _summarize(events)})
+
+    template_text = _assets_root().joinpath("table.md.j2").read_text(encoding="utf-8")
+    out = render_string(
+        template_text,
+        {"backend": backend.value, "source": str(root), "streams": streams},
+    )
+    return (out, 0, "")

agent_experience/commands/hook/scripts/write.py

@@ -0,0 +1,25 @@
+from datetime import datetime, timezone
+
+from agent_experience.core.hook_io import append_event
+from agent_experience.core.paths import ensure_init
+from agent_experience.core.prog import error_prefix
+
+
+def run(event: str, args: list[str]) -> tuple[str, int, str]:
+    ensure_init()
+    payload: dict = {"ts": datetime.now(tz=timezone.utc).isoformat()}
+    for arg in args:
+        if "=" in arg:
+            k, v = arg.split("=", 1)
+            if k:
+                payload[k] = v
+    # Positional event name is authoritative — it overrides any `event=...`
+    # pair in args so hook scripts can't misattribute events.
+    payload["event"] = event
+    try:
+        append_event(event, payload)
+    except ValueError as e:
+        # append_event → _stream_path rejects names that don't match the
+        # `^[a-z][a-z0-9-]*$` slug whitelist (path-traversal guard).
+        return ("", 2, error_prefix(str(e)))
+    return ("", 0, "")

agent_experience/commands/learn/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: learn
+description: Show available lessons, or teach one.
+type: command
+---
+
+# `agex learn [topic] --agent <backend>`
+
+Without a topic, lists the lessons available for your backend. With a topic, teaches it — emits a markdown lesson body plus inline skill-template code blocks you can write into your project.
+
+## From your shell tool
+
+```bash
+agex learn --agent claude-code
+agex learn introspect --agent claude-code
+```
+
+## Notes
+
+- Lessons gated on a backend feature (e.g., `gamify` needs hooks) may still appear in the list, but they are not currently annotated as unsupported in the menu — Phase 8 adds that capability-based routing.
+- v0.1 emits inline code blocks only. A future `--write` flag is tracked as an open issue.

agent_experience/commands/learn/assets/menu.md.j2

@@ -0,0 +1,7 @@
+# Lessons — {{ backend }}
+
+Run `{{ prog }} learn <topic> --agent {{ backend }}` to learn one.
+
+{% for topic in topics -%}
+- **`{{ topic.name }}`** — {{ topic.description }}{% if topic.unsupported %} _(unsupported on {{ backend }}: {{ topic.unsupported }})_{% endif %}
+{% endfor %}

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

@@ -0,0 +1,103 @@
+---
+name: cicd
+description: How to use `agex pr` to ship a PR end-to-end — lint, open with auto-signature, fetch the unified briefing (status + comments + readiness), batch-reply with thread resolution, and run alignment-delta when needed.
+type: lesson
+---
+
+# Lesson — CI/CD with `agex pr` for {{ backend }}
+
+The full PR loop boils down to six commands. Each one ends with a
+**Next step:** footer that names the right next command — chain it.
+
+## Standard happy path
+
+```bash
+git checkout -b feat/<desc>
+# ... edit ...
+agex pr lint --agent {{ backend }}            # portability + alignment
+git commit -am "..." && git push -u origin <branch>
+
+agex pr open --agent {{ backend }} \
+    --title "..." --body-file ./body.md \
+    --delayed-read                          # creates PR + waits 180s + briefing
+
+# briefing arrived; triage and prepare replies.jsonl, then:
+agex pr reply <PR> --agent {{ backend }} < replies.jsonl
+
+# fix anything, push, then:
+agex pr read <PR> --agent {{ backend }} --wait 180
+# repeat until reviewers quiet + CI green
+# wait for human merge — never merge yourself
+```
+
+## `read --wait` vs. `await`
+
+Both poll the same readiness loop. They differ on what they do with
+the result:
+
+- `agex pr read <PR> --wait 180` — always exits 0. Renders the briefing
+  and lets the agent decide. Use when you want the unified view.
+- `agex pr await <PR>` — exits **1** on SonarCloud gate `ERROR`,
+  unresolved review threads, or failing CI checks; **0** otherwise
+  (clean state or timeout). Use when you want to gate the next command
+  on PR health (e.g., in a shell loop that should fail if Sonar or CI
+  is red).
+
+## When CLAUDE.md / culture.yaml / .claude/skills change
+
+`agex pr lint` flags this and points you at:
+
+```bash
+agex pr delta --agent {{ backend }}
+```
+
+Read each sibling's CLAUDE.md head + culture.yaml, decide whether each
+needs a follow-up PR, and mention any drift in your reply.
+
+## JSONL reply shape
+
+Each line of stdin to `agex pr reply <PR>`:
+
+```json
+{"in_reply_to": 123456, "thread_id": "T_kw...", "body": "Fixed in <commit>."}
+```
+
+- `in_reply_to` is the inline review-comment id. Omit for top-level conversation comments.
+- `thread_id` triggers `resolveReviewThread` after the post.
+- `body` is auto-signed with `- <nick> (Claude)` if the signature is missing. `<nick>` comes from the first agent's `suffix` in `culture.yaml`, falling back to the repo basename.
+
+## Side effects
+
+Network: every command except `lint` and `delta` talks to GitHub via `gh`.
+Disk: `pr open`, `pr read`, and `pr reply` append events to
+`.agex/data/pr/events.jsonl` for retrospective tooling.
+
+## When something goes wrong
+
+- `gh` not installed → `agex: install gh — https://cli.github.com/ — then rerun`
+- `gh` not authenticated → `agex: run 'gh auth login' then rerun`
+- `pr reply` partial failure → stderr names the line slice to resubmit; the
+  command stops at the first failure to keep recovery surgical.
+- `pr read --wait` / `pr await` timeout → exit 0 with a "Still waiting on:
+  <reviewers>" banner; rerun the same command to keep waiting.
+
+## Long waits (5-minute cache TTL)
+
+Anthropic's prompt cache has a 5-minute TTL. If you expect to wait
+longer than that — for example, polling a slow CI gate with
+`agex pr read <PR> --wait 600` or `agex pr await <PR> --max-wait 1800`
+— run the wait inside a subagent and triage the result when it fires.
+The parent session keeps its cache warm; only the subagent pays the
+per-iteration cost.
+
+Pattern (Claude Code): spawn an `Agent(..., run_in_background=true)`
+that runs the command and echoes the final headline + exit code.
+Continue with unrelated work; act on the notification when it
+arrives. This is exactly how steward's `cicd` workflow handles its
+`workflow.sh await <PR>` chains.
+
+## Reply etiquette
+
+Every comment gets a reply — no silent fixes. Always include a
+`thread_id` so the thread closes automatically. Reference the fix-up
+commit SHA in the reply body where relevant.

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

@@ -0,0 +1,35 @@
+---
+name: gamify
+description: Install usage tracking hooks and build a levelup skill to advise the user.
+type: lesson
+---
+
+# Lesson — set up gamification for {{ backend }}
+
+Two parts:
+
+## Part 1 — install the tracking hooks
+
+Run in your shell tool:
+
+```bash
+agex gamify --agent {{ backend }}
+```
+
+This writes backend-native hook fragments that call `agex hook write <event>` whenever you use a tool, submit a prompt, or stop. The events land in `.agex/data/`.
+
+To uninstall: `agex gamify --uninstall --agent {{ backend }}`.
+
+## Part 2 — build the `levelup` skill
+
+The hook data is inert without something to surface it. Build the levelup skill described in `agex learn levelup --agent {{ backend }}`, or copy its skill template directly:
+
+### `.claude/skills/levelup/SKILL.md`
+
+```markdown
+{{ skill_template_body }}
+```
+
+## After both parts
+
+Use your runtime normally for a few sessions. Then invoke `/levelup` — it will read the tracking data via `agex hook read` and advise the user.

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

@@ -0,0 +1,22 @@
+---
+name: levelup
+description: Read agex usage tracking data and suggest a next-feature-to-learn for the user.
+type: command
+---
+
+# Level up
+
+> **Note:** Requires `agex hook read`, which ships in a future phase (Phase 6). Until it lands, this skill has no data source — treat it as a scaffold placeholder.
+
+Invoke when the user asks for what's next, or opportunistically after a long session.
+
+## Process
+
+1. Run in your shell tool: `agex hook read --agent claude-code`
+2. Count occurrences per event type.
+3. Pick **one** feature area the user is under-using (e.g., they have MCP servers configured but `post-tool-use` shows zero MCP tool calls).
+4. Suggest one concrete next step in 3-4 sentences.
+
+## Rule
+
+One suggestion per invocation. If nothing stands out, say so — don't invent.

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

@@ -0,0 +1,41 @@
+---
+name: introspect
+description: Build an agent-native introspect skill that audits your project setup and suggests next steps.
+type: lesson
+---
+
+# Lesson — build an `introspect` skill for {{ backend }}
+
+## What you'll end up with
+
+A backend-native skill (for {{ backend }}) that:
+1. Calls `agex overview --agent {{ backend }}` to read the project's current state.
+2. Identifies gaps (missing CLAUDE.md, no skills, no hooks, etc.).
+3. Suggests the next one or two improvements you could apply.
+4. Is small enough that invoking it doesn't blow your context budget.
+
+## Why build it instead of shipping it
+
+Two reasons: (1) each agent backend has its own native skill format, so no shipped skill fits perfectly; (2) you and the user stay in control of what gets installed into the project.
+
+## Step 1 — review the `agex overview` output
+
+Run `agex overview --agent {{ backend }}` now. Note which sections are empty — those are your candidate gaps.
+
+## Step 2 — create the skill file
+
+Write the file shown below to the path noted above its fence. Adjust the prose/tone to your project's voice.
+
+### `.claude/skills/introspect/SKILL.md`
+
+```markdown
+{{ skill_template_body }}
+```
+
+## Step 3 — try it
+
+Invoke `/introspect` (or equivalent) in your runtime. Read the output, apply one suggestion.
+
+## Why one suggestion at a time
+
+Agents that shove 10 recommendations into one turn overwhelm the user. The skill you just built is explicitly capped at two — if you want more later, iterate.

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

@@ -0,0 +1,22 @@
+---
+name: introspect
+description: Audit the current project's agent setup and suggest 1-2 next improvements.
+type: command
+---
+
+# Introspect
+
+When the user asks to audit the agent setup, improve it, or "what should I add", invoke this skill.
+
+## Process
+
+1. Run in your shell tool: `agex overview --agent claude-code`
+2. Read the output. Count what exists under each section (skills, hooks, MCP, settings).
+3. Identify the two weakest sections — the ones most likely to unblock a real workflow next.
+4. Emit a short markdown reply: what's missing, why it matters, what adding it costs.
+
+## Rules
+
+- Cap suggestions at 2.
+- No "nice-to-haves." Only suggestions that unblock something concrete.
+- Don't install anything. Advise only.

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

@@ -0,0 +1,31 @@
+---
+name: levelup
+description: Build a skill that reads agex usage data and advises the user.
+type: lesson
+---
+
+# Lesson — build the `levelup` skill for {{ backend }}
+
+> **Preview:** This lesson depends on `agex gamify` (Phase 7) and `agex hook read` (Phase 6); neither is available in agex 0.3.0. Treat the steps below as a design preview — the emitted skill template won't have real data to read until those commands ship.
+
+Prerequisite: you've run `agex gamify --agent {{ backend }}` so there's data to read.
+
+## Step 1 — understand the data source
+
+Run `agex hook read --agent {{ backend }}` now. You'll see a JSON list of events (tool calls, prompts submitted, stops). The levelup skill will parse this and suggest one area for improvement.
+
+## Step 2 — create the skill file
+
+Write the file shown below to the path noted above its fence. This skill reads the tracking data and offers one concrete suggestion per invocation.
+
+### Skill template — `.claude/skills/levelup/SKILL.md`
+
+```markdown
+{{ skill_template_body }}
+```
+
+## Step 3 — try it after a few sessions
+
+Use your runtime normally for a few turns. Then invoke `/levelup` to see what the skill suggests.
+
+See also: `agex learn gamify --agent {{ backend }}` (bundles the full setup).

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

@@ -0,0 +1,22 @@
+---
+name: levelup
+description: Read agex usage tracking data and suggest a next-feature-to-learn for the user.
+type: command
+---
+
+# Level up
+
+> **Note:** Requires `agex hook read`, which ships in a future phase (Phase 6). Until it lands, this skill has no data source — treat it as a scaffold placeholder.
+
+Invoke when the user asks for what's next, or opportunistically after a long session.
+
+## Process
+
+1. Run in your shell tool: `agex hook read --agent claude-code`
+2. Count occurrences per event type.
+3. Pick **one** feature area the user is under-using (e.g., they have MCP servers configured but `post-tool-use` shows zero MCP tool calls).
+4. Suggest one concrete next step in 3-4 sentences.
+
+## Rule
+
+One suggestion per invocation. If nothing stands out, say so — don't invent.