@event4u/agent-config 2.20.1 → 2.23.0

package/docs/contracts/caveman-telemetry.md

@@ -0,0 +1,83 @@
+---
+stability: beta
+keep-beta-until: 2026-08-15
+---
+
+# caveman telemetry — multiplier contract
+
+> **Status:** suspended (kill-criterion not met in `caveman-v1`).
+> Telemetry surface records `caveman_delta_tokens = 0` until a v2 bench
+> proves a positive multiplier on the load-bearing `vs_terse` arm.
+
+## Constant
+
+| Key | Value | Provenance |
+|---|---|---|
+| `caveman_multiplier_version` | `v1` | Tied to `bench/reports/caveman-v1.{json,md}` |
+| `caveman_multiplier_value` | `0.9155` | `median(terse_control_tokens / compressed_tokens)` over the 10-prompt v1 corpus |
+| `caveman_multiplier_p10` | `0.4506` | 10th percentile (worst-case carve-out-tax prompts) |
+| `caveman_multiplier_p90` | `2.3664` | 90th percentile (pure-prose prompts where caveman wins) |
+| `caveman_multiplier_active` | `false` | **Suspended** — kill-criterion not met (`vs_terse` median −9.27 %) |
+
+The **active** flag gates whether the multiplier is applied to runtime
+telemetry. While `false`, `scripts/caveman_stats.py` reports
+`caveman_delta_tokens = 0` regardless of `speak_scope` setting.
+
+## How the multiplier is interpreted
+
+`caveman_estimated_uncompressed_tokens = caveman_compressed_tokens × M`,
+where `M = caveman_multiplier_value`.
+
+`caveman_delta_tokens = caveman_estimated_uncompressed_tokens − caveman_compressed_tokens`.
+
+- `M > 1.0` → caveman compresses; `delta` is **positive** (saving).
+- `M = 1.0` → break-even; no delta surfaced.
+- `M < 1.0` → caveman costs more than the terse baseline; `delta` is
+  **negative**. Surfacing a negative saving is misleading for the
+  user (looks like a bug), so the contract is to **suspend the
+  multiplier** and record `delta = 0` until a v2 bench lifts `M`
+  above `1.0` on the load-bearing arm.
+
+## Why suspended after v1
+
+The `caveman-v1` bench (`bench/reports/caveman-v1.md`, 30 calls,
+2026-05-16) found:
+
+- Median savings vs raw uncompressed: **+23.51 %** (inflated by the
+  carve-out-tax-free pure-prose prompts).
+- Median savings vs terse-control: **−9.27 %** (load-bearing).
+- Carve-out-heavy prompts (path-list −108 %, mode-marker −123 %)
+  drag the median negative.
+
+The terse-control arm is the kill-criterion baseline per
+[`compression-default-kill-criterion.md`](compression-default-kill-criterion.md).
+Until a v2 bench (broader corpus or a re-tuned dialect) lifts the
+`vs_terse` median to ≥ 0 %, the multiplier stays suspended.
+
+## How to lift the suspension
+
+1. Run an extended bench against a broader corpus (Phase 3+ work).
+2. If `median(savings_vs_terse) ≥ 0` (and ideally ≥ 30 % to flip the
+   rule default), recompute `caveman_multiplier_value`.
+3. Update this contract: bump `caveman_multiplier_version` to `v2`,
+   set `caveman_multiplier_active = true`, cite the new bench file.
+4. The change is reversible — drop back to `v1` if a regression
+   appears.
+
+## Consumers
+
+- [`scripts/caveman_stats.py`](../../scripts/caveman_stats.py) — reads
+  this constant, computes per-session / per-conversation / lifetime
+  deltas from `agents/cost-tracking/sessions.jsonl`.
+- [`scripts/cost_summary.py`](../../scripts/cost_summary.py) — emits
+  the stable JSON contract for inter-tool consumption per
+  [`cost-summary-schema.md`](cost-summary-schema.md).
+- `agent-status` skill — surfaces the per-session delta in the
+  status report under the `[caveman: …]` widget.
+
+## See also
+
+- [`compression-default-kill-criterion.md`](compression-default-kill-criterion.md) — the rule-default-flip gate; this multiplier is gated on the same `vs_terse` arm.
+- [`bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md) — provenance for the `v1` value.
+- [`bench/reports/caveman-v2.md`](../../bench/reports/caveman-v2.md) — input-side (orthogonal); does NOT feed this multiplier (this multiplier is output-side).
+- [`caveman-speak`](../../.agent-src.uncompressed/rules/caveman-speak.md) — runtime rule the multiplier measures.

package/docs/contracts/compression-default-kill-criterion.md

@@ -5,14 +5,16 @@ keep-beta-until: 2026-08-14
 
 # Compression default — kill-criterion
 
-> **Status:** parked, criterion-deferred · **Owner:** `step-4-measurement-and-benchmark.md`
-> closeout phase · **Source:** [`council-synthesis.md` § 7](../../agents/audit-2026-05-14-north-star/council-synthesis.md)
+> **Status:** v1-measured · criterion not met · default stays `off` · **Owner:** `step-16-caveman-substance.md`
+> Phase 1 closeout · **Sources:** [`bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md) ·
+> [`council-synthesis.md` § 7](../../agents/audit-2026-05-14-north-star/council-synthesis.md) ·
+> [`caveman-v1-kc-verdict.json`](../../agents/council-responses/caveman-v1-kc-verdict.json) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict -->
 
 ## Rule
 
 ```
-DEFAULT STAYS OFF UNTIL `task bench` PRODUCES A NUMBER.
-DECISION OWNED BY step-4 CLOSEOUT, NOT BY THIS DOC OR BY step-99.
+DEFAULT STAYS OFF UNTIL `task bench -- --caveman` PRODUCES A POSITIVE vs_terse MEDIAN.
+DECISION OWNED BY THE NEXT BENCH CLOSEOUT, NOT BY THIS DOC.
 ```
 
 1. **Current state.** `caveman.speak_scope` defaults `off`. Carve-outs
@@ -21,49 +23,94 @@ DECISION OWNED BY step-4 CLOSEOUT, NOT BY THIS DOC OR BY step-99.
    [`caveman-speak`](../../.agent-src.uncompressed/rules/caveman-speak.md)
    but the feature is non-promoted: no skill recommends turning it on,
    no preset enables it, no profile depends on it.
-2. **Baseline window.** 60 days from the first green run of
-   `task bench` against the locked 25-prompt corpus
-   (`step-4-measurement-and-benchmark.md`
-   Phase 2). The corpus, the model, and the cost-tracker are frozen
-   for the window; mid-window changes restart the clock.
-3. **Decision points.** After the window closes, `step-4` closeout
-   reads `docs/parity/bench.json` and applies exactly one of:
-
-   | Measured tokens saved | Quality regression on corpus | Verdict |
+2. **Baselines.** Every published `bench/reports/caveman-v<N>.{json,md}`
+   measures three arms (`compressed` · `terse-control` ·
+   `uncompressed`) and reports two savings columns:
+   - `vs_raw` — median savings against the uncompressed arm.
+   - `vs_terse` — **load-bearing** median savings against the
+     `Answer concisely.` terse-control arm. `vs_raw` is inflated by the
+     carve-out-tax-free pure-prose case and is **not** the gate metric.
+3. **Decision table.** Read the latest `bench/reports/caveman-v<N>.md`
+   and apply exactly one of:
+
+   | Measured `vs_terse` median | Quality regression on corpus | Verdict |
    |---|---|---|
-   | < 30 % | any | **Deprecate** — remove `caveman-speak` rule, archive `caveman-compress` script, retire `caveman.*` settings keys with a one-release deprecation window |
-   | ≥ 30 % | < 5 % | **Flip default on** — `caveman.speak_scope` defaults to a non-`off` value, carve-outs stay, statusline surfaces lifetime tokens saved |
-   | ≥ 30 % | ≥ 5 % | **Hold** — repeat the window once with tuned intensity ladder; second hold → deprecate |
+   | < 0 % | any | **Criterion not met — defer.** Keep default `off`. No telemetry multiplier. Next move owned by the corpus-widening / methodology-revision step that produces `caveman-v<N+1>`. |
+   | 0 % – < 30 % | any | **Hold.** Keep default `off`. Authorised follow-up: widen corpus or tune carve-out share; no default flip. |
+   | ≥ 30 % | < 5 % | **Flip default on** — `caveman.speak_scope` defaults to a non-`off` value (separate roadmap), carve-outs stay, statusline surfaces lifetime tokens saved. |
+   | ≥ 30 % | ≥ 5 % | **Hold** — repeat the window once with tuned intensity ladder; second hold → deprecate. |
 
    "Quality regression" = host-side rubric on the corpus per
-   `step-4-measurement-and-benchmark.md` Phase 3. Numbers checked into
-   `docs/parity/bench.json` as the decision artefact.
+   `benchmark-report-schema.md`. Numbers checked into the published
+   `caveman-v<N>.json` as the decision artefact.
 4. **No interim flip.** The default does not move on anecdote,
-   gut feeling, or a single benchmark snapshot. The 60-day window and
-   the table above are the only path to a default change.
+   gut feeling, or a single positive prompt. Only a published
+   `caveman-v<N>` report with a `vs_terse` median in the "Flip" row
+   above authorises a default change, under a follow-up roadmap.
+
+## v1 verdict (2026-05-16)
+
+[`bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md)
+landed 30 calls · $0.0805 · 0 errors · `claude-sonnet-4-5`:
+
+| Metric | Median | p10 | p90 |
+|---|---:|---:|---:|
+| `vs_raw` savings | +23.51 % | -18.29 % | +52.53 % |
+| **`vs_terse` savings** | **−9.27 %** | **−109.85 %** | +51.32 % |
+| Realised carve-out share (compressed arm) | 30.67 % | — | — |
+
+Per row 1 of the table, the v1 verdict is **criterion not met — defer**.
+Default stays `off`; no telemetry multiplier ships; no rule retirement
+in this roadmap. Wins exist only on pure-prose prompts (caveman-09
++50.5 %, caveman-10 +58.4 %); carve-out-heavy prompts drag the median
+negative (caveman-04 path-list −108 %, caveman-06 mode-marker −123 %).
+
+### Council split (recorded, not decisive)
+
+Council run [`caveman-v1-kc-verdict.json`](../../agents/council-responses/caveman-v1-kc-verdict.json) <!-- council-ref-allowed: ADR decision trace for v1 kill-criterion verdict -->
+(2 members · 1 round · $0.0514 actual) split:
+
+- **`claude-sonnet-4-5`** → Decision A.1 (deprecate now) + Decision B.3
+  (suspend telemetry). Reasoning: the roadmap pinned `vs_terse` as
+  load-bearing; the data falsified it; retreating to `vs_raw` is
+  post-hoc rationalisation.
+- **`gpt-4o`** → Decision A.3 (hold + re-bench with widened corpus +
+  revised terse-control prompt) + Decision B.2 (per-category
+  multipliers, suppress negatives). Reasoning: 10 prompts is a
+  razor-thin sample; the terse-control prompt may under-compress; the
+  carve-out validator (Phase 4) is not yet shipped, so we are
+  measuring a half-implemented feature.
+
+**Synthesis (criterion-not-met + defer).** Both members agreed `vs_terse`
+is the right gate. Neither's strongest path is taken in full inside
+step-16: deprecation is reserved for a follow-up roadmap once v2 confirms
+v1; re-bench is reserved for a follow-up roadmap with the methodology
+revision the council requested. Step-16 ships the infrastructure (corpus,
+bench arm, validator), records the v1 verdict, suspends the telemetry
+multiplier, and hands the deprecate-vs-rebench call to the v2 roadmap.
 
 ## Why this is parked, not decided
 
-The council split (Opus = remove now, o1 = measure-then-decide) is
-real. Either branch is wrong-shaped without numbers. The kill-criterion
-gives the audit a deterministic resolution path and stops every
-downstream roadmap from re-litigating compression on every PR.
+The 2026-05-14 council split (Opus = remove now, o1 = measure-then-decide)
+predated v1 numbers. The 2026-05-16 council split (Sonnet = deprecate now,
+GPT-4o = re-bench) is informed by v1 but disagrees on which methodological
+weakness is decisive. The kill table above gives every future bench run a
+deterministic resolution path and stops every downstream roadmap from
+re-litigating compression on every PR.
 
 ## Cross-references
 
-- ``step-99-north-star-restructure.md` § Phase 4`
-  — parks this criterion, does not decide.
-- `step-4-measurement-and-benchmark.md`
-  — owns `task bench`, the corpus, and the closeout that applies the
-  table above.
-- `step-10-caveman-parity.md`
-  — implements the carve-outs and the statusline integration the
-  "flip default on" branch depends on; blocks the default flip until
-  acceptance is green.
+- [`bench/reports/caveman-v1.md`](../../bench/reports/caveman-v1.md)
+  — v1 measurement; canonical baseline this doc cites.
+- [`docs/benchmarks.md`](../benchmarks.md)
+  — cadence + when the next bench run is mandatory.
+- [`caveman-telemetry`](caveman-telemetry.md)
+  — multiplier contract; records the suspended state v2 must lift.
 - [`caveman-speak`](../../.agent-src.uncompressed/rules/caveman-speak.md)
   — runtime rule; reads `caveman.speak_scope` from settings.
 
 ## Done
 
-This doc exists to keep the decision visible. It is **not** an action
-item. `step-4` closeout closes the loop.
+This doc reflects the v1 verdict. It is **not** an action item. The next
+bench closeout (against `caveman-v2` once a widened corpus or revised
+methodology is shipped) closes the loop.

package/docs/contracts/cost-summary-schema.md

@@ -0,0 +1,107 @@
+---
+stability: beta
+keep-beta-until: 2026-08-15
+---
+
+# cost-summary schema (`cost-summary/v1`)
+
+Stable JSON contract for inter-tool consumption of cost-tracking data
+emitted by [`scripts/cost_summary.py`](../../scripts/cost_summary.py).
+Schema-versioned so downstream consumers can pin and migrate explicitly.
+
+Design reference: Ruflo `scripts/summary.mjs` (upstream cite). Our shape
+diverges to align with the local `agents/cost-tracking/sessions.jsonl`
+fields and the caveman-suspended-multiplier contract.
+
+## Envelope
+
+```json
+{
+  "schema_version": "cost-summary/v1",
+  "generated_at": "2026-05-16T23:45:00Z",
+  "totals": { ... },
+  "by_session": [ ... ],
+  "by_conversation": [ ... ],
+  "by_model": [ ... ]
+}
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `schema_version` | string | Pinned to `cost-summary/v1`. Downstream consumers MUST refuse unknown versions. |
+| `generated_at` | string (ISO-8601 UTC, `Z` suffix) | Emit time. |
+| `totals` | object | Lifetime aggregates — see `totals` below. |
+| `by_session` | array | Per `sessionId` row; ordered by `sessionId` ascending. |
+| `by_conversation` | array | Per `conversation_id` row; ordered by `conversation_id` ascending. |
+| `by_model` | array | Per `model` row; ordered by `model` ascending. |
+
+## `totals` shape
+
+```json
+{
+  "sessions": 123,
+  "total_cost_usd": 1.2345,
+  "input_tokens": 100000,
+  "output_tokens": 50000,
+  "caveman_delta_tokens": 0,
+  "caveman_multiplier_version": "v1",
+  "caveman_multiplier_active": false
+}
+```
+
+`caveman_delta_tokens` is always `0` while
+`caveman_multiplier_active == false` — see
+[`caveman-telemetry.md`](caveman-telemetry.md) for the suspension contract.
+
+## `by_session` / `by_conversation` row shape
+
+```json
+{
+  "key": "<sessionId or conversation_id>",
+  "sessions": 12,
+  "total_cost_usd": 0.4567,
+  "input_tokens": 8000,
+  "output_tokens": 4500,
+  "caveman_delta_tokens": 0
+}
+```
+
+The `key` field is the grouping identifier; consumers identify the
+group by inspecting which array the row lives in.
+
+## `by_model` row shape
+
+```json
+{
+  "model": "claude-3-5-sonnet-20241022",
+  "sessions": 12,
+  "total_cost_usd": 0.4567,
+  "input_tokens": 8000,
+  "output_tokens": 4500
+}
+```
+
+`by_model` omits caveman fields — the multiplier is dialect-scoped, not
+model-scoped.
+
+## Stability guarantees
+
+- **Field additions** are **non-breaking**: consumers MUST ignore unknown fields.
+- **Field removals or renames** bump the `schema_version` minor (`v1` → `v2`).
+- **Type changes** bump the major (`v1.*` → `v2.0`).
+- Downstream consumers SHOULD pin to a specific `schema_version` and
+  refuse unknown ones; the pin is the migration boundary.
+
+## Downstream consumers
+
+- `agent-status` skill — surfaces lifetime / current-conversation slice.
+- Future `cost-export-to-monitoring` scripts (deferred; trigger:
+  consumer request) would wrap this JSON to push to Prometheus / OTLP.
+
+## See also
+
+- [`caveman-telemetry.md`](caveman-telemetry.md) — defines the
+  `caveman_*` fields and the suspended-multiplier contract.
+- [`scripts/cost_summary.py`](../../scripts/cost_summary.py) — implementation.
+- [`scripts/cost_by_conversation.py`](../../scripts/cost_by_conversation.py) — narrower per-conversation lens with the same JSONL source.
+- [`scripts/caveman_stats.py`](../../scripts/caveman_stats.py) — caveman-only delta lens with the same JSONL source.

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

@@ -1800,6 +1800,12 @@
       "load_context": [],
       "load_context_eager": []
     },
+    ".agent-src.uncompressed/skills/compress-memory/SKILL.md": {
+      "kind": "skill",
+      "rule_type": null,
+      "load_context": [],
+      "load_context_eager": []
+    },
     ".agent-src.uncompressed/skills/content-funnel-design/SKILL.md": {
       "kind": "skill",
       "rule_type": null,
@@ -6396,6 +6402,13 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/rules/caveman-speak.md",
+      "target": ".agent-src.uncompressed/skills/compress-memory/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/rules/cli-output-handling.md",
       "target": ".agent-src.uncompressed/rules/cli-output-handling.md",
@@ -8048,6 +8061,34 @@
       "via": "self",
       "depth": 0
     },
+    {
+      "source": ".agent-src.uncompressed/skills/compress-memory/SKILL.md",
+      "target": ".agent-src.uncompressed/rules/caveman-speak.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/skills/compress-memory/SKILL.md",
+      "target": ".agent-src.uncompressed/rules/role-mode-adherence.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/skills/compress-memory/SKILL.md",
+      "target": ".agent-src.uncompressed/skills/agents-md-thin-root/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
+    {
+      "source": ".agent-src.uncompressed/skills/compress-memory/SKILL.md",
+      "target": ".agent-src.uncompressed/skills/compress-memory/SKILL.md",
+      "type": "WRITE",
+      "via": "self",
+      "depth": 0
+    },
     {
       "source": ".agent-src.uncompressed/skills/content-funnel-design/SKILL.md",
       "target": ".agent-src.uncompressed/skills/activation-design/SKILL.md",
@@ -10442,6 +10483,13 @@
       "via": "body_link",
       "depth": 1
     },
+    {
+      "source": ".agent-src.uncompressed/skills/refine-prompt/SKILL.md",
+      "target": ".agent-src.uncompressed/skills/prompt-optimizer/SKILL.md",
+      "type": "READ_ONLY",
+      "via": "body_link",
+      "depth": 1
+    },
     {
       "source": ".agent-src.uncompressed/skills/refine-prompt/SKILL.md",
       "target": ".agent-src.uncompressed/skills/refine-prompt/SKILL.md",

package/docs/guidelines/prompt-templates.md

@@ -0,0 +1,166 @@
+# Prompt Templates
+
+Reference catalogue of prompt structures the [`prompt-optimizer`](../../.agent-src.uncompressed/skills/prompt-optimizer/SKILL.md)
+skill picks from during the **Develop** step of the 4-D methodology.
+Cited by the [`refine-prompt`](../../.agent-src.uncompressed/skills/refine-prompt/SKILL.md)
+skill in `mini` mode for stack-aware shaping.
+
+Templates are tools, not dogma. Pick by request type, not by upstream
+whitelist — see the [Rejection note](#rejection-note) at the bottom.
+
+## When-to-pick rubric
+
+| Request shape | First-choice template | Fallback |
+|---|---|---|
+| One-shot technical change (refactor, lint fix) | **RTF** | File-Scope |
+| Multi-file refactor across a codebase | **File-Scope** | RTF |
+| Marketing / brand / tone-heavy copy | **CO-STAR** | CRISPE |
+| Mixed-audience explainer (technical + lay) | **CRISPE** | CO-STAR |
+| Step-by-step explainer / tutorial | **RISEN** | Few-Shot |
+| Pattern-heavy task (classification, extraction) | **Few-Shot** | RISEN |
+| Multi-step reasoning or math | **CoT** | ReAct |
+| Tool-using agent (web search, file ops) | **ReAct** | CoT |
+| Image AI (Midjourney, SD, DALL·E) | **Visual Descriptor** | Reference-Image-Edit |
+| Image edit from a source image | **Reference-Image-Edit** | Visual Descriptor |
+| ComfyUI / node-graph image workflows | **ComfyUI** | Visual Descriptor |
+| Reverse-engineer an existing good prompt | **Prompt Decompiler** | — |
+| Honest critical feedback on a finished artifact (post, design, naming, proposal) — any domain | **Honest Sparring Partner** | CRISPE |
+
+## Text templates
+
+### RTF — Role · Task · Format
+Smallest viable structure. Three lines: who the AI is, what to do,
+how the output should look. Best for one-shot technical asks.
+
+### CO-STAR — Context · Objective · Style · Tone · Audience · Response
+Six-slot structure originally from the Singapore GovTech prompt
+study. Best for copy where audience and tone carry the message.
+
+### RISEN — Role · Input · Steps · Expectation · Narrowing
+Step-explicit shape. Best for tutorials, walkthroughs, and any
+output where the reader follows the prompt's structure.
+
+### CRISPE — Capacity · Role · Insight · Statement · Personality · Experiment
+Six-slot, persona-heavy. Best when the *voice* matters more than
+the structure (creative writing, explainers with a strong narrator).
+
+### CoT — Chain-of-Thought
+Append "Think step by step" or "Reason aloud before answering" to
+any base template. Best for multi-step reasoning, math, planning.
+Pairs well with RTF or RISEN.
+
+### Few-Shot
+Two to five worked examples inline before the actual ask. Best for
+classification, extraction, format-mimicking. Costs tokens — keep
+examples minimal and representative.
+
+### File-Scope
+Codebase-aware variant of RTF. Names the files in scope, the
+allowed-edit list, and the "do not touch" list explicitly. Best for
+agent-driven refactors where blast radius matters.
+
+```
+Role: senior TypeScript engineer
+Files in scope: src/auth/*.ts, tests/auth/*.ts
+Do not modify: src/db/*, package.json, tsconfig.json
+Task: migrate from jsonwebtoken to jose; keep the exported API stable
+Format: unified diff
+```
+
+### ReAct — Reason + Act
+Interleaved thought / action / observation loop. Best for agents
+with tools — web search, file ops, shell. Each cycle:
+
+```
+Thought: <why I need this next step>
+Action: <tool call>
+Observation: <result>
+... repeat ...
+Final Answer: <synthesis>
+```
+
+### Honest Sparring Partner
+Domain-agnostic stance template for getting honest critical feedback on
+a finished artifact — blog post, design draft, naming decision, business
+proposal, care-plan, marketing copy. Works for any role (engineer,
+graphic designer, nurse, founder) because the role slot is filled by
+the user's actual profession, not hard-coded.
+
+Five-slot shape:
+
+```
+Role: <user's domain> — e.g. graphic designer, geriatric nurse, founder
+Stance: honest sparring partner, not yes-man. Push back when something
+        is weak; acknowledge when something is solid; stay silent when
+        there is nothing substantive to add. No flattery openings, no
+        artificial criticism for its own sake.
+Context-fit: ask ONE clarifying question only if real context is missing
+             (role, audience, constraint). Otherwise answer directly.
+Artifact: <the finished thing — paste, link, or describe>
+Ask: <what kind of reaction the user wants — "does the argument hold?",
+     "is the naming clear?", "would this land with audience X?">
+```
+
+**Anti-pattern this rejects:** "what do you honestly think?" prompts that
+either default to praise ("looks great!") or default to manufactured
+criticism ("here are 5 problems...") regardless of whether the work
+warrants either reaction. The stance slot makes the honest-when-warranted
+contract explicit.
+
+**Package equivalents** — inside this agent-config, the
+[`adversarial-review`](../../.agent-src.uncompressed/skills/adversarial-review/SKILL.md)
+skill implements the same stance via an Attack-Defend-Revise loop and is
+the right tool when the user submits finished work for a critical take.
+This template is for **end-users prompting their own LLM** (ChatGPT,
+Claude, Gemini) outside this package.
+
+## Image templates
+
+### Visual Descriptor
+Subject · style · composition · lighting · medium · mood · technical
+parameters (aspect ratio, resolution). Best for Midjourney, Stable
+Diffusion, DALL·E from a blank canvas.
+
+### Reference-Image-Edit
+Source image reference + change set + preservation set. Names what
+to change, what to keep, and the desired output framing. Best for
+inpainting, style transfer, character consistency.
+
+### ComfyUI
+Node-graph-aware. Names the workflow nodes (KSampler, CLIPTextEncode,
+VAEDecode) and the parameter intent per node rather than the
+parameter values. Best for advanced SD pipelines.
+
+## Reverse template
+
+### Prompt Decompiler
+Given an existing good output, reconstruct the prompt that would
+produce it. Used to mine prompts from public LLM artifacts. Not a
+shaping template — a forensic one.
+
+## Rejection note
+
+Upstream `nidhinjs/prompt-master` claims that only five techniques
+are "safe" for production prompting:
+
+- few-shot
+- role assignment
+- structured output
+- constraint-based
+- chain-of-thought
+
+This package **rejects** that whitelist. CO-STAR, RISEN, CRISPE,
+ReAct, and the image-AI templates above are first-class. The
+"5 safe" framing came from a single benchmark on a single LLM
+generation — it does not generalise. See AI Council session
+`agents/council-responses/prompt-master-mini.json` (2026-05-17) for the analysis behind this rejection. <!-- council-ref-allowed: ADR decision trace -->
+
+The right gate is request-type fit, not technique-whitelist
+membership.
+
+## See also
+
+- [`prompt-optimizer`](../../.agent-src.uncompressed/skills/prompt-optimizer/SKILL.md) — engine-outbound; cites this catalogue in its Develop step
+- [`refine-prompt`](../../.agent-src.uncompressed/skills/refine-prompt/SKILL.md) — engine-inbound; uses templates in `mini` mode for stack-aware shaping
+- [`prompt-engineering-patterns`](../../.agent-src.uncompressed/skills/prompt-engineering-patterns/SKILL.md) — production-LLM prompt patterns (sibling skill, not a catalogue)
+- AI Council session: `agents/council-responses/prompt-master-mini.json` (2026-05-17) <!-- council-ref-allowed: ADR decision trace -->

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "2.20.1",
+    "version": "2.23.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,