npm - @event4u/agent-config - Versions diffs - 5.10.0 → 6.0.0 - Mend

@event4u/agent-config 5.10.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2224) hide show

package/dist/agent-src/commands/council/default.md ADDED Viewed

@@ -0,0 +1,289 @@
+---
+model_tier: inherit
+name: council-default
+pack: meta
+tier: 2
+cluster: council
+sub: default
+skills: [ai-council]
+description: Default council lens — neutral framing, redacted context, advisory output only. Run `/council default <input>` for prompt/roadmap/diff/files; the cluster shows a menu when invoked bare.
+suggestion:
+  eligible: false
+  rationale: "Default lens — invoked via /council dispatcher; no direct trigger."
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+# /council default
+Base orchestration entry point for the council. Specialised lenses
+(`/council pr`, `/council design`, `/council optimize`) wrap this same
+flow with mode-specific neutrality preambles.
+## Instructions
+### 1. Resolve the target + capture the original ask
+The user invoked `/council default` on exactly one input mode:
+- `prompt:"<text>"` — a free-form question or proposal
+- `roadmap:<path>` — a roadmap file under `agents/roadmaps/`
+- `diff:<base>..<head>` — a git diff range
+- `files:<path>,<path>` — a comma-separated file list
+Optional invocation flag: `mode:api|manual` overrides the per-member
+and global mode for this call only (see Step 2.5).
+Optional **rounds**: `rounds:N` (1-3) overrides the multi-round
+debate count. Round 1 sees the artefact alone. Round 2+ sees the
+artefact plus anonymised critiques from the previous round
+(provider/model identity stripped). Total spend = N × single-round
+cost; surface this in the cost gate.
+Optional **depth**: `depth:deep` raises the round floor to
+`ai_council.deep_min_rounds` (default `3`, max'd with `min_rounds`)
+for architecture, refactoring, or bug-diagnosis artefacts. Set
+explicitly by the user, or derived from `council_depth: deep`
+declared in the frontmatter of the active rule, skill, or command —
+the host translates that to `--depth deep` on the CLI. If multiple
+active artefacts disagree, **deep wins** (max policy). Explicit
+`rounds:N` overrides depth.
+The default comes from `ai_council.min_rounds` in
+`.agent-settings.yml` (default `2` so members critique each other at
+least once before convergence). **Do NOT ask the user "how many
+rounds?"** when `rounds:N` is unset or `N <= min_rounds` — proceed
+with the settings default. Ask only when the artefact is genuinely
+complex and you want more depth than `min_rounds` provides; surface
+the proposal as a numbered choice (per `ask-when-uncertain`) with
+the cost delta.
+Resolution chain (highest priority first):
+1. `rounds:N` / `--rounds N` — explicit user override.
+2. `depth:deep` / `--depth deep` — floors at `max(deep_min_rounds, min_rounds)`.
+3. `ai_council.min_rounds` — default.
+Optional **mode_override**: `mode_override=pr|design|optimize` swaps
+the system-prompt addendum for one of the specialised lenses
+(see `prompts.py` `_MODE_TABLE`). The bundle mode is unchanged; only
+the per-mode neutrality addendum is replaced. Routed by the
+`/council pr`, `/council design`, `/council optimize` sub-commands —
+surface to the user as "council on <target> — <lens> lens".
+If no input mode was supplied, ask the user which mode + target. **One
+question per turn** (per `ask-when-uncertain`). Do not assume the
+working-tree diff.
+Also capture the user's **original ask** verbatim — the free-form
+sentence that triggered the council, distinct from the bundled
+artefact. For `prompt:"…"` mode the ask and the artefact are the
+same string. For `roadmap` / `diff` / `files` modes, the ask is the
+user's framing sentence ("review this roadmap before I execute it",
+"is this diff safe to merge?"). This string flows into
+`consult(..., original_ask=…)` in Step 5 (per `ai-council` skill §
+Neutrality — context-handoff).
+### 2. Check the council is configured + price table fresh
+Read `.agent-settings.yml` → `ai_council`:
+- If `ai_council.enabled` is false → state that and offer to flip it
+  on. Do not flip it autonomously.
+- If no member has `enabled: true` → list the install commands
+  (`./agent-config keys:install-anthropic`, `./agent-config keys:install-openai`)
+  and stop.
+- If a member is enabled but its `*.key` file is missing or has the
+  wrong mode → tell the user which key to install. Do not fall back
+  to env vars. Ever.
+Load the price table via `scripts.ai_council.pricing.load_prices()`
+(auto-bootstraps `agents/runtime/.agent-prices.md` from defaults if missing). Run
+`pricing.is_stale(table)` and, if stale, surface the staleness gate
+from the `ai-council` skill (§ Stale price-table gate) before
+continuing.
+### 2.5. Resolve per-member execution mode
+For each enabled member, resolve its mode via
+`scripts.ai_council.modes.resolve_mode(name, invocation_mode,
+member_settings, global_mode)`. Precedence: invocation flag >
+per-member setting > global setting > default (`manual`).
+Construct each member from the resolved mode:
+- `api` → `AnthropicClient` / `OpenAIClient` (billable, cost-gated).
+- `manual` → `ManualClient` from `scripts.ai_council.clients`
+  (`billable=False`, no API key, no SDK call).
+### 3. Cost confirmation — ALWAYS ASK for billable members
+Council calls to billable members spend money. Even under
+`personal.autonomy: on`, the agent **must** ask before invoking any
+billable member.
+Run the CLI in **estimate** mode first — it bundles the artefact, runs
+redaction, and prints the per-member preview without spending:
+```bash
+./agent-config council:estimate <question-file> \
+    [--input-mode prompt|roadmap] \
+    [--max-tokens N] \
+    [--mode-override api|manual] \
+    [--prompt-mode pr|design|optimize|analysis] \
+    [--original-ask "<framing sentence>"]
+```
+`--prompt-mode` is the lens-override flag routed by the
+`/council pr|design|optimize|analysis` wrappers. It swaps the
+per-mode neutrality addendum (see `scripts/ai_council/prompts.py`
+`_MODE_TABLE`) without changing the bundle shape. Bare
+`/council default` invocations leave it unset.
+For `prompt:"<text>"` mode, write the text to a temp file first
+(`mktemp` is fine) and pass that path. For `roadmap:<path>`, pass the
+roadmap file with `--input-mode roadmap`. `diff` and `files` modes
+remain Phase 4 — for now ask the user to convert into a `prompt`.
+The CLI prints a `council:estimate · members=N (billable=M)` line
+followed by per-member projected USD and a TOTAL. Render that to the
+user inside the cost-confirmation numbered-options block per the
+`ai-council` skill (§ Pre-call estimate format) — then `1. Run /
+2. Cancel`. If the billable count is `0`, skip the gate entirely
+(spend = $0) and proceed directly to Step 4.
+Wait for the user's pick. `1` proceeds; anything else aborts.
+### 4. Run the CLI
+Once the user picks `1`, invoke the same arguments with `run` plus
+`--confirm` and an output path under `agents/runtime/council/sessions/`:
+```bash
+./agent-config council:run <question-file> \
+    --output agents/runtime/council/sessions/<UTC-timestamp>.json \
+    --confirm \
+    [--rounds 1|2|3] \
+    [--depth standard|deep] \
+    [--input-mode …] [--max-tokens …] [--mode-override …] \
+    [--prompt-mode …] \
+    [--original-ask "<framing sentence>"]
+```
+`--rounds` defaults to `ai_council.min_rounds` from
+`.agent-settings.yml` (or `2` if unset). Pass `--rounds N` only when
+the user explicitly asked for a different count or a complex
+artefact justifies more depth — do not pass `--rounds 1` to "save
+money" by default; the settings owner already chose `min_rounds`.
+`--depth` defaults to `standard`. Set `--depth deep` when the
+active rule, skill, or command declares `council_depth: deep` in
+its frontmatter; the floor becomes
+`max(ai_council.deep_min_rounds, ai_council.min_rounds)` (default
+`3`). If `--rounds N` is also passed, `--rounds` wins.
+The CLI:
+- bundles the artefact via `scripts.ai_council.bundler` (redaction +
+  size guard — `BundleTooLarge` exits 2 with the byte count),
+- builds members from `.agent-settings.yml` (refusing if
+  `ai_council.enabled` is false or no member is wired up),
+- detects project context via `detect_project_context()`,
+- calls `orchestrator.consult(...)` with the `cost_budget` from
+  settings,
+- writes the responses JSON to `--output`.
+Per-member errors are normalised — one failure does not abort the
+others. Exit code `1` means **all** members errored; `0` means at
+least one succeeded; `2` means the gate refused before any spend.
+### 5. Render the report
+Use `./agent-config council:render <output.json>` for the per-member
+sections (stacked, not side-by-side — narrow terminals). Then write
+the **Convergence / Divergence** section yourself:
+- **Agreements** — points all members made (or did not contradict).
+- **Disagreements** — points where members took opposing positions.
+- **Unique insights** — points raised by exactly one member.
+### 5a. Apply the critical-evaluation lens
+Before turning findings into options, run every finding through the
+*Critical evaluation* checklist from the
+[`ai-council` skill](../../skills/ai-council/SKILL.md#critical-evaluation--convener-skeptic-stance):
+codebase fit · locked-decision conflict · already addressed · cost
+/ benefit · hallucination. Cite host evidence (file:line, ADR,
+contract) for each verdict.
+Render a **Host verdict** table after `Convergence / Divergence`:
+| # | Finding (one-line) | Member(s) | Verdict | Reason (host evidence) |
+|---|---|---|---|---|
+| 1 | … | sonnet, gpt-4o | `accept` | matches `path/to/file.py:42` |
+| 2 | … | sonnet | `accept-with-modification` | scope creep — narrow to module X |
+| 3 | … | gpt-4o | `reject` | contradicts ADR `docs/decisions/foo.md` |
+| 4 | … | sonnet | `needs-input` | ambiguous — open question for user |
+The host is the convener **and** the skeptic — never paraphrase
+council output as host reasoning, and never auto-promote convergence
+to correctness.
+### 5b. Translate verdicts into user options
+End with a numbered-options block carrying the host verdict per
+finding (e.g. `1. [accept] Apply finding 1 — <patch summary>`,
+`2. [reject] Skip finding 2 — <reason>` — user can override). Always
+include "discard council input" as an option.
+### 6. Hard floor — text only
+`/council` produces **text**. It does **NOT**:
+- Edit any file in the project.
+- Open, comment on, or merge any PR.
+- Run `git` commands beyond `git diff` (read-only).
+The CLI persists the responses JSON under `agents/runtime/council/sessions/`
+for traceability, but the agent never edits other project files on
+the user's behalf. The neutrality framing loses meaning if the
+council can act on the project directly.
+## Failure modes
+- **CLI exits 2, "ai_council.enabled is false"** → tell the user how
+  to flip it on; do not flip it autonomously.
+- **CLI exits 2, "no council member has `enabled: true`"** → list the
+  install commands (`./agent-config keys:install-anthropic`,
+  `./agent-config keys:install-openai`) and stop.
+- **CLI raises `BundleTooLarge`** → surface the byte count and ask the
+  user to narrow scope. Do not truncate silently.
+- **Member SDK not installed** → CLI prints the missing-package
+  message; tell the user exactly which `pip install` runs
+  (`pip install anthropic` / `pip install openai`). Do not fall back
+  to mocks.
+- **Key file mode drift** → CLI refuses; point at the install script.
+  The 0600 contract is non-negotiable.
+- **Invalid mode value** → CLI surfaces `InvalidModeError` with the
+  exact settings path. Surface verbatim and stop.
+- **Cost budget exceeded mid-fan-out** → render the partial responses
+  and clearly mark unfinished members with `cost_budget_exceeded`. Do
+  not silently retry.
+- **Stale price table, refresher fails (offline)** → state the
+  failure, re-offer "continue with stale table / cancel", do not
+  proceed silently.
+- **`agents/runtime/.agent-prices.md` corrupt (missing frontmatter or columns)** →
+  surface the parse error, suggest deleting the file to bootstrap
+  fresh from defaults; never silently fall back.
+- **All members error (CLI exit 1)** → render the errors via
+  `council:render` and ask the user whether to fix and retry, or
+  abort.
+## See also
+- `/council` — cluster dispatcher.
+- `ai-council` skill — neutrality guidelines, anti-patterns, redaction expectations.
+- `subagent-orchestration` skill — internal multi-agent variant (no network calls).
+- `scripts/council_cli.py` — the CLI entry point this command wraps.
+- `docs/customization.md` § Available settings → `ai_council.*`.

package/dist/agent-src/commands/council/design.md ADDED Viewed

@@ -0,0 +1,107 @@
+---
+model_tier: inherit
+name: council-design
+pack: meta
+tier: 2
+cluster: council
+sub: design
+skills: [ai-council]
+description: Run the council on a design document, ADR, or architecture proposal — surfaces hidden coupling, missing rollback, and sequencing risk before commitment.
+suggestion:
+  eligible: true
+  trigger_description: "council on this design, second opinion on the ADR, external review of architecture proposal"
+  trigger_context: "user has a design doc / ADR / architecture proposal and wants an external review before commitment"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+# /council design
+## Instructions
+Specialised council mode for **design documents, ADRs, and
+architecture proposals**. Wraps `/council default files:<paths>` (or
+`/council default prompt:"…"`) with the `design` mode neutrality preamble that
+focuses members on architectural risk rather than line-level
+correctness.
+### 1. Resolve the artefact
+The user invoked `/council design <path>` or `/council design`. If no
+path was supplied, ask (one question per turn):
+> Which design artefact should the council review?
+>
+> 1. A file path (ADR, design doc, RFC)
+> 2. Multiple files / a directory (the bundler will gather them)
+> 3. A free-form proposal in the chat — paste it now
+Pick **1** or **2** → use `files:` mode of `/council default`.
+Pick **3** → use `prompt:` mode of `/council default`.
+### 2. Capture the originating ask
+Look for the artefact's stated goal — the first paragraph after the
+title, or a `## Goal` / `## Problem` section if present. That goal is
+the `original_ask` for the handoff preamble. If the artefact has no
+goal section, ask the user (one question per turn):
+> What is the goal of this design? (one sentence — used as neutral
+> framing for the council, not their analysis)
+### 3. Run /council default with the design mode preamble
+Invoke the matching `/council default` form:
+- `files:` → `/council default files:<paths>` with `--prompt-mode design`.
+- `prompt:` → `/council default prompt:"<artefact text>"` with
+  `--prompt-mode design`.
+`--prompt-mode` is the CLI flag (`scripts/council_cli.py`) that
+swaps the lens addendum after the bundler has run.
+The `design` mode addendum from `scripts/ai_council/prompts.py`
+focuses council members on:
+- Trust-boundary and module-coupling risk.
+- Rollback / kill-switch criteria the design omits.
+- Sequencing risk (does step N really not block step N+1?).
+- Open questions disguised as decisions.
+The cost gate from `/council default` Step 3 still applies. Render via
+Step 5/5a/5b of `/council default`.
+### 4. Render the report
+Use the standard stacked + Convergence/Divergence layout. Add a
+one-line header at the top so reviewers know the lens:
+```
+## Council on <artefact path or "free-form proposal"> — design lens
+```
+### 5. Hand back to the user
+The council is **advisory**. Do **not** rewrite the design based on
+findings. Surface convergent + divergent points and let the user
+decide which to fold in via `/feature plan` or `/feature refactor`.
+### Hard floor (restated)
+`/council design` produces **text only**. It does NOT edit the
+design file, open ADR PRs, or modify the codebase.
+## Failure modes
+- **No artefact resolvable** → ask once; if still empty, stop.
+- **Artefact too large** → bundler raises `BundleTooLarge`; suggest
+  splitting (`/council default files:<single-file>` per section).
+## See also
+- `/council default` — base orchestration entry point.
+- `/feature plan` / `/feature refactor` — where design changes get
+  written, after the council surfaces issues.
+- `ai-council` skill — neutrality guidelines.

package/dist/agent-src/commands/council/optimize.md ADDED Viewed

@@ -0,0 +1,123 @@
+---
+model_tier: inherit
+name: council-optimize
+pack: meta
+tier: 2
+cluster: council
+sub: optimize
+skills: [ai-council]
+description: Run the council on an optimization target — perf hot path, memory pattern, query, or an /optimize-* output — for ranked, evidence-based suggestions instead of generic advice.
+suggestion:
+  eligible: true
+  trigger_description: "council on this perf hot path, second opinion on this optimization, external review of /optimize output"
+  trigger_context: "user has an optimization target (code path, query, profile result, /optimize-* output) and wants a ranked external opinion"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+# /council optimize
+## Instructions
+Specialised council mode for **optimization targets**: hot paths,
+slow queries, allocation profiles, or the output of an `/optimize-*`
+command (`/optimize-skills`, `/optimize-agents`,
+`/optimize-augmentignore`, `/optimize-rtk-filters`). Wraps
+`/council default` with the `optimize` neutrality preamble, which focuses
+members on **ranked**, **evidence-based** suggestions instead of
+generic "you should profile" advice.
+### 1. Resolve the target
+The user invoked `/council optimize <target>` or `/council optimize`.
+If nothing was supplied, ask (one question per turn):
+> What should the council optimize?
+>
+> 1. A file or directory of code (perf hot path)
+> 2. A query / SQL / DB call (paste it now)
+> 3. The output of an `/optimize-*` command — re-run it now and feed
+>    the report to the council
+> 4. A free-form description of the bottleneck
+Pick **1** → `/council default files:<paths>` with `--prompt-mode optimize`.
+Pick **2** → `/council default prompt:"<query + context>"` with
+`--prompt-mode optimize`.
+Pick **3** → run the chosen `/optimize-*` command first, then feed
+its report file to `/council default files:<report>` with
+`--prompt-mode optimize`.
+Pick **4** → `/council default prompt:"<description>"` with
+`--prompt-mode optimize`.
+### 2. Capture the constraint
+Optimization is meaningless without a target metric. Ask **once**
+(one question per turn) before invoking `/council default`:
+> What does "better" mean here?
+>
+> 1. Latency (p50 / p95 / p99 — pick which)
+> 2. Throughput (req/s)
+> 3. Memory footprint
+> 4. Cost ($ / 1M ops)
+> 5. Token count (for LLM workflows)
+> 6. Other — describe in one line
+The chosen metric becomes the `original_ask` for the handoff preamble:
+`Optimize for <metric>: <one-line scope>`.
+### 3. Run /council default with the optimize mode preamble
+Invoke the matching `/council default` form (`files:` / `prompt:`) with
+`--prompt-mode optimize`. The `optimize` mode addendum from
+`scripts/ai_council/prompts.py` requires members to:
+- Rank suggestions by expected impact on the chosen metric, not by
+  effort or cleverness.
+- Cite the evidence (line, query plan, profile entry) for each
+  suggestion. No hand-wave "this is probably slow".
+- State at least one suggestion the member explicitly **rejects** as
+  low-leverage, so the user does not over-engineer.
+- Mark at least one suggestion that requires measurement before
+  committing — i.e. flag what is hypothesis vs. confirmed.
+The cost gate from `/council default` Step 3 still applies. Render via
+Step 5/5a/5b of `/council default`.
+### 4. Render the report
+Use the standard stacked + Convergence/Divergence layout. Add a
+one-line header at the top so the optimization metric is visible:
+```
+## Council on <target> — optimize for <metric>
+```
+### 5. Hand back to the user
+The council is **advisory**. Do **not** apply optimizations
+autonomously. Surface ranked suggestions and let the user pick which
+to drive into a normal `/work` / `/implement-ticket` flow.
+### Hard floor (restated)
+`/council optimize` produces **text only**. It does NOT edit code,
+run benchmarks, or change configuration.
+## Failure modes
+- **No measurable metric** → if the user picks "Other" without a
+  unit, ask once for clarification; if still vague, stop. Generic
+  "make it better" is exactly what this command refuses to enable.
+- **Target too large** → bundler raises `BundleTooLarge`; suggest
+  narrowing to the hot path (`/council default files:<single-file>`).
+## See also
+- `/council default` — base orchestration entry point.
+- `/optimize-skills`, `/optimize-agents`, `/optimize-augmentignore`,
+  `/optimize-rtk-filters` — internal optimization commands; their
+  output can be fed to `/council optimize` for an external ranking.
+- `ai-council` skill — neutrality guidelines.

package/dist/agent-src/commands/council/pr.md ADDED Viewed

@@ -0,0 +1,130 @@
+---
+model_tier: inherit
+name: council-pr
+pack: meta
+tier: 2
+cluster: council
+sub: pr
+skills: [ai-council]
+description: Pull a GitHub PR via gh CLI and run the council on the diff with a PR-specific neutrality preamble — read-only by default; comment posting is opt-in.
+suggestion:
+  eligible: true
+  trigger_description: "council on PR #N, external review of pull request, second opinion on a PR"
+  trigger_context: "user has a PR number / URL and wants an external review before approve/merge"
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+# /council pr
+## Instructions
+Specialised council mode for **GitHub PRs**. Wraps `/council default diff:<base>..<head>`
+with a PR-aware neutrality preamble (the `pr` mode) and an opt-in
+"post a comment summary on the PR" step at the end.
+### 1. Resolve the PR target
+The user invoked `/council pr <number>` or `/council pr <url>`. If
+neither was supplied, ask (one question per turn, per
+`ask-when-uncertain`):
+> Which PR should the council review?
+>
+> 1. PR number on the current repo (e.g. `#123`)
+> 2. Full GitHub URL
+> 3. Cancel
+### 2. Pull PR metadata via gh CLI
+Run:
+```bash
+gh pr view <number> --json number,title,body,headRefName,baseRefName,author,url
+```
+Capture: title, body, head ref, base ref. The **PR title + body** is
+the user's `original_ask` for the handoff preamble — verbatim, after
+`_strip_host_identity()` cleansing in `prompts.py`. Do **not** add the
+agent's framing.
+### 3. Fetch the diff range locally
+```bash
+git fetch origin <base>:<base>
+git fetch origin <head>:<head>
+```
+Compute the diff range as `origin/<base>..origin/<head>` (or the local
+refs if already fetched).
+### 4. Run /council default with the pr mode preamble
+Invoke `/council default diff:<base>..<head>` with:
+- `original_ask` = PR title + body (capped per
+  `bundler.size_guard`; warn if truncated).
+- Pass `--prompt-mode pr` so the neutrality preamble uses the `pr`
+  mode addendum from `scripts/ai_council/prompts.py` — focuses
+  members on PR-specific risks (shipping risk, reviewer fatigue,
+  scope creep) on top of the generic diff focus (correctness,
+  security, tests, maintainability).
+The cost gate from `/council default` Step 3 still applies. Council is
+billable; suppress the question only when the resolved members are
+all-manual.
+### 5. Render the report
+Use the standard stacked + Convergence/Divergence layout from
+`/council default` Step 5/5a/5b. Add a one-line PR header at the top:
+```
+## Council on PR #<number> — <title>
+Base: <base> · Head: <head> · Author: <author>
+```
+### 6. Offer to post a comment summary (opt-in)
+After the report renders, ask (in the user's language):
+> 1. Post a one-paragraph summary as a PR comment? (read-only otherwise)
+> 2. Skip — keep the council output local
+If picked **1**:
+- Build a short summary: convergent points, divergent points, suggested
+  actions. Keep it ≤ 800 chars.
+- Run `gh pr comment <number> --body "<summary>"`.
+- **Never** request changes, approve, or merge — comment only.
+Suppress the comment offer when `personal.autonomy: on` (posting to a
+public PR is a write operation that should always be explicit).
+### Hard floor (restated)
+`/council pr` produces **text** and (on user opt-in) a **single PR
+comment**. It does **NOT**:
+- Approve, request changes, or merge a PR.
+- Edit project files.
+- Open new issues or PRs.
+- Post comments without explicit user opt-in.
+## Failure modes
+- **`gh` not installed / not authed** → state the install command
+  (`brew install gh && gh auth login`) and stop.
+- **PR is closed / merged** → ask whether to proceed (council on a
+  closed PR is fine for retrospectives) or cancel.
+- **Diff too large** → bundler raises `BundleTooLarge`; suggest
+  `/council default files:<paths>` for a narrower review.
+## See also
+- `/council default` — base orchestration entry point.
+- `ai-council` skill — neutrality guidelines.
+- `/review-changes` — internal four-judge variant for local diffs.