Release hardening for v1.0.0 (#3)

Make the integration safe and accurate for real agent-harness use, and add
release hygiene.

- AGENTS.md: "Harness safety" guards (no streaming/-f wrapping; trust raw exit
  code on pass/fail; prefer native file/search tools); corrected Setup note.
- references/commands.md: "Harness notes"; static-only log rows; drop the
  "near-lossless" overstatement.
- SKILL.md + README.md: "Compatibility & limitations" (Command Code hook gap,
  exit-code fidelity, piped/ANSI per RTK #1282, streaming, PATH, native tools,
  permission surface); honest savings table.
- Add CHANGELOG.md; bump skill to 1.0.0.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VvpBXNCbbg4eibmZQZAbb6

Author: Coding-Dev-Tools

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 <cmd>`.
+- **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

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

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 <cmd>` | 🟡 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 <cmd>`) 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
 ```

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 <cmd>`.
+- **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:

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 <cmd>` is near-lossless. `-u` / `--ultra-compact`, `rtk read … -l
+Plain `rtk <cmd>` 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 <c>`, `kubectl logs <p>` | `rtk docker logs <c>`, `rtk kubectl logs <p>` | dedups repeated lines |
+| `docker logs <c>`, `kubectl logs <p>` (finite) | `rtk docker logs <c>`, `rtk kubectl logs <p>` | 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 <cmd>` | 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