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\./); });