@event4u/agent-config 1.9.1

package/.agent-src/rules/agent-docs.md

@@ -0,0 +1,61 @@
+---
+type: "auto"
+description: "Reading, creating, or updating agent documentation, module docs, roadmaps, or AGENTS.md"
+source: package
+---
+
+# Agent Documentation
+
+## When to read agent docs
+
+**Before starting ANY work**, read the relevant documentation:
+
+1. **Always read** `AGENTS.md` (if it exists in the project root) for project-level setup and conventions.
+2. **Always read** `./agents/` for project-specific architecture, guidelines, and domain docs.
+3. **If domain contexts exist** (`agents/contexts/domain/`) → read any that are relevant to the current work area.
+4. **If working on a module** → also read `app/Modules/{Module}/agents/` for module-specific docs,
+   including `agents/contexts/` within the module if it exists.
+5. **If working on a package** → read the package's `./agents/` directory.
+6. **If a roadmap exists** for the current work → read it first and follow its steps.
+
+## When to update agent docs
+
+After making changes, check if any agent docs need to be updated:
+
+- **New module created** → create `app/Modules/{Module}/agents/` with at least a module description.
+- **Database schema changed** → update `agents/docs/database-setup.md` or equivalent.
+- **New service/pattern introduced** → update relevant guideline docs.
+- **Roadmap step completed** → mark it as done in the roadmap file (`[x]`).
+- **Structural changes** (new conventions, renamed classes, moved files) → update affected docs.
+
+If unsure whether a doc needs updating, **ask the user**.
+
+## When to create roadmaps
+
+When working on a **significant change** that spans multiple steps or sessions:
+
+- Ask the user whether to create a roadmap in `agents/roadmaps/`.
+- Use the `roadmap-create` command if yes.
+- This ensures future sessions (and other agents) can pick up the work.
+
+## Roadmap lifecycle
+
+Every roadmap ends in exactly one folder — never leave stale files in `agents/roadmaps/`:
+
+- `agents/roadmaps/` — active (in progress or planned)
+- `agents/roadmaps/archive/` — finished (work happened, fully or partially)
+- `agents/roadmaps/skipped/` — not pursued (typically 0 items `[x]`, scope rejected or superseded)
+
+The `roadmap-management` skill owns the trigger matrix and user-confirmation flow.
+Never delete a roadmap — always move it.
+
+## Documentation language
+
+- All `.md` files must be written in **English**.
+- If an existing file is in German or another language, translate it to English when you touch it.
+
+## Do NOT
+
+- Do NOT create docs unless there's a real need (new module, significant change, etc.).
+- Do NOT duplicate information that's already in `AGENTS.md` or `.github/copilot-instructions.md`.
+- Do NOT write docs just to document what you did — only document things others need to know.

package/.agent-src/rules/analysis-skill-routing.md

@@ -0,0 +1,48 @@
+---
+type: auto
+description: "When choosing an analysis skill, route to the narrowest matching skill instead of defaulting to broad analysis"
+source: package
+---
+
+# Analysis Skill Routing
+
+When choosing an analysis skill, always route to the narrowest skill that still matches the actual problem shape.
+
+Use `universal-project-analysis` only for:
+
+* full project analysis
+* deep architecture review
+* broad multi-layer debugging
+* unclear systems where the stack or boundaries must first be discovered
+
+Use framework-specific project-analysis skills only after the framework is known.
+
+Use root-cause analysis skills when the problem is concrete and hypothesis-driven.
+
+Do not use broad analysis skills for:
+
+* small isolated code questions
+* normal feature work
+* obvious local fixes
+* framework-specific issues that already have a dedicated skill
+
+Prefer:
+
+* narrow specialist skill over broad analysis skill
+* framework-specific skill over universal router when the framework is already explicit
+* root-cause skill over full-project analysis when the issue is already localized
+
+If the stack is unclear:
+
+* start broad
+* then narrow quickly
+
+## Routing quality gate
+
+Only route to the narrower skill if it still has:
+
+* executable workflow (concrete procedure steps)
+* concrete validation (specific checks, not "verify it works")
+* real decision power (not just "read the guideline")
+
+If the narrow skill is too weak or hollowed out, route through the broader skill and note the gap.

package/.agent-src/rules/architecture.md

@@ -0,0 +1,62 @@
+---
+type: "auto"
+alwaysApply: false
+description: "Architecture rules for creating new files, classes, controllers, modules, or making structural decisions about project organization"
+source: package
+---
+
+# Architecture Rules
+
+## General Principles
+
+- **Controllers are thin** — no business logic, delegate to services.
+- **Only Single Action Controllers** — every new controller MUST use `__invoke()`. No multi-action / resource controllers. See `.augment/guidelines/php/controllers.md` for naming conventions.
+- **Every controller needs a FormRequest** — never validate inline with `$request->validate()`. Use a dedicated `FormRequest` subclass.
+- **Services contain business logic** — calculations, orchestration, validation.
+- **Models have no business logic** — only relationships, scopes, accessors/mutators.
+- Always check the existing directory structure before creating new files.
+- Respect existing patterns — apply modern standards to **new** code only.
+
+## Project Detection
+
+Detect the current project type from the **Git remote URL**, **directory name**, or **project files**:
+
+- Check `composer.json` for framework (Laravel, Symfony, standalone).
+- Check if `artisan` exists → Laravel project.
+- Check `package.json` for frontend framework (React, Vue, Next.js, etc.).
+- Check `AGENTS.md` or `agents/` for project-specific documentation.
+
+For tooling detection (artisan vs composer), check if `artisan` exists in the project root.
+
+## Project-Specific Architecture
+
+Each project documents its own architecture in `./agents/` and/or `AGENTS.md`.
+**Always read those files** before making structural decisions. Do not rely on this rule file
+for project-specific directory layouts, database conventions, or module systems.
+
+## Module-Level Documentation
+
+Some projects use a module system (e.g. `app/Modules/` in Laravel projects).
+Modules may have their own agent docs in `app/Modules/*/agents/` with:
+
+- Module descriptions and feature docs
+- Module-specific roadmaps (`agents/roadmaps/`)
+- Module-specific documentation (`Docs/`)
+
+When working on a module, **always check for module-level agent docs** first.
+
+## Packages
+
+Packages (Composer, npm, etc.) may also use `./agents/` in their root
+for package-specific docs and roadmaps. Treat them the same way as projects.
+
+## Build / Task Runner Detection
+
+Projects use either `Makefile` or `Taskfile.yml` (or both) for common commands.
+**Always check which one exists** and read it to discover available targets for
+testing, quality checks, container access, migrations, etc.
+
+- `Makefile` → use `make <target>`
+- `Taskfile.yml` → use `task <target>`
+
+Prefer these targets over raw `docker compose exec` commands when available.

package/.agent-src/rules/artifact-drafting-protocol.md

@@ -0,0 +1,73 @@
+---
+type: "auto"
+alwaysApply: false
+description: "Use when the user asks to create a new skill, rule, command, or guideline, or to significantly rewrite an existing one — even if they don't explicitly say 'new artifact' or 'drafting protocol'. Runs a mandatory Understand → Research → Draft sequence before anything is written."
+source: package
+---
+
+# Artifact Drafting Protocol
+
+When the user asks to build or significantly rewrite a **skill, rule,
+command, or guideline**, the agent does **not** start writing. It runs
+three phases: **Understand → Research → Draft**. Each phase ends with a
+numbered-options prompt (per `user-interaction`).
+
+## When this rule fires
+
+Triggers: *"create a new skill/rule/command/guideline"*, *"build me a
+skill for …"*, *"refactor this skill from scratch"*, and the DE
+equivalents (*"bau mir ein Skill"*, *"neue Regel für …"*).
+
+**Does NOT fire:** typo/frontmatter-only edits, description-only
+rewrites with a specific target phrasing, < 10-line edits, or explicit
+bypass (*"just write it"*, *"skip protocol"*, *"einfach machen"*).
+Fires once per creation task, not once per edit.
+
+## Phase A — Understand
+
+Ask up to **5** clarifying questions (numbered options, each with a
+*"skip / I don't know yet"* escape):
+
+1. **Problem** — what does this solve that no existing artifact solves?
+2. **Trigger surface** — which user phrasings should fire this?
+3. **Should-trigger examples** — 2-3 in the user's words.
+4. **Near-miss cases** — 2-3 phrasings that must **not** fire.
+5. **Artifact type** — skill, rule, command, or guideline? Offer a
+   3-line primer if unsure.
+
+If the user skips Q1 or Q5, stop and surface the ambiguity — don't guess.
+
+## Phase B — Research
+
+Scan `.agent-src.uncompressed/` for overlap. Report the top 3-5
+most-similar artifacts and ask (numbered options):
+
+- Extend an existing one?
+- Create a new one — gap is real?
+- Show overlap first?
+- Promote via `learning-to-rule-or-skill` instead?
+
+Carry the summary into the commit message (*"Reviewed before drafting:
+X, Y"*).
+
+## Phase C — Draft
+
+Propose **2-3 description variants** — Conservative / Pushy
+(per `skill-quality`) / Concrete (embedded trigger example). User picks
+or merges. Only then draft the body. Surface every structural choice
+(size class, section order) as numbered options if in doubt.
+
+Enforce size live: *"Body is at 420/500 lines. Split?"* (budgets per
+`size-enforcement`). New skills also get an `evals/triggers.json` stub
+(5 should-trigger + 5 should-not-trigger). See `skill-writing` § 1c.
+
+## Golden rules
+
+- Every phase ends with a numbered-options prompt. No silent progression.
+- Zero autopilot — agent proposes, human decides.
+- At most two propose → reject cycles; then stop.
+- Commit only on approval.
+- Bypass is legitimate — *"just write it"* drops the protocol immediately.
+
+Extends (cross-link, don't restate): `ask-when-uncertain`,
+`improve-before-implement`, `user-interaction`, `skill-quality`.

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

@@ -0,0 +1,52 @@
+---
+type: "always"
+description: "Ask when uncertain — don't guess, assume, or improvise"
+alwaysApply: true
+source: package
+---
+
+# Ask When Uncertain
+
+**When in doubt, ask the user.** Do not guess, assume, or improvise.
+Asking one question too many is always better than a wrong assumption.
+
+## When to ask
+
+- Requirement is ambiguous or could be interpreted multiple ways
+- Not 100% sure which approach is correct
+- About to touch code you haven't fully understood
+- Choosing between multiple valid approaches
+- A fix "seems to work" but you can't explain why
+
+## 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:
+
+| 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?" |
+
+**Escape hatch:** If surrounding context (ticket, open file, prior conversation)
+makes the answer unambiguous, proceed — but state the assumption explicitly.
+
+## How to ask
+
+Be specific. Present numbered options (per `user-interaction`). Keep it short.
+
+- Simple (binary, small): multiple at once, numbered
+- Complex (needs thinking): one at a time, wait for answer
+- Handoff (model switch): ask LAST
+
+## Creating new agent artifacts
+
+For skill/rule/command/guideline creation or major rewrite, follow
+[`artifact-drafting-protocol`](artifact-drafting-protocol.md) — structured
+Understand → Research → Draft. Don't improvise questions.

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

@@ -0,0 +1,38 @@
+---
+type: "auto"
+description: "Editing or creating files inside .augment/ directory — skills, rules, commands, templates, contexts must be project-agnostic"
+source: package
+---
+
+# Package Portability
+
+Everything shipped with `event4u/agent-config` MUST be **project-agnostic**:
+
+- `.augment/` (skills, rules, commands, guidelines, templates, contexts)
+- Package root `AGENTS.md`
+- Package `.github/copilot-instructions.md`
+
+All three are either installed into consumer projects (`.augment/` via
+`install.sh`) or read by AI tools working on the package itself. Leaking
+consumer-specific content pollutes downstream or misleads agents.
+
+## Rules
+
+- NEVER reference a specific consumer project, repo, domain, or tech
+  stack. The package repo itself (`event4u/agent-config`) MAY appear
+  in its own root `AGENTS.md` / `copilot-instructions.md` — meta about
+  the package, not a leak.
+- NEVER hardcode consumer-project paths, class names, or conventions.
+- Write content so it works as a reusable package across any project.
+- Project-specific behavior belongs in the **consumer's**
+  `.agent-settings.yml`, `AGENTS.md`, or `agents/` — never here.
+- If a skill/rule needs project-specific input: read from
+  `.agent-settings.yml` or accept as parameter.
+- Always ask when editing package files: "Would this still make sense
+  in a completely different project?"
+
+## Enforcement
+
+`scripts/check_portability.py` scans `.augment/`, `.agent-src.uncompressed/`,
+and the package root `AGENTS.md` + `.github/copilot-instructions.md` for
+forbidden identifiers. Part of `task ci` — must pass before any PR.

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

@@ -0,0 +1,128 @@
+---
+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
+---
+
+# 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.
+
+Never edit any generated layer directly:
+
+- `.agent-src/` — compressed output shipped in the package
+- `.augment/` — local projection (gitignored in package; installer output in consumers)
+- `.claude/`, `.cursor/`, `.clinerules/`, `.windsurfrules` — tool projections
+
+## The Iron Rule
+
+```
+NEVER create or edit files in .agent-src/ or .augment/ directly — not even "just a small fix".
+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.
+
+Direct edits to `.agent-src/` break compression hashes, cause CI failures, and create drift.
+
+**Compression ONLY via `/compress` command.** Handles hashing, sync, and quality checks.
+
+## Workflow
+
+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 (`task sync-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 `task sync-mark-done -- {path}`
+
+For new non-.md files (`.php`, configs): `task 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 `task generate-tools` — creates Claude symlink automatically
+
+**Never** create `.claude/skills/{name}/SKILL.md` manually for commands — always use the symlink workflow.
+
+## Pre-review consistency checkpoints
+
+Before asking for review or creating a PR, verify derived outputs are not stale:
+
+1. Run `task sync-changed` — check if `.agent-src.uncompressed/` has changes not yet compressed
+2. If stale files exist: run `/compress` before pushing
+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
+
+| 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 `task sync` |
+| Create new command | Create in `.agent-src.uncompressed/commands/`, sync, `task generate-tools` |
+| Delete a file | Delete from `.agent-src.uncompressed/` and `.agent-src/` |
+| Check what needs compression | `task sync-changed` |
+| Mark file as compressed | `task sync-mark-done -- {path}` |
+| Verify everything is in sync | `task sync-check` |

package/.agent-src/rules/capture-learnings.md

@@ -0,0 +1,89 @@
+---
+type: "auto"
+description: "After completing a task where a repeated mistake or successful pattern appeared — capture as rule or skill"
+alwaysApply: false
+source: package
+---
+
+# Capture Learnings
+
+When a repeated mistake, successful pattern, or new constraint appears,
+evaluate whether to capture as **rule** or **skill**.
+
+## Promotion Gate
+
+A learning may be promoted to rule/skill ONLY if ALL gates pass:
+
+| Gate | Question | Must be YES |
+|---|---|---|
+| Repetition | Occurred at least twice OR clearly generalizable? | ✅ |
+| Impact | Improves correctness, reliability, or consistency? | ✅ |
+| Failure pattern | Prevents a real, observed failure? | ✅ |
+| Non-duplication | No existing rule/skill/guideline covers this? | ✅ |
+| Scope fit | Fits rule (constraint), skill (workflow), or guideline (convention)? | ✅ |
+| Minimal | Update existing preferred over creation? | Checked |
+
+**Reject immediately if:**
+- Occurred only once and is not clearly generalizable
+- Similar guidance already exists (update instead)
+- Baseline model knowledge or standard tool usage
+- Vague frustration without concrete failure pattern
+
+## Triggers
+
+- Mistake that happened 2+ times
+- Pattern that improved outcome and should be reused
+- Missing constraint that caused issues
+- **User frustration or complaint** — extract the underlying failure pattern, don't ignore or defend
+- **New skill/rule/guideline created** — evaluate if it should be contributed upstream (→ `upstream-proposal` rule)
+- **Significant improvement to existing skill/rule** — consider upstream contribution
+
+## Do NOT capture
+
+- One-off problems
+- Vague frustrations without concrete consequence
+- Content already covered by existing guidance
+
+## Rule vs Skill
+
+- **Rule** → always-apply constraint ("never X", "always Y")
+- **Skill** → repeatable workflow with steps ("when X, do 1-5")
+- **Update** → existing guidance covers topic → extend, don't duplicate
+
+## How
+
+- Smallest effective change
+- Update existing over creating duplicates
+- Full workflow: `learning-to-rule-or-skill` skill
+
+## Where learnings are written
+
+Captured learnings live in the **consumer project's** `agents/learnings/`
+directory, one file per learning:
+
+```
+agents/learnings/<YYYY-MM-DD>-<kebab-slug>.md
+```
+
+Minimum fields (markdown with a small YAML frontmatter):
+
+```yaml
+---
+slug: <same as filename>
+captured: <ISO date>
+occurrences: <integer, ≥2 or note "one-off, clearly generalizable">
+type_hint: rule | skill | guideline | update
+scope_hint: project | package
+---
+```
+
+Body: 1-paragraph **pattern** (not anecdote) + 1 concrete example.
+
+A learning file is the input to `learning-to-rule-or-skill`, which
+produces a proposal draft under `agents/proposals/`. The proposal is
+then gated by `scripts/check_proposal.py`; see
+[`self-improvement-pipeline`](../guidelines/agent-infra/self-improvement-pipeline.md).
+
+The `agents/learnings/` and `agents/proposals/` directories are
+consumer-owned — the package ships templates and schemas, never the
+data.

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

@@ -0,0 +1,94 @@
+---
+type: "auto"
+alwaysApply: false
+description: "Running CLI commands that produce verbose output — git, tests, linters, docker, build tools, artisan, npm, composer"
+source: package
+---
+
+# Development Efficiency
+
+Loaded when actively working with code, tests, quality tools, CLI, or analysis.
+For communication and response style rules → see the always-loaded `token-efficiency` rule.
+
+## Codebase Navigation
+
+### Use what you already have
+
+- Edited a file → `str-replace-editor` showed 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.
+
+## Pattern: Redirect, Summarize, Target
+
+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).
+
+## Exceptions
+
+- **Small output** (< 30 lines): Read directly, no redirect needed.
+- **Debugging**: OK to read more context around the specific error.
+- **User asks** for full output: Show it.