@event4u/agent-config 1.32.0 → 1.33.0

package/.agent-src/commands/research/deep.md

@@ -0,0 +1,149 @@
+---
+name: research:deep
+cluster: research
+sub: deep
+description: "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."
+disable-model-invocation: true
+skills: [deep-reading-analyst]
+suggestion:
+  eligible: true
+  trigger_description: "deep research, populate the research scaffold, fill outline.yaml items"
+  trigger_context: "user has run `/research <topic>` and now wants per-item depth"
+---
+
+# /research:deep
+
+Reads the `outline.yaml` produced by [`/research`](../research.md), launches
+batched per-item research, and writes one JSON per item under
+`{output_dir}/`. Each JSON is self-validated against the
+[`research-schema`](../../contexts/contracts/research-schema.md)
+contract before write — **no `validate_json.py` script, no Python
+runtime, no `~/.claude/` paths**.
+
+## Trigger
+
+`/research:deep [--batch-confirm=each|once|auto]`
+
+`--batch-confirm` controls user gating between batches:
+
+- `each` (default) — confirm before every batch.
+- `once` — confirm only the first batch, then run the rest.
+- `auto` — no confirmation, run all batches (only honoured under
+  explicit `/roadmap process-full` autonomy).
+
+## Workflow
+
+### Step 1 — Auto-locate outline
+
+Search `$PROJECT_ROOT/agents/research/*/outline.yaml` (single match) or
+ask via numbered options if multiple `outline.yaml` files exist. Read:
+
+- `topic`, `topic_slug`, `items[]`, `execution.batch_size`,
+  `execution.items_per_agent`, `execution.output_dir` (default
+  `./results` relative to the topic dir).
+
+### Step 2 — Resume check
+
+Scan `{output_dir}/` for `*.json` files; mark items whose
+`{slug(item.name)}.json` exists as **complete**. Slugify by lowercasing,
+replacing whitespace with `_`, and stripping characters outside
+`[a-z0-9_-]`.
+
+### Step 3 — Batch execution
+
+Group remaining items by `batch_size` (each batch holds
+`batch_size × items_per_agent` items at most). For each batch:
+
+1. Show the batch summary: `[N/M] items: a, b, c …`.
+2. Apply the `--batch-confirm` policy (default `each` — wait for the
+   user; `once` after the first; `auto` skips).
+3. For every item in the batch, run the per-item research using the
+   agent's **native web-search** (no `web-search-agent` persona).
+
+#### Per-item prompt template
+
+Variables in `{xxx}` only — **do not modify structure or wording**.
+
+```text
+## Task
+Research {item_related_info}, output structured JSON to {output_path}.
+
+## Field definitions
+Read {fields_path} to get all field definitions.
+
+## Output requirements
+1. Output JSON whose top-level keys map to the categories in
+   `fields.yaml` (or to the `{slug(category)}` form — both are
+   accepted by `/research:report`).
+2. Mark uncertain field values with the literal string `[uncertain]`.
+3. Append an `uncertain` array at the end of the JSON listing all
+   field names whose value contains `[uncertain]` or could not be
+   sourced.
+4. All field values in English.
+
+## Output path
+{output_path}
+
+## Validation (no Python, no host paths)
+Self-validate the JSON against
+`<package>/.agent-src.uncompressed/contexts/contracts/research-schema.md`
+in memory before writing. The well-formedness escape hatch is
+`jq -e '.[]' {output_path}` — agent runs it after write and re-tries
+once on failure. Task is complete only after both checks pass.
+```
+
+#### Variable bindings
+
+| Variable | Source |
+|---|---|
+| `{topic}` | `outline.yaml#/topic` |
+| `{item_related_info}` | the item's full YAML block (`name`, `category`, `description`, etc.) |
+| `{output_dir}` | `outline.yaml#/execution/output_dir` (default `./results`) |
+| `{fields_path}` | `$PROJECT_ROOT/agents/research/{topic_slug}/fields.yaml` |
+| `{output_path}` | `{output_dir}/{slug(item.name)}.json` |
+
+### Step 4 — Wait and monitor
+
+Wait for the current batch to finish (all per-item JSON files written
++ validated). Display per-item status (`✅ done`, `⚠️ uncertain`,
+`❌ failed`) before moving on.
+
+### Step 5 — Summary report
+
+After all batches complete, print:
+
+- Total items · completed · uncertain · failed.
+- Output directory.
+- Pointer to `/research:report` for the next phase.
+
+## Output paths
+
+```text
+$PROJECT_ROOT/agents/research/{topic_slug}/
+  ├── outline.yaml
+  ├── fields.yaml
+  └── {output_dir}/
+        ├── {slug(item_a)}.json
+        ├── {slug(item_b)}.json
+        └── …
+```
+
+## Portability notes
+
+- **No Python runtime** — validator dropped at adoption, replaced by
+  the in-memory JSON-Schema check + `jq -e` escape hatch (`jq` is
+  optional; agents skip it gracefully if not installed and report
+  `⚠️ jq missing — well-formedness not verified`).
+- **No `~/.claude/` paths** — every reference is rooted at
+  `$PROJECT_ROOT/agents/research/`.
+- **No `web-search-agent` persona** — uses the host agent's native
+  web-search tool.
+
+## ADOPT citation
+
+Adopted from [`Weizhena/Deep-Research-skills`](https://github.com/Weizhena/Deep-Research-skills)
+`@dc18cf4:skills/research-en/research-deep/SKILL.md` · MIT License.
+Refactored:
+dropped Pydantic validator + `~/.claude/` paths + `web-search-agent`
+persona, added `--batch-confirm` flag, kept the per-item prompt
+structure verbatim except for the validation block.

package/.agent-src/commands/research/report.md

@@ -0,0 +1,134 @@
+---
+name: research:report
+cluster: research
+sub: report
+description: "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."
+disable-model-invocation: true
+skills: [deep-reading-analyst]
+suggestion:
+  eligible: true
+  trigger_description: "summarise research results, build research report, render outline.yaml results"
+  trigger_context: "user has finished `/research:deep` and wants a single markdown summary"
+---
+
+# /research:report
+
+Reads the per-item JSON files emitted by
+[`/research:deep`](deep.md), asks the user which fields to surface in
+the table of contents, then writes `{topic_slug}/report.md` directly.
+Optionally emits `{topic_slug}/report-template.jq` so the same report
+can be regenerated deterministically without re-invoking the agent.
+
+## Trigger
+
+`/research:report`
+
+## Workflow
+
+### Step 1 — Locate results
+
+Find `$PROJECT_ROOT/agents/research/*/outline.yaml` (single match) or
+ask via numbered options. Read `topic`, `topic_slug`, and
+`execution.output_dir`.
+
+### Step 2 — Scan summary-field candidates
+
+Read every `*.json` in `{output_dir}/`. Collect field names whose
+values are short / numeric (e.g. `github_stars`,
+`google_scholar_cites`, `swe_bench_score`, `user_scale`, `valuation`,
+`release_date`). Filter:
+
+- numeric scalars (int / float),
+- short strings (≤ 40 chars), or
+- ISO-8601 dates.
+
+### Step 3 — Ask user (numbered options)
+
+Per [`user-interaction`](../../rules/user-interaction.md) Iron Law,
+offer numbered options for **TOC summary fields** drawn from the
+candidate list. Allow multi-select (e.g., *"1, 3, 5"*) plus *"none"*.
+
+### Step 4 — Render `report.md` directly
+
+The agent itself reads each JSON + `fields.yaml` + the user's TOC
+choices, then writes `{topic_slug}/report.md`. **No `generate_report.py`
+script, no Python runtime.**
+
+#### Required structure
+
+1. **Title** — `# {topic} — Research Report`.
+2. **TOC** — every item, anchor-linked, with the chosen summary fields
+   inline. Example:
+   `1. [GitHub Copilot](#github-copilot) — Stars: 10k · Score: 85%`.
+3. **Detailed sections** — one `## {item.name}` per item, then
+   `### {category}` per category from `fields.yaml`, then field
+   key/value rows.
+
+#### Rendering rules
+
+| Rule | Behaviour |
+|---|---|
+| **JSON shape** | Support flat (`{"name": "…"}`) and nested (`{"basic_info": {"name": "…"}}`) layouts. Lookup order: top-level → category mapping → recursive walk. |
+| **Category mapping** | Maintain a bidirectional alias map between `fields.yaml` category labels and JSON keys (e.g. `"Basic info" ↔ "basic_info"`). Use language-neutral keys, no hard-coded English/Chinese. |
+| **List of dicts** | One row per dict, `key:value` pairs joined with ` \| `. |
+| **Plain list** | Short → comma-joined; long (> 5 items) → bullet list. |
+| **Nested dict** | Recurse; render with `;` between sibling keys or hard-break on long values. |
+| **Long text** | Strings > 100 chars → wrap in a blockquote or insert `<br>`. |
+| **Extra fields** | JSON keys not declared in `fields.yaml` → group under `### Other info`. Filter `_source_file`, `uncertain`, and category-container keys. |
+| **`uncertain` array** | Render each entry on its own line under `### Uncertain fields`; never compress to a one-liner. |
+| **Skip conditions** | Field value contains `[uncertain]` · field name in `uncertain` · value is `null` / empty string. |
+
+### Step 5 — Optional `jq` template (deterministic regenerate)
+
+Also emit `{topic_slug}/report-template.jq` capturing the user's TOC
+choices + rendering rules as a `jq` program. Document the regenerate
+command in the file's leading comment:
+
+```text
+# Regenerate report.md without re-invoking the agent:
+#   jq -rsf report-template.jq results/*.json > report.md
+# Requires: jq ≥ 1.6. Skip this file if jq is unavailable —
+# `report.md` from step 4 is the canonical artefact.
+```
+
+The template is **best-effort**. Agents that cannot fully express
+the rendering rules in `jq` may emit a stub with a `# TODO` comment
+and a pointer back to step 4. The primary deliverable is `report.md`;
+the `jq` template is a power-user convenience.
+
+### Step 6 — Confirm
+
+Print:
+
+- Path to `report.md`.
+- Whether `report-template.jq` was emitted.
+- Item count · category count · skipped-uncertain count.
+
+## Output paths
+
+```text
+$PROJECT_ROOT/agents/research/{topic_slug}/
+  ├── report.md             # primary artefact (agent-rendered)
+  └── report-template.jq    # optional, deterministic regen
+```
+
+## Portability notes
+
+- **No Python runtime** — upstream's `generate_report.py` was a
+  Python conversion script; this port shifts the transformation to
+  the agent (primary) + a `jq` template (optional). `augment-portability`
+  Iron Law upheld.
+- **No `~/.claude/` paths** — every reference is rooted at
+  `$PROJECT_ROOT/agents/research/`.
+- **`jq` is optional** — agents skip the template gracefully and
+  surface `⚠️ jq template not emitted` in the summary if generation
+  fails or the dependency is missing.
+
+## ADOPT citation
+
+Adopted from [`Weizhena/Deep-Research-skills`](https://github.com/Weizhena/Deep-Research-skills)
+`@dc18cf4:skills/research-en/research-report/SKILL.md` · MIT License.
+Refactored: dropped the `generate_report.py` Python script (replaced
+with agent-side rendering + optional `jq` template), kept the
+multilingual category mapping + complex-value formatting rules,
+re-anchored every path under `$PROJECT_ROOT/agents/research/`.

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

@@ -12,15 +12,43 @@ suggestion:
 
 # /research
 
-Entry point for **preliminary research**: pick the objects to study, name
-the fields to fill, and emit a YAML scaffold that a downstream deep-research
-run will populate. Use this when the user names a topic and wants a
-structured plan, not an immediate answer.
+Top-level entry point for the `/research` family. Bare `/research <topic>`
+runs the preliminary scaffolder described under `## Default flow`. Sub-commands
+drive the downstream phases (`:deep` populates the scaffold, `:report`
+summarises the results).
 
 Routes thinking-framework support to
 [`deep-reading-analyst`](../skills/deep-reading-analyst/SKILL.md) (SCQA
 for narrative structure, mental-models lens for object selection).
 
+## Sub-commands
+
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/research <topic>` (bare) | this file (`## Default flow`) | Pick objects, define fields, emit `outline.yaml` + `fields.yaml` |
+| `/research:deep` | `commands/research/deep.md` | Read scaffold, research each item in batches, write per-item JSON |
+| `/research:report` | `commands/research/report.md` | Summarise per-item JSON into a markdown report (+ optional `jq` template) |
+
+## Dispatch
+
+1. Parse the user's argument: `/research[:<sub>] [args]`.
+2. Bare `/research <topic>` → run the `## Workflow` below verbatim.
+3. `/research:deep` → load `commands/research/deep.md` and follow its
+   `## Workflow` section verbatim.
+4. `/research:report` → load `commands/research/report.md` and follow its
+   `## Workflow` section verbatim.
+5. Unknown sub-command → print the table above and ask which one.
+
+## Rules
+
+- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
+  authorizes it.
+- **Do NOT chain sub-commands.** One `/research[:<sub>]` per turn.
+- If the user invokes `/research` with no argument, **show the menu** —
+  do not guess whether they meant the bare workflow or a sub-command.
+- **Edit `.agent-src.uncompressed/` only.** `.agent-src/` and `.augment/`
+  regenerate from source.
+
 ## Trigger
 
 `/research <topic>`
@@ -126,17 +154,19 @@ $PROJECT_ROOT/agents/research/{topic_slug}/
   └── fields.yaml     # field definitions
 ```
 
-## Out of scope (Phase 2)
+## Out of scope
 
-`/research-deep`, `/research-add-items`, `/research-add-fields`, and the
-Python `validate_json.py` validator are **not** ported in Phase 1 — they
-are queued as follow-up cluster sub-commands.
+`/research:add-items` and `/research:add-fields` are **not** ported —
+the existing scaffolder + sub-commands cover the round-trip; the
+upstream incremental-edit commands are too thin to justify their own
+sub-command. Re-run `/research <topic>` and merge by hand if the
+field framework needs a follow-up adjustment.
 
 ## ADOPT citation
 
 Adopted from [`Weizhena/Deep-Research-skills`](https://github.com/Weizhena/Deep-Research-skills)
-@ commit `dc18cf4` · upstream file research/SKILL.md inside skills/research-en/ · MIT License.
-Refactored: dropped `web-search-agent` persona (portability), dropped
-Pydantic validator (replaced with JSON-Schema reference), repathed
-`./` → `$PROJECT_ROOT/agents/research/`, deferred `/research-deep` +
-`/research-add-*` to Phase 2.
+`@dc18cf4:skills/research-en/research/SKILL.md` · MIT License.
+Refactored: dropped `web-search-agent` persona
+(portability), dropped Pydantic validator (replaced with JSON-Schema
+reference), repathed `./` → `$PROJECT_ROOT/agents/research/`. Phase 2
+ported `/research:deep` and `/research:report` as cluster sub-commands.

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.32.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,33 @@ 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

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.
 
@@ -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

package/docs/contracts/file-ownership-matrix.json

@@ -495,6 +495,18 @@
       "load_context": [],
       "load_context_eager": []
     },
+    ".agent-src.uncompressed/commands/research/deep.md": {
+      "kind": "command",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
+    ".agent-src.uncompressed/commands/research/report.md": {
+      "kind": "command",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
     ".agent-src.uncompressed/commands/review-changes.md": {
       "kind": "command",
       "rule_type": null,
@@ -3380,6 +3392,48 @@
       "via": "body_link",
       "depth": 1
     },
+    {
+      "source": ".agent-src.uncompressed/commands/research/deep.md",
+      "target": ".agent-src.uncompressed/commands/research.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/research/deep.md",
+      "target": ".agent-src.uncompressed/commands/research/deep.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/research/deep.md",
+      "target": ".agent-src.uncompressed/contexts/contracts/research-schema.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/research/report.md",
+      "target": ".agent-src.uncompressed/commands/research/deep.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/research/report.md",
+      "target": ".agent-src.uncompressed/commands/research/report.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
+    {
+      "source": ".agent-src.uncompressed/commands/research/report.md",
+      "target": ".agent-src.uncompressed/rules/user-interaction.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/commands/review-changes.md",
       "target": ".agent-src.uncompressed/commands/judge.md",

package/docs/getting-started.md

@@ -153,7 +153,7 @@ Your agent now understands slash commands:
 | `/quality-fix` | Run and fix all quality checks |
 | `/chat-history` | Inspect the persistent chat-history log (read-only `show`) |
 
-→ [Browse all 101 active commands](../.agent-src/commands/)
+→ [Browse all 103 active commands](../.agent-src/commands/)
 
 ---