@event4u/agent-config 1.16.0 → 1.17.0

package/.agent-src/commands/{tests-execute.md → tests/execute.md}

@@ -1,5 +1,7 @@
 ---
-name: tests-execute
+name: tests:execute
+cluster: tests
+sub: execute
 skills: [pest-testing]
 description: Run PHP tests inside the Docker container
 disable-model-invocation: true
@@ -9,8 +11,7 @@ suggestion:
   trigger_context: "code changes pending verification"
 ---
 
-# tests-execute
-
+# /tests execute
 ## Instructions
 
 ### 1. Detect the test runner

package/.agent-src/commands/tests.md

@@ -0,0 +1,44 @@
+---
+name: tests
+description: Tests orchestrator — routes to create, execute
+cluster: tests
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "write tests for these changes, run the test suite"
+  trigger_context: "user wants to author or run tests for the current branch"
+---
+
+# /tests
+
+Top-level orchestrator for the `/tests` family. Replaces 2 standalone
+commands with a single entry point + sub-command dispatch.
+
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/tests create` | `commands/tests/create.md` | Write meaningful tests for the changes in the current branch |
+| `/tests execute` | `commands/tests/execute.md` | Run PHP tests inside the Docker container |
+
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
+## Dispatch
+
+1. Parse the user's argument: `/tests <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Instructions` section
+   verbatim with the remaining args.
+4. If the sub-command is unknown or missing, print the table above and ask:
+
+   > 1. create — author tests for current-branch changes
+   > 2. execute — run the test suite in Docker
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
+  authorizes it.
+- **Do NOT chain sub-commands.** One `/tests <sub>` per turn.
+- If the user invokes `/tests` with no argument, **show the menu** — do
+  not guess which sub-command they meant.

package/.agent-src/contexts/communication/rules-auto/artifact-engagement-recording-mechanics.md

@@ -0,0 +1,72 @@
+# Artifact Engagement Recording — mechanics
+
+CLI invocation, privacy contract, failure-mode handling, and "what
+this rule does NOT do" catalog for the
+[`artifact-engagement-recording`](../../../rules/artifact-engagement-recording.md)
+rule. The activation gate, cadence table, and consulted-vs-applied
+definitions live in the rule; this file is the lookup material for
+the actual `telemetry:record` call and the privacy floor.
+
+## 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 in the rule.
+- `--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.

package/.agent-src/contexts/communication/rules-auto/augment-portability-mechanics.md

@@ -0,0 +1,79 @@
+# Augment portability — mechanics
+
+`task`-to-script translation table, the `./agent-config` consumer-CLI
+table, and the rationale behind both for the
+[`augment-portability`](../../../rules/augment-portability.md) rule.
+The portability obligation, the agnostic-content rules, and the
+enforcement script reference live in the rule; this file is the
+lookup material when an agent is about to write or edit an artefact
+that mentions a runtime invocation.
+
+## Why no `task` commands inside artefacts
+
+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`.
+
+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.
+
+## Translation table — `task` → script
+
+| ❌ 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) |
+
+## 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/`.
+
+| ❌ 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` |
+
+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.

package/.agent-src/contexts/communication/rules-auto/augment-source-of-truth-mechanics.md

@@ -0,0 +1,98 @@
+# Source of Truth — mechanics
+
+Workflow, compression rules, commands workflow, symlink mapping, and
+quick reference for the
+[`augment-source-of-truth`](../../../rules/augment-source-of-truth.md)
+rule. The Iron Rule and the "never edit generated layers" obligation
+live in the rule; this file is the lookup material the rule pulls
+when authoring or pre-review verification fires.
+
+## 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
+   (`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.
+
+## 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 `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` |

package/.agent-src/contexts/communication/rules-auto/cli-output-handling-mechanics.md

@@ -0,0 +1,87 @@
+# CLI output handling — mechanics
+
+Codebase navigation tips, the redirect-summarize-target fallback
+pattern, the general rules around exit codes / summary lines, and the
+CLI-over-MCP catalog for the
+[`cli-output-handling`](../../../rules/cli-output-handling.md) rule.
+The Iron Law, the detection rule (`rtk_installed`), the verbose-command
+table, and the exceptions list live in the rule; this file is the
+lookup material when the agent has to fall back from `rtk`.
+
+## Codebase Navigation
+
+### 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).

package/.agent-src/contexts/communication/rules-auto/command-suggestion-policy-mechanics.md

@@ -0,0 +1,62 @@
+# Command Suggestion — mechanics
+
+Output format, anti-noise specifics, and "what this rule does NOT do"
+catalog for the
+[`command-suggestion-policy`](../../../rules/command-suggestion-policy.md)
+rule. The Iron Law (suggest, never invoke), the six-condition fire
+gate, and the subordination list live in the rule; this file is the
+lookup material for the rendered output and engine behavior.
+
+## What to emit — exact format
+
+Render exactly one numbered-options block conforming to
+`user-interaction`:
+
+```
+> 💡 Your request matches a command. Pick one or run the prompt as-is:
+>
+> 1. /implement-ticket — drive ticket end-to-end through refine → plan → implement → test
+> 2. /refine-ticket — tighten the AC and risks on a ticket before planning
+> 3. Just run the prompt as-is, no command
+
+**Recommendation: 1 — /implement-ticket** — the request matches its trigger description (`setze ticket abc-123 um`). Pick the last option to skip the command and run the prompt as written.
+```
+
+Rules — non-negotiable:
+
+- The "run as-is" option is **always present**, **always last**, never removed.
+- At most `commands.suggestion.max_options` command suggestions
+  precede the as-is option (default 4 → 5 total).
+- Exactly **one** `Recommendation:` line follows the block, naming
+  the highest-scoring command — or no recommendation when the top
+  two scores are within 0.05 of each other (single-source-of-truth
+  Iron Law from `user-interaction`).
+- Free-text replies count as the as-is option unless they
+  unambiguously name one of the listed commands.
+
+## Anti-noise — silent when uncertain
+
+The engine's `rank.py` already drops:
+
+- Matches below the `confidence_floor` (default 0.6, per-command
+  override in frontmatter).
+- Single matches scoring `< floor + 0.1` with no structural bonus
+  (high uncertainty isn't worth interrupting for).
+- Short prompts (< 6 words) hitting > 2 commands with no structural
+  bonus (ticket key, file path) — too vague to disambiguate.
+- Pure-continuation messages (`ok`, `weiter`, `mach weiter`, `go on`,
+  …) — no new intent signal, no structural bonus → silent.
+- Suggestions that fired for the same `(command, evidence)` pair
+  within the cooldown window (default 10m, per-command override).
+
+If the engine returns an empty list → emit nothing. The user's
+prompt runs exactly as it would without this rule.
+
+## What this rule does NOT do
+
+- Invoke any command. Picking option N is what triggers `slash-command-routing-policy`.
+- Stack with other questions. One numbered-options block per turn.
+- Re-trigger on its own output. Command names emitted in the
+  suggestion block are excluded from the next-turn matcher input.
+- Override `enabled: false`, blocklist entries, or per-conversation opt-out.
+- Suggest commands that are not in the locked eligibility table.

package/.agent-src/contexts/communication/rules-auto/docs-sync-mechanics.md

@@ -0,0 +1,78 @@
+# Docs Sync — mechanics
+
+Update tables, distribution manifests, hook registries, and content
+consistency check details for the
+[`docs-sync`](../../../rules/docs-sync.md) rule. The Iron Rule, the
+mandatory sequence, the two modes (reactive/proactive), the
+settings-template sync, and the "Do NOT" list live in the rule; this
+file is the lookup material when a sync trigger fires.
+
+## What to update — count and category tables
+
+When a file is **added, removed, or renamed**:
+
+| Change | Files to update |
+|---|---|
+| Skill/command/rule count changes | `contexts/augment-infrastructure.md` (count + category table) |
+| New skill category | `contexts/augment-infrastructure.md` + `contexts/skills-and-commands.md` |
+| New workflow chain | `contexts/skills-and-commands.md` (workflow chains section) |
+
+## Cross-reference updates
+
+When a skill is **added or its scope changes**, check and update:
+
+| What | Where to check |
+|---|---|
+| Inline routing hints | "see X skill" or "use X instead" references in other skills |
+| Guideline cross-references | Guidelines that reference the changed skill |
+| Command skill references | Commands that use the changed skill |
+
+## Distribution manifests and hook registries
+
+`.augment/`-internal sync (counts, contexts, cross-refs) is one half. The
+other half is **distribution manifests** that ship the package to consumers
+and **hook registries** that wire engine code into platform lifecycles.
+These are not auto-derived — they drift silently until CI catches them, and
+on cooperative platforms (no pre-commit) they can sit broken in a branch
+for hours.
+
+When a **skill** is added, renamed, or deleted under
+`.agent-src.uncompressed/skills/`:
+
+| Manifest | Required update |
+|---|---|
+| `.claude-plugin/marketplace.json` | Add/remove the `./.claude/skills/<name>` entry in `plugins[0].skills[]`, alphabetical position. Caught by `scripts/lint_marketplace.py` in CI. |
+| `.augment-plugin/marketplace.json` | Skill-name-agnostic — no update needed. Touch only when plugin metadata (description, tags) changes. |
+| `.github/plugin/marketplace.json` | Same as above — metadata-only manifest. |
+
+When a **hook** is added, renamed, or deleted under
+`.agent-src.uncompressed/templates/scripts/work_engine/hooks/builtin/`:
+
+| Registry | Required update |
+|---|---|
+| `templates/scripts/work_engine/hooks/builtin/__init__.py` | New hook class → add the import + `__all__` entry. Single source of truth for engine-side registration. |
+| `templates/consumer-settings/claude-settings.json` | Only when a **new platform event** is wired (e.g. first time a hook listens on `SessionEnd`). Existing hooks reuse the `./agent-config chat-history:hook --platform claude` dispatcher — no per-hook entry needed. |
+| `templates/consumer-settings/augment-cli-hooks.json` | Same logic — new platform event → new `command` block; new hook on existing event → no update. |
+
+Failure mode that motivated this section: a skill on disk without its
+`marketplace.json` entry passes local edits, builds, and tests — only
+CI catches it via `lint_marketplace`. The cooperative path is
+"agent updates the manifest in the same response as the skill"; the
+structural backstop is a pre-commit hook installed by
+`scripts/install-hooks.sh` that runs `lint_marketplace` on every
+commit. Run the installer once per clone; bypass for an unrelated WIP
+commit is `git commit --no-verify`.
+
+## Content consistency check
+
+When a rule, skill, or guideline's **content** is changed (not just
+metadata), search for all other artefacts that cover the same topic
+and verify they are consistent:
+
+```bash
+grep -rl "TOPIC" .augment/rules/ .augment/skills/ .augment/guidelines/ --include="*.md"
+```
+
+If any file contradicts or is missing the updated information →
+update it in the same response. Inconsistent documentation is worse
+than no documentation.

package/.agent-src/contexts/communication/rules-auto/package-ci-checks-mechanics.md

@@ -0,0 +1,85 @@
+# Package CI checks — mechanics
+
+The five required local-CI checks, the quick one-liner, and the
+post-edit workflow rules for the
+[`package-ci-checks`](../../../rules/package-ci-checks.md) rule. The
+Iron Law, the activation trigger, and the "Do NOT" list live in the
+rule; this file is the lookup material when an agent is about to
+push or open a PR in the `agent-config` package repo.
+
+## Required checks (in order)
+
+Run all of these before pushing — they match the GitHub Actions workflows exactly:
+
+### 1. Sync check
+
+```bash
+bash scripts/compress.sh --check          # .agent-src/ matches .agent-src.uncompressed/
+bash scripts/compress.sh --check-hashes   # compression hashes are clean
+```
+
+**Common failure:** Edited uncompressed file but forgot `bash scripts/compress.sh --mark-done {path}`.
+
+### 2. Consistency checks
+
+```bash
+python3 scripts/check_compression.py   # compressed variants are valid
+python3 scripts/check_references.py     # no broken cross-references
+python3 scripts/check_portability.py    # no project-specific references in shared files
+```
+
+**Common failure:** Changed code-blocks in uncompressed but didn't re-compress.
+
+### 3. Linter
+
+```bash
+python3 scripts/skill_linter.py --all   # 0 FAIL required
+```
+
+**Common failure:** New skill missing analysis/verification sections.
+
+### 4. Tests
+
+```bash
+python3 -m pytest tests/ --tb=short     # all tests must pass
+```
+
+**Common failure:** Changed `compress.py` behavior without updating test expectations.
+
+### 5. README
+
+```bash
+python3 scripts/readme_linter.py README.md --root .
+```
+
+## Quick one-liner
+
+Run all checks in sequence — stops on first failure:
+
+```bash
+bash scripts/compress.sh --check && \
+bash scripts/compress.sh --check-hashes && \
+python3 scripts/check_compression.py && \
+python3 scripts/check_references.py && \
+python3 scripts/check_portability.py && \
+python3 scripts/skill_linter.py --all && \
+python3 -m pytest tests/ --tb=short && \
+python3 scripts/readme_linter.py README.md --root .
+```
+
+## After editing skills/rules
+
+When you edit a file in `.agent-src.uncompressed/`:
+
+1. Edit the uncompressed file
+2. Edit the compressed file in `.agent-src/` to match
+3. Run `bash scripts/compress.sh --mark-done {relative-path}` to update the hash
+4. Verify with `bash scripts/compress.sh --check-hashes`
+
+**If you skip step 3, the CI pipeline WILL fail.**
+
+## After editing `scripts/compress.py`
+
+Changes to `compress.py` often break existing tests in `tests/test_compress.py`.
+Always run `python3 -m pytest tests/test_compress.py -v --tb=short` immediately
+after changing `compress.py` — don't wait until the end.