@event4u/agent-config 2.19.0 → 2.20.1

package/.agent-src/skills/subagent-orchestration/SKILL.md

@@ -51,6 +51,39 @@ Each mode has a decision row: when to use, when not, and the expected
 model pairing. Defaults come from
 [`subagent-configuration`](../../contexts/subagent-configuration.md).
 
+### Topology hints — per-mode communication shape
+
+Descriptive, not enforced. Documents the **expected agent-to-agent
+communication topology** so consumers can predict latency, failure
+modes, and where consensus is required. Cited from
+[`external-findings.md § 2`](../../../agents/audit-2026-05-14-north-star/external-findings.md)
+row 7 (Ruflo's `hierarchical, 6–8 agents, raft consensus` anti-drift
+default).
+
+| Mode | Topology | Anti-drift default | Notes |
+|---|---|---|---|
+| do-and-judge | `hierarchical` | 1 implementer · 1 judge · session-orchestrated | Two-node hub-and-spoke; orchestrator owns the loop. |
+| do-and-judge-two-stage | `hierarchical` | 1 implementer · 2 sequential judges | Stages are serialized; spec-judge gates quality-judge. |
+| do-in-steps | `ring` | N steps · 1 judge between each | Step N output → judge → step N+1 input; cycle on revise. |
+| do-in-parallel | `star` | 6–8 implementers · 1 judge · session-hub | Capped by `subagents.max_parallel`; judge runs once on union. |
+| do-competitively | `mesh` | 2–4 implementers · 1 judge | Implementers do not see each other; judge sees all candidates. |
+| judge-with-debate | `hierarchical-mesh` | 2 judges · 1 meta-judge | Judges debate (mesh edge); meta-judge reconciles (hierarchical). |
+| do-in-worktrees | `adaptive` | per-step topology of the underlying mode | Each worktree picks its own shape; chain is hierarchical. |
+
+**Anti-drift default** (Ruflo convention, descriptive only):
+`hierarchical, 6–8 agents, raft consensus`. Consumers free to
+override per orchestration — table is **starting point**, not a
+constraint. Topology is metadata for capacity planning, not
+runtime-enforced.
+
+**Glossary:**
+- `hierarchical` — orchestrator hub; agents reply to hub only.
+- `mesh` — agents see each other's outputs (e.g. competing diffs).
+- `hierarchical-mesh` — peer debate followed by hub reconciliation.
+- `ring` — output of step N feeds input of step N+1 in order.
+- `star` — N agents fan out from single hub; no peer comms.
+- `adaptive` — topology shifts per step; outer chain remains hub.
+
 ### 1. do-and-judge
 
 Implementer produces a diff; judge reviews; loop applies, revises, or

package/.agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.py (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "2.18.0"
+agent_config_version: "2.20.0"
 
 # --- Project identity ---
 project:

package/.agent-src/templates/skill-archive-note.md

@@ -0,0 +1,101 @@
+# Skill Archive Note Template
+
+> Template for `agents/archived-skills/<slug>.md`. Created during
+> `step-2-skill-inventory-rationalization.md`
+> Phase 4 execution. Every skill removed from
+> `.agent-src.uncompressed/skills/` MUST have a matching archive note
+> here — enforced by `scripts/lint_archived_skills.py`.
+
+## Instructions
+
+1. Create the file: `agents/archived-skills/{slug}.md`.
+2. Copy the template body below and fill every required field.
+3. Commit alongside the SKILL.md removal in the same PR (the linter
+   refuses to pass if the pair drifts).
+
+## Required frontmatter
+
+```yaml
+---
+slug: {skill-slug}            # the directory name that was removed
+archived_on: 2026-MM-DD        # UTC date of the removal commit
+last_seen_count: 0             # mentions_30d at archival time (from skill-usage-report.md)
+reason: unused                 # one of: unused, merged, superseded, deprecated
+replacement: none              # successor slug, or literal "none" if reason ∈ {unused, deprecated}
+last_known_callers:            # YAML list — files / commands / rules that cited this slug
+  - "none detected"            # or e.g. ".augment/rules/foo.md", "agents/roadmaps/bar.md"
+---
+```
+
+## Required body
+
+````markdown
+# {skill-slug}
+
+## Why archived
+
+{1–3 sentences. Cite the Phase 2 candidates-table row (overlap pair,
+activation counts, or both) that justified removal. Link the row.}
+
+## What replaces it
+
+{If `replacement: <successor>`: one paragraph on how the successor
+covers the source's triggers, and which trigger phrases it absorbed.
+Link the successor's SKILL.md.}
+
+{If `replacement: none`: one paragraph on why the capability is gone —
+no successor needed because the workflow itself was retired / merged
+into a router decision tree / handled inline by another rule.}
+
+## Last-known callers
+
+{If `last_known_callers:` is non-empty, one bullet per caller with a
+short note on whether the caller was updated, redirected, or left
+referencing the archive note. The lint gate fails if a caller still
+references the removed slug without pointing at this note.}
+
+## References
+
+- Candidates table row: [`skill-rationalization-candidates.md`](../metrics/skill-rationalization-candidates.md#{anchor})
+- Activation baseline: [`skill-usage-report.md`](../metrics/skill-usage-report.md)
+- Overlap pair (if applicable): [`skill-overlap.md`](../metrics/skill-overlap.md)
+````
+
+## Field semantics
+
+- **`slug`** — must match the removed directory name exactly. The
+  linter keys on this.
+- **`archived_on`** — UTC date string `YYYY-MM-DD`. Used for cohort
+  reporting (e.g. "skills archived in the May 2026 rationalization").
+- **`last_seen_count`** — `mentions_30d` value from the activation
+  report at the moment of archival. `0` is the dominant case; non-zero
+  values demand extra justification in *Why archived*.
+- **`reason`** — exactly one of:
+  - `unused` — `mentions_30d == 0` over the soak window.
+  - `merged` — content folded into another skill; trigger phrases
+    transferred.
+  - `superseded` — thin-redirect successor exists (`replaced_by`
+    relationship documented in the successor's frontmatter).
+  - `deprecated` — capability retired; no successor needed.
+- **`replacement`** — successor slug (must exist under
+  `.agent-src.uncompressed/skills/`) or literal `none`. The linter
+  validates the successor's existence.
+- **`last_known_callers`** — references found by
+  `scripts/check_references.py` at archival time. Empty list is valid
+  only when the check truly returned zero hits.
+
+## Lint contract
+
+`scripts/lint_archived_skills.py` enforces:
+
+1. Every file under `agents/archived-skills/*.md` (except the README)
+   has a frontmatter block with the six required fields.
+2. `reason` is one of the four allowed values.
+3. When `reason ∈ {merged, superseded}`, the `replacement` slug exists
+   under `.agent-src.uncompressed/skills/`.
+4. Every slug under `agents/archived-skills/` is *absent* from
+   `.agent-src.uncompressed/skills/` (no zombies).
+5. No SKILL.md present under `.agent-src.uncompressed/skills/`
+   references an archived slug as a router target.
+
+Run via `task lint-archived-skills`. Included in `task ci`.

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": "2.19.0",
+    "version": "2.20.1",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -695,13 +695,69 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
-# Era: 2.15.x — current
+# Era: 2.17.x — current
 
-> Started at `2.15.0` (2026-05-15). Full entries live inline below.
+> Started at `2.17.0` (2026-05-15). Full entries live inline below.
 > The drift test caps this era at 200 lines of entry body; growth past
-> that forces a new era split (`# Era: 2.16.x`, etc.) — see
+> that forces a new era split (`# Era: 2.18.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [2.20.1](https://github.com/event4u-app/agent-config/compare/2.20.0...2.20.1) (2026-05-16)
+
+### Bug Fixes
+
+* **lint:** treat zero active roadmaps as pass in lint-roadmap-complexity ([ff814e2](https://github.com/event4u-app/agent-config/commit/ff814e262a25b9269ae5d1b66495602b5d8f457b))
+* **template:** bump agent_config_version pin to 2.20.0 ([ab3acfc](https://github.com/event4u-app/agent-config/commit/ab3acfc3eebd39e5fb7df919bd5b7a455e2f58ea))
+
+### Chores
+
+* **changelog:** split era 2.16.x → pre-2.17.0 ([67b668e](https://github.com/event4u-app/agent-config/commit/67b668ee2298cc56478a808a716e965482bf199d))
+* **roadmaps:** close and archive all 8 open roadmaps (Total Dominance) ([c13359f](https://github.com/event4u-app/agent-config/commit/c13359f0b676f251a9b6c6b7ed11804fdeb84257))
+
+Tests: 4535 (+0 since 2.20.0)
+
+## [2.20.0](https://github.com/event4u-app/agent-config/compare/2.19.0...2.20.0) (2026-05-16)
+
+### Features
+
+* **product:** step-15 product refinement — profiles + packs + presets + explain CLI ([59e7d6f](https://github.com/event4u-app/agent-config/commit/59e7d6f3ddce025e558da08c1da1b4c8155e68eb))
+* **parity:** step-11 ruflo parity — smoke + ADR + cost + namespace + MCP ([521b4c6](https://github.com/event4u-app/agent-config/commit/521b4c62f5fe266f5c18dfcca2abf4e06d97c217))
+* **caveman:** step-10 default-kill criterion + parity roadmap ([dd7ec3c](https://github.com/event4u-app/agent-config/commit/dd7ec3cae4f8839b28b4d3ff9dbdbb316ec5d035))
+* **bench:** step-4 measurement + benchmark infrastructure ([981d0cd](https://github.com/event4u-app/agent-config/commit/981d0cd1c48e2d23eede29bd86e833cd826ddfd9))
+* **skills:** step-2 skill inventory rationalization ([3fa651d](https://github.com/event4u-app/agent-config/commit/3fa651d2496e4fc483cd7ed452bb39f41dd39365))
+
+### Bug Fixes
+
+* **adr-create:** restore Inspect keyword in step-1 heading ([46c40ad](https://github.com/event4u-app/agent-config/commit/46c40adf4741f1e13d8d275f9363f98047d4b733))
+* **audit_mcp_tools:** drop roadmap link from generated inventory ([d35459e](https://github.com/event4u-app/agent-config/commit/d35459e94d9be473bbb567f7c348be5bff4b5e9d))
+* **audit_mcp_tools:** emit stability frontmatter in generated inventory ([ba7af12](https://github.com/event4u-app/agent-config/commit/ba7af12cf26509f2ea0ddb867303f3b225fea866))
+* **no-cheap-questions:** trim to clear concentration cap ([3516283](https://github.com/event4u-app/agent-config/commit/351628301aa168c31130b62ee306858944ecf9f2))
+* **onboard:** move recommendation off inline (recommended) tag ([6a77a06](https://github.com/event4u-app/agent-config/commit/6a77a06c014d8820662906ca6ab0ee55ac847e05))
+* **refs:** suppress legitimate council-response audit links ([d764329](https://github.com/event4u-app/agent-config/commit/d764329d8718124d150deafcce52bdd206ada740))
+* **contracts:** drop roadmap-file links from stable artefacts ([96ea60f](https://github.com/event4u-app/agent-config/commit/96ea60f8f6e85c6ce04e8042d9d2535938f75d9f))
+* **contracts:** bring beta-review markers into the 90-day window ([4be4a47](https://github.com/event4u-app/agent-config/commit/4be4a47cc30532fa20d1ea7c3311d7eaa154d7e6))
+* **contracts:** add stability frontmatter to 6 new contracts ([8b27577](https://github.com/event4u-app/agent-config/commit/8b27577bc6b4b28c36ccfbea48b4e92e35372fbd))
+* **portability:** replace task cost:* with direct script invocations ([0225f60](https://github.com/event4u-app/agent-config/commit/0225f60d0157edf4b4f74fe8fc1266295d5b90f2))
+* **rules:** restore no-cheap-questions Iron Law block ([e95315f](https://github.com/event4u-app/agent-config/commit/e95315f96323d1ef32328b1c8a630b5aacafee84))
+
+### Documentation
+
+* **readme:** restore three-audience headings, tighten user-types blurb ([fdb03bf](https://github.com/event4u-app/agent-config/commit/fdb03bf314acb1a7a570400c1ba3cadb8098b943))
+* **readme:** restore browse-all-commands canonical line ([d91f6e0](https://github.com/event4u-app/agent-config/commit/d91f6e0d99230792f570b02fab6a1b30a744187c))
+* **readme:** extract profile detail + featured commands to /docs ([e8745f3](https://github.com/event4u-app/agent-config/commit/e8745f33f1da089aefd763cc659be4568177dd07))
+* **roadmap:** regenerate dashboard + cross-roadmap link refresh ([f6b7085](https://github.com/event4u-app/agent-config/commit/f6b7085d3419f1a8b57daf9b949bd55312c17b9b))
+* **roadmap:** step-5 schema rigor + test cleanup ([b043230](https://github.com/event4u-app/agent-config/commit/b043230291222f6d6287d73e0807ea772e227e98))
+
+### Chores
+
+* **changelog:** split era 2.15.x → pre-2.16.0 ([88b81ba](https://github.com/event4u-app/agent-config/commit/88b81bac54ae5f9558a1087c81d453c47d3039bb))
+* **mcp:** regenerate MCP tool inventory ([bce3169](https://github.com/event4u-app/agent-config/commit/bce3169b353c2d240df610e4bf01c91c96d23e0d))
+* **ownership:** regenerate ownership matrix after no-cheap-questions trim ([dbe58a9](https://github.com/event4u-app/agent-config/commit/dbe58a9dfafbca487f11b2501b1f1dabb1053a8d))
+* **template:** bump agent_config_version pin to 2.19.0 ([cfc4c59](https://github.com/event4u-app/agent-config/commit/cfc4c59e288862eccf4e7b9d215adf30e527f5a0))
+* **build:** wire step-2/4/11/15 tooling into Taskfile + gitignore ([0acc9e7](https://github.com/event4u-app/agent-config/commit/0acc9e77515e611eb685c58aeba91f3d5af9423f))
+
+Tests: 4535 (+42 since 2.19.0)
+
 ## [2.19.0](https://github.com/event4u-app/agent-config/compare/2.18.0...2.19.0) (2026-05-16)
 
 ### Features
@@ -839,76 +895,23 @@ Tests: 4476 (+17 since 2.17.0)
 
 Tests: 4459 (+54 since 2.16.0)
 
-## [2.16.0](https://github.com/event4u-app/agent-config/compare/2.15.0...2.16.0) (2026-05-15)
-
-### Features
-
-* **install:** install-mode marker + minimal-init upgrade hint (Step 8 P3) ([e028468](https://github.com/event4u-app/agent-config/commit/e028468ed2b58428b99bea5a2e6c2a25e12fc113))
-* **cli:** doctor --trace-root + --context diagnostic surface (Step 8 P2) ([387a626](https://github.com/event4u-app/agent-config/commit/387a626b7795fc40e6e2442c1dde272dfc98f9d7))
-* **cli:** --root override flag + fail-loud root validation (Step 8 P1) ([0c8356e](https://github.com/event4u-app/agent-config/commit/0c8356e9034ca474827de89db5386a04c61f560c))
-* **wrapper:** export AGENT_CONFIG_PROJECT_ROOT pin so subdir invocations skip the walk ([e866cef](https://github.com/event4u-app/agent-config/commit/e866cef14d40269786fb0a88b69d9aafcfab1c88))
-* **agent-settings:** add resolve_project_root helper for Phase 3 subdir hardening ([95bac18](https://github.com/event4u-app/agent-config/commit/95bac187132d35d476716cd38d8c619bccaca6e5))
-* **install:** add --minimal / --settings-only init mode ([4c02743](https://github.com/event4u-app/agent-config/commit/4c02743cd7df6d89f7b7fa6188d654ca1eec983c))
-* **agent_settings:** extend find_project_root with agents/ + .agent-settings.yml anchors ([60dcd11](https://github.com/event4u-app/agent-config/commit/60dcd11c498f25f92bb01482943bfb95d4efef37))
+# Era: pre-2.17.0 — archived
 
-### Documentation
-
-* **changelog:** Step 8 discovery polish entry under Unreleased ([eecaf6a](https://github.com/event4u-app/agent-config/commit/eecaf6a9a2248a877d71dbd33e7db096f94dab3b))
-* **installation:** root override + monorepo semantics + diagnostics (Step 8) ([de3081f](https://github.com/event4u-app/agent-config/commit/de3081fe828cb43c628d922c50d25177d43f267e))
-* **roadmap:** archive step-7 (all phases complete) + sync dashboard ([8f2953e](https://github.com/event4u-app/agent-config/commit/8f2953ee5c867ada29c9f32cf45bd2380504bc12))
-* **step-7:** add minimal-init flow, anchor migration guide, changelog entry ([9ace019](https://github.com/event4u-app/agent-config/commit/9ace01945967e67e98e8855a940801db09de8d17))
-* **roadmap:** mark Step 7 Phase 3 complete (subdir invocation hardening) ([518f9dc](https://github.com/event4u-app/agent-config/commit/518f9dcaf6d71a34cf1700bceb1487f1e8e33175))
-* **roadmap:** mark Step 7 Phase 2 + test items complete ([1bb9b71](https://github.com/event4u-app/agent-config/commit/1bb9b712d866dd509124f7d8502f52957e972b20))
-* **roadmap:** mark Step 7 Phase 1 complete; refresh progress dashboard ([2ba8d5b](https://github.com/event4u-app/agent-config/commit/2ba8d5be1b94bbab87da4270d833697c895cc9c6))
-
-### Refactoring
-
-* **cli:** route all cmd_*.py entry points through resolve_project_root ([aa7a01a](https://github.com/event4u-app/agent-config/commit/aa7a01a7f27205919193d54339298c0dbd30c43e))
-
-### Tests
-
-* **cli:** coverage for --root override + doctor trace/context (Step 8) ([9b943aa](https://github.com/event4u-app/agent-config/commit/9b943aa9f002750499738fd36f8a203525fb84da))
-* **subdir:** cover resolve_project_root precedence + wrapper-pinned root ([0693714](https://github.com/event4u-app/agent-config/commit/06937145ac8f4e1160ec9279d3832e4f5397bb1e))
-* **install:** cover --minimal payload + nested-install guard ([5623521](https://github.com/event4u-app/agent-config/commit/56235218624792b487a92f444ff8ee114a5651a3))
-* **agent_settings:** cover anchor extension, kill-switch, perf budget ([37a080c](https://github.com/event4u-app/agent-config/commit/37a080c07ee9238fda45bbda1829764a4232f062))
-
-### Chores
-
-* **template:** bump agent_config_version pin to 2.15.0 ([093367d](https://github.com/event4u-app/agent-config/commit/093367d3e417a11a28295f2efa574e8c3fef6524))
-* **sync:** propagate Step 8 agent_settings.py to .agent-src/ projection ([7ce92e5](https://github.com/event4u-app/agent-config/commit/7ce92e514a8edbd970a4118b91d2f651bf730070))
-* **roadmap:** archive Step 8 discovery polish ([1c21982](https://github.com/event4u-app/agent-config/commit/1c219825dc413cfe45aefc3b12c08d2720583880))
-* **changelog:** split era 2.11.x → pre-2.15.0 ([c79363c](https://github.com/event4u-app/agent-config/commit/c79363c05d775ecfa95ab6fff5b3bbe706f797c9))
-
-Tests: 4405 (+53 since 2.15.0)
-
-## [2.15.0](https://github.com/event4u-app/agent-config/compare/2.14.0...2.15.0) (2026-05-15)
-
-### Features
-
-* **agent-user:** add /agents user command cluster (init, show, review, accept, update) ([15d53d8](https://github.com/event4u-app/agent-config/commit/15d53d8d9a2365b044831cd42127e247a70d7e20))
-* **agent-user:** add v1 schema contract for .agent-user.md persona file ([64f4eab](https://github.com/event4u-app/agent-config/commit/64f4eab62ccf6a2606fbca0c56d398372c05a7a0))
-
-### Bug Fixes
-
-* **agent-user:** inline council-reference summary per no-roadmap-references ([ee4d3ce](https://github.com/event4u-app/agent-config/commit/ee4d3cedf9f4429450d21ca5badc2ae5c2ecaaed))
-* **agent-user:** drop roadmap references per no-roadmap-references rule ([c8ade8d](https://github.com/event4u-app/agent-config/commit/c8ade8d7c5b495e0e4295aa0cb801e59076ee0b0))
-* **agent-user:** adjust keep-beta-until to fit 90-day window ([801b365](https://github.com/event4u-app/agent-config/commit/801b365117a2d1efb4505e504bdd730e4cbbc217))
-
-### Documentation
-
-* **persona:** README section + agent-settings legacy-fallback note ([4da7629](https://github.com/event4u-app/agent-config/commit/4da7629f1f0b5a35a64d0a861040ad8639a66ebe))
-* **roadmap:** mark step-3-agent-user-persona phases as in-progress ([f29d3bc](https://github.com/event4u-app/agent-config/commit/f29d3bce2380c0ea9c67e6094540b88d920ed9ff))
-
-### Chores
+> All `2.16.0` entries live in
+> [`docs/archive/CHANGELOG-pre-2.17.0.md`](docs/archive/CHANGELOG-pre-2.17.0.md).
+> The archive is read-only; git tag `2.16.0` remains the canonical
+> source for what shipped. Splitting these out of the main file keeps
+> the active era under the 200-line drift cap enforced by
+> `tests/test_changelog_eras.py`.
 
-* **roadmap:** close out + archive step-3-agent-user-persona ([09c0229](https://github.com/event4u-app/agent-config/commit/09c0229efd67af9cad7b2ca8202f4caa351d028d))
-* **ownership:** regenerate file-ownership-matrix for /agents user ([128890d](https://github.com/event4u-app/agent-config/commit/128890d880584704b4842a398555dd979ae54462))
-* **docs:** bump command count from 109 to 115 ([f8c61b1](https://github.com/event4u-app/agent-config/commit/f8c61b1d0ec48034e0d66e8d32534056ca4aa1f0))
-* **template:** bump agent_config_version pin to 2.14.0 ([fcb885f](https://github.com/event4u-app/agent-config/commit/fcb885fd19bdbca46ef91ec4d5e723cc6c186c6d))
-* **index:** regenerate agents/index.md + docs/catalog.md for /agents user ([56b281d](https://github.com/event4u-app/agent-config/commit/56b281d69960d3e57adbd24b9ec6fd24fc1a5aff))
-* **agent-user:** regenerate compressed sources + claude tool stubs ([f79b6d1](https://github.com/event4u-app/agent-config/commit/f79b6d1cfcf1caccde4a723ad779c65d9ed87198))
+# Era: pre-2.16.0 — archived
 
-Tests: 4352 (+12 since 2.14.0)
+> All `2.15.0` entries live in
+> [`docs/archive/CHANGELOG-pre-2.16.0.md`](docs/archive/CHANGELOG-pre-2.16.0.md).
+> The archive is read-only; git tag `2.15.0` remains the canonical
+> source for what shipped. Splitting these out of the main file keeps
+> the active era under the 200-line drift cap enforced by
+> `tests/test_changelog_eras.py`.
 
 # Era: pre-2.15.0 — archived
 

package/README.md

@@ -4,47 +4,67 @@
 
 Give your AI agents an audit-disciplined execution layer: **210 skills**, **79 governance rules**, **124 commands**, and a replayable state machine that turns any host agent (Claude Code, Augment, Cursor, Copilot, Windsurf) into a reliable team member.
 
-| 👩‍💻 Developers | 🚀 Founders & Operators | ✍️ Creators & Consultants |
-|---|---|---|
-| Implement tickets, fix CI, write tests, run PR reviews — `/implement-ticket`, `/work`, `/commit`, `/fix ci`, `/create-pr` — with stack-aware skills for Laravel · Symfony · Next.js · React · Node. | Pitch decks, runway math, OKR trees, GTM launches, pricing reviews — `runway-cognition`, `unit-economics-modeling`, `fundraising-narrative`, `gtm-launch`, `okr-tree-modeling`. | Editorial calendars, brand voice, ghostwriting, content funnels, discovery interviews — `voice-and-tone-design`, `editorial-calendar`, `ghostwriter`, `content-funnel-design`, `discovery-interview`. |
+### Pick your profile — six entry paths
+
+`/onboard` writes `profile.id` to `.agent-settings.yml`; each anchor
+below is the first-screen the wizard sends you to. One README, six
+entries, no role-detection guesswork.
+
+| Profile (`profile.id`) | Audience | First commands | First skills |
+|---|---|---|---|
+| 👩‍💻 [`developer`](docs/profiles.md#profile-developer) | IC engineer | `/implement-ticket` · `/work` · `/review-changes` · `/fix` · `/commit` | `developer-like-execution` · `verify-completion-evidence` · `minimal-safe-diff` · `systematic-debugging` · `test-driven-development` |
+| ✍️ [`content_creator`](docs/profiles.md#profile-content_creator) | Writers, ghostwriters, marketers | `/work` · `/post-as` · `/ghostwriter` · `/optimize-prompt` | `voice-and-tone-design` · `messaging-architecture` · `editorial-calendar` · `release-comms` · `prompt-engineering-patterns` |
+| 🚀 [`founder`](docs/profiles.md#profile-founder) | Solo / early-stage founder | `/work` · `/feature` · `/challenge-me` · `/council` | `refine-prompt` · `rice-prioritization` · `vision-articulation` · `fundraising-narrative` · `runway-cognition` |
+| 🏛 [`agency`](docs/profiles.md#profile-agency) | Multi-client delivery shop | `/work` · `/implement-ticket` · `/refine-ticket` · `/feature` · `/roadmap` | `doc-coauthoring` · `decision-record` · `refine-ticket` · `estimate-ticket` · `perf-feedback-craft` |
+| 💼 [`finance`](docs/profiles.md#profile-finance) | CFO / fractional finance / FP&A | `/work` · `/council` · `/challenge-me` | `dcf-modeling` · `forecasting` · `scenario-modeling` · `unit-economics-modeling` · `runway-cognition` |
+| 🛡 [`ops`](docs/profiles.md#profile-ops) | RevOps, support, SRE-adjacent | `/work` · `/threat-model` · `/review-changes` · `/fix` | `incident-commander` · `dashboard-design` · `logging-monitoring` · `threat-modeling` · `launch-readiness` |
+
+**Not sure which one?** Run `npx @event4u/agent-config init` and open
+your AI agent — `/onboard` asks a single 8-option role question and
+maps to the closest profile. Source-of-truth:
+[`.agent-src.uncompressed/profiles/`](.agent-src.uncompressed/profiles/) ·
+schema: [`docs/contracts/profile-system.md`](docs/contracts/profile-system.md).
+Beyond software: [`user-types/`](.agent-src.uncompressed/user-types/)
+(galabau · metalworking · truck — see [Who this is for](#who-this-is-for)).
 
 <p align="center">
   <strong>210 Skills</strong> · <strong>79 Rules</strong> · <strong>124 Commands</strong> · <strong>72 Guidelines</strong> · <strong>22 Personas</strong> · <strong>5 Advisors</strong> · <strong>8 AI Tools</strong>
 </p>
 
+<p align="center">
+  <a href="CHANGELOG.md">CHANGELOG</a> ·
+  <a href="https://github.com/event4u-app/agent-config/releases/latest">Latest release</a> ·
+  <a href="https://github.com/event4u-app/agent-config/discussions">Discussions</a>
+</p>
+
 ---
 
 ## Use it in your project
 
-You run the package from a consumer repo — bootstrap via `npx`, let the
-agent pick up your stack, and ship work end-to-end. New install? Start
-with the [Quickstart](#quickstart) to write `.agent-settings.yml`,
-`.augment/`, `.claude/`, …. Already installed? [Supported Tools](#supported-tools)
-shows which AIs the package wires up, and [Featured Commands](#featured-commands)
-lists the end-to-end workflows (`/implement-ticket`, `/work`, `/commit`,
-`/create-pr`). For a deeper tour, see the
-[2-minute demo: `/implement-ticket`](#2-minute-demo-implement-ticket).
+Run from a consumer repo — bootstrap via `npx`, the agent picks up
+your stack, and you ship work end-to-end. New install? Start with the
+[Quickstart](#quickstart). Already installed? [Supported Tools](#supported-tools)
+shows the wired AIs; [`docs/featured-commands.md`](docs/featured-commands.md)
+lists the end-to-end workflows (`/implement-ticket`, `/work`,
+`/commit`, `/create-pr`). Deeper tour: [2-minute demo](#2-minute-demo-implement-ticket).
 
 ## Prove it
 
-The package is audit-disciplined by construction — every memory consult,
-decision key, and hook concern lands in `agents/state/` so you can
-replay it. [Core Principles](#core-principles) names the four invariants.
+Audit-disciplined by construction — every memory consult, decision
+key, and hook concern lands in `agents/state/` so you can replay it.
+[Core Principles](#core-principles) names the four invariants;
 [What this package is — and what it isn't](#what-this-package-is--and-what-it-isnt)
-draws the scope boundary. [Documentation](#documentation) lists the
-contracts the package ships against, including
-[`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) (beta) and
-[`decision-trace-v1`](docs/contracts/decision-trace-v1.md) (beta).
+draws the scope boundary. Beta contracts:
+[`memory-visibility-v1`](docs/contracts/memory-visibility-v1.md) ·
+[`decision-trace-v1`](docs/contracts/decision-trace-v1.md).
 
 ## Contribute
 
-Working on the package itself rather than with it?
-[Development](#development) covers the `task ci` pipeline,
-[Requirements](#requirements) the toolchain, and
+Working on the package itself? [Development](#development) covers the
+`task ci` pipeline, [Requirements](#requirements) the toolchain,
 [Maintainer telemetry](#maintainer-telemetry-opt-in-default-off) the
-opt-in measurement loop. The source-of-truth tree is
-`.agent-src.uncompressed/`; never hand-edit the generated `.augment/`
-or `.agent-src/`.
+opt-in measurement loop. Source-of-truth tree is
+`.agent-src.uncompressed/`; never hand-edit `.augment/` or `.agent-src/`.
 
 ## Quickstart
 
@@ -464,18 +484,20 @@ session is explicitly not.
 
 ## You don't need everything
 
-`cost_profile` is the master switch for **rule-tier loading**. The kernel
-(always-loaded Iron-Law floor, ≤ 26k chars across 9 rules) ships in every
-profile; tier-1 and tier-2 rules are gated by profile and resolved at
-session start from `router.json`.
+Pick how much governance your agent loads up front. The safety floor
+(non-destructive defaults, ask-before-guessing, mirror-the-user's-language)
+ships in **every** profile — what changes is how much extra coaching gets
+pulled in alongside it.
 
-| Profile | Rule tiers loaded | Token footprint | Best for |
-|---|---|---|---|
-| **`minimal`** | kernel only (no router, no auto-rules) | lowest | Cost-sensitive sessions; trivial Q&A; CI runs |
-| **`balanced`** (default) | kernel + tier-1 auto-rules | medium | Day-to-day work — current behaviour superset |
-| **`full`** | kernel + tier-1 + tier-2 (everything) | highest | Agent-config development; full rule fidelity |
+| Profile | What you get | When to pick it |
+|---|---|---|
+| **`minimal`** | The non-negotiable safety floor and nothing else. Cheapest, fastest. | Quick questions · throw-away scripts · running in CI · tight token budgets |
+| **`balanced`** (default) | Safety floor plus the everyday coaching most teams want — sensible defaults, code-review nudges, common pitfalls flagged. | Day-to-day work · the right answer if you're not sure |
+| **`full`** | Everything, including the long-tail rules normally only the package maintainers need. | Working on `agent-config` itself · audits · maximum fidelity demos |
 
-Architecture: [`docs/contracts/rule-router.md`](docs/contracts/rule-router.md) (beta) ·
+Under the hood, this is the rule-tier switch: kernel-only · kernel + tier-1
+auto-rules · kernel + tier-1 + tier-2. Architecture details:
+[`docs/contracts/rule-router.md`](docs/contracts/rule-router.md) (beta) ·
 kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-membership.md) (beta) ·
 [Configure profiles →](docs/customization.md)
 
@@ -503,53 +525,27 @@ kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-member
 
 **Deepest reference stack today: Laravel** — Pest, PHPStan, Rector, Eloquent, Livewire/Flux, Horizon, Pulse, Reverb, Pennant. **Workflow-grade second tier: Symfony** (`symfony-workflow` — DI, Doctrine, Messenger, voters, Twig) and **Next.js App Router** (`nextjs-patterns` — RSC boundaries, Server Actions, caching, route handlers). Other stacks ship in the order they are battle-tested, not second-class. Adopting on a thin stack? Open an issue so we can prioritize the right skills for extraction.
 
----
-
-## Data governance & domain safety
+### …and beyond software (`user-types/`)
 
-12 domain-safety rules (`.agent-src.uncompressed/rules/domain-safety-*.md`) act as a per-domain output floor — PII redaction for support / finance / recruiting / marketing, advice disclaimers for legal / financial / medical / consulting drafts, retention guidance for finance / support, and ops floors for logging / export. Full surface → rule(s) → floor matrix: [`docs/safety.md`](docs/safety.md).
+The same orchestration core drives non-software trades. Worked-example user types ship as the actual prompt-pack the agent loads: [`galabau-field-crew`](.agent-src.uncompressed/user-types/galabau-field-crew.md) (landscaping) · [`metalworking-shop`](.agent-src.uncompressed/user-types/metalworking-shop.md) · [`truck-driver`](.agent-src.uncompressed/user-types/truck-driver.md). Contributing your own? [5-minute scaffold](.agent-src.uncompressed/user-types/_template/) + [conventions](.agent-src.uncompressed/user-types/README.md). Same governance, command suite, and safety rules apply.
 
 ---
 
-## Featured Skills
+## Data governance & domain safety
 
-| Skill | What your agent learns |
-|---|---|
-| [`laravel`](.agent-src/skills/laravel/SKILL.md) | Write Laravel code following framework conventions and project architecture |
-| [`pest-testing`](.agent-src/skills/pest-testing/SKILL.md) | Write Pest tests with clear intent, good coverage, and project conventions |
-| [`eloquent`](.agent-src/skills/eloquent/SKILL.md) | Eloquent models, relationships, scopes, eager loading, type safety |
-| [`create-pr`](.agent-src/commands/create-pr.md) | Create GitHub PRs with structured descriptions from Jira tickets |
-| [`commit`](.agent-src/commands/commit.md) | Stage and commit changes following Conventional Commits |
-| [`/fix ci`](.agent-src/commands/fix.md) | Fetch CI errors from GitHub Actions and fix them |
-| [`/fix pr-comments`](.agent-src/commands/fix.md) | Fix and reply to all open review comments on a PR |
-| [`quality-fix`](.agent-src/commands/quality-fix.md) | Run PHPStan/Rector/ECS and fix all errors |
-| [`bug-analyzer`](.agent-src/skills/bug-analyzer/SKILL.md) | Root cause analysis from Sentry errors or Jira tickets |
-| [`improve-before-implement`](.agent-src/rules/improve-before-implement.md) | Challenge weak requirements before coding |
-| [`docker`](.agent-src/skills/docker/SKILL.md) | Dockerfile, docker-compose, container management |
-| [`security`](.agent-src/skills/security/SKILL.md) | Auth, policies, CSRF, rate limiting, secure coding |
-| [`api-design`](.agent-src/skills/api-design/SKILL.md) | REST conventions, versioning, deprecation |
-| [`database`](.agent-src/skills/database/SKILL.md) | MariaDB optimization, indexing, query performance |
-
-→ [Public catalog](docs/catalog.md) (all rules, skills, commands, guidelines) · [Skills only](docs/skills-catalog.md) · [llms.txt](llms.txt)
+12 domain-safety rules (`.agent-src.uncompressed/rules/domain-safety-*.md`) act as a per-domain output floor — PII redaction for support / finance / recruiting / marketing, advice disclaimers for legal / financial / medical / consulting drafts, retention guidance for finance / support, and ops floors for logging / export. Full surface → rule(s) → floor matrix: [`docs/safety.md`](docs/safety.md).
 
 ---
 
-## Featured Commands
+## Profile entry paths & featured commands
 
-| Command | What it does |
-|---|---|
-| [`/commit`](.agent-src/commands/commit.md) | Stage and commit with Conventional Commits |
-| [`/create-pr`](.agent-src/commands/create-pr.md) | Create PR with Jira-linked description |
-| [`/fix ci`](.agent-src/commands/fix.md) | Fetch and fix GitHub Actions failures |
-| [`/fix pr-comments`](.agent-src/commands/fix.md) | Fix and reply to review comments |
-| [`/optimize skills`](.agent-src/commands/optimize.md) | Audit skills, find duplicates, run linter |
-| [`/feature plan`](.agent-src/commands/feature.md) | Interactively plan a feature |
-| [`/quality-fix`](.agent-src/commands/quality-fix.md) | Run and fix all quality checks |
-| [`/review-changes`](.agent-src/commands/review-changes.md) | Self-review before creating a PR |
-| [`/jira-ticket`](.agent-src/commands/jira-ticket.md) | Read ticket from branch, implement feature |
-| [`/compress`](.agent-src/commands/compress.md) | Compress skills for token efficiency |
-
-→ [Browse all 124 active commands](.agent-src/commands/)
+Deep version of the profile table above (audience · first commands ·
+first skills · preset default per profile):
+[`docs/profiles.md`](docs/profiles.md). Curated featured-commands
+subset: [`docs/featured-commands.md`](docs/featured-commands.md).
+[Browse all 124 active commands](.agent-src/commands/) · full catalog:
+[`docs/catalog.md`](docs/catalog.md) ·
+[skills only](docs/skills-catalog.md) · [`llms.txt`](llms.txt).
 
 ---
 

package/config/agent-settings.template.yml

@@ -30,6 +30,28 @@ agent_config_version: ""
 # custom   = ignore profile — every matrix value must be set explicitly.
 cost_profile: __COST_PROFILE__
 
+# --- Cost tracking + budget enforcement ---
+#
+# USD budgets evaluated against `agents/cost-tracking/sessions.jsonl` by
+# `scripts/cost/budget.mjs`. Empty / 0 = unbudgeted (no enforcement,
+# `cost:check` reports spend only). See docs/contracts/cost-enforcement.md
+# for the full contract (tier ladder, hook surface, bypass mechanism).
+cost:
+  budgets:
+    # Daily USD ceiling (rolling 24h). 0 / null = no daily budget.
+    daily: 0
+    # Weekly USD ceiling (rolling 7d). 0 / null = no weekly budget.
+    weekly: 0
+    # Monthly USD ceiling (rolling 30d). 0 / null = no monthly budget.
+    monthly: 0
+  # Enforcement mode at the HARD_STOP tier (100% utilization):
+  #   advisory  = dashboards and `cost:check` show the breach; agent
+  #               keeps working. Default. Safe for greenfield projects.
+  #   hard-stop = preflight hook (scripts/cost/preflight.mjs) exits
+  #               non-zero on HARD_STOP; CI / shell wrappers refuse to
+  #               start the turn until the budget is raised or reset.
+  enforcement: advisory
+
 # --- Personal preferences ---
 personal:
   # IDE to use for opening files (code, phpstorm, cursor, …)