@event4u/agent-config 1.16.0 → 1.18.0

package/.agent-src/rules/artifact-engagement-recording.md

@@ -3,6 +3,8 @@ type: "auto"
 alwaysApply: false
 description: "After a /implement-ticket or /work phase-step (refine/memory/analyze/plan/implement/test/verify/report) or full task — emit one telemetry:record call with consulted+applied ids when enabled"
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/artifact-engagement-recording-mechanics.md
 ---
 
 <!-- cloud_safe: noop -->
@@ -15,11 +17,10 @@ Default-off; opt-in via `.agent-settings.yml`. Zero overhead when disabled.
 
 The schema, CLI, and storage layer are owned by
 [`scripts/telemetry/`](../../../scripts/telemetry/) and the
-`./agent-config telemetry:record` / `telemetry:status` commands shipped
-in Phase 1+2 of the
-[`road-to-artifact-engagement-telemetry`](../../../agents/roadmaps/road-to-artifact-engagement-telemetry.md)
-roadmap. This rule says **when** to call the CLI, not how the file is
-structured.
+`./agent-config telemetry:record` / `telemetry:status` commands. The
+recording contract lives in
+[`docs/contracts/artifact-engagement-flow.md`](../../docs/contracts/artifact-engagement-flow.md).
+This rule says **when** to call the CLI, not how the file is structured.
 
 ## Activation gate — read settings ONCE per task, then cache
 
@@ -60,73 +61,16 @@ consulted three times in the same boundary records once.
 When in doubt → record as `consulted` only. Over-recording `applied`
 inflates the engagement signal and defeats the purpose.
 
-## What to record — id-only, no payload
-
-```bash
-./agent-config telemetry:record \
-  --task-id "$TASK_ID" \
-  --boundary task \
-  --consulted skills:php-coder \
-  --consulted skills:eloquent \
-  --consulted rules:scope-control \
-  --applied skills:php-coder \
-  --applied rules:scope-control
-```
-
-- `--task-id` — the ticket key (`PROJ-123`) for `/implement-ticket`, or a
-  short opaque slug derived from the prompt for `/work`. **Never** a
-  branch name, a file path, or a free-text title.
-- `--boundary` — `task` or `phase-step`, matching the cadence above.
-- `--consulted <kind>:<id>` — repeat per artefact. `<kind>` is one of
-  `skills`, `rules`, `commands`, `guidelines`, `personas`.
-- `--applied <kind>:<id>` — repeat per artefact actually applied.
-- Exit `0` always when disabled (silent). Exit `1` on schema validation
-  failure (rule must NOT swallow this — surface to the user). Exit `2`
-  on IO failure.
-
-## Privacy contract — what NEVER goes into a record
-
-The CLI rejects most violations on the input boundary, but the agent must
-not even attempt these:
-
-- ❌  File paths (`src/Foo.php`, `tests/...`) — id fields are
-  artefact identifiers only.
-- ❌  Source code, prompt text, ticket body, AC text.
-- ❌  Branch names, commit shas, PR numbers, URLs.
-- ❌  Secrets, env vars, credentials, customer data.
-- ❌  Free-text strings longer than 200 chars (CLI enforces; agent must
-  not generate).
-
-When in doubt → **don't record**. A missing event is cheap; a leaked
-prompt is not.
-
-## Failure modes — DO NOT block the user's task
-
-- Schema rejection (CLI exit `1`) → log the message internally, continue
-  the user's task. Do **not** halt the dispatch loop.
-- IO failure (CLI exit `2`) → same. The telemetry is **observation**, not
-  a delivery requirement.
-- Settings malformed → already handled by the CLI: it falls back to
-  disabled and exits `0`. Agent treats it as "disabled this task".
-
-The only error the agent surfaces is when the user explicitly asked for
-recording (`telemetry:status` confirms enabled) but no event reached the
-log — that is a real bug, not a swallowed error.
-
-## What this rule does NOT do
-
-- Run when `enabled: false` (cost floor is zero — see
-  [`tests/telemetry/test_cost_floor.py`](../../../tests/telemetry/test_cost_floor.py)).
-- Track the agent's tool calls, file reads, or token spend — that is
-  out of scope, see the roadmap's "out-of-scope" section.
-- Decide retirement. Phase 4's aggregator + report renderer are the only
-  consumers that may interpret the JSONL.
-- Run on cloud surfaces (Claude.ai Web, Skills API). The
-  `cloud_safe: noop` marker keeps it inert there.
+## Mechanics — CLI invocation, privacy contract, failure handling
+
+The exact `telemetry:record` call shape with all flags, the privacy
+contract (what NEVER goes into a record), the failure-mode handling
+(do NOT block the user's task), and the "what this rule does NOT do"
+catalog live in
+[`contexts/communication/rules-auto/artifact-engagement-recording-mechanics.md`](../contexts/communication/rules-auto/artifact-engagement-recording-mechanics.md).
 
 ## See also
 
-- [`road-to-artifact-engagement-telemetry`](../../../agents/roadmaps/road-to-artifact-engagement-telemetry.md) — phase contract
 - [`docs/contracts/artifact-engagement-flow.md`](../../docs/contracts/artifact-engagement-flow.md) — recording contract details
 - [`/implement-ticket`](../commands/implement-ticket.md) and [`/work`](../commands/work.md) — boundary points where this rule fires
 - [`scripts/telemetry/`](../../../scripts/telemetry/) — engine source

package/.agent-src/rules/ask-when-uncertain.md

@@ -17,16 +17,13 @@ ONE QUESTION PER TURN. NO EXCEPTIONS.
 ASK. WAIT FOR THE ANSWER. THEN ASK THE NEXT.
 ```
 
-This is absolute. Not a default, not a guideline, not "usually".
-Every turn that contains a question contains **exactly one** question.
-Even if the questions look trivial. Even if they look independent.
-Even if they would fit on one screen. Even if batching "feels more
-efficient". Full self-check, ordering, and handoff rules under
-[How to ask](#how-to-ask).
+Absolute. Not a default, not "usually". Every turn with a question
+has **exactly one**. Even if trivial, independent, or batchable.
+Self-check, ordering, handoff under [How to ask](#how-to-ask).
 
 ## When to ask
 
-- Requirement is ambiguous or could be interpreted multiple ways
+- Requirement ambiguous or multi-interpretable
 - Not 100% sure which approach is correct
 - About to touch code you haven't fully understood
 - Choosing between multiple valid approaches
@@ -34,47 +31,35 @@ efficient". Full self-check, ordering, and handoff rules under
 
 ## Vague-request triggers — MUST ask
 
-The following patterns are almost always too vague to execute safely. When the user's
-request matches one of these without further context, ask **before** touching code:
+These patterns are too vague to execute safely. Match without further
+context → ask **before** touching code:
 
-| Pattern | Missing info | Example question |
-|---|---|---|
-| "improve / optimize this" | What metric? Speed, readability, memory? | "Optimize for what — execution speed or readability?" |
-| "add caching" | Cache store? Scope? Invalidation rules? | "Which cache driver, and what invalidates it?" |
-| "make it better / cleaner" | By what standard? | "What specifically feels wrong in the current code?" |
-| "clean up this file" | Dead code? Formatting? Refactor? | "Remove unused code, reformat, or restructure?" |
-| "fix this" (without specifying) | What's the symptom? | "What output/behavior is wrong right now?" |
-| "refactor X" | Target pattern? Boundaries? | "Refactor toward what — smaller methods, extract class, or something else?" |
-| "use best practices" | Whose? For what? | "Best practices for what specifically — testing, naming, structure?" |
-| "handle errors properly" | Which errors? How? Log, retry, propagate? | "For which failure modes, and what should happen on error?" |
-| "add a UI / component / tile / page" when the repo mixes frameworks | Which stack? Tailwind? Flux? Livewire? Custom? | "This repo uses {A} and {B} for UI — which one for this?" |
+- "improve / optimize this" — metric? speed, readability, memory?
+- "add caching" — store? scope? invalidation?
+- "make it better / cleaner" — by what standard?
+- "clean up this file" — dead code? format? refactor?
+- "fix this" (no symptom) — what output is wrong?
+- "refactor X" — target pattern? boundaries?
+- "use best practices" — whose? for what?
+- "handle errors properly" — which errors? log/retry/propagate?
+- "add a UI/component/tile/page" in mixed-framework repo — which stack?
 
-**Escape hatch:** If surrounding context (ticket, open file, prior conversation)
-makes the answer unambiguous, proceed — but state the assumption explicitly.
+Example questions per pattern:
+[`asking-and-brevity-examples`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#vague-request-triggers--example-questions).
 
-## How to ask
-
-Be specific. Present numbered options (per `user-interaction`). Keep it short.
+**Escape hatch:** if context (ticket, open file, prior turn) makes
+the answer unambiguous, proceed — but state the assumption.
 
-The Iron Law (one question per turn) is at the top of this file.
-This section adds the rationale, self-check, and ordering.
-
-The user must never have to track sub-numbers, scroll through stacked
-option blocks, or split their reply across multiple questions. One
-question, numbered options (per `user-interaction`), one short
-answer, next turn.
+## How to ask
 
-Rationale — why even "trivial" batches fail:
+Numbered options (per `user-interaction`). Short. The Iron Law is at
+the top; this section adds self-check and ordering.
 
-| Situation | Why serial always wins |
-|---|---|
-| Design / architecture decisions | Answer to Q1 reframes Q2 |
-| Naming / command-syntax / API shape | Later choices depend on it |
-| Scope / PR boundaries | Changes what the other questions even mean |
-| Tool / library selection | Downstream choices branch from it |
-| "Which approach: A vs B vs C" | Each answer opens a different follow-up |
-| Even "independent" yes/no pairs | User still has to parse two contexts |
-| Any question the user has to **think** about, not just pick | Thinking load compounds when stacked |
+The user must never track sub-numbers, scroll stacked option blocks,
+or split a reply across multiple questions. Rationale shorthand: if
+the user has to *think* about an answer, that answer almost always
+reframes the next question. Full rationale:
+[`asking-and-brevity-examples`](../../docs/guidelines/agent-infra/asking-and-brevity-examples.md#one-question-per-turn--why-serial-always-wins).
 
 ### Self-check before asking
 

package/.agent-src/rules/augment-portability.md

@@ -2,6 +2,8 @@
 type: "auto"
 description: "Editing or creating files inside .augment/ directory — skills, rules, commands, templates, contexts must be project-agnostic"
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/augment-portability-mechanics.md
 ---
 
 # Package Portability
@@ -36,76 +38,28 @@ content into any of them pollutes downstream projects or misleads agents.
 
 ## Runtime invocations — no `task` commands
 
-Skills, rules, commands, guidelines, personas, and context docs
-shipped by this package run in **consumer projects**. Consumer
-projects may not have [Task](https://taskfile.dev) installed —
-they might use npm scripts, Composer scripts, Make, or nothing at
-all. A skill that instructs an agent to run `task <something>`
-silently breaks in every project without a `Taskfile.yml`.
-
-**Rule:** Never reference a `task <something>` invocation inside any
-artefact file under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contexts}/`
+Skills, rules, commands, guidelines, personas, and context docs run in
+**consumer projects**, which may not have Task installed. **Never**
+reference a `task <something>` invocation inside any artefact file
+under `.agent-src.uncompressed/{skills,rules,commands,guidelines,personas,contexts}/`
 (and therefore also not in the compressed mirror under `.agent-src/`).
-Use the direct script invocation instead:
-
-| ❌ Forbidden | ✅ Portable |
-|---|---|
-| `task sync` | `bash scripts/compress.sh --sync` |
-| `task sync-check` | `bash scripts/compress.sh --check` |
-| `task sync-check-hashes` | `bash scripts/compress.sh --check-hashes` |
-| `task sync-changed` | `bash scripts/compress.sh --changed` |
-| `task sync-mark-done -- X` | `bash scripts/compress.sh --mark-done X` |
-| `task generate-tools` | `python3 scripts/compress.py --generate-tools` |
-| `task lint-skills` | `python3 scripts/skill_linter.py --all` |
-| `task check-refs` | `python3 scripts/check_references.py` |
-| `task check-portability` | `python3 scripts/check_portability.py` |
-| `task check-compression` | `python3 scripts/check_compression.py` |
-| `task validate-schema` | `python3 scripts/validate_frontmatter.py` |
-| `task counts-check` | `python3 scripts/update_counts.py --check` |
-| `task roadmap-progress` | `./agent-config roadmap:progress` |
-| `task ci` | run each underlying script directly (no single portable equivalent) |
-
-Task remains a convenience shortcut for maintainers working on the
-package repo itself — `task ci` is the recommended local gate before
-a PR and lives in `Taskfile.yml`, `AGENTS.md`, and the package README.
-Those maintainer-facing surfaces are outside the scope of this rule.
-Artefact files must assume Task is absent.
-
-The detection pattern *"if the consumer has a `Makefile` / build
-script, prefer its targets over raw commands"* is still allowed when
-the skill adapts to the **consumer's own** tooling (e.g.
-`tests-execute` detecting `php artisan test` vs `vendor/bin/pest`).
-It is not allowed to reference `task <name>` as the detected target —
-every direct invocation must resolve to a real script path.
+Use direct script invocations instead.
 
 ## Consumer CLI — `./agent-config`
 
 A subset of package scripts is exposed through a project-local CLI
 wrapper `./agent-config` (written into the project root by the
 installer, gitignored). Artefacts MUST prefer the CLI over raw
-`python3 scripts/…` paths for every command the CLI already covers,
-because the raw paths only resolve inside the package repo — in a
-consumer project the scripts live under `node_modules/` or `vendor/`.
+`python3 scripts/…` paths for every command the CLI already covers.
 
-| ❌ Forbidden in artefacts | ✅ Portable |
-|---|---|
-| `python3 scripts/mcp_render.py` | `./agent-config mcp:render` |
-| `python3 scripts/mcp_render.py --check` | `./agent-config mcp:check` |
-| `python3 .augment/scripts/update_roadmap_progress.py` | `./agent-config roadmap:progress` |
-| `python3 .augment/scripts/update_roadmap_progress.py --check` | `./agent-config roadmap:progress-check` |
-| `bash scripts/first-run.sh` | `./agent-config first-run` |
-| `PYTHONPATH=… python3 -m implement_ticket` | `./agent-config implement-ticket` |
-| `python3 scripts/memory_lookup.py` | `./agent-config memory:lookup` |
-| `python3 scripts/memory_signal.py` | `./agent-config memory:signal` |
-| `python3 scripts/memory_hash.py` | `./agent-config memory:hash` |
-| `python3 scripts/check_memory.py` | `./agent-config memory:check` |
-| `python3 scripts/check_memory_proposal.py` | `./agent-config memory:check-proposal` |
-| `python3 scripts/check_proposal.py` | `./agent-config proposal:check` |
-| `python3 scripts/refine_ticket_detect.py` | `./agent-config refine-ticket:detect` |
+## Translation tables — see mechanics
 
-Commands not covered by the CLI stay as direct script invocations
-(e.g. `bash scripts/compress.sh --sync`) — those are maintainer-only
-and not reachable from a consumer project anyway.
+The full `task`-to-script translation table, the `./agent-config`
+CLI mapping, and the rationale (Task absence on consumers,
+maintainer-vs-artefact split) all live in
+[`contexts/communication/rules-auto/augment-portability-mechanics.md`](../contexts/communication/rules-auto/augment-portability-mechanics.md).
+Pull it whenever an artefact is about to mention a runtime
+invocation.
 
 ## Enforcement
 

package/.agent-src/rules/augment-source-of-truth.md

@@ -2,19 +2,22 @@
 type: "auto"
 description: "Creating, editing, or modifying files inside .agent-src/ or .augment/ — the source of truth is .agent-src.uncompressed/, never edit the generated directories directly"
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/augment-source-of-truth-mechanics.md
 ---
 
 # Source of Truth
 
-`.agent-src.uncompressed/` is the **single source of truth**. Compressed output
-ships as `.agent-src/`. In the package repo, `.augment/` is a local projection
-of `.agent-src/` for Augment Code (rules copied, rest symlinked). Consumer
-projects still see `.augment/` as the installed runtime tree.
+`.agent-src.uncompressed/` is the **single source of truth**. The compressed
+output ships as `.agent-src/`. In the package repo, `.augment/` is a local
+projection of `.agent-src/` for Augment Code (rules copied, rest symlinked).
+Consumer projects still see `.augment/` as the installed runtime tree.
 
-Never edit any generated layer directly:
+Never edit any of these generated layers directly:
 
 - `.agent-src/` — compressed output shipped in the package
-- `.augment/` — local projection (gitignored in package; installer output in consumers)
+- `.augment/` — local projection (gitignored in the package repo; installer
+  output in consumer projects)
 - `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` — tool projections
 
 ## The Iron Rule
@@ -24,73 +27,20 @@ NEVER create or edit files in .agent-src/ or .augment/ directly — not even "ju
 ALWAYS work in .agent-src.uncompressed/ — then compress via /compress command.
 ```
 
-**ZERO exceptions.** Even if the fix is obvious, small, or "faster" — STOP.
-Edit `.agent-src.uncompressed/` first. Always.
+**There are ZERO exceptions to this rule.** Even if:
 
-Direct edits to `.agent-src/` break compression hashes, cause CI failures, and create drift.
+- You "know" the compressed content is correct
+- It's "just adding a missing section"
+- It's "faster to edit the compressed file directly"
+- The fix is "trivially obvious"
 
-**Compression ONLY via `/compress` command.** Handles hashing, sync, and quality checks.
+**STOP. Edit `.agent-src.uncompressed/` first. Always.**
 
-## Workflow
+Direct edits to `.agent-src/` break compression hashes, cause CI failures
+("Verify compression hashes" step), and create drift between source and output.
 
-1. **Create or edit** the file in `.agent-src.uncompressed/{path}`
-2. **Do NOT auto-compress.** Continue working.
-3. **Before commit/push:** Check if compression is needed (`bash scripts/compress.sh --changed`).
-   If files need compression, ask the user:
-   ```
-   > 📦 {N} .agent-src files need compression before commit.
-   >
-   > 1. Compress now — run /compress
-   > 2. Later — commit without compression
-   ```
-4. If compressing: run `/compress` command, then `bash scripts/compress.sh --mark-done {path}`
-
-For new non-.md files (`.php`, configs): `bash scripts/compress.sh --sync` copies them automatically.
-
-**Key change:** Compression happens once before commit/push — not after every edit.
-This avoids interruptions when work is still in progress.
-
-## What "compress" means
-
-- Remove articles (a, an, the), filler, hedging, connective fluff
-- Shorten phrases: "in order to" → "to", "make sure to" → "ensure"
-- Fragments OK: "Run tests before commit" not "You should always run tests before committing"
-- Merge redundant bullets
-
-## What NEVER changes during compression
-
-- Code blocks, inline code, URLs, file paths, commands
-- Headings (exact text preserved)
-- Tables (structure preserved, compress cell text only)
-- YAML frontmatter
-- Technical terms, library names, API names
-- Strong language: "NEVER", "MUST", "Do NOT" — these are load-bearing
-
-## Commands workflow
-
-Commands live in `.agent-src.uncompressed/commands/{name}.md` (single source of truth).
-Claude Code reads them via symlinks in `.claude/skills/{name}/SKILL.md`.
-
-**Required frontmatter for commands:**
-
-```yaml
-name: {command-name}
-description: {what it does}
-disable-model-invocation: true
-```
-
-- `name` and `disable-model-invocation: true` are required for Claude Code compatibility
-- Augment ignores unknown frontmatter fields — no conflict
-- Template: `.agent-src.uncompressed/templates/command.md`
-
-**Creating a new command:**
-
-1. Create `.agent-src.uncompressed/commands/{name}.md` (use template)
-2. Run `python3 scripts/skill_linter.py` — must be 0 FAIL
-3. Compress via `/compress`, which writes to `.agent-src/commands/`
-4. Run `python3 scripts/compress.py --generate-tools` — creates Claude symlink automatically
-
-**Never** create `.claude/skills/{name}/SKILL.md` manually for commands — always use the symlink workflow.
+**Compression is ONLY done via the `/compress` command.** The command handles
+hashing, sync verification, and quality checks automatically.
 
 ## Pre-review consistency checkpoints
 
@@ -101,28 +51,12 @@ Before asking for review or creating a PR, verify derived outputs are not stale:
 3. Before merge: verify derived outputs (`.agent-src/`, `.augment/`, `.claude/skills/`) are regenerated
 4. Do NOT leave `.agent-src/` stale across review cycles
 
-## Multi-agent symlink mapping
-
-`.claude/skills/` contains symlinks to **both** `.agent-src/skills/` and `.agent-src/commands/`.
-Claude Code treats both as "skills" — but they are different artifact types in our taxonomy.
-
-| `.claude/skills/{name}/SKILL.md` points to... | Actual type |
-|---|---|
-| `.agent-src/skills/{name}/SKILL.md` | **Skill** (workflow) |
-| `.agent-src/commands/{name}.md` | **Command** (slash-invoked procedure) |
-
-Always check the symlink target to determine the actual artifact type.
-Commands have `disable-model-invocation: true` in their frontmatter.
-
-## Quick reference
+## Mechanics — workflow, compression rules, commands, symlinks, quick reference
 
-| Task | What to do |
-|---|---|
-| Edit existing file | Edit in `.agent-src.uncompressed/`, compress to `.agent-src/` |
-| Create new `.md` | Create in `.agent-src.uncompressed/`, compress to `.agent-src/` |
-| Create new non-`.md` | Create in `.agent-src.uncompressed/`, run `bash scripts/compress.sh --sync` |
-| Create new command | Create in `.agent-src.uncompressed/commands/`, sync, `python3 scripts/compress.py --generate-tools` |
-| Delete a file | Delete from `.agent-src.uncompressed/` and `.agent-src/` |
-| Check what needs compression | `bash scripts/compress.sh --changed` |
-| Mark file as compressed | `bash scripts/compress.sh --mark-done {path}` |
-| Verify everything is in sync | `bash scripts/compress.sh --check` |
+The authoring workflow, what compression does (and never touches), the
+commands workflow with required frontmatter, the multi-agent symlink
+mapping, and the per-task quick-reference table live in
+[`contexts/communication/rules-auto/augment-source-of-truth-mechanics.md`](../contexts/communication/rules-auto/augment-source-of-truth-mechanics.md).
+Pull it whenever an edit, new file, new command, or sync question
+fires — the rule above is the obligation surface; the mechanics file
+is the lookup material.

package/.agent-src/rules/cli-output-handling.md

@@ -3,6 +3,8 @@ type: "auto"
 alwaysApply: false
 description: "Running CLI commands that produce verbose output — git, tests, linters, docker, build tools, artisan, npm, composer. Wrap with rtk when installed; tail/grep is fallback."
 source: package
+load_context:
+  - .agent-src.uncompressed/contexts/communication/rules-auto/cli-output-handling-mechanics.md
 ---
 
 # Development Efficiency
@@ -32,83 +34,15 @@ exits 0. Caching the result for the session is fine.
 For the full rtk subcommand catalog and project-local filter setup → see
 the `rtk-output-filtering` skill.
 
-## Codebase Navigation
+## Lookup material — see mechanics
 
-### Use what you already have
-
-- Edited a file → the edit tool already returned the result. Skip re-reading.
-- Ran a command → you have the output. Skip re-running to "verify".
-- File in context from recent messages → skip reloading.
-- Found a symbol → use it. Skip searching again differently.
-
-### Search before reading
-
-- **Search first** — `codebase-retrieval`, `search_query_regex`, or `grep`.
-- **Load only what you need** — use `view_range` or `search_query_regex`, not full files.
-- **Small files** (< 50 lines) — OK to read fully.
-
-### Ignored files (`.augmentignore`)
-
-- `vendor/`, `node_modules/`, lock files, and generated files are excluded from `codebase-retrieval`.
-- When you need to understand a vendor package (base class, interface, API), **read the specific file** with `view`. This bypasses the ignore.
-- Load only the file you need — never browse entire vendor directories.
-
-### Minimize tool calls
-
-- **Parallel reads** — read multiple files in one batch, not sequentially.
-- **`search_query_regex`** over full file reads.
-- **`view_range`** when you know the exact lines.
-- **One `codebase-retrieval` call** with all symbols — batch, not 5 separate calls.
-
-## Fallback Pattern: Redirect, Summarize, Target
-
-When `rtk` has no matching subcommand for the tool at hand, fall back to
-this pattern. Every command that MAY produce more than ~30 lines of output:
-
-### Step 1: Redirect to file
-```bash
-docker compose exec -T <service> <command> 2>&1 > /tmp/<tool>-output.txt
-echo "EXIT=$?"
-```
-
-### Step 2: Read ONLY the summary
-```bash
-tail -5 /tmp/<tool>-output.txt
-```
-
-### Step 3: If errors exist, read ONLY what you need to fix
-```bash
-grep "ERROR\|error\|✏️" /tmp/<tool>-output.txt | head -20
-grep "app/Services/MyService.php" /tmp/<tool>-output.txt
-```
-
-**NEVER** do:
-- `cat /tmp/<tool>-output.txt` (loads everything)
-- Read the full output of a passing command (waste)
-- Read diffs you don't plan to act on
-
-## General Rules
-
-For tool-specific commands → see the `quality-tools` skill.
-
-1. **Exit code first**: Check `$?` before reading ANY output. If 0, you're done — skip reading.
-2. **Summary line**: Most tools print a summary as the last few lines. That's all you need.
-3. **Targeted grep**: When you need details, `grep` for the specific file or error type.
-4. **Read once, act, move on**: Once you've read output and acted on it, skip re-reading.
-5. **Iterative fixing**: Fix one error at a time, re-run, check exit code.
-   Output becomes stale after each fix — always re-run before reading again.
-
-## CLI Over MCP
-
-MCP servers are **significantly more token-expensive** than CLI equivalents.
-When both options exist, prefer the CLI tool.
-
-- **Git**: `git` CLI, not Git MCP
-- **Files**: shell commands, not filesystem MCP
-- **APIs**: `curl`/`httpie`, not HTTP MCP
-- **Database**: `mysql`/`psql` CLI, not DB MCP
-
-Exception: MCPs with **unique capabilities** (Sentry, Playwright, Jira).
+Codebase-navigation tips, the redirect-summarize-target fallback
+pattern (with the three-step `tail`/`grep` recipe), the general rules
+(exit code first, summary line, targeted `grep`, read-once-act-move-on,
+iterative fixing), and the CLI-over-MCP catalog all live in
+[`contexts/communication/rules-auto/cli-output-handling-mechanics.md`](../contexts/communication/rules-auto/cli-output-handling-mechanics.md).
+Pull it whenever a verbose command is about to run without an `rtk`
+match.
 
 ## Exceptions