npm - @event4u/agent-config - Versions diffs - 1.16.0 → 1.18.0 - Mend

@event4u/agent-config 1.16.0 → 1.18.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 (224) hide show

package/.agent-src/commands/{copilot-agents-optimize.md → copilot-agents/optimize.md} RENAMED Viewed

@@ -1,5 +1,7 @@
 ---
-name: copilot-agents-optimize
+name: copilot-agents:optimize
+cluster: copilot-agents
+sub: optimize
 description: Analyzes and refactors AGENTS.md and copilot-instructions.md — removes duplications, enforces line budgets, and ensures both files are optimized for their audience.
 skills: [copilot-agents-optimization, copilot-config, agent-docs-writing]
 disable-model-invocation: true
@@ -8,8 +10,7 @@ suggestion:
   rationale: "Maintenance refactor; only when the maintainer chooses to run it."
 ---
-# /copilot-agents-optimize
+# /copilot-agents optimize
 Analyzes and refactors `AGENTS.md` and `.github/copilot-instructions.md` against the `.augment/` ecosystem.
 ## Steps

package/.agent-src/commands/copilot-agents.md ADDED Viewed

@@ -0,0 +1,44 @@
+---
+name: copilot-agents
+description: Copilot agents-doc orchestrator — routes to init, optimize
+cluster: copilot-agents
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "create AGENTS.md, optimize copilot-instructions.md, scaffold copilot agent docs"
+  trigger_context: "user wants to author or tune AGENTS.md / copilot-instructions.md"
+---
+# /copilot-agents
+Top-level orchestrator for the `/copilot-agents` family. Replaces 2
+standalone commands with a single entry point + sub-command dispatch.
+## Sub-commands
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/copilot-agents init` | `commands/copilot-agents/init.md` | Create AGENTS.md and `.github/copilot-instructions.md` from scratch |
+| `/copilot-agents optimize` | `commands/copilot-agents/optimize.md` | Refactor existing AGENTS.md and copilot-instructions.md for line budgets |
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+## Dispatch
+1. Parse the user's argument: `/copilot-agents <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Instructions` section
+   verbatim with the remaining args.
+4. If the sub-command is unknown or missing, print the table above and ask:
+   > 1. init — scaffold AGENTS.md + copilot-instructions.md from scratch
+   > 2. optimize — refactor existing files for budget and audience
+## Rules
+- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
+  authorizes it.
+- **Do NOT chain sub-commands.** One `/copilot-agents <sub>` per turn.
+- If the user invokes `/copilot-agents` with no argument, **show the
+  menu** — do not guess which sub-command they meant.

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

@@ -0,0 +1,221 @@
+---
+name: council:default
+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.
+disable-model-invocation: true
+suggestion:
+  eligible: false
+  rationale: "Default lens — invoked via /council dispatcher; no direct trigger."
+---
+# /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). `mode:playwright`
+is reserved for Phase 2c — refuse politely if invoked.
+Optional **rounds**: `rounds:N` (1-3) enables multi-round debate. 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.
+Default `rounds:1`.
+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 `.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 (`api`).
+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).
+- `playwright` → reserved for Phase 2c. If a settings/invocation
+  resolves to it, refuse with a one-line note.
+### 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.
+Compute `orchestrator.estimate(question, members, table)` over the
+**billable** subset only (`getattr(m, "billable", True)`). Manual
+members contribute `$0` and skip the estimate.
+Render the cost-confirmation numbered-options block per the
+`ai-council` skill (§ Pre-call estimate format) — per-member tokens
++ USD, projected total, budget caps, then `1. Run / 2. Cancel`. If
+the resolved member set is **all-manual**, skip the gate entirely
+(spend = $0) and proceed directly to Step 4.
+Wait for the user's pick. `1` proceeds; anything else aborts.
+### 4. Bundle the context
+Use `scripts.ai_council.bundler`:
+- `prompt` mode → `bundle_prompt(text)`
+- `roadmap` mode → `bundle_roadmap(path)`
+- `diff` mode → `bundle_diff(base, head)`
+- `files` mode → `bundle_files(paths)`
+The bundler runs redaction + size guard. If `BundleTooLarge` raises,
+surface the byte count and ask the user to narrow scope. Do **not**
+truncate silently.
+Print the manifest (what was included) and the excluded list before
+sending — gives the user a chance to abort if scope is wrong.
+### 5. Run the orchestrator
+Members are constructed from the settings file plus
+`load_anthropic_key()` / `load_openai_key()`. Cost budget comes from
+`ai_council.cost_budget`.
+Detect project context once via
+`scripts.ai_council.project_context.detect_project_context()` (reads
+`composer.json`, `package.json`, root `README.md` — never raises;
+empty-fields fall back to bare neutrality preamble).
+Call:
+```python
+consult(
+    members, question, budget,
+    table=table,
+    on_overrun=_handle_overrun,
+    project=project,
+    original_ask=original_ask,
+    rounds=rounds,  # 1 by default; 2-3 enables multi-round debate
+)
+```
+`project` + `original_ask` flow into `handoff_preamble()` so each
+member receives a neutral context-handoff alongside the artefact
+(see `ai-council` skill § Neutrality — context-handoff). Members run
+**sequentially**; per-member errors are normalised — one failure
+does not abort the others. Define `_handle_overrun(event)` per the
+`ai-council` skill (§ Mid-flow overrun callback) to surface the user
+prompt before each breaching member.
+### 6. Render the report
+Use `scripts.ai_council.orchestrator.render(responses)` 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.
+- **Suggested next actions** — translated into concrete options for
+  the user.
+End with a numbered-options block asking the user how to proceed
+(e.g. update the roadmap, request a second round, ignore the
+critique).
+### 7. 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).
+- Persist API responses outside the current chat unless the user
+  explicitly asks (Phase 4 — out of scope for v1).
+This is restated in step 7 deliberately. The neutrality framing
+loses meaning if the council can act on the project directly.
+## Failure modes
+- **Member SDK not installed** → tell the user exactly which `pip
+  install` runs (`pip install anthropic` / `pip install openai`).
+  Do not fall back to mocks.
+- **Key file mode drift** → refuse and point at the install script.
+  The 0600 contract is non-negotiable.
+- **Manual mode + non-interactive stdin** → `ManualClient` reads
+  pasted replies from stdin terminated by a line containing only
+  `END`. If stdin is closed before any reply lands, the member
+  returns empty text with `error="manual_aborted"`; render the
+  partial result and ask the user.
+- **Invalid mode value** → `resolve_mode()` raises
+  `InvalidModeError` with the exact settings path. Surface verbatim
+  and stop.
+- **Cost budget exceeded mid-fan-out** → render the partial
+  responses and clearly mark the unfinished members with their
+  `cost_budget_exceeded` error. Do not silently retry.
+- **Stale price table, refresher fails (offline)** → state the
+  failure, re-offer "continue with stale table / cancel", do not
+  proceed silently.
+- **`.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** → render the errors 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).
+- `docs/customization.md` § Available settings → `ai_council.*`.

package/.agent-src/commands/{council-design.md → council/design.md} RENAMED Viewed

@@ -1,6 +1,7 @@
 ---
-name: council-design
-cluster: optimize
+name: council:design
+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.
 disable-model-invocation: true
@@ -10,7 +11,7 @@ suggestion:
   trigger_context: "user has a design doc / ADR / architecture proposal and wants an external review before commitment"
 ---
-# council-design
+# /council design
 ## Instructions
@@ -22,7 +23,7 @@ correctness.
 ### 1. Resolve the artefact
-The user invoked `/council-design <path>` or `/council-design`. If no
+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?
@@ -79,7 +80,7 @@ decide which to fold in via `/feature plan` or `/feature refactor`.
 ### Hard floor (restated)
-`/council-design` produces **text only**. It does NOT edit the
+`/council design` produces **text only**. It does NOT edit the
 design file, open ADR PRs, or modify the codebase.
 ## Failure modes

package/.agent-src/commands/{council-optimize.md → council/optimize.md} RENAMED Viewed

@@ -1,6 +1,7 @@
 ---
-name: council-optimize
-cluster: optimize
+name: council:optimize
+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.
 disable-model-invocation: true
@@ -10,7 +11,7 @@ suggestion:
   trigger_context: "user has an optimization target (code path, query, profile result, /optimize-* output) and wants a ranked external opinion"
 ---
-# council-optimize
+# /council optimize
 ## Instructions
@@ -24,7 +25,7 @@ generic "you should profile" advice.
 ### 1. Resolve the target
-The user invoked `/council-optimize <target>` or `/council-optimize`.
+The user invoked `/council optimize <target>` or `/council optimize`.
 If nothing was supplied, ask (one question per turn):
 > What should the council optimize?
@@ -95,7 +96,7 @@ to drive into a normal `/work` / `/implement-ticket` flow.
 ### Hard floor (restated)
-`/council-optimize` produces **text only**. It does NOT edit code,
+`/council optimize` produces **text only**. It does NOT edit code,
 run benchmarks, or change configuration.
 ## Failure modes
@@ -111,5 +112,5 @@ run benchmarks, or change configuration.
 - `/council` — 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.
+  output can be fed to `/council optimize` for an external ranking.
 - `ai-council` skill — neutrality guidelines.

package/.agent-src/commands/{council-pr.md → council/pr.md} RENAMED Viewed

@@ -1,6 +1,7 @@
 ---
-name: council-pr
-cluster: optimize
+name: council:pr
+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.
 disable-model-invocation: true
@@ -10,7 +11,7 @@ suggestion:
   trigger_context: "user has a PR number / URL and wants an external review before approve/merge"
 ---
-# council-pr
+# /council pr
 ## Instructions
@@ -20,7 +21,7 @@ with a PR-aware neutrality preamble (the `pr` mode) and an opt-in
 ### 1. Resolve the PR target
-The user invoked `/council-pr <number>` or `/council-pr <url>`. If
+The user invoked `/council pr <number>` or `/council pr <url>`. If
 neither was supplied, ask (one question per turn, per
 `ask-when-uncertain`):
@@ -99,7 +100,7 @@ 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
+`/council pr` produces **text** and (on user opt-in) a **single PR
 comment**. It does **NOT**:
 - Approve, request changes, or merge a PR.

package/.agent-src/commands/council.md CHANGED Viewed

@@ -1,219 +1,54 @@
 ---
 name: council
-cluster: optimize
-skills: [ai-council]
-description: Consult external AIs (OpenAI, Anthropic) for an independent second opinion on a prompt, roadmap, diff, or file set — neutral framing, redacted context, advisory output only.
+description: Council orchestrator — routes to default, pr, design, optimize
+cluster: council
 disable-model-invocation: true
 suggestion:
   eligible: true
-  trigger_description: "external second opinion, cross-AI review, devil's advocate on a plan/roadmap/diff, polling another model"
-  trigger_context: "user wants an outside critique on an artefact (roadmap, diff, prompt, files) without polluting the reviewer with the host agent's framing"
+  trigger_description: "external second opinion, cross-AI review, devil's advocate on a plan/roadmap/diff, council on PR/design/optimize, polling another model"
+  trigger_context: "user wants an outside critique on an artefact (roadmap, diff, prompt, files, PR, design doc, optimization target) without polluting the reviewer with the host agent's framing"
 ---
-# council
-## Instructions
-### 1. Resolve the target + capture the original ask
-The user invoked `/council` 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). `mode:playwright`
-is reserved for Phase 2c — refuse politely if invoked.
-Optional **rounds**: `rounds:N` (1-3) enables multi-round debate. 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.
-Default `rounds:1` (single round, v1 behaviour).
-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 (`prompt:` /
-`roadmap:` / `diff:` / `files:`) is unchanged; only the per-mode
-neutrality addendum is replaced. Routed by `/council-pr`,
-`/council-design`, `/council-optimize` — surface to the user as
-"council on <target> — <lens> lens" so the report header is
-unambiguous.
-If none 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 so council members receive
-the neutral handoff preamble alongside the artefact (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 `.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 (`api`).
-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).
-- `playwright` → reserved for Phase 2c. If a settings/invocation
-  resolves to it, refuse with a one-line note.
-### 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.
-Compute `orchestrator.estimate(question, members, table)` over the
-**billable** subset only (`getattr(m, "billable", True)`). Manual
-members contribute `$0` and skip the estimate.
-Render the cost-confirmation numbered-options block per the
-`ai-council` skill (§ Pre-call estimate format) — per-member tokens
-+ USD, projected total, budget caps, then `1. Run / 2. Cancel`. If
-the resolved member set is **all-manual**, skip the gate entirely
-(spend = $0) and proceed directly to Step 4.
-Wait for the user's pick. `1` proceeds; anything else aborts.
-### 4. Bundle the context
-Use `scripts.ai_council.bundler`:
-- `prompt` mode → `bundle_prompt(text)`
-- `roadmap` mode → `bundle_roadmap(path)`
-- `diff` mode → `bundle_diff(base, head)`
-- `files` mode → `bundle_files(paths)`
-The bundler runs redaction + size guard. If `BundleTooLarge` raises,
-surface the byte count and ask the user to narrow scope. Do **not**
-truncate silently.
-Print the manifest (what was included) and the excluded list before
-sending — gives the user a chance to abort if scope is wrong.
-### 5. Run the orchestrator
-Members are constructed from the settings file plus
-`load_anthropic_key()` / `load_openai_key()`. Cost budget comes from
-`ai_council.cost_budget`.
-Detect project context once via
-`scripts.ai_council.project_context.detect_project_context()` (reads
-`composer.json`, `package.json`, root `README.md` — never raises;
-empty-fields fall back to bare neutrality preamble).
-Call:
-```python
-consult(
-    members, question, budget,
-    table=table,
-    on_overrun=_handle_overrun,
-    project=project,
-    original_ask=original_ask,
-    rounds=rounds,  # 1 by default; 2-3 enables multi-round debate
-)
-```
-`project` + `original_ask` flow into `handoff_preamble()` so each
-member receives a neutral context-handoff alongside the artefact
-(see `ai-council` skill § Neutrality — context-handoff). Members run
-**sequentially**; per-member errors are normalised — one failure
-does not abort the others. Define `_handle_overrun(event)` per the
-`ai-council` skill (§ Mid-flow overrun callback) to surface the user
-prompt before each breaching member.
-### 6. Render the report
-Use `scripts.ai_council.orchestrator.render(responses)` 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.
-- **Suggested next actions** — translated into concrete options for
-  the user.
-End with a numbered-options block asking the user how to proceed
-(e.g. update the roadmap, request a second round, ignore the
-critique).
-### 7. 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).
-- Persist API responses outside the current chat unless the user
-  explicitly asks (Phase 4 — out of scope for v1).
-This is restated in step 7 deliberately. The neutrality framing
-loses meaning if the council can act on the project directly.
-## Failure modes
-- **Member SDK not installed** → tell the user exactly which `pip
-  install` runs (`pip install anthropic` / `pip install openai`).
-  Do not fall back to mocks.
-- **Key file mode drift** → refuse and point at the install script.
-  The 0600 contract is non-negotiable.
-- **Manual mode + non-interactive stdin** → `ManualClient` reads
-  pasted replies from stdin terminated by a line containing only
-  `END`. If stdin is closed before any reply lands, the member
-  returns empty text with `error="manual_aborted"`; render the
-  partial result and ask the user.
-- **Invalid mode value** → `resolve_mode()` raises
-  `InvalidModeError` with the exact settings path. Surface verbatim
-  and stop.
-- **Cost budget exceeded mid-fan-out** → render the partial
-  responses and clearly mark the unfinished members with their
-  `cost_budget_exceeded` error. Do not silently retry.
-- **Stale price table, refresher fails (offline)** → state the
-  failure, re-offer "continue with stale table / cancel", do not
-  proceed silently.
-- **`.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** → render the errors and ask the user
-  whether to fix and retry, or abort.
-## See also
-- `ai-council` skill — neutrality guidelines, anti-patterns, redaction expectations.
-- `subagent-orchestration` skill — internal multi-agent variant (no network calls).
-- `docs/customization.md` § Available settings → `ai_council.*`.
+# /council
+Top-level orchestrator for the `/council` family. Replaces 4 standalone
+commands with a single entry point + sub-command dispatch. Each lens
+shares the same transport, neutrality preamble, and cost gate; the
+sub-command swaps the mode-specific addendum.
+## Sub-commands
+| Sub-command | Routes to | Purpose |
+|---|---|---|
+| `/council default` | `commands/council/default.md` | Generic neutral lens — prompt, roadmap, diff, or files |
+| `/council pr` | `commands/council/pr.md` | Pull a GitHub PR via `gh` and run the council on the diff with PR-specific framing |
+| `/council design` | `commands/council/design.md` | Run the council on a design doc / ADR / architecture proposal |
+| `/council optimize` | `commands/council/optimize.md` | Run the council on an optimization target — ranked, evidence-based suggestions |
+Sub-command names match the locked contract in
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+## Dispatch
+1. Parse the user's argument: `/council <sub-command> [args]`.
+2. Look up the sub-command in the table above.
+3. Load the body of the routed file and follow its `## Instructions` section
+   verbatim with the remaining args.
+4. If the sub-command is unknown or missing, print the table above and ask:
+   > 1. default — neutral lens on a prompt / roadmap / diff / files
+   > 2. pr — review a GitHub PR (read-only by default)
+   > 3. design — review a design doc / ADR / architecture proposal
+   > 4. optimize — ranked, evidence-based optimization advice
+## Rules
+- **Do NOT commit, push, or open a PR** unless the sub-command explicitly
+  authorizes it. The PR sub-command can post **one** comment per
+  invocation, opt-in only.
+- **Do NOT chain sub-commands.** One `/council <sub>` per turn.
+- **Hard floor — text only.** `/council` produces text and (under
+  `pr` with explicit opt-in) one PR comment. It does NOT edit files,
+  approve / merge PRs, or run optimizations.
+- If the user invokes `/council` with no argument, **show the menu** —
+  do not guess which sub-command they meant.