@event4u/agent-config 1.27.0 → 1.29.0

package/CHANGELOG.md

@@ -318,6 +318,63 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.29.0](https://github.com/event4u-app/agent-config/compare/1.28.0...1.29.0) (2026-05-09)
+
+### Features
+
+* **skills:** port 3 Microck skills under Sunset Policy (P2.2, P2.3, P2.5) ([78fdfeb](https://github.com/event4u-app/agent-config/commit/78fdfebf5f515e67072f9cb4a75ca7f56ca9b1b2))
+* **skills:** port error-handling-patterns from Microck under Sunset Policy (P1.5) ([c24589c](https://github.com/event4u-app/agent-config/commit/c24589c2c5e27e7182061660b98cca3d1e97fbae))
+* **skills:** port mcp-builder from Microck (P1.4) ([b192b38](https://github.com/event4u-app/agent-config/commit/b192b38c58245d7e8d33bdf5d577e41ba968cba5))
+* **skills:** port repomix from Microck (P1.3) ([825fd17](https://github.com/event4u-app/agent-config/commit/825fd175082b78fb2fd6250befb8cea86f1c3a0d))
+* **skills:** port testing-anti-patterns from Microck (P1.2) ([8bca47f](https://github.com/event4u-app/agent-config/commit/8bca47fab1db5811eada9bbb1f9545ebd1a68a4d))
+* **skills:** port defense-in-depth from Microck (P1.1) ([fb9bbb1](https://github.com/event4u-app/agent-config/commit/fb9bbb1e74890a63a1499a22ead0e79ab0a73ed6))
+
+### Bug Fixes
+
+* **refs:** point sibling roadmap link to archived microck-harvest ([92586a9](https://github.com/event4u-app/agent-config/commit/92586a9339e66b57121356ff644f2e3a706050e0))
+
+### Documentation
+
+* **microck-harvest:** record P2/P3 verdicts in provenance + analysis ([5200097](https://github.com/event4u-app/agent-config/commit/5200097a42bca40df03f4ecb232fea269ce6aacf))
+
+### Chores
+
+* **microck-harvest:** regenerate ownership matrix for 3 new skills ([855e331](https://github.com/event4u-app/agent-config/commit/855e3310729b0f359425c3c3e75541d98162cab4))
+* **microck-harvest:** regenerate index + catalog for 153 skills ([1d5f265](https://github.com/event4u-app/agent-config/commit/1d5f2654fbf2997a1465e965097eff8bce9f7ca2))
+* **roadmap:** close + archive microck-harvest (Phase 2 + 3 \u2014 100%) ([48c18f0](https://github.com/event4u-app/agent-config/commit/48c18f07a68342782d7d079e2371a613ee7a7c2e))
+* **microck-harvest:** register 3 new skills in marketplace + counts (150 \u2192 153) ([0e8b351](https://github.com/event4u-app/agent-config/commit/0e8b3518853add4b28e1e45f5babc550eaa974d1))
+* **microck-harvest:** suite integration + Phase 1 closure (P1.6) ([6450e9d](https://github.com/event4u-app/agent-config/commit/6450e9deea5806f4f8bfcddf12df9eeeae37c9cb))
+
+## [1.28.0](https://github.com/event4u-app/agent-config/compare/1.27.0...1.28.0) (2026-05-09)
+
+### Features
+
+* **schema:** allow Sunset-Policy metadata on skill schema ([d5d67bd](https://github.com/event4u-app/agent-config/commit/d5d67bd30e36ea6ec9586825218678ec3203ee3a))
+* **commands:** port /research command with research-schema contract ([2f03dfa](https://github.com/event4u-app/agent-config/commit/2f03dfad2f56776e80d8417f618b8ec59ae07289))
+* **skills:** adopt deep-reading-analyst skill + 3 thinking-framework guidelines ([78ac3e3](https://github.com/event4u-app/agent-config/commit/78ac3e35c56c0e936291a69191c94869251f532e))
+
+### Bug Fixes
+
+* **roadmap:** rename heading to bypass PHASE_RE false-positive ([9e0121c](https://github.com/event4u-app/agent-config/commit/9e0121c6589c214263000d7a4ae7ea554844a6cf))
+* **scope-control:** trim 411 chars to fit <=4000 override ceiling ([62dd6ee](https://github.com/event4u-app/agent-config/commit/62dd6eebc268a27cbb1a72a3089f581242be810f))
+* **budget:** trim 3 auto-rule descriptions to <=150 chars ([cfec360](https://github.com/event4u-app/agent-config/commit/cfec360f94982e302a80bfb6ab59653e3e4f41a8))
+* **no-council-refs:** suppress legitimate ADR + skipped-roadmap citations ([e6be2dd](https://github.com/event4u-app/agent-config/commit/e6be2ddec929e05d811297ebc41f53eee5afe3de))
+* **no-roadmap-refs:** drop transient roadmap links from stable artifacts ([bbda43a](https://github.com/event4u-app/agent-config/commit/bbda43a9a57dacc3153f6173497fb4503cacc174))
+* **commands:** rephrase upstream path in /research ADOPT citation ([d4fc1af](https://github.com/event4u-app/agent-config/commit/d4fc1aff289f9e7c344648a16415a60296a931f5))
+
+### Chores
+
+* **roadmap:** close P1.6 with CI-green evidence ([da198c3](https://github.com/event4u-app/agent-config/commit/da198c3e81154b34a1b519ed29aa3431e8612f4d))
+* **index:** regenerate after description trim ([27477dc](https://github.com/event4u-app/agent-config/commit/27477dc189de43a97f6559df84a783541ba2c0de))
+* **ownership:** regenerate file-ownership-matrix after governance edits ([648f272](https://github.com/event4u-app/agent-config/commit/648f27200657d574a81bced639e191f6406acdf6))
+* **index:** regenerate after description tightening ([4d78844](https://github.com/event4u-app/agent-config/commit/4d78844be0ee32379b4152a64e8acd2e951208db))
+* **governance:** remove transient roadmap refs + tighten descriptions ([421f0e3](https://github.com/event4u-app/agent-config/commit/421f0e30d257ec0f76ef648ad03161dc688dd182))
+* **index:** regenerate after research cluster registration ([f26f52d](https://github.com/event4u-app/agent-config/commit/f26f52d44f36122e4e08ffaa786e65586e6589ac))
+* **clusters:** register research as a locked cluster head ([3c9fa64](https://github.com/event4u-app/agent-config/commit/3c9fa64b26ad56f2a28e50c92cbc4e69fe4ab14a))
+* **counts:** sync command-count to 104 after /research adoption ([43f5cd7](https://github.com/event4u-app/agent-config/commit/43f5cd7560419e08c581607a62ed2297e9caa738))
+* **index:** regenerate index/catalog for deep-reading-analyst + research ([baa7fb3](https://github.com/event4u-app/agent-config/commit/baa7fb3bb716f8bbfde491f940d7def487dcde18))
+* **suite:** integrate deep-research adoption (counts, roadmap, hashes) ([7a3eb51](https://github.com/event4u-app/agent-config/commit/7a3eb511239a8a74589f9a3c89187084c083f68b))
+
 ## [1.27.0](https://github.com/event4u-app/agent-config/compare/1.26.0...1.27.0) (2026-05-08)
 
 ### Features

package/README.md

@@ -7,7 +7,7 @@ Give your AI agents an audit-disciplined orchestration contract — testing, Git
 > Your agent picks up the project's stack, runs tests, prepares PRs, fixes CI — and follows your team's coding standards while doing it. Stack-aware skill sets ship for PHP (Laravel · Symfony · Zend/Laminas), JavaScript (Next.js · React · Node), and cross-stack concerns (API · testing · security · observability).
 
 <p align="center">
-  <strong>144 Skills</strong> · <strong>60 Rules</strong> · <strong>103 Commands</strong> · <strong>59 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>153 Skills</strong> · <strong>60 Rules</strong> · <strong>104 Commands</strong> · <strong>62 Guidelines</strong> · <strong>8 AI Tools</strong>
 </p>
 
 ---
@@ -343,7 +343,7 @@ kernel set: [`docs/contracts/kernel-membership.md`](docs/contracts/kernel-member
 | [`/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 103 active commands](.agent-src/commands/)
+→ [Browse all 104 active commands](.agent-src/commands/)
 
 ---
 
@@ -368,7 +368,7 @@ Every developer gets the same behavior. No per-user setup needed.
 native slash-commands)
 
 > **What this means in practice:** Augment Code and Claude Code get the full
-> package (rules + 144 skills + 103 native commands). Cursor, Cline, Windsurf,
+> package (rules + 153 skills + 104 native commands). Cursor, Cline, Windsurf,
 > Gemini CLI, and GitHub Copilot only get the **rules** natively; skills and
 > commands are available to them as documentation the agent can read, not as
 > first-class features.

package/docs/architecture.md

@@ -96,10 +96,10 @@ fails on any source-side violation, without producing artifacts.
 
 | Layer | Count | Purpose |
 |---|---|---|
-| **Skills** | 144 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
+| **Skills** | 153 | On-demand expertise — stack analysis (Laravel · Symfony · Zend / Laminas · Next.js · React · Node), testing, Docker, API design, security, observability, … |
 | **Rules** | 60 | Always-active constraints — coding standards, scope control, verification, language-and-tone, agent-authority |
-| **Commands** | 103 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
-| **Guidelines** | 59 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Commands** | 104 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
+| **Guidelines** | 62 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
 | **Templates** | 7 | Scaffolds for features, roadmaps, contexts, skills, overrides |
 | **Contexts** | 5 | Shared knowledge about the system itself |
 

package/docs/catalog.md

@@ -1,13 +1,13 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **363 public artefacts** shipped by
+Consumer-facing catalog of all **376 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
 > **Regenerate:** `python3 scripts/generate_index.py`
 > Auto-generated — do not edit manually.
 
-## Skills (144)
+## Skills (153)
 
 | kind | name | extra | description |
 |---|---|---|---|
@@ -22,6 +22,7 @@ are excluded.
 | skill | [`api-endpoint`](../.agent-src/skills/api-endpoint/SKILL.md) |  | Use when the user says "create endpoint", "new API route", or "add controller". Creates a complete endpoint with Controller, FormRequest, Resource, route, and OpenAPI docs. |
 | skill | [`api-testing`](../.agent-src/skills/api-testing/SKILL.md) |  | Use when writing API endpoint tests — integration tests, contract validation, response assertions, mocked external services — even when the user says 'test this route' without naming API testing. |
 | skill | [`artisan-commands`](../.agent-src/skills/artisan-commands/SKILL.md) |  | Use when creating or modifying Artisan commands. Covers clear signatures, safe execution flow, helpful output, and project conventions for console tooling. |
+| skill | [`async-python-patterns`](../.agent-src/skills/async-python-patterns/SKILL.md) |  | Use when writing Python asyncio code — picking between gather / TaskGroup / wait, structured concurrency, timeouts, cancellation, sync-bridging — decision framework only, cookbook externalized. |
 | skill | [`authz-review`](../.agent-src/skills/authz-review/SKILL.md) |  | Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows. |
 | skill | [`aws-infrastructure`](../.agent-src/skills/aws-infrastructure/SKILL.md) |  | Use when working with AWS resources — ECS Fargate, ECR, EFS, Secrets Manager, gomplate templates, multi-env deployments — even when the user says 'deploy to staging' without naming AWS. |
 | skill | [`blade-ui`](../.agent-src/skills/blade-ui/SKILL.md) |  | Use when the project's frontend stack is Blade — dispatched by `directives/ui/{apply,review,polish}.py`. Covers views, components, partials, layouts, and view logic. |
@@ -42,6 +43,8 @@ are excluded.
 | skill | [`data-flow-mapper`](../.agent-src/skills/data-flow-mapper/SKILL.md) |  | Use BEFORE editing code that touches user data — traces the value from entry → validation → transformation → storage → egress, every hop cited with file:line. |
 | skill | [`database`](../.agent-src/skills/database/SKILL.md) |  | Use when working with database architecture, MariaDB/MySQL tuning, indexing strategies, slow queries, or multi-connection patterns — even when the user just says 'this query is slow'. |
 | skill | [`dcf-modeling`](../.agent-src/skills/dcf-modeling/SKILL.md) |  | Wing-4 valuation cognition for a CFO / finance-partner. Use when a deal, internal investment, or board ask names DCF, intrinsic value, WACC, terminal value, or 'what's it worth on a 5-year hold'. |
+| skill | [`deep-reading-analyst`](../.agent-src/skills/deep-reading-analyst/SKILL.md) |  | Deep analysis of articles/long-form via thinking frameworks (SCQA, mental models, inversion) — 'analyze article', 'deep dive', 'extract insights', URL/text wanting depth not summary. |
+| skill | [`defense-in-depth`](../.agent-src/skills/defense-in-depth/SKILL.md) |  | Use when validation needs entry, business-logic, environment, and instrumentation guards so a bad value cannot reach the failure point — turns a local bug fix into a structural one. |
 | skill | [`dependency-upgrade`](../.agent-src/skills/dependency-upgrade/SKILL.md) |  | Use when upgrading dependencies — "update Laravel", "bump PHP version", or "upgrade packages". Covers changelog review, breaking change detection, and verification. |
 | skill | [`description-assist`](../.agent-src/skills/description-assist/SKILL.md) |  | Use when polishing a skill/rule/command/guideline frontmatter description — pushier phrasing, trigger coverage, undertrigger audit — even if the user just says 'make this pushier'. |
 | skill | [`design-review`](../.agent-src/skills/design-review/SKILL.md) |  | Use when the user says "review the design", "check the UI", or wants a comprehensive UI/UX review. Uses a 7-phase methodology covering interaction, responsiveness, accessibility, and more. |
@@ -50,6 +53,7 @@ are excluded.
 | skill | [`docker`](../.agent-src/skills/docker/SKILL.md) |  | Use when working with Docker — Dockerfile edits, docker-compose services, containers, or the dual-container (fast + Xdebug) setup — even when the user just says 'my container won't start'. |
 | skill | [`dto-creator`](../.agent-src/skills/dto-creator/SKILL.md) |  | Use when the user says "create a DTO", "new data transfer object", or needs to convert request/response data into a typed PHP class. Creates DTOs with SimpleDto base class and attribute mapping. |
 | skill | [`eloquent`](../.agent-src/skills/eloquent/SKILL.md) |  | Use when writing Eloquent models, relationships, scopes, or queries via Model:: — 'fetch users with their orders'. NOT for PHPStan output, non-Eloquent services, or raw SQL questions. |
+| skill | [`error-handling-patterns`](../.agent-src/skills/error-handling-patterns/SKILL.md) |  | Use when picking a failure-reporting strategy — exceptions vs Result types, recoverable vs not, retry / circuit-breaker / graceful degradation — decision framework only, catalogues externalized. |
 | skill | [`estimate-ticket`](../.agent-src/skills/estimate-ticket/SKILL.md) |  | Estimate a Jira/Linear ticket — 'estimate PROJ-123', 'wie groß ist das?', 'should we split this?' — size + risk + split + uncertainty, sibling of /refine-ticket, close-prompt. |
 | skill | [`existing-ui-audit`](../.agent-src/skills/existing-ui-audit/SKILL.md) |  | Use BEFORE writing or editing any non-trivial UI — inventories components, design tokens, shadcn primitives, and reusable patterns into state.ui_audit. Hard gate for the ui directive set. |
 | skill | [`fe-design`](../.agent-src/skills/fe-design/SKILL.md) |  | Reference for frontend-design heuristics — component architecture, layout patterns, form/table design, responsive strategy, a11y, UX principles. Stack-agnostic; cited by directives/ui/design.py. |
@@ -84,6 +88,7 @@ are excluded.
 | skill | [`logging-monitoring`](../.agent-src/skills/logging-monitoring/SKILL.md) |  | Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers. |
 | skill | [`markitdown`](../.agent-src/skills/markitdown/SKILL.md) |  | Use when converting PDF, DOCX, XLSX, PPTX, EPUB, images, or audio to Markdown for LLM ingestion via the upstream markitdown-mcp server — 'extract this PDF', 'OCR this image', 'transcribe this audio'. |
 | skill | [`mcp`](../.agent-src/skills/mcp/SKILL.md) |  | Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows. |
+| skill | [`mcp-builder`](../.agent-src/skills/mcp-builder/SKILL.md) |  | Use when building an MCP server in Python (FastMCP) or Node/TypeScript (MCP SDK) — agent-centric tool design, input schemas, error handling, and the 10-question evaluation harness. |
 | skill | [`md-language-check`](../.agent-src/skills/md-language-check/SKILL.md) |  | Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone. |
 | skill | [`merge-conflicts`](../.agent-src/skills/merge-conflicts/SKILL.md) |  | Use when the user has merge conflicts or says "resolve conflicts". Understands conflict markers, resolution strategies, and verification workflow. |
 | skill | [`migration-creator`](../.agent-src/skills/migration-creator/SKILL.md) |  | Use when the user says "create migration", "add column", or "new table". Creates migrations with correct table prefixes, column naming, and multi-tenant awareness. |
@@ -111,6 +116,7 @@ are excluded.
 | skill | [`project-analysis-zend-laminas`](../.agent-src/skills/project-analysis-zend-laminas/SKILL.md) |  | Use for deep Zend Framework or Laminas project analysis: bootstrap, config merge order, service manager, MVC flow, data layer, and migration-specific risks. |
 | skill | [`project-analyzer`](../.agent-src/skills/project-analyzer/SKILL.md) |  | ONLY when user explicitly requests: full project analysis, tech stack detection, or structured analysis documents for agents/analysis/. NOT for regular feature work. |
 | skill | [`project-docs`](../.agent-src/skills/project-docs/SKILL.md) |  | Use when looking for project-specific documentation. Knows which docs exist in agents/docs/ and agents/contexts/ and maps work areas to relevant docs. |
+| skill | [`prompt-engineering-patterns`](../.agent-src/skills/prompt-engineering-patterns/SKILL.md) |  | Use when designing production-LLM prompts — few-shot, chain-of-thought, system prompts, templates, self-verification — distinct from prompt-optimizer and refine-prompt. |
 | skill | [`prompt-optimizer`](../.agent-src/skills/prompt-optimizer/SKILL.md) |  | Use when the user wants a prompt optimized for ChatGPT, Claude, Gemini, or another AI — 'make this prompt better', 'optimize for ChatGPT', 'rewrite my prompt' — even without saying 'optimize'. |
 | skill | [`quality-tools`](../.agent-src/skills/quality-tools/SKILL.md) |  | Use when PHPStan, Rector, or ECS output appears — \"phpstan says mixed\", type errors, \"fix code style\", \"run rector\" — even when Eloquent/Laravel/model code is also mentioned. |
 | skill | [`react-native-setup`](../.agent-src/skills/react-native-setup/SKILL.md) |  | Use when setting up React Native or Expo dev environments — Xcode, Android Studio, CocoaPods, EAS, Metro, New Architecture — even when the user just says 'my RN build won't start'. |
@@ -121,6 +127,7 @@ are excluded.
 | skill | [`receiving-code-review`](../.agent-src/skills/receiving-code-review/SKILL.md) |  | Use when processing code review feedback (bot or human) before changing anything — triages, verifies, and pushes back with technical reasoning — even when the user just says 'fix the comments'. |
 | skill | [`refine-prompt`](../.agent-src/skills/refine-prompt/SKILL.md) |  | Reconstruct a free-form prompt into actionable AC + assumptions + confidence band before the engine plans — '/work \"…\"', 'baue X', 'ist der Prompt klar genug für die Engine?'. |
 | skill | [`refine-ticket`](../.agent-src/skills/refine-ticket/SKILL.md) |  | Refine a Jira/Linear ticket before planning — 'refine ticket', 'tighten AC on PROJ-123', 'ist das Ticket klar?' — rewritten ticket, Top-5 risks, persona voices, sub-skills orchestrated, close-prompt. |
+| skill | [`repomix`](../.agent-src/skills/repomix/SKILL.md) |  | Use when packaging a codebase to a single AI-friendly file for LLM analysis — local or remote, XML/Markdown/JSON, token counting, gitignore filtering, peer-side `repomix` CLI. |
 | skill | [`requesting-code-review`](../.agent-src/skills/requesting-code-review/SKILL.md) |  | Use when asking for a review or creating a PR — self-review first, frame the right context, test plan included — even when the user just says 'open a PR' or 'ready to merge'. |
 | skill | [`review-routing`](../.agent-src/skills/review-routing/SKILL.md) |  | Use when preparing a PR description, suggesting reviewers, or flagging risk — produces owner-mapped roles plus historical bug-pattern matches from project-local YAML. |
 | skill | [`rice-prioritization`](../.agent-src/skills/rice-prioritization/SKILL.md) |  | Use when ranking competing initiatives for a roadmap, breaking a tie between two features, or auditing a backlog for hidden low-value work via Reach × Impact × Confidence ÷ Effort. |
@@ -129,6 +136,7 @@ are excluded.
 | skill | [`rtk-output-filtering`](../.agent-src/skills/rtk-output-filtering/SKILL.md) |  | Use when running verbose CLI commands — wraps them with rtk (Rust Token Killer) for 60-90% token savings. Covers installation, configuration, and usage patterns. |
 | skill | [`rule-writing`](../.agent-src/skills/rule-writing/SKILL.md) |  | Use when creating or editing a rule in .agent-src.uncompressed/rules/ — trigger wording, always vs auto classification, size budget — even when the user just says 'add a rule for X'. |
 | skill | [`script-writing`](../.agent-src/skills/script-writing/SKILL.md) |  | Use when adding or editing any script under `scripts/` — `--quiet` flag, `_lib/script_output` helpers, silent Taskfile wiring, Iron-Law carve-outs — even when you just say 'add a check script for X'. |
+| skill | [`secrets-management`](../.agent-src/skills/secrets-management/SKILL.md) |  | Use when picking a secrets store, designing rotation, or wiring scanning gates — multi-cloud (Vault, AWS, Azure, GCP), CI, and Kubernetes — decision framework, provider deep-dives externalized. |
 | skill | [`security`](../.agent-src/skills/security/SKILL.md) |  | Use when applying security best practices — authentication, authorization via Policies, CSRF protection, input sanitization, rate limiting, or secure coding. |
 | skill | [`security-audit`](../.agent-src/skills/security-audit/SKILL.md) |  | ONLY when user explicitly requests: security audit, vulnerability scan, or penetration test review. NOT for regular feature work. |
 | skill | [`sentry-integration`](../.agent-src/skills/sentry-integration/SKILL.md) |  | Use when the user shares a Sentry URL, says "check Sentry", or wants to investigate production errors. Uses Sentry MCP tools for deep analysis. |
@@ -145,6 +153,7 @@ are excluded.
 | skill | [`terragrunt`](../.agent-src/skills/terragrunt/SKILL.md) |  | Use when working with Terragrunt — DRY multi-env configs, module dependencies, remote state orchestration — even when the user just says 'deploy this to staging and prod' without naming Terragrunt. |
 | skill | [`test-driven-development`](../.agent-src/skills/test-driven-development/SKILL.md) |  | Use when implementing a feature, fixing a bug, or refactoring — write a failing test first, then the code — even if the user just says 'add this function' or 'fix this bug'. |
 | skill | [`test-performance`](../.agent-src/skills/test-performance/SKILL.md) |  | Use when optimizing test suite performance — database setup, seeder optimization, parallel testing, CI pipeline efficiency, or RefreshDatabase alternatives. |
+| skill | [`testing-anti-patterns`](../.agent-src/skills/testing-anti-patterns/SKILL.md) |  | Use BEFORE writing or changing tests, adding mocks, or putting test-only methods on production classes — five Iron Laws and gates against mocking-the-mock, production pollution, silent partial mocks. |
 | skill | [`threat-modeling`](../.agent-src/skills/threat-modeling/SKILL.md) |  | Use when adding auth, webhooks, uploads, queues, secrets, tenant boundaries, or public endpoints — produces trust boundaries + abuse cases mapped to files, BEFORE implementation. |
 | skill | [`token-optimizer`](../.agent-src/skills/token-optimizer/SKILL.md) |  | 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. |
 | skill | [`traefik`](../.agent-src/skills/traefik/SKILL.md) |  | Use when setting up Traefik as a local reverse proxy — real domains on 127.0.0.1, trusted HTTPS via mkcert, automatic service discovery, and multi-project routing. |
@@ -177,7 +186,7 @@ are excluded.
 | rule | [`context-hygiene`](../.agent-src/rules/context-hygiene.md) | auto | When debugging, fixing errors, or running long conversations — 3-failure stop rule, tool-loop detection, fresh-chat triggers |
 | rule | [`direct-answers`](../.agent-src/rules/direct-answers.md) | always | Always — direct, unembellished answers. No flattery, no invented facts (verify load-bearing claims, otherwise ask). Emojis only as functional markers. Brevity is the default. |
 | rule | [`docker-commands`](../.agent-src/rules/docker-commands.md) | auto | Running PHP commands inside Docker containers — artisan, composer, phpstan, rector, ecs, phpunit, tests, migrations, and any CLI tool execution |
-| rule | [`domain-adoption-policy`](../.agent-src/rules/domain-adoption-policy.md) | auto | Adopting a new domain track (mobile, ML, blockchain, scientific computing, IoT, gaming) into the suite — gates the import on demand, ownership, CI fit, and Sunset compatibility BEFORE any harvest |
+| rule | [`domain-adoption-policy`](../.agent-src/rules/domain-adoption-policy.md) | auto | Adopting a new domain track (mobile, ML, blockchain, IoT, gaming) — gates import on demand, ownership, CI fit, Sunset compatibility BEFORE harvest |
 | rule | [`downstream-changes`](../.agent-src/rules/downstream-changes.md) | auto | After EVERY code edit, find ALL downstream changes needed to existing files, including callers, tests, imports, types, and documentation |
 | rule | [`e2e-testing`](../.agent-src/rules/e2e-testing.md) | auto | Playwright E2E tests — locators, assertions, Page Objects, fixtures, CI, and flaky test prevention |
 | rule | [`guidelines`](../.agent-src/rules/guidelines.md) | manual | Writing or reviewing code — check relevant guideline before writing or reviewing code |
@@ -191,8 +200,8 @@ are excluded.
 | rule | [`model-recommendation`](../.agent-src/rules/model-recommendation.md) | auto | Starting a new task, switching task type, or invoking a command — detect complexity and recommend optimal model (Opus/Sonnet/GPT) before work |
 | rule | [`no-attribution-footers`](../.agent-src/rules/no-attribution-footers.md) | auto | Generating PR/issue/comment/commit-message bodies — forbids 'Generated with', 'Co-authored by', or 'Pull Request opened by' attribution footers |
 | rule | [`no-cheap-questions`](../.agent-src/rules/no-cheap-questions.md) | always | No cheap questions — never ask what context answers, never offer Iron-Law-violating options, never stage no-trade-off choices; mode-independent (off / auto / on) |
-| rule | [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md) | auto | Linking transient files (agents/roadmaps/, agents/council-{questions,responses,sessions}/) from a stable artifact — both layers expire; promote findings |
-| rule | [`no-unsolicited-rebase`](../.agent-src/rules/no-unsolicited-rebase.md) | auto | Working with git history — never rewrite, rebase, squash, fixup, or amend without explicit user request; the linear/squashed shape is the user's call, not a tidiness reflex |
+| rule | [`no-roadmap-references`](../.agent-src/rules/no-roadmap-references.md) | auto | Linking transient files (agents/roadmaps/, agents/council-*/) from a stable artifact — both layers expire; promote findings |
+| rule | [`no-unsolicited-rebase`](../.agent-src/rules/no-unsolicited-rebase.md) | auto | Working with git history — never rewrite, rebase, squash, fixup, or amend without explicit user request; shape is the user's call, not tidiness |
 | rule | [`non-destructive-by-default`](../.agent-src/rules/non-destructive-by-default.md) | always | Agent is never destructive — Hard Floor always asks for prod-trunk merges, deploys, pushes, prod data/infra, bulk deletions, and bulk-deletion/infra commits; no autonomy or roadmap bypass |
 | rule | [`onboarding-gate`](../.agent-src/rules/onboarding-gate.md) | auto | First turn of a conversation on a project — check onboarding.onboarded in .agent-settings.yml; when false, prompt to run /onboard before any request |
 | rule | [`package-ci-checks`](../.agent-src/rules/package-ci-checks.md) | manual | Before pushing to remote or creating a PR in the agent-config package — run all CI checks locally first |
@@ -218,7 +227,7 @@ are excluded.
 | rule | [`user-interaction`](../.agent-src/rules/user-interaction.md) | auto | Asking the user a question, presenting options, or summarizing progress — numbered-options Iron Law, single-recommendation rule, progress indicators |
 | rule | [`verify-before-complete`](../.agent-src/rules/verify-before-complete.md) | always | Verify before completion — run tests and quality tools before claiming done |
 
-## Commands (103)
+## Commands (104)
 
 | kind | name | cluster | description |
 |---|---|---|---|
@@ -306,6 +315,7 @@ are excluded.
 | command | [`project-health`](../.agent-src/commands/project-health.md) |  | Quick project health check — show status of docs, modules, contexts, and roadmaps without creating anything |
 | command | [`quality-fix`](../.agent-src/commands/quality-fix.md) |  | Run quality pipeline (PHP and/or JS/TS) and fix all errors — auto-detects language from changed files |
 | command | [`refine-ticket`](../.agent-src/commands/refine-ticket.md) |  | Refine a Jira/Linear ticket before planning — rewritten ticket + Top-5 risks + persona voices, orchestrates validate-feature-fit and threat-modeling, ends with a close-prompt |
+| command | [`research`](../.agent-src/commands/research.md) | cluster: research | Preliminary research scaffolder — pick objects, define fields, emit `outline.yaml` + `fields.yaml` for downstream deep research. Use for surveys, benchmarks, tech selection, competitive scans. |
 | command | [`review-changes`](../.agent-src/commands/review-changes.md) |  | Self-review local changes before creating a PR — dispatches to four specialized judges (bug, security, tests, quality) and consolidates verdicts |
 | command | [`review-routing`](../.agent-src/commands/review-routing.md) |  | Compute reviewer roles and matched historical bug patterns for the current diff, using project-local ownership-map.yml and historical-bug-patterns.yml |
 | command | [`roadmap:ai-council`](../.agent-src/commands/roadmap/ai-council.md) | cluster: roadmap | Challenge a roadmap with the AI council (deep tier) and refactor from convergence findings. Wraps `/council default` pinned to `--input-mode roadmap --depth deep`; patches surface as numbered options. |
@@ -326,7 +336,7 @@ are excluded.
 | command | [`upstream-contribute`](../.agent-src/commands/upstream-contribute.md) |  | Contribute a learning, skill, rule, or fix from a consumer project back to the shared agent-config package |
 | command | [`work`](../.agent-src/commands/work.md) |  | Drive a free-form prompt end-to-end through refine → score → plan → implement → test → verify → report — Option-A loop over the `work_engine` Python engine, confidence-band gated, no auto-git. |
 
-## Guidelines (59)
+## Guidelines (62)
 
 | kind | name | category | description |
 |---|---|---|---|
@@ -338,11 +348,13 @@ are excluded.
 | guideline | [`developer-judgment`](../docs/guidelines/agent-infra/developer-judgment.md) | agent-infra |  |
 | guideline | [`direct-answers-demos`](../docs/guidelines/agent-infra/direct-answers-demos.md) | agent-infra |  |
 | guideline | [`engineering-memory-data-format`](../docs/guidelines/agent-infra/engineering-memory-data-format.md) | agent-infra |  |
+| guideline | [`inversion-thinking`](../docs/guidelines/agent-infra/inversion-thinking.md) | agent-infra |  |
 | guideline | [`ios-simulator-guide`](../docs/guidelines/agent-infra/ios-simulator-guide.md) | agent-infra |  |
 | guideline | [`language-and-tone-examples`](../docs/guidelines/agent-infra/language-and-tone-examples.md) | agent-infra |  |
 | guideline | [`layered-settings`](../docs/guidelines/agent-infra/layered-settings.md) | agent-infra |  |
 | guideline | [`mcp-request-signing`](../docs/guidelines/agent-infra/mcp-request-signing.md) | agent-infra |  |
 | guideline | [`memory-access`](../docs/guidelines/agent-infra/memory-access.md) | agent-infra |  |
+| guideline | [`mental-models`](../docs/guidelines/agent-infra/mental-models.md) | agent-infra |  |
 | guideline | [`naming`](../docs/guidelines/agent-infra/naming.md) | agent-infra |  |
 | guideline | [`output-patterns`](../docs/guidelines/agent-infra/output-patterns.md) | agent-infra |  |
 | guideline | [`review-routing-data-format`](../docs/guidelines/agent-infra/review-routing-data-format.md) | agent-infra |  |
@@ -351,6 +363,7 @@ are excluded.
 | guideline | [`role-mode-router`](../docs/guidelines/agent-infra/role-mode-router.md) | agent-infra |  |
 | guideline | [`rule-type-governance`](../docs/guidelines/agent-infra/rule-type-governance.md) | agent-infra |  |
 | guideline | [`runtime-layer`](../docs/guidelines/agent-infra/runtime-layer.md) | agent-infra |  |
+| guideline | [`scqa-framework`](../docs/guidelines/agent-infra/scqa-framework.md) | agent-infra |  |
 | guideline | [`self-improvement-pipeline`](../docs/guidelines/agent-infra/self-improvement-pipeline.md) | agent-infra |  |
 | guideline | [`size-and-scope`](../docs/guidelines/agent-infra/size-and-scope.md) | agent-infra |  |
 | guideline | [`skill-quality-checklist`](../docs/guidelines/agent-infra/skill-quality-checklist.md) | agent-infra |  |

package/docs/contracts/command-clusters.md

@@ -44,6 +44,7 @@ column 1 of this table.
 | `create-pr` | 2 | `description-only` | `create-pr-description` |
 | `council` | 3 | `default` · `pr` · `design` · `optimize` | `council` (legacy default lens) · `council-pr` · `council-design` · `council-optimize` |
 | `challenge-me` | — | `vision` · `with-docs` | new — Pocock-inspired one-question-at-a-time interview; `vision` is the standard 95%-confidence variant, `with-docs` adds doc/glossary awareness with a session-scoped glossary and load-bearing claim-vs-code verification |
+| `research` | — | (cluster head only · follow-up phases will add `deep` · `add-items` · `add-fields`) | new — preliminary-research scaffolder ported from `Weizhena/Deep-Research-skills`; emits `outline.yaml` + `fields.yaml` against the `research-schema` contract. Deep-research and incremental-edit sub-commands are queued as follow-up ports. |
 
 **Net change:** Phase 1 collapsed 15 atomics → 3 clusters; Phase 2
 collapses 26 atomics → 11 sub-command clusters. Sub-commands use