From a2c102498ff82c482b3525f1d03defb74a0f88de Mon Sep 17 00:00:00 2001 From: NagyVikt Date: Mon, 4 May 2026 06:12:10 +0200 Subject: [PATCH] Prefer RTK guidance for noisy gx agent commands 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: OmX --- .../proposal.md | 22 ++++++++++++++ .../specs/gx-rtk-command-guidance/spec.md | 29 +++++++++++++++++++ .../tasks.md | 24 +++++++++++++++ skills/gitguardex/SKILL.md | 2 ++ src/context.js | 15 ++++++++++ templates/AGENTS.multiagent-safety.md | 13 +++++++++ templates/codex/skills/gitguardex/SKILL.md | 2 ++ test/prompt.test.js | 8 +++++ 8 files changed, 115 insertions(+) create mode 100644 openspec/changes/agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03/proposal.md create mode 100644 openspec/changes/agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03/specs/gx-rtk-command-guidance/spec.md create mode 100644 openspec/changes/agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03/tasks.md diff --git a/openspec/changes/agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03/proposal.md b/openspec/changes/agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03/proposal.md new file mode 100644 index 00000000..c28ac264 --- /dev/null +++ b/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. diff --git a/openspec/changes/agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03/specs/gx-rtk-command-guidance/spec.md b/openspec/changes/agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03/specs/gx-rtk-command-guidance/spec.md new file mode 100644 index 00000000..58fe696c --- /dev/null +++ b/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 diff --git a/openspec/changes/agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03/tasks.md b/openspec/changes/agent-codex-optimize-gx-to-use-rtk-2026-05-04-06-03/tasks.md new file mode 100644 index 00000000..ef16bb9a --- /dev/null +++ b/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. diff --git a/skills/gitguardex/SKILL.md b/skills/gitguardex/SKILL.md index e156736c..ada7e706 100644 --- a/skills/gitguardex/SKILL.md +++ b/skills/gitguardex/SKILL.md @@ -9,3 +9,5 @@ Use when repo safety may be broken. Bootstrap: `gx setup` Ops: `gx branch start "" ""`, `gx locks claim --branch "" `, `gx branch finish --branch "" --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 `). Do not wrap commands whose stdout is parsed by scripts. diff --git a/src/context.js b/src/context.js index 9c97604d..da650d22 100644 --- a/src/context.js +++ b/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 "" ', ], }, + { + 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 `, `rtk read -l aggressive`, `rtk smart `, `rtk find "" .`, `rtk grep "" .`, `rtk diff `.', + 'Git/GitHub: `rtk git status`, `rtk git diff`, `rtk git log -n 10`, `rtk gh pr list`, `rtk gh pr view `.', + 'Tests/build: `rtk test `, `rtk err `, `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 ` 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', diff --git a/templates/AGENTS.multiagent-safety.md b/templates/AGENTS.multiagent-safety.md index f97780e7..0295befc 100644 --- a/templates/AGENTS.multiagent-safety.md +++ b/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 `, `rtk read -l aggressive`, `rtk smart `, `rtk find "" .`, `rtk grep "" .`, `rtk diff `. +- Git and GitHub: `rtk git status`, `rtk git diff`, `rtk git log -n 10`, `rtk gh pr list`, `rtk gh pr view `. +- Tests and builds: `rtk test `, `rtk err `, `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 `, `rtk kubectl pods`, `rtk json `, `rtk log `, `rtk curl `. +- Savings checks: `rtk gain`, `rtk discover`, and `rtk session`. +- Use `rtk proxy ` 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: diff --git a/templates/codex/skills/gitguardex/SKILL.md b/templates/codex/skills/gitguardex/SKILL.md index e156736c..ada7e706 100644 --- a/templates/codex/skills/gitguardex/SKILL.md +++ b/templates/codex/skills/gitguardex/SKILL.md @@ -9,3 +9,5 @@ Use when repo safety may be broken. Bootstrap: `gx setup` Ops: `gx branch start "" ""`, `gx locks claim --branch "" `, `gx branch finish --branch "" --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 `). Do not wrap commands whose stdout is parsed by scripts. diff --git a/test/prompt.test.js b/test/prompt.test.js index fbcf9ee7..fd9ad65a 100644 --- a/test/prompt.test.js +++ b/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 /); + 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\./); });