@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.28

package/packages/agent-settings/src/opencode-hooks.ts

@@ -51,7 +51,7 @@ function parseArgs(args: readonly string[]): { home: string; mode: "plan" | "rem
 	return { home, mode };
 }
 
-export function main(args: readonly string[]): number {
+function main(args: readonly string[]): number {
 	const { home, mode } = parseArgs(args);
 	const path = pluginPath(home);
 	const state = classifyRetiredCarrier(home);

package/packages/agent-settings/tsconfig.json

@@ -0,0 +1,23 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "types": ["bun"],
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitOverride": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "useUnknownInCatchVariables": true
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"]
+}

package/packages/agent-skills/assets/agent-search-tool-audit/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: agent-search-tool-audit
+description: Measure how often each agent host (Claude Code, Codex, Kimi, OpenCode) reaches for `ast-grep` and `search query "<text>"` versus how often agent-hooks denies them for `grep`, `find`, or the host's native `Grep` / `Glob` / `Search` tool. Produces a dated research page under `docs/research/` with frontmatter and updates `docs/research/index.md`. Use when the user wants to audit search-tool behaviour across surfaces, when investigating why the deny messages aren't redirecting the model, or as a scheduled weekly check.
+disable-model-invocation: false
+---
+
+# Agent Search-Tool Audit
+
+Per-host, per-day tally of agent-hooks decisions in `.adl/logs/`,
+grouped by surface (claude / codex / kimi / opencode). The same
+audit that produced `docs/research/research-2026-10-02-search-tool-usage-across-surfaces.md`
+and its evidence siblings.
+
+## Use When
+
+- The user wants to measure how often each agent host reaches for
+  `ast-grep` / `search query` vs how often they reach for `grep` /
+  `find` / native `Grep`.
+- The user is investigating why the deny messages aren't
+  redirecting the model to the recommended tools.
+- A weekly check is needed (the script runs in <30 s and writes a
+  dated `docs/research/research-YYYY-MM-DD-search-tool-usage-across-surfaces.md`).
+
+## Do Not Use When
+
+- The repo has no `.adl/logs/` (no agent-hooks hooks installed).
+- The question is about a non-search tool (use a different audit
+  script).
+- The repo is not a git repo and the script's `git rev-parse
+  --show-toplevel` fallback cannot find the project root — pass
+  `--out <absolute-dir>` to write the report elsewhere.
+
+## Process
+
+### 1. Locate the script
+
+After deploy, the script lives at:
+
+```
+.agents/skills/agent-search-tool-audit/scripts/audit.sh
+```
+
+In dev (this repo's `packages/agent-skills/`), the equivalent path is
+`packages/agent-skills/assets/agent-search-tool-audit/scripts/audit.sh`.
+The script finds the project root via `git rev-parse --show-toplevel`,
+so it works in both layouts.
+
+### 2. Run with the desired window
+
+```sh
+.agents/skills/agent-search-tool-audit/scripts/audit.sh --days 7
+```
+
+Flags:
+- `--days N` — trailing window in UTC days (default 7)
+- `--out DIR` — output directory (default `docs/research`)
+
+The script writes one markdown file per run:
+
+```
+docs/research/research-YYYY-MM-DD-search-tool-usage-across-surfaces.md
+```
+
+If a file with that name already exists, the script leaves it
+untouched (it might be a hand-curated analysis from earlier in the
+day) and only updates `docs/research/index.md`. Delete the existing
+file to force regeneration.
+
+### 3. Verify the page has frontmatter and is in the catalog
+
+The script emits a valid research page (frontmatter included) and
+appends one row to `docs/research/index.md`. Confirm both with:
+
+```sh
+head -10 docs/research/research-$(date -u +%Y-%m-%d)-search-tool-usage-across-surfaces.md
+rg "$(date -u +%Y-%m-%d)-search-tool-usage" docs/research/index.md
+```
+
+### 4. (Optional) Schedule it
+
+The cheapest repeatable cadence is `crontab` on the workstation:
+
+```
+0 9 * * 1 cd <repo-root> && .agents/skills/agent-search-tool-audit/scripts/audit.sh
+```
+
+Weekly Monday 09:00 local. The output lands in `docs/research/`,
+ready for the next research-page review.
+
+## What the script measures
+
+| Metric | Source | Use |
+| --- | --- | --- |
+| Total decisions per host | `hooks.log` / `hooks.log.1` / `hooks-deny.log`, deduped by `(ts, command, rule)` | Volume baseline |
+| Denials per host, broken down by `rule` field | same | Where the hook fires |
+| Search-tool denials (`tool.grep` / `tool.native-search` / `tool.find`) | same | The hook category this skill cares about |
+| `ast-grep` invocations (Bash command starting with `ast-grep`) | same | Whether the recommended tool is being used |
+| `search query` invocations (Bash command starting with `search `) | same | Same |
+| Session count per host/day | same | Volume sanity check |
+
+The script does NOT compute the per-denial retry/pivot analysis
+that's in the hand-curated research page. That step needs the model
+itself (it requires reading the actual `command` strings and
+classifying them by tool). For the retry analysis, follow the
+"Process" steps in `docs/research/research-2026-10-02-search-tool-usage-across-surfaces.md`.
+
+## Cost
+
+- <30 s on a typical 2-3 MB log set
+- No network, no new tools beyond `jq` + `python3` + the shell
+- Read-only on `.adl/logs/`; writes one markdown file and one row
+  to `docs/research/index.md`
+
+## Related
+
+- `docs/research/research-2026-10-02-search-tool-usage-across-surfaces.md`
+  — the hand-curated analysis this script would generate for today
+- `packages/agent-hooks/src/rules/impl/tool-grep.ts`,
+  `tool-find.ts`, `tool-native-search.ts` — the deny messages the
+  audit is measuring

package/packages/agent-skills/assets/agent-search-tool-audit/scripts/audit.sh

@@ -0,0 +1,276 @@
+#!/usr/bin/env bash
+# scripts/audit.sh — part of the agent-search-tool-audit skill
+# (packages/agent-skills/assets/agent-search-tool-audit/).
+#
+# Per-host, per-day tally of agent-hooks decisions in `.adl/logs/`,
+# grouped by surface (claude / codex / kimi / opencode). Writes one
+# dated markdown under `docs/research/` so the next weekly research
+# page in the "agent search-tool behaviour" series can compare against
+# the previous one. Reads only — never modifies the repo.
+#
+# Usage:
+#   scripts/audit.sh [--days N] [--out DIR]
+#
+# Defaults: --days 7, --out docs/research
+#
+# Output:
+#   <out>/research-YYYY-MM-DD-search-tool-usage-across-surfaces.md
+#   <out>/index.md  (one new row appended for the new page)
+#
+# Source data:
+#   .adl/logs/hooks.log            (current decision log)
+#   .adl/logs/hooks.log.1          (rotated decision log)
+#   .adl/logs/hooks-deny.log       (dedicated deny stream)
+#   .adl/logs/agents/tool-calls.log (adl run lifecycle)
+#
+# Path discovery: this script lives in the agent-skills asset tree
+# (5 levels deep in dev, 4 levels deep once deployed to
+# `.agents/skills/`). Use `git rev-parse --show-toplevel` so it
+# works in both layouts.
+#
+# Cost: <30 s on a typical 2-3 MB log set; no network, no new tools
+# beyond jq + python3 + the shell.
+
+set -euo pipefail
+
+DAYS=7
+OUT=docs/research
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --days) DAYS="$2"; shift 2;;
+    --out)  OUT="$2"; shift 2;;
+    -h|--help)
+      sed -n '2,30p' "$0"
+      exit 0
+      ;;
+    *)
+      echo "unknown arg: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+cd "$(dirname "$0")/../.."
+
+# `git rev-parse --show-toplevel` works in both dev (5 levels deep
+# under packages/agent-skills/assets/agent-search-tool-audit/scripts)
+# and deployed (4 levels deep under .agents/skills/). Fall back to
+# the dev layout if git is missing.
+if command -v git >/dev/null 2>&1; then
+  if toplevel=$(git rev-parse --show-toplevel 2>/dev/null) && [[ -n "$toplevel" ]]; then
+    cd "$toplevel"
+  fi
+fi
+
+command -v jq >/dev/null 2>&1 || { echo "jq is required and is not on PATH" >&2; exit 1; }
+command -v python3 >/dev/null 2>&1 || { echo "python3 is required and is not on PATH" >&2; exit 1; }
+
+LOG_FILES=(
+  .adl/logs/hooks.log
+  .adl/logs/hooks.log.1
+  .adl/logs/hooks-deny.log
+)
+LOGS_PRESENT=()
+for f in "${LOG_FILES[@]}"; do
+  [[ -f "$f" ]] && LOGS_PRESENT+=("$f")
+done
+[[ ${#LOGS_PRESENT[@]} -gt 0 ]] || { echo "no hook log files present under .adl/logs/" >&2; exit 1; }
+
+TODAY="$(date -u +%Y-%m-%d)"
+RUN_TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+OUT_FILE="${OUT}/research-${TODAY}-search-tool-usage-across-surfaces.md"
+
+# If today's page already exists, leave it alone — it might be a hand-curated
+# analysis from earlier in the day. Append / update `index.md` either way so
+# the catalog stays current.
+if [[ -f "$OUT_FILE" ]]; then
+  echo "${OUT_FILE} already exists; leaving it untouched. Re-run after deleting it (or pass --out to a different dir)."
+  # Still touch index.md so the catalog row stays current (idempotent).
+  INDEX="${OUT}/index.md"
+  ROW="| [Search-tool usage across surfaces — ${TODAY}](research-${TODAY}-search-tool-usage-across-surfaces.md) | Auto-generated weekly audit of per-host search-tool denials and recommended-tool invocations |"
+  if [[ -f "$INDEX" ]] && ! grep -q "research-${TODAY}-search-tool-usage-across-surfaces.md" "$INDEX"; then
+    python3 - "$INDEX" "$ROW" <<'PYEOF' >/dev/null
+import sys
+path, row = sys.argv[1], sys.argv[2]
+with open(path) as f:
+    body = f.read()
+if body.endswith("\n\n"):
+    body = body.rstrip() + "\n" + row + "\n"
+elif body.endswith("\n"):
+    body = body + row + "\n"
+else:
+    body = body + "\n" + row + "\n"
+with open(path, "w") as f:
+    f.write(body)
+PYEOF
+    echo "appended row to ${INDEX}"
+  fi
+  exit 0
+fi
+
+python3 - "${DAYS}" "${RUN_TS}" "${TODAY}" "${LOGS_PRESENT[@]}" >"${OUT_FILE}" <<'PYEOF'
+import json, sys, datetime, collections
+
+days = int(sys.argv[1])
+run_ts = sys.argv[2]
+today = sys.argv[3]
+log_files = sys.argv[4:]
+
+cutoff = datetime.datetime.fromisoformat(today + "T00:00:00Z") - datetime.timedelta(days=days-1)
+
+# Per (host, day), tally. Dedupe by (ts, command, rule) within each log.
+per_host_day = collections.defaultdict(lambda: collections.Counter())
+per_host_day_deny_rule = collections.defaultdict(lambda: collections.Counter())
+per_host_day_ast_grep = collections.defaultdict(int)
+per_host_day_search_query = collections.defaultdict(int)
+per_host_day_session_ids = collections.defaultdict(set)
+
+seen = set()
+for path in log_files:
+    with open(path) as f:
+        for line in f:
+            try:
+                d = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            host = d.get("host")
+            ts = d.get("ts")
+            if host is None or ts is None:
+                continue
+            day = ts[:10]
+            try:
+                t = datetime.datetime.fromisoformat(ts.replace("Z", "+00:00"))
+            except ValueError:
+                continue
+            if t < cutoff:
+                continue
+            key = (ts, d.get("command"), d.get("rule"))
+            if key in seen:
+                continue
+            seen.add(key)
+
+            sess = d.get("session_id")
+            if sess:
+                per_host_day_session_ids[(host, day)].add(sess)
+
+            per_host_day[(host, day)][d.get("decision", "?")] += 1
+
+            if d.get("decision", "").startswith("DENY"):
+                per_host_day_deny_rule[(host, day)][d.get("rule", "?")] += 1
+
+            cmd = (d.get("command") or "").lower()
+            if "ast-grep" in cmd and cmd.lstrip().startswith("ast-grep"):
+                per_host_day_ast_grep[(host, day)] += 1
+            if cmd.lstrip().startswith("search "):
+                per_host_day_search_query[(host, day)] += 1
+
+hosts = sorted({h for (h, _) in per_host_day})
+days_sorted = sorted({d for (_, d) in per_host_day})
+
+search_tool_rules = ("tool.grep", "tool.native-search", "tool.find")
+
+lines = []
+lines.append("---")
+lines.append("title: Agent interface search-tool usage across surfaces ({0})".format(today))
+lines.append("description: Auto-generated per-host, per-day tally of search-tool denials and recommended-tool invocations. Produced by `scripts/research/weekly-search-tool-audit.sh --days {n}` at {run_ts}.".format(today, n=days, run_ts=run_ts))
+lines.append("type: Research")
+lines.append("created: {0}".format(today))
+lines.append("status: stable")
+lines.append("last_update: {0}".format(run_ts))
+lines.append("sources: .adl/logs/hooks.log, .adl/logs/hooks.log.1, .adl/logs/hooks-deny.log")
+lines.append("related: ./index.md, ./research-2026-10-02-search-tool-usage-across-surfaces.md")
+lines.append("---")
+lines.append("")
+lines.append("# Agent interface search-tool usage across surfaces ({0})".format(today))
+lines.append("")
+lines.append("Auto-generated weekly audit. Window: trailing {0} UTC days ending {1}. Source: `.adl/logs/hooks*.log` and `.adl/logs/hooks-deny.log`. Re-run with `just research/weekly-search-audit`.".format(days, today))
+lines.append("")
+lines.append("## Headline per host")
+lines.append("")
+lines.append("| Host | Decisions | Denials | Search-tool denials | ast-grep invocations | search query invocations |")
+lines.append("| --- | --- | --- | --- | --- | --- |")
+totals = collections.Counter()
+for host in hosts:
+    d_total = sum(per_host_day[(host, d)]["PASS"] + per_host_day[(host, d)].get("DENY", 0) + per_host_day[(host, d)].get("ERROR", 0) + per_host_day[(host, d)].get("SKIP", 0) for d in days_sorted)
+    d_denials = sum(per_host_day_deny_rule[(host, d)][r] for d in days_sorted for r in per_host_day_deny_rule[(host, d)])
+    d_search = sum(per_host_day_deny_rule[(host, d)][r] for d in days_sorted for r in search_tool_rules)
+    d_ag = sum(per_host_day_ast_grep[(host, d)] for d in days_sorted)
+    d_sq = sum(per_host_day_search_query[(host, d)] for d in days_sorted)
+    totals["decisions"] += d_total
+    totals["denials"] += d_denials
+    totals["search_tool_denials"] += d_search
+    totals["ast_grep"] += d_ag
+    totals["search_query"] += d_sq
+    lines.append("| {0} | {1} | {2} | {3} | {4} | {5} |".format(host, d_total, d_denials, d_search, d_ag, d_sq))
+
+if not hosts:
+    lines.append("| — | 0 | 0 | 0 | 0 | 0 | (no decisions in the window) |")
+
+lines.append("")
+lines.append("## Per-day, per-host breakdown")
+lines.append("")
+for host in hosts:
+    lines.append("### {0}".format(host))
+    lines.append("")
+    lines.append("| Date | Decisions | Denials | DENY tool.grep | DENY tool.native-search | DENY tool.find | ast-grep | search query | Sessions |")
+    lines.append("| --- | --- | --- | --- | --- | --- | --- | --- | --- |")
+    for d in days_sorted:
+        c = per_host_day[(host, d)]
+        r = per_host_day_deny_rule[(host, d)]
+        total = c["PASS"] + c.get("DENY", 0) + c.get("ERROR", 0) + c.get("SKIP", 0)
+        lines.append("| {0} | {1} | {2} | {3} | {4} | {5} | {6} | {7} | {8} |".format(
+            d, total, sum(r.values()), r.get("tool.grep", 0), r.get("tool.native-search", 0), r.get("tool.find", 0),
+            per_host_day_ast_grep[(host, d)], per_host_day_search_query[(host, d)], len(per_host_day_session_ids[(host, d)])
+        ))
+    lines.append("")
+
+lines.append("## Window totals")
+lines.append("")
+lines.append("- Decisions: {0}".format(totals["decisions"]))
+lines.append("- Denials: {0}".format(totals["denials"]))
+lines.append("- Search-tool denials (tool.grep + tool.native-search + tool.find): {0}".format(totals["search_tool_denials"]))
+lines.append("- ast-grep invocations: {0}".format(totals["ast_grep"]))
+lines.append("- search query invocations: {0}".format(totals["search_query"]))
+lines.append("")
+lines.append("If search-tool denials are non-zero AND ast-grep / search-query invocations are zero, the deny text in `packages/agent-hooks/src/rules/impl/` is not redirecting the agent. See `research-2026-10-02-search-tool-usage-across-surfaces.md` top-5 for the concrete edits.")
+lines.append("")
+
+sys.stdout.write("\n".join(lines))
+PYEOF
+
+# Append / update index.md with the new page row. We don't disturb
+# other rows; we add one to the end of the table.
+INDEX="${OUT}/index.md"
+ROW="| [Search-tool usage across surfaces — ${TODAY}](research-${TODAY}-search-tool-usage-across-surfaces.md) | Auto-generated weekly audit of per-host search-tool denials and recommended-tool invocations |"
+
+if [[ ! -f "$INDEX" ]]; then
+  echo "index.md not present at ${INDEX}; not updating" >&2
+  exit 0
+fi
+if grep -q "research-${TODAY}-search-tool-usage-across-surfaces.md" "$INDEX"; then
+  echo "index.md already has today's page; not appending"
+else
+  # Insert before the closing fence (if any) or just append before EOF.
+  python3 - "$INDEX" "$ROW" <<'PYEOF'
+import sys
+path, row = sys.argv[1], sys.argv[2]
+with open(path) as f:
+    body = f.read()
+# Idempotent append: ensure exactly one matching row.
+needle = row.split("|")[1].strip()
+if needle in body:
+    sys.exit(0)
+# Insert before final blank line(s).
+if body.endswith("\n\n"):
+    body = body.rstrip() + "\n" + row + "\n"
+elif body.endswith("\n"):
+    body = body + row + "\n"
+else:
+    body = body + "\n" + row + "\n"
+with open(path, "w") as f:
+    f.write(body)
+PYEOF
+  echo "appended row to ${INDEX}"
+fi
+
+echo "wrote ${OUT_FILE}"

package/packages/agent-skills/assets/debug-issue/SKILL.md

@@ -21,11 +21,11 @@ You already know the cause and are planning the fix — use `refactor-safely`.
 
 ## Steps
 
-1. Use `semantic_search_nodes_tool` to find code related to the issue.
-2. Use `query_graph_tool` with `callers_of` and `callees_of` to trace call chains.
-3. Use `get_flow_tool` to see full execution paths through suspected areas.
-4. Run `detect_changes_tool` to check if recent changes caused the issue.
-5. Use `get_impact_radius_tool` on suspected files to see what else is affected.
+1. Run `crg search "<query>"` to find code related to the issue.
+2. Run `crg query callers_of <target>` and `crg query callees_of <target>` to trace call chains.
+3. Run `crg flow --name <n>` to see full execution paths through suspected areas.
+4. Run `crg detect-changes --base <ref>` to check if recent changes caused the issue.
+5. Run `crg impact --files <f…>` on suspected files to see what else is affected.
 
 ## Tips
 
@@ -36,5 +36,6 @@ You already know the cause and are planning the fix — use `refactor-safely`.
 ## Token Efficiency
 
 Trace efficiently using `explore-codebase`'s **Token Efficiency Rules** —
-start minimal, cap calls at 5 and output around 800 tokens, then verify the
-suspected cause against real source before proposing a fix.
+start with capped output (`--limit`, `--brief`), keep commands around 5 and
+output around 800 tokens, then verify the suspected cause against real source
+before proposing a fix.

package/packages/agent-skills/assets/explore-codebase/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 
 # Explore Codebase
 
-Use the code-review-graph MCP tools to explore and understand the codebase.
+Use the `crg` CLI (code-review-graph) to explore and understand the codebase.
 
 ## Use When
 
@@ -21,21 +21,21 @@ You already know where the problem is and need to trace a bug — use
 
 ## Steps
 
-1. Run `list_graph_stats_tool` to see overall codebase metrics.
-2. Run `get_architecture_overview_tool` for high-level community structure.
-3. Use `list_communities_tool` to find major modules, then `get_community_tool` for details.
-4. Use `semantic_search_nodes_tool` to find specific functions or classes.
-5. Use `query_graph_tool` with patterns like `callers_of`, `callees_of`, `imports_of` to trace relationships.
-6. Use `list_flows_tool` and `get_flow_tool` to understand execution paths.
+1. Run `crg status` to see overall codebase metrics.
+2. Run `crg architecture` for high-level community structure.
+3. Run `crg communities` to find major modules, then `crg community --name <n> --members` for details.
+4. Run `crg search "<query>"` to find specific functions or classes (semantic only after a one-time `crg embed`; otherwise keyword fallback).
+5. Run `crg query callers_of|callees_of|imports_of|importers_of <target>` to trace relationships.
+6. Run `crg flows` and `crg flow --name <n>` to understand execution paths.
 
 ## Tips
 
-- Start broad (stats, architecture) then narrow down to specific areas.
-- Use `children_of` on a file to see all its functions and classes.
-- Use `find_large_functions_tool` to identify complex code.
+- Start broad (status, architecture) then narrow down to specific areas.
+- Use `crg query children_of <file>` to see all its functions and classes.
+- Use `crg large-functions` to identify complex code.
 
 ## Token Efficiency Rules
-- Start with `get_minimal_context_tool(task="<your task>")` before other graph tools.
-- Use `detail_level="minimal"` on all calls. Only escalate to "standard" when minimal is insufficient.
-- Target: complete any review/debug/refactor task in ≤5 tool calls and ≤800 total output tokens.
+- Start with `crg status` + `crg architecture --detail-level minimal` before other graph commands.
+- Use `--limit N` on `crg search`/`crg flows`/`crg large-functions` and `--brief` on `crg detect-changes` to cap output. Only escalate to full output when the capped view is insufficient.
+- Target: complete any review/debug/refactor task in ≤5 commands and ≤800 total output tokens.
 - Read the implementation and its tests before changing code. The graph narrows scope; it does not replace the source.

package/packages/agent-skills/assets/refactor-safely/SKILL.md

@@ -24,21 +24,22 @@ use `explore-codebase`. You are chasing the cause of a live bug — use
 
 ## Steps
 
-1. Use `refactor_tool` with mode="suggest" for community-driven refactoring suggestions.
-2. Use `refactor_tool` with mode="dead_code" to find unreferenced code.
-3. For renames, use `refactor_tool` with mode="rename" to preview all affected locations.
-4. Use `apply_refactor_tool` with the refactor_id to apply renames.
-5. After changes, run `detect_changes_tool` to verify the refactoring impact.
+1. Run `crg refactor suggest` for community-driven refactoring suggestions.
+2. Run `crg refactor dead_code` (or `crg dead-code`) to find unreferenced code.
+3. For renames, run `crg refactor rename --old-name X --new-name Y` to preview the full edit list.
+4. Apply the rename with your own edit tools — the CLI previews the edit list but does not apply it.
+5. After changes, run `crg detect-changes` to verify the refactoring impact.
 
 ## Safety Checks
 
 - Always preview before applying (rename mode gives you an edit list).
-- Check `get_impact_radius_tool` before major refactors.
-- Use `get_affected_flows_tool` to ensure no critical paths are broken.
-- Run `find_large_functions_tool` to identify decomposition targets.
+- Run `crg impact` before major refactors.
+- Run `crg detect-changes` and read the full JSON's affected flows to ensure no critical paths are broken.
+- Run `crg large-functions` to identify decomposition targets.
 
 ## Token Efficiency
 
-Follow `explore-codebase`'s **Token Efficiency Rules** — minimal-context
-first, `detail_level="minimal"`, a ≤5-call/≤800-token target, and read the
-real source before editing.
+Follow `explore-codebase`'s **Token Efficiency Rules** — `crg status` and
+`crg architecture --detail-level minimal` first, `--limit`/`--brief` to cap
+output, a ≤5-command/≤800-token target, and read the real source before
+editing.

package/packages/agent-skills/assets/review-changes/SKILL.md

@@ -23,10 +23,10 @@ You are planning your own refactor rather than reviewing one — use
 
 ## Steps
 
-1. Run `detect_changes_tool` to get risk-scored change analysis.
-2. Run `get_affected_flows_tool` to find impacted execution paths.
-3. For each high-risk function, run `query_graph_tool` with pattern="tests_for" to check test coverage.
-4. Run `get_impact_radius_tool` to understand the blast radius.
+1. Run `crg detect-changes` (`--base <ref>` to pick the diff base) for risk-scored change analysis — the full JSON embeds affected flows; add `--brief` for a summary.
+2. Run `crg flow --name <n>` on each affected flow to see the impacted execution paths.
+3. For each high-risk function, run `crg query tests_for <fn>` to check test coverage.
+4. Run `crg impact` to understand the blast radius.
 5. For any untested changes, suggest specific test cases.
 
 ## Output Format
@@ -40,6 +40,6 @@ Provide findings grouped by risk level (high/medium/low) with:
 ## Token Efficiency
 
 Keep this review token-light per `explore-codebase`'s **Token Efficiency
-Rules**: `get_minimal_context_tool` first, `detail_level="minimal"` on every
-call, ≤5 calls and ≤800 tokens, and confirm findings against the actual source
-and tests.
+Rules**: `crg status` + `crg architecture --detail-level minimal` first,
+`--brief`/`--limit` on every command, ≤5 commands and ≤800 tokens, and
+confirm findings against the actual source and tests.

package/packages/agent-skills/assets/testing/references/e2e.md

@@ -0,0 +1,37 @@
+# End-to-end testing
+
+## Purpose
+
+End-to-end tests prove a complete business outcome from initiation to an
+observable completion across the integrated system. They validate outcomes and
+orchestration: UI state, sequencing, multi-system coordination, and the user
+journey. They do not provide exhaustive contract or error-path coverage for
+each boundary.
+
+## Use it for
+
+- Critical user journeys such as onboarding, checkout, order-to-cash, or
+  recovery flows.
+- Business workflows that span app UI, backend services, persistence, and
+  permitted external integrations.
+- Production-like load or timing scenarios where the complete workflow is the
+  thing being evaluated.
+
+Keep E2E scenarios few and outcome-oriented. Put contract variants, malformed
+data, retries, and service-boundary failures in integration tests unless the
+workflow itself changes their user-visible outcome.
+
+## Canonical location
+
+This repository has one cross-workspace E2E location: `tests/e2e/`.
+App workflows and package-contributed behaviour meet there; do not create
+`apps/<app>/tests/e2e/` or `packages/<package>/tests/e2e/`. App and package
+fixtures remain with their owning test trees unless they are shared fixtures
+owned by the E2E workspace.
+
+## Evidence
+
+Run the whole journey through its real runtime in the CI-parity environment,
+using production-like data and isolated dependencies. Assert the user-visible
+completion and the durable business result. External live or billable calls
+need explicit opt-in; without it, do not silently substitute a fake path.

package/packages/agent-skills/assets/testing/references/integration.md

@@ -0,0 +1,37 @@
+# Integration testing
+
+## Purpose
+
+Integration tests prove that two or more components communicate correctly at a
+real boundary. They validate connections: contracts, transformations,
+authentication, persistence, messages, retries, timeouts, and error handling.
+They do not replace a complete user or business workflow test.
+
+## Use it for
+
+- Service-to-service APIs, database adapters, queues, files, and external
+  provider boundaries.
+- Contract fields, response and error shapes, and data transformation edge
+  cases.
+- Failure modes that happy-path journeys rarely exercise: expired credentials,
+  timeouts, retries, duplicate delivery, and transaction coordination.
+
+Keep unrelated dependencies out of the scenario. A browser-driven checkout is
+not an integration test merely because it crosses an API; test the specific
+checkout-to-payment boundary directly when that contract is the subject.
+
+## Canonical location
+
+Place app-owned integration tests in `apps/<app>/tests/integration/` and
+package-owned integration tests in `packages/<package>/tests/integration/`.
+Use containerized or otherwise isolated real dependencies whenever the scenario
+crosses a service, database, broker, streaming, or provider boundary. Do not
+put integration scenarios in `tests/e2e/`; that workspace is reserved for
+complete workflows.
+
+## Evidence
+
+Exercise the real interface with controlled data and assert both the boundary
+response and the observable transformed result. Run through the repository's
+CI-parity entrypoint; live or billable services require an explicit opt-in and
+must fail loudly or skip cleanly when credentials are absent.