diff --git a/AGENTS.md b/AGENTS.md index 4468b19..91faba3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,11 +8,10 @@ These rules keep it net-positive. ## Setup -RTK is optional. If `rtk --version` fails, run commands normally — never block -work to install it. Best setup: install RTK's auto-rewrite hook once with -`rtk init -g` (then restart Command Code) so Bash commands are rewritten to `rtk` -automatically and you never prefix by hand. Without a hook, prefix manually per -the tiers in @references/commands.md. +RTK is optional. If `rtk --version` fails or `rtk` isn't on PATH, run commands +normally — never block work to install it. There's no auto-rewrite hook for +Command Code yet (RTK's `rtk init` doesn't target it), so prefix commands +yourself per the tiers in @references/commands.md. ## The one rule: compress noise, preserve signal @@ -38,6 +37,16 @@ and strips only noise. `-u` / `--ultra-compact`, `rtk read … -l aggressive`, a (2-line summary) are **lossy** — opt-in only for skimming something huge and unimportant, never your default. +## Harness safety — don't let it break the tool call + +- **Don't wrap streaming/follow output** (`-f`, `tail -f`, a growing log): RTK + buffers output to filter it, so it can hang the command. Run these raw. +- **When a pass/fail verdict matters** (tests, CI gates), trust the command's raw + exit code. If you can't tell whether the `rtk` view preserved it, re-run raw or + use `rtk proxy `. +- **Prefer the native file/search tools** over `rtk ls/grep/find/read` — they're + lossless, give line numbers, and don't pass through RTK anyway. + ## If a compressed view isn't enough On failure, RTK's tee fallback already kept the full output. Otherwise don't diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6ba72f0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,38 @@ +# Changelog + +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.0] — 2026-06-30 + +First stable release. The integration is now selective, accurate against the real +RTK command surface, and hardened for agent-harness use. + +### Changed +- Reworked from "always prefix every command with `rtk`, use ultra-compact for + maximum savings" to a **selective, signal-preserving** policy: compress noisy, + large, low-stakes output; keep full fidelity for diffs, structured/JSON output, + secrets, small outputs, and files you'll edit. +- Recommend RTK's auto-rewrite hook where supported, and document that `rtk init` + does not target Command Code yet — so manual prefixing is the working default. +- Optimize for **net** savings (gross minus re-runs and the standing prompt cost); + trimmed the always-on instruction footprint. + +### Fixed +- Removed commands/flags that don't exist in real RTK: `rtk tree`, + `rtk gain --failures`, `rtk json --keys-only`. +- Corrected `rtk read` vs the native Read tool guidance. +- Softened "lossless" to "signal-preserving" to match RTK's filter-plus-tee + behavior (full output recovered on failure, not guaranteed lossless). + +### Added +- **Harness-safety guidance**: don't wrap streaming/`-f` commands (buffer hang); + 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. + +[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 4c43541..c7b28e2 100644 --- a/README.md +++ b/README.md @@ -129,15 +129,17 @@ leaves precise output alone: | Category | Command | Through RTK? | Est. savings | |---|---|---|---| | Status / listings | `rtk git status`, `rtk ls`, `rtk git log` | 🟢 yes | ~80% | -| Logs / containers | `rtk docker ps`, `rtk log app.log` | 🟢 yes | ~80% | +| Logs / containers | `rtk docker ps`, `rtk log app.log` *(static, not `-f`)* | 🟢 yes | ~80% | | Dependencies | `rtk pip list`, `rtk pnpm list` | 🟢 yes | ~70% | | Tests / build | `rtk cargo test`, `rtk err ` | 🟡 plain mode (keeps failures) | ~90% | | Diffs you'll apply | `git diff`, `git show` | 🔴 run raw | — | | JSON / parsed output | `… --format json` | 🔴 run raw | — | | Files you'll edit | native Read tool | 🔴 not RTK | — | -_Savings are illustrative; actual numbers vary by command and output size. Run -`rtk gain` to measure your own — and `rtk discover` to spot poor fits._ +_Savings are illustrative and apply to **large** output — small outputs can be +net-neutral or negative. Run streaming/`-f` commands, and anything whose pass/fail +exit code matters, **raw** (see [Compatibility & limitations](#compatibility--limitations)). +Run `rtk gain` to measure your own; `rtk discover` to spot poor fits._ See [references/commands.md](references/commands.md) for the full tiered list and [references/analytics.md](references/analytics.md) for measuring net savings. @@ -155,6 +157,46 @@ accumulated savings. Track **net** savings, not just the headline number: tee fallback keeps full output whenever a command fails. See [references/analytics.md](references/analytics.md). +## Compatibility & limitations + +This is a documentation/instruction integration: it tells Command Code *when* to +route output through the real [RTK](https://github.com/rtk-ai/rtk) binary. A few +things to know before relying on it: + +- **No native Command Code hook (yet).** RTK's `rtk init` supports Claude Code, + Copilot, Cursor, Gemini, Cline, and others — **not** Command Code. So + `rtk init -g` won't wire up Command Code; the manual-prefix path this repo + installs is the working default. Closing that gap upstream is the goal in + [Upstream](#upstream) below. +- **Exit-code fidelity.** Agent harnesses key success off a command's exit code. + RTK aims to pass it through, but this has been fixed command-by-command and + 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. +- **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 + as optional and falls back to the bare command, so a missing binary is a no-op, + not a failure. +- **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` (especially `rtk proxy `) can execute arbitrary + wrapped commands, so an `rtk` allow-list entry is broad by nature — grant 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`. + +None of these corrupt your repository — the worst case is a failed or misread +tool call that's recoverable by re-running raw. + ## Files ``` @@ -170,6 +212,7 @@ rtk-command-code/ ├── CONTRIBUTING.md # How to contribute ├── CODE_OF_CONDUCT.md # Contributor Covenant ├── SECURITY.md # Vulnerability reporting policy +├── CHANGELOG.md # Release history ├── LICENSE # Apache 2.0 └── README.md # This file ``` diff --git a/SKILL.md b/SKILL.md index 2e3e624..2f280b3 100644 --- a/SKILL.md +++ b/SKILL.md @@ -13,7 +13,7 @@ compatibility: >- normally if it isn't installed. metadata: author: Coding-Dev-Tools - version: "0.2.0" + version: "1.0.0" 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:*) --- @@ -104,6 +104,23 @@ full output. Optimize **net** tokens (savings minus re-runs), not the headline number. Full reference: [references/analytics.md](references/analytics.md). +## Compatibility & limitations + +- **No native Command Code hook yet.** `rtk init` doesn't list Command Code, so + the manual-prefix path (Method 2) is the working default; an auto-rewrite hook + needs hand-wiring until Command Code is supported upstream. +- **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. +- **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. +- **Permissions.** `rtk` (and `rtk proxy`) can execute arbitrary wrapped commands + — allow-list it deliberately. + ## Prerequisite RTK on PATH (`rtk --version`). If missing: diff --git a/references/commands.md b/references/commands.md index c65c9fc..a24796d 100644 --- a/references/commands.md +++ b/references/commands.md @@ -8,7 +8,7 @@ output**. The skill is knowing *when* that helps. Three tiers: failures: use plain `rtk` (which keeps errors/diffs), never `-u`/aggressive. - 🔴 **Keep full fidelity** — run raw; compression risks dropping what you need. -Plain `rtk ` is near-lossless. `-u` / `--ultra-compact`, `rtk read … -l +Plain `rtk ` keeps the signal and strips only noise. `-u` / `--ultra-compact`, `rtk read … -l aggressive`, and `rtk smart` (2-line summary) are lossy — reserve them for skimming something huge and unimportant. @@ -18,10 +18,10 @@ skimming something huge and unimportant. | `ls -la` | `rtk ls` | listings dedup/group cleanly | | `git status`, `git log -n 20` | `rtk git status`, `rtk git log -n 20` | already summaries | | `docker ps`, `docker images` | `rtk docker ps`, `rtk docker images` | tabular, repetitive | -| `docker logs `, `kubectl logs

` | `rtk docker logs `, `rtk kubectl logs

` | dedups repeated lines | +| `docker logs `, `kubectl logs

` (finite) | `rtk docker logs `, `rtk kubectl logs

` | dedups repeated lines — **never** with `-f`/follow | | `kubectl get pods/services` | `rtk kubectl pods`, `rtk kubectl services` | tabular | | `pip list`, `pnpm list`, `bundle install` | `rtk pip list`, `rtk pnpm list`, `rtk bundle install` | long dependency dumps | -| `cat app.log` (triage) | `rtk log app.log` | collapses repeated log lines with counts | +| `cat app.log` (static triage) | `rtk log app.log` | collapses repeated lines — not for `-f`/follow | | `env` (scan, non-secret) | `rtk env -f AWS` | filters to a prefix | ## 🟡 Default mode only — keep the failures, drop the green @@ -44,6 +44,15 @@ the `file:line` you need, which forces a re-run that costs more than it saved. | A file you'll **edit** | native Read tool | lossless + line numbers; bypasses RTK anyway | | You need everything, just this once | `rtk proxy ` | passthrough + still tracks savings | +## Harness notes + +- **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). +- **Native tools** → prefer the built-in file/search tools over `rtk read/grep/find`. + ## Analytics Measuring real savings — and spotting bad fits before they cost you — lives in