@event4u/agent-config 1.20.0 → 1.21.0

package/.agent-src/skills/token-optimizer/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: token-optimizer
+description: "Use BEFORE any verbose CLI run, large file read, doc conversion, or near-context handoff — single decision tree keyed by intent that cites the canonical token-saving asset. Consult before the action."
+source: package
+execution:
+  type: assisted
+  handler: shell
+  allowed_tools: []
+---
+
+# Token Optimizer — decision tree + catalog
+
+## Iron Law
+
+```
+CONSULT THIS SKILL BEFORE THE ACTION, NOT AFTER.
+THE TREE NAMES THE CANONICAL ASSET — DO NOT RESTATE OR DUPLICATE IT.
+```
+
+## When to use
+
+Proactively, BEFORE you:
+
+- Run a verbose CLI command (tests, linters, build, git log, large `grep`)
+- Read or paste a large document, log, or tool dump
+- Repeat the same tool call across many files / records
+- Approach the context-window limit and need to hand off
+- Make a cost-aware decision (which model, which budget, when to stop)
+
+Reactively when output already burned tokens — record the lesson, do
+not re-explore. Cite the leaf, move on.
+
+## Procedure
+
+1. **Classify intent** — match the situation to one branch of the tree below.
+2. **Cite the leaf** — name the canonical asset (rule, skill, or upstream link).
+3. **Apply** — execute the cited asset's contract; do NOT inline its content.
+4. **Verify** — output respects the cited Iron Law (redirect, wrap, batch, etc.).
+
+### Decision tree
+
+```
+INTENT
+├── Verbose CLI output incoming
+│     → cite [cli-output-handling](../../rules/cli-output-handling.md)
+│       (Iron Law: redirect / tail / grep / wrap)
+│     → cite [rtk-output-filtering](../rtk-output-filtering/SKILL.md)
+│       (rtk wrapper, 60-90% savings on tests/linters/git)
+│
+├── Large document or paste (PDF, DOCX, HTML, transcript)
+│     → cite markitdown (upstream: https://github.com/microsoft/markitdown)
+│       Convert FIRST, then read the markdown — never paste raw binary.
+│
+├── Repeated tool-call across N targets
+│     → cite [token-efficiency](../../rules/token-efficiency.md)
+│       (batch, parallelize, prune; one tool call > many)
+│
+├── Near context limit, work not finished
+│     → cite [agent-handoff](../../../.claude/skills/agent-handoff/SKILL.md)
+│       (structured handoff envelope; resume in fresh chat)
+│
+└── Cost-aware decision (model pick, budget, stop-criterion)
+      → cite /cost:report (when shipped) — until then, fall back to
+        [token-efficiency](../../rules/token-efficiency.md) and
+        [direct-answers § Brevity by Default](../../rules/direct-answers.md)
+```
+
+## Catalog
+
+| Asset | Path | Trigger keywords | What it does |
+|---|---|---|---|
+| `cli-output-handling` | `.agent-src.uncompressed/rules/cli-output-handling.md` | `verbose`, `tail`, `grep`, `CLI` | Wrap-tail-grep contract for any verbose command |
+| `rtk-output-filtering` | `.agent-src.uncompressed/skills/rtk-output-filtering/SKILL.md` | `rtk`, `verbose`, `filter`, `wrap` | Project-local rtk filters; wrapper command |
+| `token-efficiency` | `.agent-src.uncompressed/rules/token-efficiency.md` | `redirect`, `verbose`, `concise`, `tool` | Batch + parallelize tool calls; brevity floor |
+| `agent-handoff` | `.claude/skills/agent-handoff/SKILL.md` | `handoff`, `fresh`, `chat`, `context` | Context envelope for fresh-chat continuation |
+| `direct-answers` | `.agent-src.uncompressed/rules/direct-answers.md` | `brevity`, `flattery`, `severity`, `tiered` | Iron-Law brevity floor (kernel) |
+| `markitdown` | upstream: github.com/microsoft/markitdown | `PDF`, `DOCX`, `HTML`, `convert` | Document → markdown converter (authoritative-link only) |
+| `/cost:report` | TBD — `road-to-ruflo-adoption.md § P1.2` | `cost`, `model spend`, `budget` | Per-session cost telemetry (planned) |
+
+## Output format
+
+1. Name the cited asset by its leaf id (e.g. `cli-output-handling`, `rtk-output-filtering`).
+2. State the Iron Law in one line; do NOT inline the asset's body.
+3. If multiple branches match, cite all relevant leaves (no merge, no rewrite).
+4. End with the action you take next, citing the asset that authorizes it.
+
+## Gotcha
+
+- Catalog rows live and die with their target asset. If you edit a
+  cited asset's trigger keywords or scope, update the matching row in
+  this skill in the same commit (enforced by
+  [`token-optimizer-maintenance`](../../rules/token-optimizer-maintenance.md)
+  rule + `scripts/check_token_optimizer_freshness.py` CI gate).
+- Tree must stay scannable (≤ 50 lines incl. labels). Catalog rows
+  carry the long form.
+- Authoritative-link assets (`rtk` upstream, `markitdown` upstream,
+  pricing constants) are never copied — always linked.
+
+## Do NOT
+
+- Do NOT inline content from a cited asset. If the leaf is "rtk does X",
+  the agent reads `rtk-output-filtering`. Duplication = drift = stale.
+- Do NOT replace any rule. The rules carry the Iron Laws; this skill
+  carries the lookup index.
+- Do NOT define new policies — every leaf must cite an existing rule,
+  skill, or upstream asset.
+- Do NOT consult this skill AFTER tokens were already burned — record
+  the lesson and move on.
+
+<!-- TELEMETRY: consulted=[uncomment + ISO timestamp on each consult] context=[CLI|doc|repeat|handoff|cost] -->

package/.agent-src/skills/universal-project-analysis/SKILL.md

@@ -71,7 +71,7 @@ Goal: understand structure, identify major components, detect investigation path
 ### Investigation mode
 
 Use when there is a concrete issue inside a large or unclear system.
-Goal: isolate the affected area, route into root-cause analysis, verify likely causes with evidence.
+Goal: isolate the affected area, route into root-cause analysis, verify likely → with evidence.
 
 ### Optimization mode
 

package/.agent-src/templates/AGENTS.md

@@ -113,7 +113,7 @@ Regenerate: `task generate-tools` · Clean: `task clean-tools`
 |---|---|
 | `.env` | Main environment |
 | `.env.local` | Local overrides |
-| `.env.testing` | Testing environment |
+| `.env.testing` | Testing env |
 
 ---
 

package/.agent-src/templates/agent-settings.md

@@ -14,7 +14,7 @@ Keep the format regular — 2-space indent, no tabs, no lists, one nesting
 level only. The installer's YAML handler is a restricted stdlib parser, not
 a full YAML engine. Ask the agent to normalize after manual edits — it
 follows the merge rules in
-[`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+[`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
 
 ### Migration from the legacy `.agent-settings` (key=value)
 
@@ -36,7 +36,7 @@ This block defines the personal and project-level settings that
 `scripts/install.py` (via `config/agent-settings.template.yml`)
 writes to `.agent-settings.yml` on first install. Subsequent edits are
 made by the user directly or by the agent on request, following the
-[section-aware merge rules](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
+[section-aware merge rules](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules).
 
 ```yaml
 # Agent Settings
@@ -45,14 +45,19 @@ made by the user directly or by the agent on request, following the
 
 # --- Cost profile ---
 #
-# Controls which agent surfaces are active. See `docs/customization.md` for
-# the authoritative description.
+# Master switch that controls which rule tiers load each session.
+# See `docs/customization.md` for the authoritative description and
+# `docs/contracts/rule-router.md` for the kernel + router architecture.
 #
-# minimal  = rules, skills, and commands only (zero extra surface, default)
-# balanced = + runtime dispatcher for skills that declare a shell command
-# full     = + tool adapters (GitHub / Jira, read-only, opt-in)
-# custom   = ignore profile — every matrix value must be set explicitly
-cost_profile: minimal
+# minimal  = kernel only (always-loaded Iron-Law floor, ≤ 26k chars).
+#            No router, no auto-rules. Lowest token footprint.
+# balanced = kernel + router + tier-1 auto-rules (default — current behaviour
+#            superset; matches what existing consumer projects expect).
+# full     = kernel + tier-1 + tier-2 (everything). Highest fidelity,
+#            highest token cost. Pick this when working on agent-config
+#            itself or when you need every behavioural rule active.
+# custom   = ignore profile — every matrix value must be set explicitly.
+cost_profile: balanced
 
 # --- Personal preferences ---
 personal:
@@ -294,8 +299,8 @@ commands:
 # rules, commands, guidelines, personas) the agent consulted and
 # applied. Local only, append-only JSONL, never reaches a consumer
 # repo (gitignored). Maintainer-targeted feature; consumers leave it
-# off. See `docs/contracts/artifact-engagement-flow.md` (once Phase 3
-# of road-to-artifact-engagement-telemetry lands).
+# off. See `.augment/contexts/contracts/artifact-engagement-flow.md`
+# (once Phase 3 of road-to-artifact-engagement-telemetry lands).
 telemetry:
   artifact_engagement:
     # Master switch. `false` (default) produces zero file IO and zero
@@ -323,7 +328,7 @@ telemetry:
 
 Personal and project-level settings (initial file written by
 `scripts/install.py`, edits follow the merge rules in
-[`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)).
+[`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)).
 **Key paths use dot-notation** to denote nesting: `personal.user_name`
 lives under `personal:` in YAML.
 
@@ -353,16 +358,16 @@ lives under `personal:` in YAML.
 | `hooks.halt_surface_audit` | `true`, `false` | `true` | Defense-in-depth check that every halt surfaced by the dispatcher carries the expected shape. Cheap. |
 | `hooks.state_shape_validation` | `true`, `false` | `true` | Re-run the state schema validator on `AFTER_LOAD` and `BEFORE_SAVE`. Cheap, catches drift. |
 | `hooks.directive_set_guard` | `true`, `false` | `true` | Verify the dispatcher-resolved directive set matches the input envelope intent. Cheap, catches routing drift. |
-| `hooks.chat_history.enabled` | `true`, `false` | `true` | Register chat-history hooks (`append` on `after_step`, `halt_append` on `on_halt`). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. Schema v4: every entry self-identifies via 16-char session fingerprint, no ownership/sidecar layer. |
+| `hooks.chat_history.enabled` | `true`, `false` | `true` | Register the chat-history hooks (`append` on `after_step`, `halt_append` on `on_halt`). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. Schema v4: every entry self-identifies via a 16-char session fingerprint, no ownership/sidecar layer. |
 | `hooks.chat_history.script` | path | `scripts/chat_history.py` | Override path to the chat-history CLI. Set only when the script lives outside the standard location. |
 | `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
 | `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap execute` runs the project's quality pipeline. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. `verify-before-complete` still requires fresh output before any "roadmap complete" claim. |
 | `subagents.implementer_model` | model alias or empty | _(empty)_ | Model for implementer subagents. Empty = same tier as session model. See [subagent-configuration](../contexts/subagent-configuration.md). |
 | `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
 | `subagents.max_parallel` | integer | `3` | Maximum parallel subagent invocations. `1` serializes. |
-| `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. See [`role-contracts`](../../docs/guidelines/agent-infra/role-contracts.md). |
+| `roles.default_role` | `""`, `developer`, `reviewer`, `tester`, `po`, `incident`, `planner` | _(empty)_ | Role the agent defaults to at the start of a session. See [`role-contracts`](../docs/guidelines/agent-infra/role-contracts.md). |
 | `roles.active_role` | same as `default_role` | _(empty)_ | Role currently active; set by `/mode <name>`, cleared by `/mode none`. Enables the `role-mode-adherence` rule. |
-| `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast. Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../../docs/guidelines/agent-infra/layered-settings.md). |
+| `personas.override` | list of persona ids | `[]` | Developer-local override of the team default lens cast. Empty = inherit `personas.default` from `.agent-project-settings.yml`. See [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md). |
 | `personas.ignore` | list of persona ids | `[]` | Persona ids dropped from the default cast locally. Ignored personas stay invokable via `--personas=<id>`. |
 | `onboarding.onboarded` | `true`, `false` | `false` | Whether `/onboard` has run on this project. The `onboarding-gate` rule prompts for `/onboard` when this is `false`. Missing entirely = legacy project, treated as onboarded. |
 | `commands.suggestion.enabled` | `true`, `false` | `true` | Master switch for the command-suggestion layer. `false` = the layer is silent; explicit `/commands` still work. See `rules/command-suggestion-policy.md`. |
@@ -427,7 +432,7 @@ they ship with a live consumer in code and get documented here, not before.
 ## Sync rules
 
 When new settings are added to this template, the
-[section-aware merge rules](../../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
+[section-aware merge rules](../docs/guidelines/agent-infra/layered-settings.md#section-aware-merge-rules)
 govern the update:
 
 1. Missing keys are added with their **default value** from this template,

package/.agent-src/templates/contexts/tenant-boundaries.md

@@ -16,10 +16,10 @@
 - [ ] **Single-tenant** — one database per deployment. No cross-tenant
       leakage is possible at the infra layer. Delete this file if true
       and the app will never shard.
-- [ ] **Multi-tenant, shared database** — one table with a tenant key
+- [ ] **Multi-tenant, shared DB** — one table with a tenant key
       column (e.g., `tenant_id`, `workspace_id`).
 - [ ] **Multi-tenant, schema per tenant** — one DB, one schema each.
-- [ ] **Multi-tenant, database per tenant** — each tenant has its own
+- [ ] **Multi-tenant, DB per tenant** — each tenant has its own
       connection.
 
 ## Tenant identifier

package/.agent-src/templates/contexts.md

@@ -24,7 +24,7 @@ agents (and developers) quickly orient themselves when working in that area.
 |---|---|---|
 | **Module** | Document a module's structure and purpose | `client-software.md` |
 | **Domain** | Document a business domain across modules | `import-pipeline.md` |
-| **Service** | Document a complex service and its dependencies | `customer-service.md` |
+| **Service** | Document a complex service and its deps | `customer-service.md` |
 | **Integration** | Document an external API/system integration | `probaus-api.md` |
 | **Infrastructure** | Document infrastructure or DevOps concerns | `queue-system.md` |
 

package/.agent-src/templates/copilot-instructions.md

@@ -86,6 +86,27 @@ This repository contains {{project_description_oneline}}.
 - Do NOT review or suggest changes to unmodified code in the same file.
 - Do NOT nitpick style issues that linters/formatters auto-fix.
 
+## ✅ Known False Positives — Do NOT Flag
+
+The repo ships agent-config rules and skills under `.augment/`,
+`.agent-src/`, and `.agent-src.uncompressed/`. These trees use a
+deliberate path convention; the following patterns are **correct by
+design** — do not flag them as broken:
+
+- **Relative cross-references inside markdown rules / skills** like
+  `[x](../docs/guidelines/foo.md)` or `[y](../contexts/bar.md)`. The
+  base resolves from the file's delivered location (e.g.
+  `.augment/rules/<rule>.md`) — these paths are valid via the
+  `.augment/` tree, even when the file is symlinked into
+  `.claude/rules/`, `.cursor/rules/`, or `.clinerules/`.
+- **`path_prefix:` triggers containing `.agent-src.uncompressed/`**
+  in YAML frontmatter. This is a literal match pattern for the
+  host's router, **not** a file reference — keeping the verbatim
+  source path is required for the rule to fire on the right edits.
+- **Symlinked rule files** under `.claude/rules/`, `.cursor/rules/`,
+  `.clinerules/`. Targets resolve into `.augment/rules/`; missing-file
+  reports here are renderer artifacts, not real bugs.
+
 ## ✅ Code Review Comment Behavior
 
 - **Never create duplicate comments** — one comment per concern per location.

package/.agent-src/templates/copilot-review-instructions.md

@@ -0,0 +1,76 @@
+# Copilot Code Review — Repository-Specific Suppressions
+
+> Read by GitHub Copilot Code Review (PR bot) when reviewing this repo.
+> Companion to `.github/copilot-instructions.md`. **This file is the
+> path-resolution suppression floor** — it carries the rules Copilot
+> needs to *not* flag, sharply scoped to the agent-config layout.
+
+## Why this file exists
+
+The repo ships agent-config rules, skills, commands, and contexts under
+`.augment/`, `.agent-src/`, and (during authoring) `.agent-src.uncompressed/`.
+Cross-references inside those trees are valid via the **delivered**
+`.augment/` layout — not via raw git checkout. Copilot's static checker
+walks the git tree, so it sees broken paths where there are none.
+
+This is **intentional, not a bug**. The installer (`scripts/install.sh`)
+projects `.agent-src/` → `.augment/` and creates the symlinks that make
+the paths resolve at agent runtime.
+
+## ✅ Known False Positives — Do NOT Flag
+
+### Relative cross-references inside markdown rules / skills / commands
+
+```markdown
+[link](../docs/guidelines/foo.md)
+[link](../contexts/bar.md)
+[link](../docs/guidelines/baz.md)
+```
+
+These resolve from the file's delivered location (e.g.
+`.augment/rules/<rule>.md`). Even when the file is symlinked into
+`.claude/rules/`, `.cursor/rules/`, or `.clinerules/`, the relative
+form is correct by construction.
+
+### `path_prefix:` triggers containing `.agent-src.uncompressed/`
+
+```yaml
+triggers:
+  - path_prefix: ".agent-src.uncompressed/rules/"
+```
+
+This is a **literal match string** for the host's router — *not* a file
+reference. Source-of-truth meta-rules (`augment-source-of-truth`,
+`augment-portability`, `skill-quality`, `docs-sync`,
+`rule-type-governance`) legitimately match against the authoring tree.
+
+### Symlinked rule / skill / command files
+
+Targets resolve into `.augment/rules/`, `.augment/skills/`,
+`.augment/commands/` via installer-managed symlinks. Missing-file
+reports under `.claude/`, `.cursor/`, `.clinerules/` are renderer
+artifacts, not real bugs.
+
+### Body-link forms `../docs/guidelines/...`
+
+Single-up form is the post-rewrite shape produced by
+`scripts/compress.py`. The compressed `.agent-src/rules/` tree is one
+level deeper than the source `.agent-src.uncompressed/rules/`, so the
+rewriter collapses `../../docs/...` to `../docs/...`. Both forms are
+expected — one in source, one in compressed output.
+
+## ✅ What TO flag
+
+- Code defects, security issues, broken tests, type errors — normal
+  review.
+- New `.agent-src.uncompressed/` substrings introduced into
+  `.agent-src/rules/` body content (the `check-compressed-paths` task
+  already gates this — flag it as a regression if it slips through).
+- Rule frontmatter with `load_context:` entries that don't follow the
+  logical-name convention (`contexts/<area>/<file>.md`).
+
+## Pointer
+
+The full architecture is in `docs/architecture.md` § "Path resolution
+and Copilot integration". The compressed-path validator is
+`scripts/check_compressed_paths.py`, wired into `task ci`.

package/.agent-src/templates/features.md

@@ -22,7 +22,7 @@ Templates for feature plan files stored in `agents/features/` or `app/Modules/{M
 | 💡 | Idea | Rough concept, not yet validated |
 | 🔍 | Exploring | Being researched and brainstormed |
 | 📋 | Planned | Structured plan complete, ready for roadmap |
-| 🗺️ | Roadmapped | Roadmap(s) generated, ready for implementation |
+| 🗺️ | Roadmapped | Roadmap(s) generated, ready for impl |
 | 🔄 | In Progress | Implementation started |
 | ✅ | Complete | Feature shipped |
 | ❌ | Rejected | Decided not to build |

package/.agent-src/templates/rule.md

@@ -0,0 +1,127 @@
+# Rule Template
+
+> Template for creating new rules in `.agent-src.uncompressed/rules/{rule-name}.md`.
+> Rules ship to `.agent-src/rules/` (compressed) and `.augment/rules/` (projected).
+> Schema: `scripts/schemas/rule.schema.json`.
+
+## Instructions
+
+1. Pick a kebab-case `{rule-name}` matching the file stem.
+2. Copy the template below into `.agent-src.uncompressed/rules/{rule-name}.md`.
+3. Replace placeholders, drop sections that don't apply.
+4. Run `task lint-skills` and `python3 scripts/lint_load_context.py`.
+5. Compress: `bash scripts/compress.sh --changed` then follow the agent flow.
+
+## Path conventions — load-bearing
+
+Two different fields, two different rules. Mixing them up will either
+break linting or produce paths that resolve to nothing in the
+consumer's `.augment/`.
+
+### `load_context:` / `load_context_eager:` — logical names
+
+Use **logical names** rooted at the source — never the
+`.agent-src.uncompressed/` prefix. The compress-time rewriter
+(`scripts/compress.py::_rewrite_paths`) resolves logical names to
+deployment-correct relative paths; the schema regex
+(`scripts/schemas/rule.schema.json`) and `scripts/lint_load_context.py`
+both reject the legacy prefix.
+
+| Write this (logical) | Forbidden (legacy) |
+|---|---|
+| `contexts/execution/verification-mechanics.md` | `.agent-src.uncompressed/contexts/execution/verification-mechanics.md` |
+| `contexts/authority/commit-mechanics.md` | `.agent-src.uncompressed/contexts/authority/commit-mechanics.md` |
+| `agents/contexts/local.md` (project-local) | `.agent-src.uncompressed/contexts/...` for project-only material |
+
+### `triggers[].path_prefix:` — literal match pattern, not a file path
+
+`path_prefix:` is a **literal match pattern** the host evaluates against
+the file the agent is editing — it is **not** a file reference and is
+**not rewritten**. Rules that fire when the agent edits source-of-truth
+files legitimately keep the `.agent-src.uncompressed/` prefix (see
+`skill-quality`, `docs-sync`, `rule-type-governance`,
+`augment-portability`). Rules that fire on consumer-project paths use
+`agents/`, `lang/`, `.augment/`, etc.
+
+| Use case | Example `path_prefix:` |
+|---|---|
+| Fires when editing source-of-truth artifacts | `.agent-src.uncompressed/skills/` |
+| Fires when editing consumer project files | `agents/`, `lang/`, `app/`, `src/` |
+| Fires when editing the projected layer | `.augment/` |
+
+### Body links — `../../docs/...` is fine in source
+
+Source files keep verbatim `../../docs/guidelines/...` and
+`../../docs/contracts/...` links so they work in any markdown viewer.
+The rewriter rewrites them to depth-aware single-up form at compress
+time and is idempotent. Do not pre-rewrite in source.
+
+### Why "logical, depth-aware, idempotent"
+
+A rule at `rules/{name}.md` resolves `contexts/{area}/{file}.md` to
+`../contexts/{area}/{file}.md` in the compressed output; a nested
+file at `commands/{cluster}/{sub}.md` resolves to
+`../../contexts/{area}/{file}.md`. Re-running the rewriter does not
+double-prefix. The full decision history lives in the archived
+path-fixes roadmap under `agents/roadmaps/archive/`.
+
+## Template
+
+````markdown
+---
+type: "always"
+tier: "kernel"
+description: "{One-line trigger sentence — what fires this rule}"
+source: package
+load_context:
+  - contexts/{area}/{file}.md
+triggers:
+  - path_prefix: "{project-relative path or .augment/...}"
+  - keyword: "{trigger-keyword}"
+routes_to:
+  - "skill:{target-skill}"
+---
+
+# {Rule Title}
+
+**Iron Law.** {The single non-negotiable behavior the rule enforces.}
+
+## When this fires
+
+{1–3 bullets on the trigger surface — what the agent is doing when this rule applies.}
+
+## What to do
+
+{Numbered procedure or short directive list. Reference skills / guidelines
+for full detail; rules are pointers, not playbooks.}
+
+## What NOT to do
+
+- {Anti-pattern 1}
+- {Anti-pattern 2}
+
+## See also
+
+- [`{related-rule}`](./{related-rule}.md)
+- [`{guideline-ref}`](docs/guidelines/{group}/{name}.md) — full pattern catalog
+````
+
+## Field reference
+
+| Field | Required | Notes |
+|---|---|---|
+| `type` | yes | `always` or `auto`. Always-rules load every turn; auto-rules require trigger match. |
+| `tier` | yes | `kernel` (Iron Law floor), `tier-1` (default), `tier-2` (full profile only). Legacy values still accepted. |
+| `description` | yes | One sentence, ≤ 500 chars. Trigger-clarity wins over poetry. |
+| `source` | yes | `package` (this repo) or `project` (consumer override). |
+| `load_context` | no | Lazy context list — logical names only. Budget enforced by `lint_load_context.py`. |
+| `load_context_eager` | no | Eager context list — counts against per-rule char budget. |
+| `triggers` | no | Required on non-kernel rules per `rule-router.md`. |
+| `routes_to` | no | `skill:`, `guideline:`, `command:`, `contract:` targets. Forbidden on kernel rules. |
+| `alwaysApply` | no | Cursor/Cline sidecar — by convention `true` for `type: always`. |
+
+## Size budget
+
+- Kernel rules: ≤ 4 000 chars (Iron-Law overrides documented in `docs/contracts/iron-law-overrides.txt`).
+- Non-kernel rules: ≤ 2 500 chars.
+- Enforced by `task lint-rule-budget`.

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Shared agent configuration \u2014 skills for AI coding tools (Claude Code, Augment, Cursor, Cline, Windsurf, Gemini CLI).",
-    "version": "1.20.0"
+    "version": "1.21.0"
   },
   "plugins": [
     {
@@ -157,6 +157,7 @@
         "./.claude/skills/optimize",
         "./.claude/skills/optimize-agents",
         "./.claude/skills/optimize-augmentignore",
+        "./.claude/skills/optimize-prompt",
         "./.claude/skills/optimize-rtk",
         "./.claude/skills/optimize-skills",
         "./.claude/skills/override",
@@ -185,6 +186,7 @@
         "./.claude/skills/project-analyzer",
         "./.claude/skills/project-docs",
         "./.claude/skills/project-health",
+        "./.claude/skills/prompt-optimizer",
         "./.claude/skills/quality-fix",
         "./.claude/skills/quality-tools",
         "./.claude/skills/react-shadcn-ui",
@@ -229,6 +231,7 @@
         "./.claude/skills/tests-execute",
         "./.claude/skills/threat-model",
         "./.claude/skills/threat-modeling",
+        "./.claude/skills/token-optimizer",
         "./.claude/skills/traefik",
         "./.claude/skills/unit-economics-modeling",
         "./.claude/skills/universal-project-analysis",

package/AGENTS.md

@@ -111,7 +111,7 @@ want to measure which skills/rules/commands the agent actually applies set
 `telemetry.artifact_engagement.enabled: true` in `.agent-settings.yml`. The
 log is local-only JSONL (no upload, no cross-project share) and is bound
 by the redaction floor described in
-[`docs/contracts/artifact-engagement-flow.md`](docs/contracts/artifact-engagement-flow.md) (beta).
+[`contexts/contracts/artifact-engagement-flow.md`](.agent-src.uncompressed/contexts/contracts/artifact-engagement-flow.md) (beta).
 The recording rule lives at
 [`.agent-src/rules/artifact-engagement-recording.md`](.agent-src/rules/artifact-engagement-recording.md).
 
@@ -125,7 +125,7 @@ picks every time. Engine: `scripts/command_suggester/`. Rule:
 Locked eligibility table, scoring contract, and hardening list:
 [`docs/contracts/adr-command-suggestion.md`](docs/contracts/adr-command-suggestion.md)
 and
-[`docs/contracts/command-suggestion-flow.md`](docs/contracts/command-suggestion-flow.md) (beta).
+[`contexts/contracts/command-suggestion-flow.md`](.agent-src.uncompressed/contexts/contracts/command-suggestion-flow.md) (beta).
 
 ## Key rules for agents editing this repo
 
@@ -139,19 +139,46 @@ and
 | Keep `.agent-src/` / `agents/` cross-refs in sync on add/rename/delete | [`docs-sync`](.agent-src/rules/docs-sync.md) |
 | Creating a new skill/rule/command/guideline runs Understand → Research → Draft | [`artifact-drafting-protocol`](.agent-src/rules/artifact-drafting-protocol.md) |
 
+## Kernel + Router
+
+The rule set runs on a **Kernel + Router** model (locked 2026-05-06,
+see [`docs/decisions/ADR-rule-kernel-and-router.md`](docs/decisions/ADR-rule-kernel-and-router.md)):
+
+- **Kernel** = 9 always-loaded Iron-Law rules, ≤ 26k chars
+  (`agent-authority`, `ask-when-uncertain`, `commit-policy`,
+  `direct-answers`, `language-and-tone`, `no-cheap-questions`,
+  `non-destructive-by-default`, `scope-control`, `verify-before-complete`).
+  Locked set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-membership.md) (beta).
+- **Router** = frontmatter `tier:` + `triggers:` + `routes_to:` keys
+  on every rule. `scripts/compile_router.py` builds `router.json`
+  deterministically. Contract: [`docs/contracts/rule-router.md`](docs/contracts/rule-router.md) (beta).
+- **Cost profiles** gate which tiers load:
+  `minimal` = kernel only · `balanced` = kernel + tier-1 (default) ·
+  `full` = kernel + tier-1 + tier-2.
+
+Hard caps enforced by `task lint-rule-budget`: kernel-bucket ≤ 26k chars,
+per-rule ≤ 2.5k chars (Iron-Law overrides up to 4.0k via ADR in
+[`docs/decisions/`](docs/decisions/) and
+[`docs/contracts/iron-law-overrides.txt`](docs/contracts/iron-law-overrides.txt)).
+Daily snapshots: `python3 scripts/measure_rule_budget.py --trend-append`
+appends to `agents/.rule-budget-history.jsonl`.
+
 ## Repository layout
 
 ```
 .agent-src.uncompressed/      ← edit here
-  skills/       (134 skills)
-  rules/        (56 rules)
-  commands/     (94 commands)
+  skills/       (136 skills)
+  rules/        (58 rules)
+  commands/     (95 commands)
   personas/     (7 personas)
   templates/    (AGENTS.md, copilot-instructions.md, skill.md, …)
   contexts/
 
 docs/guidelines/            (47 guidelines — reference material, not packaged)
+docs/contracts/             (kernel-membership, rule-router, rule-classification, …)
+docs/decisions/             (ADRs — kernel overrides, scope decisions)
 .agent-src/                 ← compressed output shipped in the package
+.agent-src/router.json      ← compiled router manifest (consumed at runtime)
 .augment/                   ← local projection for Augment Code (gitignored)
 scripts/                    ← install.sh, install.py, compress.py, linters
 tests/                      ← pytest (324 tests) + test_install.sh