@event4u/agent-config 1.27.0 → 1.29.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/async-python-patterns/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: async-python-patterns
+description: "Use when writing Python asyncio code — picking between gather / TaskGroup / wait, structured concurrency, timeouts, cancellation, sync-bridging — decision framework only, cookbook externalized."
+source: package
+status: active
+refresh_trigger: "Python ships a new structured-concurrency primitive (post-TaskGroup), OR ≥30% of cited upstream cookbook examples become deprecated, OR the cited libraries (aiohttp, httpx, anyio, trio) cut a major version with breaking async surface changes."
+sunset_criterion: "When `https://docs.python.org/3/library/asyncio.html` ships an in-tree decision framework AND consumer projects no longer cite this skill in PR reviews for two consecutive review cycles."
+---
+
+# async-python-patterns
+
+Decision framework for picking the right Python asyncio primitive. **The pattern cookbook lives upstream** (links in § Provenance) — this skill is the predicate, not the recipe library. Sunset-policy compliant: the 600+ lines of language-specific cookbook stay in authoritative Python docs.
+
+## When to use
+
+- Designing a new async I/O-bound service (FastAPI, aiohttp, async DB client).
+- Reviewing a diff that introduces `asyncio.gather`, `asyncio.create_task`, `TaskGroup`, `as_completed`, or `wait_for`.
+- Mixing sync and async code (calling sync libs from async context, or vice versa).
+- Diagnosing event-loop blocking, never-awaited warnings, or cancellation leaks.
+
+Do NOT use when:
+
+- The work is CPU-bound — async will not help; route to multiprocessing or threadpool.
+- The runtime is not Python — read the host runtime's concurrency guide.
+- The fix is a single missing `await` — read the upstream tutorial directly.
+
+## Decision framework
+
+### Step 1 — Verify async is the right tool
+
+```
+Workload is:
+  I/O-bound, many concurrent waits  → async fits (network, disk, IPC).
+  CPU-bound (parsing, math, crypto) → async is wrong; use ProcessPoolExecutor.
+  Mixed                              → async shell + run_in_executor for CPU bursts.
+  Single sequential call             → don't introduce async; sync is simpler.
+```
+
+### Step 2 — Pick the concurrency primitive
+
+```
+Run N independent coroutines, ALL must complete:
+  Same trust level, exceptions cancel siblings  → asyncio.TaskGroup (3.11+; preferred).
+  Pre-3.11 OR exceptions must NOT cancel peers  → asyncio.gather(*, return_exceptions=...).
+
+Run N coroutines, react to results as they finish:
+  → asyncio.as_completed (yields completed futures in finish order).
+
+Run N coroutines, race to first success / failure:
+  → asyncio.wait(..., return_when=FIRST_COMPLETED) + cancel pending.
+
+Schedule fire-and-forget background work:
+  → asyncio.create_task + keep a strong reference (else GC eats it).
+  Forgetting the reference is the #1 silent-failure source.
+
+Bound the wait time:
+  → asyncio.wait_for(coro, timeout=...)  → raises TimeoutError on expiry.
+  → asyncio.timeout(...) context manager (3.11+; preferred when many awaits share a deadline).
+
+Bound concurrency (rate-limit, connection pool):
+  → asyncio.Semaphore(n); acquire around the awaitable.
+```
+
+### Step 3 — Bridge sync ↔ async correctly
+
+```
+Async code calls sync, blocking, function:
+  Short pure-CPU              → fine, accept the block (microseconds).
+  Long, blocking, or I/O-sync → await loop.run_in_executor(None, fn, *args).
+  Library has async sibling   → switch the library (httpx vs requests, aiosqlite vs sqlite3).
+
+Sync code calls async function:
+  Top-level entrypoint        → asyncio.run(coro()).
+  Inside running loop         → never asyncio.run; create_task + await it.
+  Test suite                  → pytest-asyncio fixture; never raw run() in tests.
+```
+
+### Step 4 — Cancellation discipline
+
+Every long-running coroutine MUST be cancellation-safe:
+
+- Catch `asyncio.CancelledError`, perform cleanup, **re-raise**. Swallowing it silently breaks the propagation chain.
+- Use `try / finally` (or `async with`) around resource acquisition so cancellation cannot leak file handles, DB connections, locks.
+- Detached `create_task` without a strong reference is undefined behavior; either store the task or use a TaskGroup.
+
+### Step 5 — Don't block the event loop
+
+A single blocking call (sync I/O, time.sleep, CPU-heavy parse, large JSON load) freezes every coroutine. Audit every leaf function under `async def`:
+
+- Sleep → `await asyncio.sleep`, never `time.sleep`.
+- HTTP → `httpx.AsyncClient` / `aiohttp`, never `requests`.
+- DB → `asyncpg` / `aiosqlite` / `motor`, never the sync driver.
+- File → `aiofiles` for hot-paths, or `run_in_executor` for one-shots.
+
+## Procedure: Apply to a new async feature
+
+1. Run Step 1; reject if work is CPU-bound.
+2. Sketch the call graph; tag each `await` site with its primitive (Step 2).
+3. Mark every sync↔async boundary; pick the bridge per Step 3.
+4. For each long-running coroutine, write the cancel-safety contract (Step 4).
+5. Grep the leaf calls for blocking sins (Step 5); replace or push to executor.
+6. Hand the sketch to a reviewer **before** coding; cite this skill.
+
+## Output format
+
+1. Call-graph table: coroutine · concurrency primitive · timeout · cancel-safety note.
+2. Sync↔async boundary list: site · bridge · justification.
+3. Blocking-call audit: leaf function · status (async / executor / accepted-block + reason).
+4. Cancel-safety contract for each background task.
+
+## Gotcha
+
+- "It works in my REPL" — `asyncio.run` inside an already-running loop (Jupyter, FastAPI startup) raises `RuntimeError`. Use `await` directly or `nest_asyncio` (last resort).
+- `asyncio.gather` swallows the second exception silently; use `return_exceptions=True` and inspect, or use `TaskGroup` (cancels all on first error, surfaces the group).
+- `create_task` results that nobody awaits look fine until the program exits and Python prints `Task was destroyed but it is pending!`. Always `await` or use a TaskGroup.
+- `wait_for` on a non-cancellation-safe coroutine leaks resources; the timeout cancels the task but cleanup never runs.
+- Libraries that "support async" via thread pools (e.g. `requests-async`) often re-block the loop under load; verify with the cited upstream library docs, not the README.
+
+## Do NOT
+
+- Do NOT call `asyncio.run` from a running loop.
+- Do NOT swallow `CancelledError` without re-raising.
+- Do NOT call sync blocking I/O from async paths without `run_in_executor`.
+- Do NOT spawn `create_task` without storing the reference (or using TaskGroup).
+- Do NOT inline the asyncio cookbook into this skill — externalize per Sunset Policy.
+
+## Auto-trigger keywords
+
+- asyncio
+- async / await
+- gather / TaskGroup / wait_for
+- event loop blocking
+- cancellation
+- sync to async bridge
+
+## Provenance
+
+- Adopted from: `Microck/ordinary-claude-skills@8f5c83174f7aa683b4ddc7433150471983b93131:skills_all/async-python-patterns/SKILL.md` (MIT, © 2025 Microck) — **Sunset Policy applied**: 694-line cookbook source reduced to a ~140-line decision framework; pattern catalogues externalized to upstream docs below.
+- Externalized cookbook:
+  - asyncio core: https://docs.python.org/3/library/asyncio.html · https://docs.python.org/3/library/asyncio-task.html
+  - TaskGroup (3.11+): https://docs.python.org/3/library/asyncio-task.html#task-groups
+  - Structured concurrency: https://anyio.readthedocs.io · https://trio.readthedocs.io
+  - Async HTTP: https://www.python-httpx.org/async/ · https://docs.aiohttp.org/en/stable/
+  - Async DB: https://magicstack.github.io/asyncpg/ · https://aiosqlite.omnilib.dev/
+- Cross-linked: [`error-handling-patterns`](../error-handling-patterns/SKILL.md), [`mcp-builder`](../mcp-builder/SKILL.md), [`api-design`](../api-design/SKILL.md), [`performance`](../performance/SKILL.md).
+- Provenance registry: `agents/contexts/skills-provenance.yml` (entry: `async-python-patterns`).
+- Iron-Law floor: `verify-before-complete`, `skill-quality`, `non-destructive-by-default`.