@event4u/agent-config 1.27.0 → 1.28.0

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

@@ -0,0 +1,142 @@
+---
+name: research
+cluster: research
+description: "Preliminary research scaffolder — pick objects, define fields, emit `outline.yaml` + `fields.yaml` for downstream deep research. Use for surveys, benchmarks, tech selection, competitive scans."
+disable-model-invocation: true
+skills: [project-analyzer, deep-reading-analyst]
+suggestion:
+  eligible: true
+  trigger_description: "research a topic, scan competitors, benchmark X, do a tech-selection survey"
+  trigger_context: "user names a research topic and wants a structured scaffold (objects + fields), not an immediate answer"
+---
+
+# /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.
+
+Routes thinking-framework support to
+[`deep-reading-analyst`](../skills/deep-reading-analyst/SKILL.md) (SCQA
+for narrative structure, mental-models lens for object selection).
+
+## Trigger
+
+`/research <topic>`
+
+## Workflow
+
+### Step 1 — Initial framework from model knowledge
+
+Generate, from the model's existing knowledge, the candidate object list
+and field framework for the topic:
+
+- **Objects / items** — entities, products, methods, datasets to compare.
+- **Field framework** — dimensions to fill per item (basic info, technical
+  features, evidence, etc.).
+
+Output `{step1_output}` and confirm with the user via numbered options
+(per [`user-interaction`](../rules/user-interaction.md) Iron Law):
+
+1. Add or remove items?
+2. Field framework adequate?
+
+### Step 2 — Web-search supplement
+
+Ask one numbered question for the time range (e.g., last 6 months,
+since 2024, unlimited). Use the agent's native web-search tool — do
+**not** spawn a separate `web-search-agent` persona.
+
+Search prompt template (variables in `{xxx}` only — do not modify
+structure):
+
+```text
+Research topic: {topic}
+Current date: {YYYY-MM-DD}
+Time range: {time_range}
+
+Existing framework:
+{step1_output}
+
+Goals:
+1. Verify existing items are not missing important objects.
+2. Supplement items based on missing objects.
+3. Continue searching for {topic}-related items within {time_range}.
+4. Supplement new fields where helpful.
+
+Output (return inline, do not write files):
+
+### Supplementary items
+- item_name: brief explanation (why it should be added)
+
+### Recommended supplementary fields
+- field_name: field description (why this dimension is needed)
+
+### Sources
+- [Source 1](url)
+- [Source 2](url)
+```
+
+### Step 3 — Existing fields merge
+
+Ask via numbered options whether the user has an existing field-definition
+file. If yes, read the file and merge into the framework before Step 4.
+
+### Step 4 — Generate outline (two files)
+
+Merge `{step1_output}`, `{step2_output}`, and any user-provided fields,
+then write two files into `$PROJECT_ROOT/agents/research/{topic_slug}/`:
+
+**`outline.yaml`** (items + execution config):
+
+- `topic`: research topic
+- `items`: research-objects list
+- `execution`: `batch_size`, `items_per_agent`, `output_dir`
+  (defaults: `./results`; confirm with the user via numbered options)
+
+**`fields.yaml`** (field definitions):
+
+- field categories + definitions
+- per field: `name`, `description`, `detail_level`
+  (`brief` → `moderate` → `detailed`)
+- `uncertain`: list reserved for the deep-research phase
+
+YAML structure validation: see
+[`research-schema`](../contexts/contracts/research-schema.md) for the
+project-local JSON-Schema reference (no runtime Python validator; the
+agent reads the schema and self-validates).
+
+### Step 5 — Output + confirm
+
+Create `agents/research/{topic_slug}/` if absent, write both YAML files,
+and present a summary block to the user:
+
+- Topic + slug.
+- Item count + field count.
+- Path to the two files.
+- Next-step pointer: deep-research orchestration is a follow-up port;
+  use the YAML scaffold as input when that lands.
+
+## Output paths
+
+```text
+$PROJECT_ROOT/agents/research/{topic_slug}/
+  ├── outline.yaml    # items list + execution config
+  └── fields.yaml     # field definitions
+```
+
+## Out of scope (Phase 2)
+
+`/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.
+
+## 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.

package/.agent-src/contexts/contracts/frugality-charter.md

@@ -21,9 +21,10 @@ Cite the source rule in writer artifacts; do **not** restate it here.
 
 ## Confirmation taxonomy
 
-Iron-Law / Routine / Contextual classification with carve-outs
-lives in the roadmap [`§ Confirmation taxonomy`](../../../agents/roadmaps/road-to-token-frugality.md#confirmation-taxonomy).
-Charter does not duplicate the table.
+Iron-Law / Routine / Contextual classification with carve-outs is
+canonical in the active token-frugality plate under `agents/roadmaps/`
+(or `agents/roadmaps/archive/` once closed). Charter does not duplicate
+the table.
 
 ## Settings hooks
 

package/.agent-src/contexts/contracts/research-schema.md

@@ -0,0 +1,117 @@
+# research-schema
+
+Project-local JSON-Schema reference for the
+[`/research`](../../commands/research.md) command's two output files —
+`outline.yaml` and `fields.yaml`. The agent reads the schemas below and
+self-validates the YAML before writing; **no runtime Python validator
+ships in this package** — the Pydantic validator from upstream was
+dropped at adoption time and replaced with this reference contract.
+
+## `outline.yaml` schema
+
+```yaml
+# JSON-Schema (YAML form) — outline.yaml
+type: object
+required: [topic, items, execution]
+properties:
+  topic:
+    type: string
+    description: Research topic, free-form.
+  topic_slug:
+    type: string
+    pattern: "^[a-z0-9][a-z0-9-]*$"
+    description: Lower-kebab slug used as the directory name.
+  items:
+    type: array
+    minItems: 1
+    items:
+      type: object
+      required: [name]
+      properties:
+        name: { type: string }
+        explanation: { type: string }
+        source: { type: string, format: uri }
+  execution:
+    type: object
+    required: [batch_size, items_per_agent, output_dir]
+    properties:
+      batch_size:
+        type: integer
+        minimum: 1
+        description: Number of parallel agents in the deep-research phase.
+      items_per_agent:
+        type: integer
+        minimum: 1
+        description: Items each agent processes per batch.
+      output_dir:
+        type: string
+        default: "./results"
+        description: Path (relative to the topic dir) for deep-research output.
+```
+
+## `fields.yaml` schema
+
+```yaml
+# JSON-Schema (YAML form) — fields.yaml
+type: object
+required: [categories]
+properties:
+  categories:
+    type: array
+    minItems: 1
+    items:
+      type: object
+      required: [name, fields]
+      properties:
+        name:
+          type: string
+          description: Category label (e.g., "Basic info", "Technical features").
+        fields:
+          type: array
+          minItems: 1
+          items:
+            type: object
+            required: [name, description, detail_level]
+            properties:
+              name: { type: string }
+              description: { type: string }
+              detail_level:
+                type: string
+                enum: [brief, moderate, detailed]
+  uncertain:
+    type: array
+    description: Reserved field, populated during deep-research phase.
+    items:
+      type: object
+      properties:
+        item: { type: string }
+        field: { type: string }
+        reason: { type: string }
+```
+
+## Self-validation procedure
+
+1. Generate the YAML in memory.
+2. Walk the schema above against the candidate object.
+3. On mismatch, fix the YAML before writing — do not write invalid
+   files and rely on a downstream check.
+4. Validation diagnostics surface to the user inline (file path,
+   field path, expected vs actual). No external dependencies.
+
+## Why no Pydantic / runtime validator
+
+Upstream (`Weizhena/Deep-Research-skills`) shipped a `validate_json.py`
+Pydantic-based validator that assumed `~/.claude/` paths and a Python
+runtime in the consumer environment. Both are
+`augment-portability` violations for this package (zero-runtime-Python
+goal, host-agnostic distribution). The schema reference above lets the
+agent validate by reading; consumers needing programmatic validation
+can pipe the YAML through any JSON-Schema validator they prefer
+(`ajv`, `python-jsonschema`, `check-jsonschema`, etc.).
+
+## Cross-references
+
+- [`/research`](../../commands/research.md) — the command this schema
+  validates.
+- Future `/research:deep` and `/research:report` sub-commands will
+  reference this same schema once ported.

package/.agent-src/rules/domain-adoption-policy.md

@@ -2,7 +2,7 @@
 type: "auto"
 tier: "2b"
 alwaysApply: false
-description: "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"
+description: "Adopting a new domain track (mobile, ML, blockchain, IoT, gaming) — gates import on demand, ownership, CI fit, Sunset compatibility BEFORE harvest"
 source: package
 triggers:
   - intent: "adopt new domain"

package/.agent-src/rules/no-roadmap-references.md

@@ -1,7 +1,7 @@
 ---
 type: "auto"
 tier: "mechanical-already"
-description: "Linking transient files (agents/roadmaps/, agents/council-{questions,responses,sessions}/) from a stable artifact — both layers expire; promote findings"
+description: "Linking transient files (agents/roadmaps/, agents/council-*/) from a stable artifact — both layers expire; promote findings"
 alwaysApply: false
 source: package
 triggers:

package/.agent-src/rules/no-unsolicited-rebase.md

@@ -2,7 +2,7 @@
 type: "auto"
 tier: "2a"
 alwaysApply: false
-description: "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"
+description: "Working with git history — never rewrite, rebase, squash, fixup, or amend without explicit user request; shape is the user's call, not tidiness"
 source: package
 triggers:
   - intent: "rebase the branch"

package/.agent-src/rules/scope-control.md

@@ -28,15 +28,15 @@ The user decides the git shape. Never improvise. Commit specifics: canonical [`c
 - NEVER create / switch / delete a branch without explicit permission — includes spike, scratch, throwaway, worktree branches.
 - NEVER create, close, reopen, or change the target of a pull request without permission.
 - NEVER push a tag or create a release without permission.
-- NEVER include version numbers, target releases, deprecation dates, release-tied milestones, or git tags in roadmaps, plans, tickets, or any planning artifact. Roadmaps plan **work**; releases / tags are a separate decision outside the roadmap. Never surface "which release should this ship in?" as a numbered choice. User pins by saying so explicitly.
+- NEVER include version numbers, target releases, deprecation dates, release-tied milestones, or git tags in roadmaps, plans, tickets, or any planning artifact. Roadmaps plan **work**; releases / tags are a separate decision. User pins by saying so explicitly.
 - Task seems to need a separate branch / PR → STOP and **brief before asking** ([`scope-mechanics § Brief-before-asking`](../contexts/authority/scope-mechanics.md)).
-- BEFORE the first commit on related work, **inventory** existing branches and open PRs (`git branch --show-current`, `gh pr list --state open`). If a plausible base beyond the current branch exists, STOP and ask with numbered options — never improvise the base. Inventory + 4-option template + diverging-stack failure mode: [`scope-mechanics § Branch-base inventory`](../contexts/authority/scope-mechanics.md).
+- BEFORE the first commit on related work, **inventory** existing branches and open PRs. Plausible base beyond the current branch → STOP and ask with numbered options — never improvise. Commands + 4-option template + diverging-stack failure mode: [`scope-mechanics § Branch-base inventory`](../contexts/authority/scope-mechanics.md).
 
 "Explicit permission" = user said so **this turn or in a standing instruction not yet revoked**. Earlier permission for a different operation does not carry over.
 
 ## Production, infrastructure, bulk-destructive — Hard Floor
 
-A subset is **never** autonomous and never auto-permitted by a standing autonomy directive. Canonical: [`non-destructive-by-default`](non-destructive-by-default.md). Trigger list (prod-branch merges, deploys / releases, prod data / infra, bulk-destructive ops) and the "authorization is this turn, not earlier" clarification: [`scope-mechanics § Production, infrastructure, bulk-destructive`](../contexts/authority/scope-mechanics.md).
+A subset is **never** autonomous, regardless of standing autonomy. Canonical: [`non-destructive-by-default`](non-destructive-by-default.md). Triggers (prod-branch merges, deploys, prod data / infra, bulk-destructive) + this-turn-only clarification: [`scope-mechanics § Production, infrastructure, bulk-destructive`](../contexts/authority/scope-mechanics.md).
 
 ## Kernel-rule edits — slow-rollout guarantee
 
@@ -44,11 +44,11 @@ Each kernel-rule edit ships in **its own PR**, ≥ 24 h between merges. Autonomo
 
 ## Decline = silence — no re-asking on the same task
 
-After the user **declines** a proposal (branch switch, PR creation, tag/release entry, separate worktree, version pinning), do **not** raise it again on the same task. Decline stands until the user reopens the topic. Timing / "is this worth asking?": [`scope-mechanics § Decline = silence`](../contexts/authority/scope-mechanics.md).
+After the user **declines** a proposal (branch switch, PR creation, tag/release, separate worktree, version pinning), do **not** raise it again on the same task. Decline stands until reopened. Timing: [`scope-mechanics § Decline = silence`](../contexts/authority/scope-mechanics.md).
 
 ## Fenced step — user-set review gates
 
-User explicitly fences off the next step — *"don't implement yet"*, *"plan only"*, *"just write the roadmap, I'll review"*, *"review first"*, *"erst Roadmap, ich schau drüber"*, *"nichts implementieren"*, *"nur planen"*, *"erstmal nur X, dann ich"* — reply is **the deliverable plus a handoff**, never deliverable plus *"shall we start?"*.
+User explicitly fences off the next step (*"plan only"*, *"review first"*, *"don't implement yet"*, German equivalents) — reply is **deliverable + handoff**, never deliverable + *"shall we start?"*.
 
 ```
 USER FENCED OFF EXECUTION → DELIVER + HAND BACK.
@@ -57,6 +57,4 @@ NO "READY TO IMPLEMENT?" RE-ASK.
 NO "STARTEN WIR MIT PHASE 1?" PIVOT.
 ```
 
-Fence stands until the user reopens, exactly like `Decline = silence`. Permitted follow-up questions cover **the deliverable** (adjust scope, fix wording, add a section), never **its execution**.
-
-Failure-mode catalog (Option 1 = "start now", re-asking after delivery, hand-off-to-execution drift, inferring acceptance from a thumbs-up) and explicit bypass phrases: [`scope-mechanics § Fenced step`](../contexts/authority/scope-mechanics.md).
+Fence stands until reopened (like `Decline = silence`). Follow-ups cover **the deliverable** (scope, wording, sections), never its execution. Failure modes + bypass phrases: [`scope-mechanics § Fenced step`](../contexts/authority/scope-mechanics.md).

package/.agent-src/skills/deep-reading-analyst/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: deep-reading-analyst
+description: "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."
+status: active
+source: package
+external_source: "https://github.com/ginobefun/deep-reading-analyst-skill/tree/26cd7dc9920e025d39751e396e707399022e49ef/src/deep-reading-analyst"
+refresh_trigger: "Upstream `ginobefun/deep-reading-analyst-skill` major rewrite (new framework added, dispatch table reshaped, or SHA pin invalidated by reference rename)."
+sunset_criterion: "Replace with a 50-line pointer skill if (a) all referenced modules are adopted as project-local guidelines (`docs/guidelines/agent-infra/{framework}.md`) AND (b) the dispatch logic moves into a project-native router."
+---
+
+> **Pinned upstream:** `ginobefun/deep-reading-analyst-skill` @ SHA `26cd7dc9` (MIT). Re-verify per upstream major rewrite. Reference modules below link to the same SHA.
+
+# deep-reading-analyst
+
+Wing-1 deep-thinking skill for articles, papers, opinion pieces, case studies, and long-form decision documents. Routes the user's content through 8 thinking frameworks at four depth levels (Quick / Standard / Deep / Research) and returns insight tied to the user's **goal**, not framework completion.
+
+## When to use
+
+- User pastes an article URL, paper, or long text and wants depth ("analyze", "deep dive", "extract insights", "help me understand").
+- User asks for a specific framework ("apply SCQA to this", "use inversion thinking", "give me the mental models lens").
+- User is making a decision and wants pre-mortem / multi-lens analysis on a written proposal.
+- User is studying or note-taking on dense material (research papers, strategy memos, books).
+
+Do NOT use when:
+- User wants a 3-bullet TL;DR — use `agent-docs-writing` or write a direct summary.
+- Content is code or a diff — route to `judge-bug-hunter`, `judge-code-quality`, or `adversarial-review`.
+- User wants risk analysis on a code change — route to `adversarial-review` (diff-bound) or `threat-modeling`.
+- User wants debugging or incident analysis — route to `bug-analyzer` or `systematic-debugging`.
+
+## Framework Arsenal
+
+| Depth | Time | Frameworks | Reference module |
+|---|---|---|---|
+| **L1 — Quick** | ~15 min | SCQA, 5W2H | [`scqa-framework`](../../../docs/guidelines/agent-infra/scqa-framework.md), `5w2h_analysis.md` (upstream) |
+| **L2 — Standard** | ~30 min | L1 + Critical Thinking, Inversion | + [`inversion-thinking`](../../../docs/guidelines/agent-infra/inversion-thinking.md), `critical_thinking.md` (upstream) |
+| **L3 — Deep** | ~60 min | L2 + Mental Models, First Principles, Systems Thinking, Six Hats | + [`mental-models`](../../../docs/guidelines/agent-infra/mental-models.md), `first_principles.md`, `systems_thinking.md`, `six_hats.md` (upstream) |
+| **L4 — Research** | 120 min+ | L3 + Cross-source comparison via web search | + `comparison_matrix.md` (upstream) |
+
+Modules tagged `(upstream)` link to SHA-pinned files at the URL in `external_source` above; project-local modules are adopted as guidelines.
+
+## Procedure: deep-reading-analyst
+
+### Step 0: Inspect
+
+1. **Detect content type** — article, paper, opinion piece, case study, how-to, strategy memo. Drives auto-suggested frameworks (Step 1).
+2. **Detect goal signal** — problem-solving, learning, writing reference, decision-making, curiosity. Drives Step 4 output shape.
+3. **Skip if mismatched** — see "Do NOT use when" above; route to the named skill.
+
+### Step 1: Initialize Analysis
+
+Ask the user three things in **one** message (not three turns), per `ask-when-uncertain` Iron Law (one question per turn — these three are bundled into a single numbered-options block):
+
+1. **Goal** — problem-solving · learning · writing · decision-making · curiosity.
+2. **Depth** — L1 Quick (15 min) · L2 Standard (30 min) · L3 Deep (60 min) · L4 Research (120 min+).
+3. **Framework override** — defaults are auto-suggested by content type (table below); user may name specific frameworks.
+
+If the user does not answer, default to L2 Standard with auto-selected frameworks.
+
+**Auto-suggest matrix:**
+
+| Content type | Default frameworks |
+|---|---|
+| Strategy / business article | SCQA + Mental Models + Inversion |
+| Research paper | 5W2H + Critical Thinking + Systems Thinking |
+| How-to guide | SCQA + 5W2H + First Principles |
+| Opinion piece | Critical Thinking + Inversion + Six Hats |
+| Case study | SCQA + Mental Models + Systems Thinking |
+
+### Step 2: Structural Understanding (always run)
+
+Regardless of depth, open with two short blocks:
+
+**2A — Basic structure.**
+
+```markdown
+📄 Type: [article/paper/report]
+🎯 Core thesis: [one sentence]
+Structure:
+├─ Argument 1 → [key support]
+├─ Argument 2 → [key support]
+└─ Argument 3 → [key support]
+Key concepts: [3–5 terms with one-line definitions]
+```
+
+**2B — SCQA breakdown.** Apply the four-element decomposition from [`scqa-framework`](../../../docs/guidelines/agent-infra/scqa-framework.md):
+
+```markdown
+**S (Situation)**: [context the article establishes]
+**C (Complication)**: [problem identified]
+**Q (Question)**: [core question]
+**A (Answer)**: [main solution / conclusion]
+Structure quality — clarity / logic / completeness: [★★★☆☆]
+```
+
+**2C — 5W2H gap check** (L1+). Quick scan: which of *What, Why, Who, When, Where, How, How much* are well-covered, partial, or missing? Flag the 1–2 most critical gaps.
+
+### Step 3: Apply Frameworks (depth-gated)
+
+Load only the frameworks the user's depth bought. Each framework follows the same pattern: **load reference module → apply lens → produce one fixed-shape block**.
+
+**L2 additions:**
+
+- **Critical Thinking** (`critical_thinking.md`, upstream) — argument strength score (X/10), strengths, weaknesses, logical fallacies detected.
+- **Inversion** ([`inversion-thinking`](../../../docs/guidelines/agent-infra/inversion-thinking.md)) — pre-mortem on the article's recommendation: "how would this fail?", missing risk factors, mitigations.
+
+**L3 additions:**
+
+- **Mental Models** ([`mental-models`](../../../docs/guidelines/agent-infra/mental-models.md)) — pick 3–5 models from different disciplines (physics, biology, psychology, economics, math), apply each lens, surface cross-model patterns.
+- **First Principles** (`first_principles.md`, upstream) — strip to fundamental truths, validate each core assumption, rebuild from base.
+- **Systems Thinking** (`systems_thinking.md`, upstream) — map relationships, feedback loops, leverage points.
+- **Six Hats** (`six_hats.md`, upstream) — White (facts), Red (feelings), Black (cautions), Yellow (benefits), Green (creativity), Blue (process).
+
+**L4 addition:**
+
+- **Cross-source comparison** (`comparison_matrix.md`, upstream) — web-search 2–3 related sources, compare SCQA across sources, identify consensus vs divergence, synthesize integrated perspective.
+
+### Step 4: Synthesize by Goal
+
+Output shape is **driven by Step 0 goal**, not by frameworks applied. Pick exactly one of the four blocks below.
+
+**For problem-solving:** Applicable solutions (2–3 from content) → Application plan with timed action steps → Success metrics → Risk mitigations from Inversion.
+
+**For learning:** Core concepts (definition + example) → Mental models gained → Connections to prior knowledge → First Principles fundamental question → 3 verification questions (understanding / application / evaluation).
+
+**For writing reference:** Key arguments + evidence (with paragraph citations) → Quotable insights with context → Critical analysis (strengths for citing, limitations for balanced discussion) → Alternative perspectives from Mental Models → Gaps and counterfactuals.
+
+**For decision-making:** Options presented → Multi-model evaluation (economic + risk + systems lens) → Six Hats decision analysis → Scenario analysis (best / worst / most likely) → Synthesized recommendation.
+
+### Step 5: Knowledge Activation (always end here)
+
+Regardless of goal, close with three fixed blocks:
+
+```markdown
+## 🎯 Top 3 takeaways
+1. **[Insight]** — Why it matters: [...] · One action: [specific, time-bound]
+2. **[Insight]** — Why it matters: [...] · One action: [specific, time-bound]
+3. **[Insight]** — Why it matters: [...] · One action: [specific, time-bound]
+
+## 💡 Quick win — one tiny, specific action for the next 24 hours.
+
+## 🧭 Frameworks used
+✅ SCQA  ✅ 5W2H  ✅ Critical  ✅ Inversion
+□ Mental Models  □ First Principles  □ Systems  □ Six Hats
+```
+
+### Step 6: Validate
+
+1. Every claim is faithful to the source — no misrepresentation, facts distinguished from opinions.
+2. Frameworks applied **purposefully**, not force-fit — drop a framework that adds no insight rather than padding the output.
+3. Output ends with concrete, actionable steps — no analysis-without-application.
+4. Specific citations (paragraph numbers, quotes) where the source supports them.
+
+## Output format
+
+1. **Structural block (Step 2)** — type / thesis / structure tree / key concepts / SCQA / 5W2H gaps.
+2. **Framework blocks (Step 3)** — one fixed-shape block per framework the depth bought.
+3. **Goal-shaped synthesis (Step 4)** — problem-solving / learning / writing / decision-making.
+4. **Knowledge activation (Step 5)** — top 3 takeaways · quick win · frameworks-used checkboxes.
+
+## Gotcha
+
+- The model tends to **apply every framework** even at L1 — respect the depth budget; skip frameworks the user did not buy.
+- The model tends to **summarize** instead of analyze when the user pastes long text — go deep on 1–3 points, not shallow on all of them.
+- Inversion drifts into adversarial code review — this skill targets **decisions and arguments**, not diffs. Route diff stress-tests to `adversarial-review` / `judge-bug-hunter`.
+- Mental Models drifts into name-dropping — pick 3–5, apply each lens *concretely* to the article's claims, drop models that yield no new insight.
+- L4 cross-source comparison drifts into a literature review — keep it to 2–3 sources, focus on consensus / divergence / unique value.
+- Output without action steps is a failure mode — every Step-4 synthesis must end with timed, concrete actions tied to the user's goal.
+
+## Do NOT
+
+- Do NOT force-apply all frameworks at the user's chosen depth — drop ones that add no insight.
+- Do NOT copy text verbatim from the source — always reword for the user's understanding.
+- Do NOT use academic jargon without one-line definitions in the "key concepts" block.
+- Do NOT skip Step 5 — the takeaways + quick win are the load-bearing output, not optional decoration.
+- Do NOT route code reviews, diff stress-tests, or incident debugging through this skill.
+
+## Reference modules
+
+Project-local guidelines (full text adopted under the Reference-Guideline Sunset Policy):
+
+- [`scqa-framework`](../../../docs/guidelines/agent-infra/scqa-framework.md) — full 499-line authoritative-link adopt.
+- [`mental-models`](../../../docs/guidelines/agent-infra/mental-models.md) — pure adopt of Munger's multi-discipline toolkit.
+- [`inversion-thinking`](../../../docs/guidelines/agent-infra/inversion-thinking.md) — pre-mortem on decisions, distinct from `adversarial-review`.
+
+Upstream modules (loaded on demand from the SHA-pinned URL in `external_source`):
+
+- `5w2h_analysis.md` — completeness check (7 questions).
+- `critical_thinking.md` — argument quality / fallacy detection.
+- `first_principles.md` — fundamental-truth extraction.
+- `systems_thinking.md` — feedback loops + leverage points.
+- `six_hats.md` — White / Red / Black / Yellow / Green / Blue protocol.
+- `comparison_matrix.md` — cross-source synthesis (L4 only).

package/.agent-src/skills/roadmap-writing/SKILL.md

@@ -152,6 +152,6 @@ to every roadmap you author.
 
 ## Examples
 
-See `agents/roadmaps/archive/road-to-token-frugality.md`
-(structural, multi-phase, council-integrated) and any
-`agents/roadmaps/road-to-*.md` for canonical structure.
+Browse `agents/roadmaps/` (active plate) and `agents/roadmaps/archive/`
+(closed work) for canonical structural / tactical / structural-with-council
+examples.

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

@@ -453,7 +453,7 @@ the canonical narrative lives in
 | `commands.suggestion.max_options` | integer | `4` | Max number of command suggestions before the always-present "run as-is" option (total rendered = `max_options + 1`). |
 | `commands.suggestion.blocklist` | list of command names | `[]` | Commands that never appear as a suggestion. They still work when typed explicitly. |
 | `commands.create_pr.preview_description` | `true`, `false` | `false` | When `false`: `/create-pr` skips the title/body preview + adjust loop and uses the generated content directly. Saves agent tokens. When `true`: show title and body before creating and ask for adjustments. `/create-pr:description-only` always previews regardless of this setting. |
-| `verbosity.preview_artifacts` | `true`, `false` | `false` | Show generated commit messages, PR titles/bodies, branch names before acting. `false` = use generated content directly. See [`road-to-token-frugality`](../../../agents/roadmaps/road-to-token-frugality.md) Phase 2/3. |
+| `verbosity.preview_artifacts` | `true`, `false` | `false` | Show generated commit messages, PR titles/bodies, branch names before acting. `false` = use generated content directly. See the token-frugality plate under `agents/roadmaps/` (Phase 2/3). |
 | `verbosity.routine_confirmations` | `true`, `false` | `false` | Confirmation prompts for routine workflow steps when there is one obvious answer ("looks good — commit?"). Iron-Law gates (`commit-policy`, `scope-control` git-ops, `non-destructive-by-default`) ALWAYS ask regardless. |
 | `verbosity.offer_council_in_delivery` | `true`, `false` | `false` | Offer "run AI Council on this?" inside delivery commands (`/feature-plan`, `/review-changes`, `/roadmap-create`). Council commands themselves are unaffected. |
 | `verbosity.post_action_reports` | `off`, `minimal`, `full` | `minimal` | Multi-line status / summary blocks after a successful action. `off` = no report; `minimal` = one-line confirmation; `full` = bullet list. |

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.27.0"
+    "version": "1.28.0"
   },
   "plugins": [
     {
@@ -80,6 +80,7 @@
         "./.claude/skills/data-flow-mapper",
         "./.claude/skills/database",
         "./.claude/skills/dcf-modeling",
+        "./.claude/skills/deep-reading-analyst",
         "./.claude/skills/dependency-upgrade",
         "./.claude/skills/description-assist",
         "./.claude/skills/design-review",
@@ -208,6 +209,7 @@
         "./.claude/skills/refine-prompt",
         "./.claude/skills/refine-ticket",
         "./.claude/skills/requesting-code-review",
+        "./.claude/skills/research",
         "./.claude/skills/review-changes",
         "./.claude/skills/review-routing",
         "./.claude/skills/rice-prioritization",

package/CHANGELOG.md

@@ -318,6 +318,36 @@ our recommendation order, not its support status.
   users" tension without removing any path that an existing user
   might rely on.
 
+## [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