Prefer RTK guidance for noisy gx agent commands (#515)

Agents need concrete compact-command examples in the gx prompt and managed AGENTS snippet. This adds an RTK prompt slice and matching skill guidance while keeping Guardex internals on raw command output for parsed contracts.

Constraint: rtk may be absent from PATH, so guidance must fall back cleanly without making it a hard dependency

Rejected: Routing internal git helpers through rtk | RTK output filtering would break --porcelain, --json, and other parsed stdout contracts

Confidence: high

Scope-risk: narrow

Directive: Do not wrap machine-readable Guardex command calls with RTK unless the parser contract is changed and tested

Tested: /home/deadpool/.local/bin/rtk test node --test test/prompt.test.js test/metadata.test.js

Tested: /home/deadpool/.local/bin/rtk test openspec validate agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03 --strict

Tested: git diff --check

Not-tested: Full repo test suite

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>
Co-authored-by: OmX <omx@oh-my-codex.dev>

Author: 3 people

openspec/changes/agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03/proposal.md

@@ -0,0 +1,22 @@
+# Optimize gx guidance for RTK command wrappers
+
+## Why
+
+Guardex already pushes agents toward compact, phase-based execution, but `gx prompt`
+and managed AGENTS snippets do not name the concrete RTK command surface. Agents
+therefore fall back to raw `git`, `rg`, test, and build commands even when RTK is
+available, increasing terminal output and context load.
+
+## What
+
+- Add RTK command-compression guidance to the `gx prompt` checklist.
+- Add the same rule to the managed multi-agent AGENTS snippet so `gx setup`/`gx doctor`
+  can propagate it to guarded repos.
+- Keep internal `gx` machine-readable git/process calls raw so RTK filtering cannot
+  break parsed stdout contracts.
+
+## Impact
+
+Agents get concrete RTK examples for file discovery, git/GitHub, tests, builds,
+logs, and savings analytics while existing scripted Guardex behavior remains
+compatible when RTK is not installed.

openspec/changes/agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03/specs/gx-rtk-command-guidance/spec.md

@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: GX Prompt Surfaces SHOULD Prefer RTK For Noisy Agent Commands
+
+`gx prompt` managed guidance SHALL tell agents to prefer RTK wrappers for noisy
+file discovery, git/GitHub inspection, test/build output, logs, and savings
+analytics when `rtk` is available.
+
+#### Scenario: default prompt includes RTK command examples
+
+- **WHEN** a user runs `gx prompt`
+- **THEN** the checklist includes RTK examples for file, git/GitHub, test/build,
+  passthrough, and savings commands
+
+#### Scenario: managed snippet includes RTK command discipline
+
+- **WHEN** a user runs `gx prompt --snippet`
+- **THEN** the managed AGENTS snippet includes RTK command-compression rules
+
+### Requirement: GX Internal Parsers MUST Keep Machine Output Raw
+
+Guardex SHALL NOT require internal machine-readable commands to be routed through
+RTK when code parses stdout.
+
+#### Scenario: parsed command output stays unfiltered
+
+- **WHEN** Guardex code needs exact stdout from commands such as `git status --porcelain`,
+  JSON output, NUL-delimited output, or other parsed command contracts
+- **THEN** the guidance tells agents not to wrap those commands with RTK

openspec/changes/agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03/tasks.md

@@ -0,0 +1,24 @@
+# Tasks
+
+## 1. Spec
+
+- [x] Record RTK prompt/guidance behavior and the machine-readable output boundary.
+
+## 2. Tests
+
+- [x] Cover `gx prompt` and `gx prompt --snippet` RTK guidance.
+
+## 3. Implementation
+
+- [x] Add an RTK command-compression slice to the AI setup prompt.
+- [x] Add RTK command discipline to the managed AGENTS snippet.
+- [x] Keep Codex skill guidance aligned with the managed template.
+
+## 4. Verification
+
+- [x] Run focused prompt/OpenSpec verification.
+
+## 5. Cleanup
+
+- [ ] Commit, push, PR, merge, and sandbox cleanup through `gx branch finish --branch "agent/codex/optimize-gx-to-use-rtk-2026-05-04-06-03" --base main --via-pr --wait-for-merge --cleanup`.
+- [ ] Record final PR URL, `MERGED` state, and cleanup evidence.

skills/gitguardex/SKILL.md

@@ -9,3 +9,5 @@ Use when repo safety may be broken.
 
 Bootstrap: `gx setup`
 Ops: `gx branch start "<task>" "<agent>"`, `gx locks claim --branch "<agent-branch>" <file...>`, `gx branch finish --branch "<agent-branch>" --base <base> --via-pr --wait-for-merge --cleanup`, `gx finish --all`, `gx cleanup`
+
+When inspecting or verifying, prefer `rtk` compact wrappers if available (`rtk git status`, `rtk grep`, `rtk test <cmd>`). Do not wrap commands whose stdout is parsed by scripts.

src/context.js

@@ -452,6 +452,9 @@ const DOCTOR_AUTO_FINISH_MESSAGE_MAX = 160;
 const AI_SETUP_PART_ALIASES = new Map([
   ['task', 'task-loop'],
   ['loop', 'task-loop'],
+  ['compact-commands', 'rtk'],
+  ['command-compression', 'rtk'],
+  ['token-commands', 'rtk'],
   ['reviewbot', 'review-bot'],
   ['forksync', 'fork-sync'],
 ]);
@@ -503,6 +506,18 @@ const AI_SETUP_PARTS = [
       'gx locks claim --branch "<agent-branch>" <file...>',
     ],
   },
+  {
+    name: 'rtk',
+    label: 'RTK command compression',
+    promptLines: [
+      'Prefer RTK wrappers for noisy shell discovery and verification when `rtk` is available; fall back to raw commands when missing.',
+      'Files: `rtk ls .`, `rtk read <file>`, `rtk read <file> -l aggressive`, `rtk smart <file>`, `rtk find "<glob>" .`, `rtk grep "<pattern>" .`, `rtk diff <a> <b>`.',
+      'Git/GitHub: `rtk git status`, `rtk git diff`, `rtk git log -n 10`, `rtk gh pr list`, `rtk gh pr view <id>`.',
+      'Tests/build: `rtk test <cmd>`, `rtk err <cmd>`, `rtk jest`, `rtk vitest`, `rtk playwright test`, `rtk pytest`, `rtk cargo test`, `rtk tsc`, `rtk lint`.',
+      'Use `rtk gain`, `rtk discover`, and `rtk session` to audit savings; use `rtk proxy <command>` only when raw passthrough is required.',
+      'Do not wrap machine-readable commands with RTK when code parses stdout (`--porcelain`, `--json`, NUL-delimited output, or exact stdout contracts).',
+    ],
+  },
   {
     name: 'integrate',
     label: 'Integrate',

templates/AGENTS.multiagent-safety.md

@@ -134,6 +134,19 @@ Default: less word, same proof.
 - Treat local edit/commit, remote publish/PR, CI diagnosis, and cleanup as bounded phases.
 - Do not spend fresh narration or approval turns on obvious safe follow-ons inside an already authorized phase unless the risk changes.
 
+### RTK command compression
+
+When `rtk` is available, prefer it for noisy shell discovery and verification.
+
+- Files: `rtk ls .`, `rtk read <file>`, `rtk read <file> -l aggressive`, `rtk smart <file>`, `rtk find "<glob>" .`, `rtk grep "<pattern>" .`, `rtk diff <a> <b>`.
+- Git and GitHub: `rtk git status`, `rtk git diff`, `rtk git log -n 10`, `rtk gh pr list`, `rtk gh pr view <id>`.
+- Tests and builds: `rtk test <cmd>`, `rtk err <cmd>`, `rtk jest`, `rtk vitest`, `rtk playwright test`, `rtk pytest`, `rtk cargo test`, `rtk tsc`, `rtk lint`.
+- Runtime and data probes: `rtk docker ps`, `rtk docker logs <container>`, `rtk kubectl pods`, `rtk json <file>`, `rtk log <file>`, `rtk curl <url>`.
+- Savings checks: `rtk gain`, `rtk discover`, and `rtk session`.
+- Use `rtk proxy <command>` only when raw passthrough is required.
+- Do not wrap machine-readable commands with RTK when code parses stdout (`--porcelain`, `--json`, NUL-delimited output, or exact stdout contracts).
+- If `rtk` is missing, use raw commands and summarize only meaningful lines.
+
 ### Caveman style
 
 Commentary and progress updates use smart-caveman `ultra` by default:

templates/codex/skills/gitguardex/SKILL.md

@@ -9,3 +9,5 @@ Use when repo safety may be broken.
 
 Bootstrap: `gx setup`
 Ops: `gx branch start "<task>" "<agent>"`, `gx locks claim --branch "<agent-branch>" <file...>`, `gx branch finish --branch "<agent-branch>" --base <base> --via-pr --wait-for-merge --cleanup`, `gx finish --all`, `gx cleanup`
+
+When inspecting or verifying, prefer `rtk` compact wrappers if available (`rtk git status`, `rtk grep`, `rtk test <cmd>`). Do not wrap commands whose stdout is parsed by scripts.

test/prompt.test.js

@@ -77,6 +77,10 @@ test('prompt outputs AI setup instructions', () => {
   assert.match(result.stdout, /avoid repeated peeks or stdin loops/);
   assert.match(result.stdout, /checkpoint after each milestone: Task -> Done -> Current status -> Next/);
   assert.match(result.stdout, /keep execution log separate from reasoning context/);
+  assert.match(result.stdout, /RTK command compression/);
+  assert.match(result.stdout, /rtk git status/);
+  assert.match(result.stdout, /rtk test <cmd>/);
+  assert.match(result.stdout, /Do not wrap machine-readable commands with RTK/);
   assert.match(result.stdout, /gx finish --all/);
   assert.match(result.stdout, /\/opsx:propose/);
   assert.match(result.stdout, /https:\/\/github\.com\/apps\/pull/);
@@ -133,6 +137,7 @@ test('prompt --list-parts prints the available prompt slices', () => {
   assert.equal(result.status, 0, result.stderr || result.stdout);
   assert.match(result.stdout, /^install$/m);
   assert.match(result.stdout, /^task-loop$/m);
+  assert.match(result.stdout, /^rtk$/m);
   assert.match(result.stdout, /^openspec$/m);
   assert.match(result.stdout, /^review-bot$/m);
 });
@@ -156,6 +161,9 @@ test('prompt --snippet prints the managed AGENTS template with token budget and
   assert.match(result.stdout, /Default: less word, same proof\./);
   assert.match(result.stdout, /Keep raw terminal interaction out of long-lived context/);
   assert.match(result.stdout, /Keep execution log separate from reasoning context/);
+  assert.match(result.stdout, /### RTK command compression/);
+  assert.match(result.stdout, /rtk git status/);
+  assert.match(result.stdout, /Do not wrap machine-readable commands with RTK/);
   assert.match(result.stdout, /### Caveman style/);
   assert.match(result.stdout, /Answer order stays fixed: answer first, cause next, fix or next step last\./);
 });