@event4u/agent-config 1.31.0 → 1.33.0

package/.agent-src/skills/subagent-orchestration/prompts/judge-with-debate.md

@@ -0,0 +1,63 @@
+# Prompt — judge-with-debate
+
+Mode reference: [`../SKILL.md`](../SKILL.md) § *5. judge-with-debate*.
+
+## Judge-A / Judge-B prompt (run twice in parallel)
+
+```
+You are JUDGE {{judge_letter}} reviewing a high-stakes diff (security,
+data integrity, public API). Another judge is independently reviewing
+the same diff. A meta-judge will reconcile your verdicts.
+
+DO NOT reach for the safe answer. Disagreement IS the value.
+
+TASK: {{task_description}}
+DIFF: {{diff}}
+TEST OUTPUT: {{test_output}}
+SENSITIVITY: {{security_or_data_or_api}}
+
+VERDICT (one envelope, schemas/subagent-status.json):
+  - DONE                — diff is correct and safe; evidence[] cites
+                          the specific defenses you verified.
+  - DONE_WITH_CONCERNS  — correct but the failure modes you can name
+                          go in concerns[].
+  - NEEDS_CONTEXT       — paused; meta-judge will adjudicate after
+                          orchestrator answers blocking_question.
+  - BLOCKED             — diff is wrong; explain in blocking_reason.
+
+NAME ONE FAILURE MODE you actively looked for, even if you did not
+find it. "I looked for X, did not find it" is stronger evidence than
+"this looks fine".
+```
+
+## Meta-judge prompt (run once after Judge-A and Judge-B return)
+
+```
+You are the META-JUDGE reconciling two independent verdicts. Both
+judges saw the same diff; their envelopes are below.
+
+JUDGE-A ENVELOPE: {{envelope_a}}
+JUDGE-B ENVELOPE: {{envelope_b}}
+DIFF: {{diff}}
+
+RECONCILIATION RULES:
+1. Both DONE → your verdict is DONE.
+2. Either BLOCKED → your verdict is BLOCKED. No tiebreaker.
+3. One DONE, one DONE_WITH_CONCERNS → DONE_WITH_CONCERNS (carry the
+   concerns).
+4. One NEEDS_CONTEXT → consolidate blocking_question(s); your status
+   is NEEDS_CONTEXT.
+5. Mixed otherwise → DONE_WITH_CONCERNS, listing every concern from
+   both judges.
+
+DISAGREEMENT IS THE VALUE: do NOT average. The strict-er verdict wins.
+
+VERDICT (one envelope, schemas/subagent-status.json) using the rules
+above. Cite both judges' evidence[] in your evidence[].
+```
+
+## High-stakes-only rule
+
+`judge-with-debate` is two-judges-plus-meta = three subagent calls per
+review. Reserve for security, data migration, public API, or
+cross-tenant boundaries. Routine refactors use plain `do-and-judge`.

package/.agent-src/skills/subagent-orchestration/schemas/subagent-status.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://event4u.dev/agent-config/schemas/subagent-status.json",
+  "title": "Subagent Status Envelope",
+  "description": "Required wire format for every implementer or judge subagent return. Loaded by /do-and-judge, /do-in-steps, and the subagent-orchestration skill. Hand-validated by tests/test_subagent_status_schema.py (no jsonschema runtime dep).",
+  "type": "object",
+  "required": ["status", "summary"],
+  "additionalProperties": false,
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["DONE", "DONE_WITH_CONCERNS", "NEEDS_CONTEXT", "BLOCKED"],
+      "description": "DONE = work shipped, gate green. DONE_WITH_CONCERNS = work shipped but caller must read concerns[]. NEEDS_CONTEXT = paused, blocking_question[] must be answered. BLOCKED = halted, blocking_reason describes why no path forward."
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "description": "One- or two-sentence outcome. Required for every status."
+    },
+    "evidence": {
+      "type": "array",
+      "items": {"type": "string", "minLength": 1},
+      "description": "Citations: file:line, command output, test name, contract section. Required for DONE / DONE_WITH_CONCERNS."
+    },
+    "concerns": {
+      "type": "array",
+      "items": {"type": "string", "minLength": 1},
+      "description": "Caller-actionable concerns. Required when status = DONE_WITH_CONCERNS, must be empty otherwise."
+    },
+    "blocking_question": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Single specific question whose answer would unblock. Required when status = NEEDS_CONTEXT."
+    },
+    "blocking_reason": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Why no path forward exists. Required when status = BLOCKED. Distinguish from NEEDS_CONTEXT (where caller can supply context)."
+    },
+    "next_action": {
+      "type": "string",
+      "description": "What the caller does now. Optional; orchestrator infers from status when omitted."
+    }
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"status": {"const": "DONE"}}, "required": ["status"]},
+      "then": {"required": ["evidence"], "not": {"required": ["concerns"]}}
+    },
+    {
+      "if": {"properties": {"status": {"const": "DONE_WITH_CONCERNS"}}, "required": ["status"]},
+      "then": {"required": ["evidence", "concerns"]}
+    },
+    {
+      "if": {"properties": {"status": {"const": "NEEDS_CONTEXT"}}, "required": ["status"]},
+      "then": {"required": ["blocking_question"]}
+    },
+    {
+      "if": {"properties": {"status": {"const": "BLOCKED"}}, "required": ["status"]},
+      "then": {"required": ["blocking_reason"]}
+    }
+  ]
+}

package/.agent-src/skills/test-driven-development/SKILL.md

@@ -64,6 +64,20 @@ stay on plain TDD — the section above.
 If step 2 is skipped, the test is not trusted — a test that has never
 failed proves nothing about the code under test.
 
+### Iron Law — delete-and-restart over keep-as-reference
+
+```
+WHEN UNTESTED CODE EXISTS AND A TEST IS NEEDED — DELETE THE CODE,
+WRITE THE TEST, REIMPLEMENT. NEVER KEEP IT "AS REFERENCE".
+```
+
+Reading the existing implementation while writing its test is
+test-after-the-fact with extra steps. The 12-row anti-rationalization
+table that follows expands the most common ways this Iron Law gets
+talked-around. Externalized to
+[`testing-anti-patterns/process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md)
+to keep this skill under the 400-line sunset trigger.
+
 ## Procedure
 
 ### 1. Identify the behavior to test
@@ -140,22 +154,20 @@ Back to step 1 with the next single-sentence behavior.
 3. Captured green-run output
 4. Any refactor diff (optional)
 
-## Anti-rationalizations table
+## Anti-rationalizations
 
-The urge to skip TDD is strongest on tasks where TDD matters most. Name
-the rationalization and reject it:
+Twelve common rationalizations that fire *before* the test is written —
+plus the delete-and-restart Iron Law — live in
+[`testing-anti-patterns/process-anti-patterns.md`](../testing-anti-patterns/process-anti-patterns.md).
+Read the table when:
 
-| Thought | Reality |
-|---|---|
-| "This is too simple to need a test" | Simple code still breaks. A test takes less time than one debug cycle. |
-| "I'll add the test after the code works" | A test written after code passes on the first run — it has never failed. It does not prove the code is correct. |
-| "I already ran it manually" | Manual runs are not repeatable. The next edit breaks it silently. |
-| "Deleting this code I just wrote is wasteful" | Sunk cost. The cheap path is: delete, write the test, reimplement minimally. |
-| "I'll keep the code as reference while I write the test" | You will read it and adapt it. That is test-after-the-fact with extra steps. Delete it. |
-| "I just need to explore the API first" | Spike it on a throwaway branch. Then delete it and restart with TDD. |
-| "The test is too hard to write" | That signals a design problem in the code, not in the test. Listen to it. |
-| "This bug is urgent, no time for a test" | The test **is** the fastest path to a verified fix. Guessing takes longer. |
+- You catch yourself thinking "I'll add the test after" — row 2.
+- You want to keep the code "as reference" while writing the test — row 5.
+- "CI is red, patch first, test later" — row 9.
+- "Follow-up PR will add the test" — row 12.
 
+For mock-isolation failure modes (separate concern), see
+[`testing-anti-patterns`](../testing-anti-patterns/SKILL.md).
 
 ## Examples
 

package/.agent-src/skills/testing-anti-patterns/SKILL.md

@@ -8,6 +8,13 @@ source: package
 
 Tests must verify real behavior, not mock behavior. Mocks isolate; they are not the thing under test. This skill is the **prevention** layer; [`judge-test-coverage`](../judge-test-coverage/SKILL.md) catches what slips through afterwards.
 
+For the **process / rationalization** failure modes that fire *before* a
+test is written (the urges to skip TDD, keep code "as reference", patch
+without a regression test), see the sibling reference table in
+[`process-anti-patterns.md`](process-anti-patterns.md). Both layers are
+required — a correctly-mocked test that was written *after* the code is
+still test-after-the-fact.
+
 ## When to use
 
 - About to write a new test that mocks a collaborator.

package/.agent-src/skills/testing-anti-patterns/process-anti-patterns.md

@@ -0,0 +1,67 @@
+# Testing process anti-patterns — reference table
+
+Sibling reference for [`testing-anti-patterns`](SKILL.md) and
+[`test-driven-development`](../test-driven-development/SKILL.md).
+
+`testing-anti-patterns/SKILL.md` covers **mock-isolation** failure modes
+(mocking-the-mock, production pollution, partial mocks). This doc covers
+the **process / rationalization** failure modes — the urges that fire
+*before* the test is written and convince you to skip TDD entirely.
+
+Both layers are required. A correctly-mocked test that was written *after*
+the code is still test-after-the-fact. A TDD-first test that mocks itself
+is still mocking the mock.
+
+## The Iron Law (delete-and-restart)
+
+```
+WHEN YOU FIND YOURSELF KEEPING UNTESTED CODE "AS REFERENCE" WHILE WRITING
+A TEST FOR IT — DELETE THE CODE. WRITE THE TEST. THEN REIMPLEMENT.
+```
+
+The cheap path is one extra round-trip. The expensive path is a test that
+silently encodes the bug it was supposed to catch.
+
+## 12-row anti-rationalization table
+
+The urge to skip TDD is strongest on tasks where TDD matters most. Name
+the rationalization, then reject it:
+
+| # | Thought | Reality |
+|---|---|---|
+| 1 | "This is too simple to need a test" | Simple code still breaks. A test takes less time than one debug cycle. |
+| 2 | "I'll add the test after the code works" | A test written after code that passed first try has never failed. It does not prove the code is correct. |
+| 3 | "I already ran it manually" | Manual runs are not repeatable. The next edit breaks it silently. |
+| 4 | "Deleting code I just wrote is wasteful" | Sunk cost. The cheap path: delete, write the test, reimplement minimally. |
+| 5 | "I'll keep the code as reference while I write the test" | You will read it and adapt to it. That is test-after-the-fact with extra steps. Delete it. |
+| 6 | "I just need to explore the API first" | Spike on a throwaway branch. Then delete the spike and restart with TDD. |
+| 7 | "The test is too hard to write" | That signals a design problem in the code, not the test. Listen to it — refactor the seam, then test. |
+| 8 | "This bug is urgent, no time for a test" | The test **is** the fastest path to a verified fix. Guessing takes longer and re-occurs. |
+| 9 | "CI is red — patch first, test later" | A red CI is the cheapest moment to write the regression test. The patch without the test invites the same bug back. |
+| 10 | "The test is just proof-of-work for the PR review" | A test that exists to placate review is not a test — it is theater. Either it asserts behavior or delete it. |
+| 11 | "The dependency is too awkward to seam" | The seam discomfort *is* the design feedback. A constructor-injection refactor pays for itself the second time you change the dependency. |
+| 12 | "We'll add the test in a follow-up PR" | Follow-up PRs that add tests to merged code arrive 0% of the time. The test ships with the change or never. |
+
+## When to use this doc
+
+- Reviewing your own draft before writing a test — read the table, check
+  none of the 12 are firing in your head.
+- Reviewing a teammate's PR — if the PR description matches one of the 12
+  patterns, surface the row number in the review.
+- Onboarding — pair with [`test-driven-development`](../test-driven-development/SKILL.md)
+  to give new devs the *why* behind the discipline.
+
+## Cross-references
+
+- Mock-specific anti-patterns: [`testing-anti-patterns`](SKILL.md)
+- TDD discipline: [`test-driven-development`](../test-driven-development/SKILL.md)
+- Coverage hygiene on a finished diff: [`judge-test-coverage`](../judge-test-coverage/SKILL.md)
+- Pest conventions: [`pest-testing`](../pest-testing/SKILL.md)
+- Quality tooling: [`quality-tools`](../quality-tools/SKILL.md)
+
+## Provenance
+
+- Adapted from `obra/superpowers@v5.1.0` `testing/anti-patterns.md`.
+- Council convergence (anthropic/claude-sonnet-4-5 + openai/gpt-4o,
+  2026-05-07): both members ADOPT — the catalogue surfaces specific
+  rationalization patterns that would otherwise leak past code review.

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.31.0"
+    "version": "1.33.0"
   },
   "plugins": [
     {
@@ -213,6 +213,8 @@
         "./.claude/skills/repomix-packer",
         "./.claude/skills/requesting-code-review",
         "./.claude/skills/research",
+        "./.claude/skills/research-deep",
+        "./.claude/skills/research-report",
         "./.claude/skills/review-changes",
         "./.claude/skills/review-routing",
         "./.claude/skills/rice-prioritization",

package/CHANGELOG.md

@@ -318,6 +318,57 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [1.33.0](https://github.com/event4u-app/agent-config/compare/1.32.0...1.33.0) (2026-05-09)
+
+### Features
+
+* **commands:** port /research:deep + /research:report as cluster sub-commands ([71f8141](https://github.com/event4u-app/agent-config/commit/71f8141a3c553ee5b35f31ffdd7ab33e9cb110e5))
+* **guidelines:** port 5w2h, six-hats, systems-thinking, first-principles, critical-thinking from ginobefun ([40ea866](https://github.com/event4u-app/agent-config/commit/40ea8662f4e7714aa66348aff5456b53a3045350))
+
+### Bug Fixes
+
+* **roadmap:** inline council convergence summary instead of file ref ([1087cab](https://github.com/event4u-app/agent-config/commit/1087cab557c12fb353cb7a3e5ac7ab27a8d19379))
+* **research:** add ## Rules section to cluster head ([044bdab](https://github.com/event4u-app/agent-config/commit/044bdabd82b2b16350277f3f7b5e1b0e50703242))
+* **research:** collapse ADOPT citation paths into repo@sha:path tokens ([54deb0d](https://github.com/event4u-app/agent-config/commit/54deb0ddcf201ecbeecf6a57c1074d904fb2d197))
+
+### Documentation
+
+* **counts:** bump command count 101→103 in README + getting-started ([f2fb002](https://github.com/event4u-app/agent-config/commit/f2fb0026c803819569c0c739fdbad8addd96928a))
+* **roadmap:** refresh counts and progress for deep-research adoption phase 2 ([2c284cd](https://github.com/event4u-app/agent-config/commit/2c284cd431480e9c2ae39ec70132a1f8d5eb6e59))
+
+### Chores
+
+* **roadmap:** close road-to-feedback-followups (P0-P3+P5 done, P4 deferred) ([b07db6c](https://github.com/event4u-app/agent-config/commit/b07db6cae705a1e372ed9b75e47d2b14f8447b18))
+* **roadmap:** cancel road-to-event-driven-discipline (skipped, 0% executed) ([590f27d](https://github.com/event4u-app/agent-config/commit/590f27d8c7239431df92e1b7e003837c6e0be178))
+* **roadmap:** close road-to-deep-research-adoption (P1+P2 done, P3 dropped) ([d2a8808](https://github.com/event4u-app/agent-config/commit/d2a880836d79f13efefe6b3257a2ac869e6c9697))
+* **ownership:** regenerate file-ownership matrix for research cluster ([e90f886](https://github.com/event4u-app/agent-config/commit/e90f8861a356e51dbb7bce8baf5c2d8e53732bd2))
+
+Tests: 2560 (+0 since 1.32.0)
+
+## [1.32.0](https://github.com/event4u-app/agent-config/compare/1.31.0...1.32.0) (2026-05-09)
+
+### Features
+
+* **roadmap:** bite-sized task granularity gate for structural roadmaps ([b23683d](https://github.com/event4u-app/agent-config/commit/b23683df15dd43229a25cad33882f6a692d92a97))
+* **skills:** add 3-scan self-review to planning skills ([6784fb8](https://github.com/event4u-app/agent-config/commit/6784fb8ad355ef5b2d7f2cebe5d5e26f114cbe4a))
+* **subagent-orchestration:** status taxonomy + externalized prompts + two-stage mode ([6d846a7](https://github.com/event4u-app/agent-config/commit/6d846a74441196b98cabf8cd1c18ca40db0cec89))
+* **skills:** TDD hardening with externalized anti-pattern catalogue ([db2b1a2](https://github.com/event4u-app/agent-config/commit/db2b1a2a550f10fa51742bef360044b9de1bb7ca))
+
+### Bug Fixes
+
+* **investigation:** inline council convergence (council files gitignored) ([ff93aa7](https://github.com/event4u-app/agent-config/commit/ff93aa7ee6f6cffff062838a644047470e1d462e))
+* **skills:** inline council convergence in anti-patterns provenance ([7d7e663](https://github.com/event4u-app/agent-config/commit/7d7e663f8e619882fd59465dfbfdb268132eeb8d))
+* **skills:** drop roadmap reference from anti-patterns provenance ([a49c010](https://github.com/event4u-app/agent-config/commit/a49c0107971a5b70a1fdf33ed1a19c91d075980a))
+
+### Chores
+
+* **ownership:** regenerate matrix after superpowers-harvest landing ([faf4794](https://github.com/event4u-app/agent-config/commit/faf479470db9c83d17e8332dd3498df1e5f4c34b))
+* **index:** regenerate after superpowers-harvest landing ([946f3cc](https://github.com/event4u-app/agent-config/commit/946f3ccad54da3a3898d0aeb4474be0b87e66800))
+* **roadmap:** remove old roadmap path (already archived) ([18f281b](https://github.com/event4u-app/agent-config/commit/18f281bbeb51e93feef40146af3a3b5e5cb916f2))
+* **roadmap:** close superpowers-harvest — Phase 1 LANDED, P1.4b deferred ([a296106](https://github.com/event4u-app/agent-config/commit/a296106c6a846a54c3fe20728203fb3bbae7fffc))
+
+Tests: 2560 (+74 since 1.31.0)
+
 ## [1.31.0](https://github.com/event4u-app/agent-config/compare/1.29.0...1.31.0) (2026-05-09)
 
 ### 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>153 Skills</strong> · <strong>60 Rules</strong> · <strong>101 Commands</strong> · <strong>63 Guidelines</strong> · <strong>8 AI Tools</strong>
+  <strong>153 Skills</strong> · <strong>60 Rules</strong> · <strong>103 Commands</strong> · <strong>68 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 101 active commands](.agent-src/commands/)
+→ [Browse all 103 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 + 153 skills + 101 native commands). Cursor, Cline, Windsurf,
+> package (rules + 153 skills + 103 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

@@ -98,8 +98,8 @@ fails on any source-side violation, without producing artifacts.
 |---|---|---|
 | **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** | 101 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
-| **Guidelines** | 63 | Reference material cited by skills — PHP patterns, Eloquent, Playwright, agent-infra, … |
+| **Commands** | 103 | Slash-command workflows — `/commit`, `/create-pr`, `/fix ci`, `/optimize skills`, `/feature plan`, `/work`, `/implement-ticket`, `/compress`, … |
+| **Guidelines** | 68 | 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,6 +1,6 @@
 # agent-config — Public Catalog
 
-Consumer-facing catalog of all **374 public artefacts** shipped by
+Consumer-facing catalog of all **381 public artefacts** shipped by
 this package. Internal package-maintenance rules and deprecation shims
 are excluded.
 
@@ -146,7 +146,7 @@ are excluded.
 | skill | [`skill-reviewer`](../.agent-src/skills/skill-reviewer/SKILL.md) |  | Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations. |
 | skill | [`skill-writing`](../.agent-src/skills/skill-writing/SKILL.md) |  | Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'. |
 | skill | [`sql-writing`](../.agent-src/skills/sql-writing/SKILL.md) |  | Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL. |
-| skill | [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) |  | Use when orchestrating implementer/judge subagents — six modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate, do-in-worktrees) — models from .agent-settings.yml. |
+| skill | [`subagent-orchestration`](../.agent-src/skills/subagent-orchestration/SKILL.md) |  | Use when orchestrating implementer/judge subagents — seven modes (do-and-judge ±two-stage, do-in-steps/parallel/worktrees, do-competitively, judge-with-debate) — models from .agent-settings.yml. |
 | skill | [`systematic-debugging`](../.agent-src/skills/systematic-debugging/SKILL.md) |  | Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'. |
 | skill | [`technical-specification`](../.agent-src/skills/technical-specification/SKILL.md) |  | Use when the user says "write a spec", "create RFC", "write a PRD", or "document this decision". Writes technical specifications, PRDs, RFCs, and ADRs with clear structure. |
 | skill | [`terraform`](../.agent-src/skills/terraform/SKILL.md) |  | Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform. |
@@ -227,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 (101)
+## Commands (103)
 
 | kind | name | cluster | description |
 |---|---|---|---|
@@ -312,6 +312,8 @@ 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:deep`](../.agent-src/commands/research/deep.md) | cluster: research | Read `outline.yaml`, research each item in batches, write per-item JSON validated against the project-local research-schema. No Python runtime, no `~/.claude/` paths. |
+| command | [`research:report`](../.agent-src/commands/research/report.md) | cluster: research | Summarise per-item JSON results from `/research:deep` into `report.md`. Agent renders directly + emits an optional `jq` template for deterministic regeneration. No Python runtime. |
 | 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 |
@@ -333,18 +335,21 @@ 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 (63)
+## Guidelines (68)
 
 | kind | name | category | description |
 |---|---|---|---|
+| guideline | [`5w2h-analysis`](../docs/guidelines/agent-infra/5w2h-analysis.md) | agent-infra |  |
 | guideline | [`agent-interaction-and-decision-quality`](../docs/guidelines/agent-infra/agent-interaction-and-decision-quality.md) | agent-infra |  |
 | guideline | [`ask-when-uncertain-demos`](../docs/guidelines/agent-infra/ask-when-uncertain-demos.md) | agent-infra |  |
 | guideline | [`asking-and-brevity-examples`](../docs/guidelines/agent-infra/asking-and-brevity-examples.md) | agent-infra |  |
 | guideline | [`break-glass-usage`](../docs/guidelines/agent-infra/break-glass-usage.md) | agent-infra |  |
 | guideline | [`carve-out-predicates`](../docs/guidelines/agent-infra/carve-out-predicates.md) | agent-infra |  |
+| guideline | [`critical-thinking`](../docs/guidelines/agent-infra/critical-thinking.md) | agent-infra |  |
 | 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 | [`first-principles`](../docs/guidelines/agent-infra/first-principles.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 |  |
@@ -362,8 +367,10 @@ are excluded.
 | 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 | [`six-hats`](../docs/guidelines/agent-infra/six-hats.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 |  |
+| guideline | [`systems-thinking`](../docs/guidelines/agent-infra/systems-thinking.md) | agent-infra |  |
 | guideline | [`tool-integration`](../docs/guidelines/agent-infra/tool-integration.md) | agent-infra |  |
 | guideline | [`verify-before-complete-demos`](../docs/guidelines/agent-infra/verify-before-complete-demos.md) | agent-infra |  |
 | guideline | [`augment-portability-patterns`](../docs/guidelines/augment-portability-patterns.md) | (root) |  |

package/docs/contracts/command-clusters.md

@@ -43,7 +43,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. |
+| `research` | 2 | `deep` · `report` | preliminary-research scaffolder ported from `Weizhena/Deep-Research-skills` (cluster head emits `outline.yaml` + `fields.yaml` against the `research-schema` contract). `:deep` populates per-item JSON in batches with native web-search + JSON-Schema self-validation (no Python runtime); `:report` renders `report.md` directly + optionally emits a `jq` template for deterministic regeneration. `add-items` / `add-fields` intentionally **not** ported — re-run `/research <topic>` to extend the field framework. |
 
 **Net change:** Phase 1 collapsed 15 atomics → 3 clusters; Phase 2
 collapses 26 atomics → 11 sub-command clusters. Sub-commands use