@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/skills/jira-integration/SKILL.md

@@ -0,0 +1,187 @@
+---
+model_tier: medium
+name: jira-integration
+description: "Use when the user says \"check Jira\", \"create ticket\", \"update issue\", or needs JQL queries, ticket transitions, or branch-to-ticket linking."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# Jira Skill
+
+## When to use
+
+Use this skill when:
+- Reading a Jira ticket for context (bug reports, feature requests)
+- Creating new Jira issues from discovered bugs or planned work
+- Transitioning ticket status (e.g., "In Progress" → "In Review")
+- Writing JQL queries to find related issues
+- Linking branches or PRs to Jira tickets
+
+
+Do NOT use when:
+- GitHub Issues (use `github-api` tool directly)
+- Linear or other issue trackers
+
+## Procedure: Work with Jira
+
+1. **Identify action** — Search, read, create, update, or transition a ticket?
+2. **Use the correct endpoint** — See API table below.
+3. **Execute** — Make the API call with required fields.
+4. **Verify** — Confirm the response contains expected data or the ticket was updated.
+
+| Tool | Purpose |
+|---|---|
+| `jira-integration` (GET `/search/jql`) | Search issues with JQL |
+| `jira-integration` (GET `/issue/{key}`) | Read a specific ticket |
+| `jira-integration` (POST `/issue`) | Create a new ticket |
+| `jira-integration` (PUT `/issue/{key}`) | Update a ticket |
+| `jira-integration` (GET `/issue/{key}/transitions`) | Get available status transitions |
+| `jira-integration` (POST `/issue/{key}/transitions`) | Transition ticket status |
+| `jira-integration` (POST `/issue/{key}/comment`) | Add a comment |
+| `jira-integration` (GET `/project`) | List projects |
+| `jira-integration` (GET `/field`) | List available fields (check before writing JQL) |
+
+## Branch-to-ticket detection
+
+Extract ticket IDs from branch names automatically:
+
+```
+feat/DEV-1234/user-notifications  →  DEV-1234
+fix/DEV-5678/null-pointer         →  DEV-5678
+hotfix/DEV-999/critical-fix       →  DEV-999
+```
+
+Pattern: `[A-Z]+-[0-9]+` anywhere in the branch name.
+
+Use `git branch --show-current` to detect, then fetch the ticket:
+
+```
+jira GET /issue/DEV-1234
+```
+
+## JQL patterns
+
+### Common queries
+
+```jql
+# My open tickets
+assignee = currentUser() AND status != Done ORDER BY priority DESC
+
+# Tickets in current sprint
+project = DEV AND sprint in openSprints() AND assignee = currentUser()
+
+# Recently updated bugs
+project = DEV AND type = Bug AND updated >= -7d ORDER BY updated DESC
+
+# Tickets by component
+project = DEV AND component = "Import" AND status != Done
+```
+
+### Tips
+
+- Always check available fields first: `GET /field`
+- Use `currentUser()` for the authenticated user
+- Use `sprint in openSprints()` for current sprint
+- JQL is case-insensitive for field names but case-sensitive for values
+
+## Creating tickets
+
+### Required fields
+
+Always check issue types first: `GET /issue/createmeta/{project}/issuetypes`
+
+Minimum fields for creation:
+- `project` — project key (e.g., `DEV`)
+- `issuetype` — issue type (Bug, Task, Story, etc.)
+- `summary` — short title
+
+### Description format (ADF)
+
+Jira uses Atlassian Document Format for descriptions:
+
+```json
+{
+  "version": 1,
+  "type": "doc",
+  "content": [
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "text": "Description text here." }
+      ]
+    }
+  ]
+}
+```
+
+### Attribution
+
+Always add attribution when creating issues or comments:
+
+```
+Co-authored by Augment Code
+```
+
+With link to `https://www.augmentcode.com/?utm_source=atlassian&utm_medium=jira_issue&utm_campaign=jira`
+
+## Status transitions
+
+Before transitioning, always get available transitions first:
+
+```
+GET /issue/DEV-1234/transitions
+```
+
+Then transition with the correct ID:
+
+```json
+POST /issue/DEV-1234/transitions
+{ "transition": { "id": "31" } }
+```
+
+**Important:** Never transition without explicit user permission (see `rules/no-commit.md` — same principle applies to ticket status changes).
+
+## Linking to PRs
+
+When creating PRs, include the Jira ticket in:
+- **Branch name:** `feat/DEV-1234/description`
+- **PR title:** `feat(DEV-1234): description`
+- **PR description:** Link to the ticket
+
+## Related
+
+- **Skill:** `bug-analyzer` — uses Jira as input source for bug investigation
+- **Skill:** `feature-planning` — uses Jira for feature context
+- **Command:** `/bug-investigate` — auto-detects Jira tickets from branch
+- **Command:** `/feature-plan` — auto-detects Jira tickets from branch
+- **Rule:** `no-commit.md` — never change ticket status without permission
+
+
+## Output format
+
+1. Jira ticket data presented in structured format
+2. Ticket key, summary, status, and relevant fields
+
+## Gotcha
+
+- Jira field names are case-sensitive in JQL — `status` works, `Status` doesn't.
+- Don't create duplicate tickets — always search first with JQL before creating.
+- The model tends to forget that Jira description uses ADF (Atlassian Document Format), not Markdown.
+- `accountId` is required for assignee — display name alone doesn't work in the API.
+
+## Do NOT
+
+- Do NOT change ticket status without explicit user permission.
+- Do NOT create tickets without checking for duplicates.
+
+## Auto-trigger keywords
+
+- Jira
+- ticket
+- issue
+- JQL
+- workflow transition
+- sprint

package/dist/agent-src/skills/lint-skills/SKILL.md

@@ -0,0 +1,95 @@
+---
+model_tier: medium
+name: lint-skills
+description: "Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata."
+domain: process
+execution:
+  type: assisted
+  handler: shell
+  timeout_seconds: 120
+  allowed_tools: []
+  command:
+    - python3
+    - src/scripts/skill_linter.py
+    - "--all"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# lint-skills
+
+## When to use
+
+Use this skill when:
+
+- Validating the shape of every skill and rule in `.agent-src.uncondensed/`
+- Verifying execution metadata (`execution.type`, `handler`, `command`) is well-formed
+- Checking locally before opening a PR that CI's skill-lint job will pass
+- Investigating a reported linter failure on a specific skill or rule
+
+Do NOT use when:
+
+- Linting only one file — call `python3 src/scripts/skill_linter.py <path>` directly
+- Checking cross-references between files — use `check-refs` instead
+- Checking condensation freshness — use `bash scripts/condense.sh --check` instead
+
+## Procedure
+
+### 1. Inspect the environment
+
+Confirm `python3` is available and the working directory is the agent-config
+repository root — the linter expects to find `.agent-src.uncondensed/skills/`
+and related directories relative to `cwd`.
+
+### 2. Dispatch via the runtime layer
+
+Invoke the skill through the runtime dispatcher so the `execution:` block in
+this skill's frontmatter governs the call:
+
+```bash
+python3 scripts/runtime_dispatcher.py run --skill lint-skills
+```
+
+The dispatcher resolves the request, the shell handler runs
+`python3 src/scripts/skill_linter.py --all`, captures stdout/stderr, and returns
+a typed `ExecutionResult`.
+
+### 3. Verify the result
+
+Check the returned `ExecutionResult`:
+
+- `status: success` and `exit_code: 0` → all skills and rules are clean
+- `exit_code: 1` → warnings only — review `stdout` for the listed warnings
+- `exit_code: 2` → errors present — fix the flagged files before continuing
+- `status: timeout` → the linter exceeded `timeout_seconds` — investigate
+- `status: error` → the interpreter could not launch — check that `python3`
+  is on `PATH` and the repository root is the current working directory
+
+## Output format
+
+1. One-line summary: `success | failure | timeout | error`, exit code,
+   duration in milliseconds
+2. Count of skills and rules the linter inspected, if known
+3. List of files with errors (first 10), each with code and message
+4. Next action: fix errors, re-run, or surface the raw `stdout` for review
+
+## Gotchas
+
+- The command uses `--all`, which walks the full tree — expect several seconds
+  of runtime on a warm repo; bump `timeout_seconds` if the repo has grown
+- Running outside the agent-config repo root will make the linter report zero
+  skills, which looks like a pass but is actually a no-op
+- Warnings (`exit_code: 1`) do not fail CI by default; do not dismiss them as
+  "green" when the task is to get to zero warnings
+
+## Do NOT
+
+- Do NOT invoke `src/scripts/skill_linter.py` directly when the intent is to test
+  the runtime path — use the dispatcher so the handler and result object are
+  exercised
+- Do NOT raise `timeout_seconds` to hide a genuinely slow linter pass —
+  investigate the slowdown first
+- Do NOT add shell redirection or pipes to `command` — the handler runs
+  `subprocess.run` with `shell=False`; only argv form is supported

package/dist/agent-src/skills/livewire/SKILL.md

@@ -0,0 +1,139 @@
+---
+model_tier: medium
+name: livewire
+description: "Use when the project's frontend stack is Livewire — dispatched by `directives/ui/{apply,review,polish}.py`. Covers reactive state, events, lifecycle hooks, and component/view separation."
+domain: engineering
+workspaces:
+  - engineering
+packs:
+  - laravel
+trust:
+  level: professional
+install:
+  default: false
+  removable: true
+---
+
+# livewire
+
+> **Grounded stack guidance:** pull idiomatic Blade/UI Do/Don't + docs URLs
+> via `ground.py search --manifest <skills-root>/design-intelligence/data/manifest.json
+> --stack laravel "<topic>"` (UI-scoped corpus). See
+> [`design-intelligence`](../design-intelligence/SKILL.md).
+
+## Positioning — dispatched, not standalone
+
+`livewire` is the **apply-step executor** for the Livewire stack. It is
+invoked by [`directives/ui/apply.py`](../../templates/scripts/work_engine/directives/ui/apply.py)
+once the design brief is locked, and revisited by `review.py` /
+`polish.py` during the design-review loop. It does **not** own the
+flow, does **not** drive the audit, and does **not** lock the design.
+
+| Concern | Owner |
+|---|---|
+| Audit + token inventory (mandatory pre-step) | [`existing-ui-audit`](../existing-ui-audit/SKILL.md) |
+| Design brief (layout / states / microcopy) | [`directives/ui/design.py`](../../templates/scripts/work_engine/directives/ui/design.py) |
+| Universal design heuristics | [`fe-design`](../fe-design/SKILL.md) |
+| Static Blade partials inside the view | [`blade-ui`](../blade-ui/SKILL.md) |
+| Flux primitives inside the view | [`flux`](../flux/SKILL.md) |
+
+## When to use
+
+Cite this skill when:
+
+- `state.stack.frontend == "livewire"` and `directives/ui/apply.py` dispatches to this skill
+- Editing or creating Livewire components — reactive state, forms, tables, real-time updates
+
+Do NOT use when:
+
+- Static Blade views with no interactivity (use `blade-ui` skill)
+- Flux UI primitives (use `flux` skill — `livewire` composes Flux internally)
+- Driving the full UI flow yourself — that is the `directives/ui/` orchestrator
+
+## Procedure: Create a Livewire component
+
+### Step 0: Inspect
+
+1. Detect Livewire version — `composer.json` for `livewire/livewire`.
+   - v3: `#[Layout]`, `#[Title]`, property attributes.
+   - v2: `$layout`, `$listeners`, method-based hooks.
+2. Check existing components — `app/Livewire/` or `app/Http/Livewire/`.
+3. Check views — `resources/views/livewire/`.
+
+### Step 1: Create component class
+
+1. `declare(strict_types=1)`, `final` class.
+2. Typed public properties for state — keep minimal.
+3. `#[Locked]` for tamper-proof properties.
+4. `#[Url]` for URL-synced properties.
+
+### Step 2: Implement actions
+
+1. Public methods callable from frontend.
+2. Validate before processing: `$this->validate()`.
+3. `$this->dispatch()` for cross-component communication (v3).
+
+### Step 3: Create view
+
+1. One root element (`<div>`).
+2. `wire:key` on dynamic lists.
+3. `wire:loading` for user feedback.
+4. `wire:model.live` for real-time updates (v3 default is deferred).
+
+### Step 4: Test
+
+- `Livewire::test(ComponentClass::class)`
+- `->set()`, `->call()`, `->assertSee()`, `->assertHasNoErrors()`
+
+## Conventions
+
+→ See guideline `php/livewire.md` for state management, forms, performance, Alpine.js, templates.
+
+## Output format
+
+1. Livewire component class with typed properties and actions
+2. Blade view with wire: bindings and Flux components
+
+### Review pass — a11y findings + preview envelope
+
+When this skill is dispatched by `directives/ui/review.py` (test slot)
+or `directives/ui/polish.py` (verify slot) — i.e. a review/polish run,
+not the initial apply — it also emits:
+
+- `state.ui_review.a11y` — `{violations: [{rule, selector, severity}, ...],
+  severity_floor?, accepted_violations?}`. Use the same `(rule, selector)`
+  shape as `state.ui_audit.a11y_baseline` so the engine's de-dup matches
+  pre-existing entries on replay. Omit the envelope on apply passes; the
+  engine's `_apply_a11y_gate` only fires when a baseline is present.
+- `state.ui_review.preview` — `{render_ok: bool, screenshot_path?,
+  dom_dump_path?, error?, skipped?}`. `render_ok: false` with `error`
+  populated triggers the `preview_render_failed` halt; `render_ok: true`
+  with `screenshot_path` threads the screenshot into the delivery
+  report's `artifacts` list. Browser tooling (Playwright/Cypress/…) is
+  a consumer-project dependency — this package does not ship one.
+
+Polish dispatch: when the dispatcher skips `review` because a previous
+review pass already returned `SUCCESS`, this skill MUST itself
+synthesise the updated `state.ui_review.findings` (including any
+remaining `a11y_violation` entries) so the engine's gate sees the
+current state on the next polish round.
+
+## Gotcha
+
+- Public properties serialize between requests — don't put large objects in state.
+- `wire:model` is deferred by default in v3 — use `wire:model.live` for real-time.
+- `$this->redirect()` + `$this->dispatch()` in same method — only redirect executes.
+
+## Do NOT
+
+- Do NOT put heavy computation in `render()` — it runs on every update.
+- Do NOT nest Livewire components deeply — keep the tree shallow.
+- Do NOT expose sensitive data as public properties.
+
+## Auto-trigger keywords
+
+- Livewire
+- reactive component
+- wire:model
+- lifecycle
+- real-time UI

package/dist/agent-src/skills/mcp-builder/SKILL.md

@@ -0,0 +1,113 @@
+---
+model_tier: medium
+name: mcp-builder
+description: "Use when building an MCP server in Python (FastMCP) or Node/TypeScript (MCP SDK) — agent-centric tool design, input schemas, error handling, and the 10-question evaluation harness."
+domain: process
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# mcp-builder
+
+Author MCP servers that LLMs can drive end-to-end. The quality bar is *can the agent finish the workflow*, not *does the endpoint return 200*. This skill is the **server-author** counterpart to the existing [`mcp`](../mcp/SKILL.md) consumer skill.
+
+## When to use
+
+- Wrapping an external API or service as MCP tools for an LLM client.
+- Adding tools to an existing MCP server (Python FastMCP or TypeScript SDK).
+- Reviewing an MCP server before shipping — Phase 4 evaluation gate below.
+
+Do NOT use when:
+
+- You only need to *call* an MCP server — route to [`mcp`](../mcp/SKILL.md).
+- The integration belongs in the host process — write a regular service, not an MCP server.
+- The "server" wraps one endpoint with no workflow — a CLI wrapper is enough.
+
+## Procedure: Four phases, one tool at a time
+
+### Phase 1 — Research & plan
+
+1. **Agent-centric design**. Tools encode *workflows*, not raw endpoints. Consolidate (`schedule_event` checks availability **and** creates the event). Default to human-readable names over IDs. Errors are educational, not just diagnostic ("retry with `filter='active_only'` to reduce results").
+2. **Load the protocol**. Fetch `https://modelcontextprotocol.io/llms-full.txt` once into context — the canonical spec.
+3. **Load the SDK README** for the chosen language:
+   - Python: `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
+   - TypeScript: `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
+4. **Read the target service's API docs in full** — auth, rate limits, pagination, error codes, schemas. Skipping this produces incomplete mocks (see [`testing-anti-patterns`](../testing-anti-patterns/SKILL.md) § Anti-Pattern 4).
+5. **Write the plan**: tool list with priority, shared utilities (request helper, pagination, formatter), input/output schemas, error strategy, response-detail levels (concise vs detailed), character limits (default 25 000 tokens).
+
+### Phase 2 — Implement
+
+1. **Project layout**. Python: single `.py` or modular package; Pydantic v2 with `model_config`. TypeScript: standard `package.json` + `tsconfig.json` strict mode; Zod schemas with `.strict()`.
+2. **Shared utilities first**. API request helper with retry/timeout, error formatter, JSON-vs-Markdown response builder, pagination cursor handling, auth/token cache.
+3. **Per tool**:
+   - Input schema (Pydantic / Zod) with constraints, descriptions, and *examples*.
+   - One-line summary + detailed docstring covering purpose, parameters, return shape, when-to-use, when-NOT-to-use, error handling.
+   - Tool annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`.
+   - Async/await for all I/O. Honor pagination. Truncate to the character limit and signal truncation in the response.
+
+### Phase 3 — Review & test
+
+1. **Code-quality pass**: DRY across tools, shared helpers extracted, consistent response shapes, all external calls have error handling, full type coverage.
+2. **Build & syntax**:
+   - Python: `python -m py_compile server.py`.
+   - TypeScript: `npm run build`; verify `dist/index.js`.
+3. **Run the server safely**. MCP servers block on stdio. Either run inside `tmux` and drive from the harness, or wrap with `timeout 5s python server.py` for a smoke check. Do NOT block your own session by running it in-process.
+
+### Phase 4 — Evaluations (10-question harness)
+
+Each evaluation is a question the agent must answer using only the new tools.
+
+Requirements per question — **independent**, **read-only**, **complex** (multiple tool calls), **realistic**, **verifiable** (string-comparable answer), **stable** (answer does not drift over time).
+
+```xml
+<evaluation>
+  <qa_pair>
+    <question>...</question>
+    <answer>...</answer>
+  </qa_pair>
+  <!-- 9 more -->
+</evaluation>
+```
+
+Process: enumerate the tools, explore READ-ONLY data, draft 10 questions, **solve each yourself first** to confirm the answer is reachable and stable.
+
+## Output format
+
+1. The server source plus the 10-question evaluation XML.
+2. A README with: install, env vars, transport mode (stdio / sse / http), example tool call.
+3. A line in `agents/settings/contexts/skills-provenance.yml` if the server was forked from an upstream, or a note that it was authored from scratch.
+
+## Gotcha
+
+- "Wrap every endpoint" is the failure mode — agents cannot orchestrate 60 thin tools as well as 12 workflow tools.
+- Returning the full upstream payload blows the agent's context. Default to a *concise* shape with an opt-in *detailed* mode.
+- Pydantic / Zod descriptions are the *only* documentation the LLM sees at runtime — write them like usage docs, not comments.
+- A server that hangs your session usually means stdio transport ran in the main process — move it under `tmux` or use a `timeout`.
+- Inflated token claims are not credible without an evaluation harness — Phase 4 is the validation gate, not optional.
+
+## Do NOT
+
+- Do NOT mirror REST routes 1:1.
+- Do NOT use `any` (TypeScript) or untyped `dict` (Python) in tool I/O.
+- Do NOT skip the 10-question evaluation — Phase 4 IS the quality bar.
+- Do NOT run the MCP server in your main process during testing — it will block.
+- Do NOT log tokens, API keys, or full request bodies — sanitize before logging.
+
+## Auto-trigger keywords
+
+- mcp server
+- model context protocol
+- fastmcp
+- mcp builder
+- agent-centric tools
+
+## Provenance
+
+- Upstream protocol: https://modelcontextprotocol.io
+- Upstream SDKs: https://github.com/modelcontextprotocol/python-sdk · https://github.com/modelcontextprotocol/typescript-sdk
+- Adopted from: an external reference (MIT, © 2025 an external reference) — external `./reference/*.md` file links replaced with inline guidance + upstream URLs.
+- Cross-linked: [`mcp`](../mcp/SKILL.md), [`testing-anti-patterns`](../testing-anti-patterns/SKILL.md), [`api-design`](../api-design/SKILL.md).
+- Provenance registry: `agents/settings/contexts/skills-provenance.yml` (entry: `mcp-builder`).
+- Iron-Law floor: `verify-before-complete`, `tool-safety`, `skill-quality`.

package/dist/agent-src/skills/md-language-check/SKILL.md

@@ -0,0 +1,130 @@
+---
+model_tier: lite
+name: md-language-check
+description: "Use BEFORE saving any .md under .augment/, dist/agent-src*/, or agents/ — scans umlauts, German function words, and German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone."
+domain: process
+execution:
+  type: assisted
+  handler: shell
+  timeout_seconds: 30
+  allowed_tools: []
+  command:
+    - python3
+    - scripts/check_md_language.py
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+# md-language-check
+
+## When to use
+
+Fire this skill **before** writing or saving any `.md` file under:
+
+- `.agent-src.uncondensed/` (source of truth — skills, rules, commands, guidelines, templates, contexts)
+- `dist/agent-src/` (condensed projection)
+- `.augment/` (local agent projection)
+- `agents/` (project-specific roadmaps, contexts, sessions)
+
+Per [`language-and-tone`](../../rules/language-and-tone.md) § "`.md` files
+are ALWAYS English" and § Detection heuristic, every `.md` file in those
+trees must be English. Bilingual content lives only in labeled
+`DE: … · EN: …` anchor blocks.
+
+Do NOT use when:
+
+- Editing project content outside the trees listed above (READMEs of
+  consumer projects, application docs that follow a different policy)
+- Reviewing chat history files (`agents/runtime/.agent-chat-history` is JSONL, not `.md`)
+- Inspecting non-`.md` files — the checker rejects them with a warning
+
+## Procedure
+
+### 1. Identify the file(s) about to be saved
+
+Collect the absolute or repo-relative path of every `.md` file the
+agent is about to create or modify in this turn. Multiple files in
+one turn → pass them all to a single invocation.
+
+### 2. Run the checker
+
+```bash
+python3 scripts/check_md_language.py <path> [<path> …] [--format json]
+```
+
+Exit codes:
+
+- `0` → no German content detected, save proceeds
+- `1` → violations found, save is **blocked** until they are resolved
+  or explicitly suppressed
+- `3` → internal error (unreadable file, decode failure)
+
+### 3. Resolve findings
+
+For every violation:
+
+| Kind | Likely cause | Fix |
+|---|---|---|
+| `umlaut` | German prose leaked into body text | Translate the sentence to English |
+| `de_word` | German function word in unquoted prose | Translate; or move into a `DE: … · EN: …` block if intentional bilingual anchor |
+
+If the line is meta-documentation that **must** quote German tokens
+(e.g. the detection heuristic in `language-and-tone.md` itself),
+append `<!-- md-language-check: ignore -->` at the end of that single
+line — never as a wholesale silencer.
+
+### 4. Re-run and confirm
+
+After every fix, re-run the checker on the same paths. Save only
+proceeds on exit `0`.
+
+## Allowed escape hatches
+
+- **Labeled anchor block** — lines starting with `DE:` / `- DE:` /
+  `* DE:` (and the same for `EN:`) are skipped automatically. Use this
+  for intent-based opt-in / opt-out anchors.
+- **Fenced code blocks** — `\`\`\` … \`\`\`` content is exempt, so
+  shell snippets, JSON fixtures, and quoted user input in code
+  blocks pass through untouched.
+- **Inline code** — backtick spans are stripped before scanning;
+  identifiers like `für_test` inside backticks do not flag.
+- **Per-line marker** — append `<!-- md-language-check: ignore -->`
+  to a line that genuinely needs to quote a German token in body
+  prose (rare; reserved for the rules that document the heuristic).
+
+## Output format
+
+1. One-line summary: `clean` or `N violation(s) found`
+2. Per violation: `file:line — kind \`match\`` plus the offending line
+3. Next action: translate, move into a `DE:`/`EN:` block, add the
+   per-line ignore marker, or revert the change
+
+## Gotchas
+
+- The checker scans `.md` files only; passing a non-`.md` path emits a
+  warning and skips it
+- The detection word list is intentionally short and conservative —
+  a clean run is **necessary but not sufficient**; the agent still
+  owns the final language judgement
+- Frontmatter (`--- … ---` at file head) is exempt; descriptions and
+  YAML keys can use international characters where the schema allows
+
+## Do NOT
+
+- Do NOT silence the checker by deleting trigger words from
+  `scripts/check_md_language.py`; extend the allow-list (anchor
+  blocks, ignore marker) instead
+- Do NOT add the ignore marker to body prose just to push a save
+  through; the marker is for meta-documentation that quotes tokens,
+  not a generic mute
+- Do NOT skip the gate "because the file is small" — `language-and-tone`
+  § Detection heuristic applies to every save under the four trees
+
+## Cloud Behavior
+
+On cloud surfaces (Claude.ai Web, Skills API) the checker script is
+not shipped, so this skill is **inert** — the agent applies the
+heuristic from [`language-and-tone`](../../rules/language-and-tone.md)
+manually before emitting the file.