diff --git a/AGENTS.md b/AGENTS.md index 91faba3..b9da45e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -33,9 +33,11 @@ When unsure, start raw. Lean context comes from cutting *noise*, not *signal*. ## Never default to lossy modes Plain `rtk ` keeps the signal — errors, diffs, stack traces, exit codes — -and strips only noise. `-u` / `--ultra-compact`, `rtk read … -l aggressive`, and `rtk smart` +and strips only noise. `--ultra-compact`, `rtk read … -l aggressive`, and `rtk smart` (2-line summary) are **lossy** — opt-in only for skimming something huge and -unimportant, never your default. +unimportant, never your default. (RTK's own docs still mention a `-u` short form +for `--ultra-compact`; it was removed upstream and doesn't work — use the long +flag.) ## Harness safety — don't let it break the tool call diff --git a/CHANGELOG.md b/CHANGELOG.md index 6ba72f0..6032c2c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,26 @@ All notable changes to this integration are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/), and this project aims to adhere to [Semantic Versioning](https://semver.org/). +## [1.0.1] — 2026-06-30 + +Follow-up accuracy pass after an independent audit against live upstream +rtk-ai/rtk sources (commits, issues, and the current README). + +### Fixed +- Removed all references to a `-u` short form of `--ultra-compact`. RTK's own + README still documents it, but it was removed from the CLI upstream (it + collided with `git push -u`) and was never restored — invoking it fails + outright (RTK [#2369](https://github.com/rtk-ai/rtk/issues/2369), open). + Every reference now uses the working long form, `--ultra-compact`. +- Corrected the piped-output citation: RTK + [#1282](https://github.com/rtk-ai/rtk/issues/1282) is a correctness bug + (RTK can silently substitute its compressed summary for the real content on + a non-TTY pipe), not an ANSI/decoration issue as previously described. The + ANSI-codes-on-pipe claim now cites the correct issue, RTK + [#1409](https://github.com/rtk-ai/rtk/issues/1409) (fixed). +- Synced SKILL.md's "Compatibility & limitations" section with README.md's — + it was missing the "Native tools" and "Hooks on Windows" bullets. + ## [1.0.0] — 2026-06-30 First stable release. The integration is now selective, accurate against the real @@ -31,8 +51,11 @@ RTK command surface, and hardened for agent-harness use. trust the raw exit code for pass/fail; prefer native file/search tools; treat `rtk` as optional with a raw fallback when it isn't on PATH. - **Compatibility & limitations** documentation covering the Command Code hook - gap, exit-code fidelity, piped/ANSI behavior (RTK - [#1282](https://github.com/rtk-ai/rtk/issues/1282)), streaming, and the - permission surface. + gap, exit-code fidelity, piped-output correctness (RTK + [#1282](https://github.com/rtk-ai/rtk/issues/1282)), ANSI-on-pipe (RTK + [#1409](https://github.com/rtk-ai/rtk/issues/1409)), the non-functional `-u` + short flag (RTK [#2369](https://github.com/rtk-ai/rtk/issues/2369)), + streaming, and the permission surface. +[1.0.1]: https://github.com/Coding-Dev-Tools/rtk-command-code/releases/tag/v1.0.1 [1.0.0]: https://github.com/Coding-Dev-Tools/rtk-command-code/releases/tag/v1.0.0 diff --git a/README.md b/README.md index c7b28e2..8d6500d 100644 --- a/README.md +++ b/README.md @@ -42,8 +42,8 @@ command. Two design choices keep it net-positive: - **Signal-preserving by default.** Plain `rtk ` keeps errors, stack traces, - diff hunks, and exit codes and strips only noise; the lossy modes (`-u` / - `--ultra-compact`, `-l aggressive`, `rtk smart`) are opt-in for skimming only — + diff hunks, and exit codes and strips only noise; the lossy modes + (`--ultra-compact`, `-l aggressive`, `rtk smart`) are opt-in for skimming only — never the default. If a command fails or RTK can't parse its output, you get the full raw text back (tee fallback). - **Measure net, not gross.** `rtk gain` reports gross savings; the goal is *net* @@ -173,11 +173,20 @@ things to know before relying on it: isn't guaranteed for every command/version. **For a pass/fail that matters (tests, CI gates), trust the raw exit code** — or run the command raw / `rtk proxy`. The tiers keep `rtk cargo test` in *plain* mode, never aggressive. -- **Piped (non-TTY) output.** A harness captures stdout as a pipe. RTK can still - emit icons/decoration there (RTK issue - [#1282](https://github.com/rtk-ai/rtk/issues/1282)), which wastes tokens or - corrupts parsed output. Run anything you'll parse **raw**, and set `NO_COLOR=1` - if decoration leaks in. +- **Piped (non-TTY) output can be silently wrong, not just decorated.** A harness + captures stdout as a pipe; RTK can substitute its compressed summary for the + real content there — e.g. a redirected `grep` writing a line-count summary + instead of the matching lines (RTK issue + [#1282](https://github.com/rtk-ai/rtk/issues/1282), a correctness bug). Run + anything you'll parse or redirect **raw**. Separately, RTK has also emitted ANSI + color codes into piped output before (RTK issue + [#1409](https://github.com/rtk-ai/rtk/issues/1409), fixed) — set `NO_COLOR=1` + defensively if you see escape codes leak through. +- **`-u` is not a working flag.** RTK's own README still documents `-u` as a short + form of `--ultra-compact`, but it was removed upstream (it collided with + `git push -u`) and was never restored — using it fails outright (RTK issue + [#2369](https://github.com/rtk-ai/rtk/issues/2369), open). Always use the long + form, `--ultra-compact`. - **Streaming / follow.** RTK buffers output to filter it, so `-f`, `tail -f`, or a growing log can hang. Run those raw. - **PATH.** A non-interactive shell may not find `rtk`; the integration treats it diff --git a/SKILL.md b/SKILL.md index 2f280b3..22b6310 100644 --- a/SKILL.md +++ b/SKILL.md @@ -13,7 +13,7 @@ compatibility: >- normally if it isn't installed. metadata: author: Coding-Dev-Tools - version: "1.0.0" + version: "1.0.1" homepage: https://github.com/rtk-ai/rtk allowed-tools: Bash(rtk:*) Bash(git:*) Bash(cargo:*) Bash(ls:*) Bash(cat:*) Bash(grep:*) Bash(find:*) Bash(diff:*) Bash(docker:*) Bash(kubectl:*) Bash(gh:*) Bash(glab:*) Bash(pnpm:*) Bash(npm:*) Bash(pip:*) Bash(bundle:*) Bash(ruff:*) Bash(tsc:*) Bash(eslint:*) Bash(pytest:*) Bash(go:*) Bash(jest:*) Bash(vitest:*) Bash(dotnet:*) Bash(aws:*) Bash(psql:*) Bash(prisma:*) Bash(wget:*) --- @@ -68,7 +68,7 @@ remember it — and `|` pipes and `<<` heredocs bypass the rewrite. - 🟢 **Compress freely** — large, noisy, low-stakes output you skim: `rtk ls`, `rtk git status`, `rtk git log`, `rtk docker ps`, `rtk pip list`. - 🟡 **Default mode only** — big runs where you need the failures: `rtk cargo - test`, `rtk err `. Plain `rtk` keeps errors/diffs — don't add `-u`. + test`, `rtk err `. Plain `rtk` keeps errors/diffs — don't add `--ultra-compact`. - 🔴 **Keep full fidelity (run raw)** — diffs/patches you'll apply, JSON or `--format` output you'll parse, secrets, small outputs, and files you'll edit (use the native Read tool). @@ -80,7 +80,7 @@ Full tiered table: [references/commands.md](references/commands.md). Use the *least* compression that still answers the question: ``` -raw / native Read → rtk (keeps signal, default) → -u / -l aggressive / rtk smart (lossy, skim-only) +raw / native Read → rtk (keeps signal, default) → --ultra-compact / -l aggressive / rtk smart (lossy, skim-only) ``` Start as far left as the task needs. Escalate compression only for big, boring @@ -112,14 +112,30 @@ number. Full reference: - **Exit codes.** RTK aims to pass the wrapped command's exit code through, but it isn't guaranteed for every command/version. When a pass/fail verdict matters (tests, gates), trust the raw exit code or re-run raw / `rtk proxy `. -- **Piped output.** The harness captures stdout as a non-TTY pipe; RTK may still - emit icons/decoration ([RTK #1282](https://github.com/rtk-ai/rtk/issues/1282)). - For anything you'll parse, run raw; set `NO_COLOR=1` if decoration leaks in. +- **Piped output can be silently wrong, not just decorated.** On a non-TTY pipe + RTK can substitute its compressed summary for the real content — e.g. a + redirected `grep` writing a line *count* summary instead of the matching lines + ([RTK #1282](https://github.com/rtk-ai/rtk/issues/1282), a correctness bug, not + a cosmetic one). Run anything you'll parse or redirect **raw**. Separately, RTK + has emitted ANSI color codes into piped/non-TTY output before + ([RTK #1409](https://github.com/rtk-ai/rtk/issues/1409), fixed); set + `NO_COLOR=1` defensively if you see escape codes leak through. +- **`-u` is not a working flag.** RTK's own README still lists `-u` as a short + form of `--ultra-compact`, but it was removed upstream (it collided with + `git push -u`) and isn't restored — using it fails outright + ([RTK #2369](https://github.com/rtk-ai/rtk/issues/2369), open). Always use the + long form `--ultra-compact`. - **Streaming.** RTK buffers to filter, so don't wrap `-f`/follow or growing logs. - **PATH.** In a non-interactive shell `rtk` may not be found; the integration treats it as optional and falls back to raw commands. +- **Native tools.** Command Code's built-in file/search tools (Read/Grep/Glob) + are lossless, give line numbers, and don't pass through RTK — prefer them over + `rtk read/grep/find`. - **Permissions.** `rtk` (and `rtk proxy`) can execute arbitrary wrapped commands — allow-list it deliberately. +- **Hooks on Windows.** RTK's filters work on Windows, but its auto-rewrite hook + has gaps there ([RTK discussion #671](https://github.com/rtk-ai/rtk/discussions/671)); + `.ps1` stays CRLF per `.gitattributes`. ## Prerequisite diff --git a/references/commands.md b/references/commands.md index a24796d..72468d4 100644 --- a/references/commands.md +++ b/references/commands.md @@ -5,12 +5,14 @@ output**. The skill is knowing *when* that helps. Three tiers: - 🟢 **Compress freely** — large, noisy, low-stakes output you only skim. - 🟡 **Default mode only** — worth compressing because it's big, but you need the - failures: use plain `rtk` (which keeps errors/diffs), never `-u`/aggressive. + failures: use plain `rtk` (which keeps errors/diffs), never `--ultra-compact`/aggressive. - 🔴 **Keep full fidelity** — run raw; compression risks dropping what you need. -Plain `rtk ` keeps the signal and strips only noise. `-u` / `--ultra-compact`, `rtk read … -l +Plain `rtk ` keeps the signal and strips only noise. `--ultra-compact`, `rtk read … -l aggressive`, and `rtk smart` (2-line summary) are lossy — reserve them for -skimming something huge and unimportant. +skimming something huge and unimportant. (RTK's own README still lists a `-u` +short form for `--ultra-compact`; it was removed upstream and doesn't work — +use the long flag, see Harness notes below.) ## 🟢 Compress freely (skim-only output) | Instead of | Use | Why it's safe | @@ -31,8 +33,9 @@ skimming something huge and unimportant. | any command you only want errors from | `rtk err ` | errors-only filter | | `cargo build`, `tsc`, `eslint`, `ruff`, `clippy` | `rtk cargo build`, `rtk tsc`, `rtk lint`, `rtk ruff check`, `rtk cargo clippy` | keeps diagnostics, drops progress | -Don't add `-u` / aggressive here — you'd risk dropping the failing assertion or -the `file:line` you need, which forces a re-run that costs more than it saved. +Don't add `--ultra-compact` / aggressive here — you'd risk dropping the failing +assertion or the `file:line` you need, which forces a re-run that costs more +than it saved. ## 🔴 Keep full fidelity — run raw (no `rtk`) | Situation | Do this | Why | @@ -49,8 +52,16 @@ the `file:line` you need, which forces a re-run that costs more than it saved. - **Streaming/follow** (`-f`, `tail -f`, a growing log) → run raw; RTK buffers and can hang. - **Exit status** → for a pass/fail verdict that matters (tests, gates), trust the command's raw exit code; if unsure RTK preserved it, re-run raw or `rtk proxy`. -- **Piped output** → RTK may emit icons/decoration over a non-TTY pipe; for anything - you'll parse, run raw (set `NO_COLOR=1` if decoration leaks in). +- **Piped output** → RTK can substitute its compressed summary for the real + content on a non-TTY pipe (e.g. a redirected `grep` writing a line-count summary + instead of the matches — [RTK #1282](https://github.com/rtk-ai/rtk/issues/1282), + a correctness bug). Run anything you'll parse or redirect raw. RTK has also + emitted ANSI codes into piped output before + ([RTK #1409](https://github.com/rtk-ai/rtk/issues/1409), fixed) — set + `NO_COLOR=1` defensively if escape codes leak through. +- **`-u` doesn't work** → removed upstream (it collided with `git push -u`); using + it fails outright ([RTK #2369](https://github.com/rtk-ai/rtk/issues/2369), open). + Use `--ultra-compact`. - **Native tools** → prefer the built-in file/search tools over `rtk read/grep/find`. ## Analytics