@event4u/agent-config 1.15.0 → 1.17.0

package/llms.txt

@@ -16,7 +16,7 @@ api-testing: Use when writing API endpoint tests — integration tests, contract
 artisan-commands: Use when creating or modifying Artisan commands. Covers clear signatures, safe execution flow, helpful output, and project conventions for console tooling.
 authz-review: Use when reviewing authorization end-to-end — route → gate → policy → query scope → response filter — before changes to permissions, tenants, ownership, or admin flows.
 aws-infrastructure: Use when working with AWS resources — ECS Fargate, ECR, EFS, Secrets Manager, gomplate templates, multi-env deployments — even when the user says 'deploy to staging' without naming AWS.
-blade-ui: Use when creating or editing Blade views, components, partials, layouts, or view logic — even when the user says 'add a new page' or 'render this data' without naming Blade.
+blade-ui: Stack-implementation skill for Laravel Blade — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Blade. Covers views, components, partials, layouts, and view logic.
 blast-radius-analyzer: Use BEFORE editing shared code — enumerates every call site, event consumer, queue worker, API client, migration, and test that a planned change will touch, with a file:line citation per dependency.
 bug-analyzer: Use when the user shares a Sentry error, Jira bug ticket, or error description and wants root cause analysis. Also for proactive bug hunting and code audits for hidden bugs.
 check-refs: Use when verifying cross-references between skills, rules, commands, guidelines, and context documents are not broken after edits, renames, or deletions.
@@ -41,15 +41,17 @@ developer-like-execution: Use when implementing, debugging, refactoring, or revi
 docker: Use when working with Docker — Dockerfile edits, docker-compose services, containers, or the dual-container (fast + Xdebug) setup — even when the user just says 'my container won't start'.
 dto-creator: Use when the user says "create a DTO", "new data transfer object", or needs to convert request/response data into a typed PHP class. Creates DTOs with SimpleDto base class and attribute mapping.
 eloquent: Use when writing Eloquent models, relationships, scopes, or queries via Model:: — 'fetch users with their orders'. NOT for PHPStan output, non-Eloquent services, or raw SQL questions.
-fe-design: Use when designing frontend interfaces — component architecture, layout patterns, form design, table patterns, responsive strategies, and UX principles for Blade/Livewire/Flux/Tailwind.
+"estimate-ticket": Estimate a Jira/Linear ticket — 'estimate PROJ-123', 'wie groß ist das?', 'should we split this?' — size + risk + split + uncertainty, sibling of /refine-ticket, close-prompt.
+existing-ui-audit: Use BEFORE writing or editing any non-trivial UI — inventories components, design tokens, shadcn primitives, and reusable patterns into state.ui_audit. Hard gate for the ui directive set.
+fe-design: Reference for frontend-design heuristics — component architecture, layout patterns, form/table design, responsive strategy, a11y, UX principles. Stack-agnostic; cited by directives/ui/design.py.
 feature-planning: Use when the user says "plan a feature", "brainstorm", "explore this idea", or wants to go from idea to structured plan and roadmap.
 file-editor: Use when opening edited files in the user's IDE. Reads settings from .agent-settings.yml to determine IDE and whether auto-open is enabled.
 finishing-a-development-branch: Use when the feature is implementation-complete and the next step is 'ship it' — verifies, cleans up, and routes to merge/PR/park/discard — even when the user just says 'I'm done, what now?'.
-flux: Use when writing Laravel Flux UI components — the official Livewire component library by the Laravel team. Covers components, slots, and variants.
+flux: Stack-implementation skill for Laravel Flux — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project uses `livewire/flux`. Covers Flux components, slots, variants, and form primitives.
 git-workflow: Use when working with Git — branch naming, commit messages, PR creation, rebasing, or the code review process — even when the user says 'push this' or 'merge the branch' without naming Git.
 github-ci: Use when working with GitHub Actions — workflow YAML, quality gates, test matrices, deployment triggers, reusable workflows — even when the user just says 'my CI is failing' or 'add a check'.
 grafana: Use when working with Grafana — dashboards, Loki LogQL queries, alerting rules, monitoring panels — even when the user just says 'build me a dashboard' or 'query the logs' without naming Grafana.
-guideline-writing: Use when creating or editing a guideline in .agent-src.uncompressed/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'.
+guideline-writing: Use when creating or editing a guideline in docs/guidelines/ — reference material cited by skills, no auto-triggers — even when the user just says 'write up our naming conventions'.
 jira-integration: Use when the user says "check Jira", "create ticket", "update issue", or needs JQL queries, ticket transitions, or branch-to-ticket linking.
 jobs-events: Use when creating Laravel jobs, queued workflows, events, or listeners. Covers clear responsibilities, safe serialization, and retry/failure handling.
 judge-bug-hunter: Use when a diff needs correctness review — null-safety, edge cases, off-by-one, races, error handling — dispatched by /review-changes, /do-and-judge, /judge, even without 'judge'.
@@ -68,9 +70,10 @@ laravel-scheduling: Use when configuring Laravel task scheduling — cron expres
 laravel-validation: Use when writing validation — Form Requests, rules, custom rule objects, request-boundary design — even when the user just says 'validate this input' or 'check the request' without naming it.
 learning-to-rule-or-skill: Use when a repeated learning, mistake, or successful pattern should be turned into a new rule or skill. Also use after completing a task to capture learnings from the work.
 lint-skills: Use when running the package's skill linter against all skills and rules to validate frontmatter, required sections, and execution metadata.
-livewire: Use when writing Livewire components — reactive state, events, lifecycle hooks, and clean separation between component logic and Blade templates.
+livewire: Stack-implementation skill for Livewire — dispatched by `directives/ui/apply.py` (and `review.py` / `polish.py`) when the project's frontend stack is Livewire. Covers reactive state, events, lifecycle hooks, and component/view separation.
 logging-monitoring: Use when working with logging or monitoring — Sentry error tracking, Grafana/Loki log aggregation, structured logging channels, or monitoring helpers.
 mcp: Use when working with MCP (Model Context Protocol) servers — their tools, capabilities, and best practices for effective agent workflows.
+md-language-check: Use BEFORE saving any .md under .augment/, .agent-src*/, or agents/ — scans umlauts, German function words, and quoted German phrases outside DE:/EN: anchor blocks. Hard gate per language-and-tone.
 merge-conflicts: Use when the user has merge conflicts or says "resolve conflicts". Understands conflict markers, resolution strategies, and verification workflow.
 migration-creator: Use when the user says "create migration", "add column", or "new table". Creates migrations with correct table prefixes, column naming, and multi-tenant awareness.
 module-management: Use when the user says "create module", "explore module", or works within app/Modules/. Understands module structure, auto-loading, route registration, and namespace conventions.
@@ -95,10 +98,13 @@ project-analysis-zend-laminas: Use for deep Zend Framework or Laminas project an
 project-analyzer: ONLY when user explicitly requests: full project analysis, tech stack detection, or structured analysis documents for agents/analysis/. NOT for regular feature work.
 project-docs: Use when looking for project-specific documentation. Knows which docs exist in agents/docs/ and agents/contexts/ and maps work areas to relevant docs.
 quality-tools: Use when PHPStan, Rector, or ECS output appears — \"phpstan says mixed\", type errors, \"fix code style\", \"run rector\" — even when Eloquent/Laravel/model code is also mentioned.
+react-shadcn-ui: Use when building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack.
 readme-reviewer: Use when reviewing a README for accuracy, usability, and alignment with the actual repository. Detects invented content, broken setup steps, and structural issues.
 readme-writing: Use when creating, rewriting, or significantly improving a README based on the actual repository structure, commands, and intended audience.
 readme-writing-package: Use when creating or rewriting a README for a reusable package or library. Focus on installability, minimal usage example, compatibility, and developer onboarding.
 receiving-code-review: Use when processing code review feedback (bot or human) before changing anything — triages, verifies, and pushes back with technical reasoning — even when the user just says 'fix the comments'.
+"refine-prompt": Reconstruct a free-form prompt into actionable AC + assumptions + confidence band before the engine plans — '/work \"…\"', 'baue X', 'ist der Prompt klar genug für die Engine?'.
+"refine-ticket": Refine a Jira/Linear ticket before planning — 'refine ticket', 'tighten AC on PROJ-123', 'ist das Ticket klar?' — rewritten ticket, Top-5 risks, persona voices, sub-skills orchestrated, close-prompt.
 requesting-code-review: Use when asking for a review or creating a PR — self-review first, frame the right context, test plan included — even when the user just says 'open a PR' or 'ready to merge'.
 review-routing: Use when preparing a PR description, suggesting reviewers, or flagging risk — produces owner-mapped roles plus historical bug-pattern matches from project-local YAML.
 roadmap-management: Use when the user says "create roadmap", "show roadmap", or "execute roadmap". Creates, reads, and manages roadmap files with phase tracking.
@@ -113,7 +119,7 @@ skill-management: Use when compressing, decompressing, refactoring, or improving
 skill-reviewer: Use when reviewing, auditing, or optimizing skills — validates against the 7 Skill Killers checklist and produces fix recommendations.
 skill-writing: Use when deciding 'should this be a skill or a rule?', creating/improving/reviewing agent skills, SKILL.md frontmatter, or procedure sections — even without saying 'skill-writing'.
 sql-writing: Use when writing raw SQL — MariaDB/MySQL syntax, parameterization, raw migrations, seeders with `DB::statement` — even when the user just pastes a query and asks 'why is this slow' without naming SQL.
-subagent-orchestration: Use when orchestrating implementer/judge subagents — five modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate) — model pairing and parallelism from .agent-settings.yml.
+subagent-orchestration: Use when orchestrating implementer/judge subagents — five modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate) — models from .agent-settings.yml.
 systematic-debugging: Use when hitting a bug, test failure, crash, or unexpected behavior — enforces reproduce → isolate → hypothesize → verify before any fix — even when the user just says 'this is broken' or 'quick fix'.
 technical-specification: Use when the user says "write a spec", "create RFC", or "document this decision". Writes technical specifications, RFCs, and ADRs with clear structure.
 terraform: Use when writing Terraform — AWS modules, resources, variables, outputs, remote state — even when the user just says 'provision this infra' or 'add an S3 bucket' without naming Terraform.
@@ -126,5 +132,5 @@ universal-project-analysis: ONLY when user explicitly requests: full project ana
 upstream-contribute: Use when a learning, new skill, rule improvement, or bug fix from a consumer project should be contributed back to the shared agent-config package.
 using-git-worktrees: Use when starting parallel work in isolation from the current branch — spawn a git worktree with ignore-safety checks and a clean test baseline — even when the user says 'try this on the side'.
 "validate-feature-fit": Validate whether a feature request fits the existing codebase — check for duplicates, contradictions, scope creep, and architectural misfit
-verify-before-complete: Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs.
+verify-completion-evidence: Use when claiming 'done', suggesting a commit, push, or PR — runs the evidence gate so completion claims come from fresh output in this message, not memory or earlier runs.
 websocket: Use when building real-time features — WebSocket broadcasting, live updates, presence channels, connection state — even when the user just says 'push this to the client live'.

package/package.json

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

package/scripts/_one_off_phase4_dispatch_latency.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+"""Phase 4.3.1 — council cluster dispatch-latency benchmark.
+
+Measures the wall-clock overhead of the cluster dispatch layer for the
+`/council` family. Compares:
+
+  baseline: directly read council-pr.md / council-design.md (atomic shape)
+  cluster : read council.md (dispatcher) + parse table + read council-pr.md
+            / council-design.md (cluster shape)
+
+The dispatch layer in agent-config is a markdown parse, not a runtime
+function, so this benchmarks the file-system + frontmatter + table-row
+extraction cost. Threshold per roadmap § 4.3.1: ≤ +100ms wall-clock.
+"""
+from __future__ import annotations
+
+import re
+import statistics
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+COMMANDS = ROOT / ".agent-src/commands"
+N_ITER = 1000  # cold + warm; markdown is tiny so we run a lot of iterations
+
+FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
+TABLE_ROW_RE = re.compile(r"\|\s*`/council\s+([a-z-]+)`\s*\|\s*`([^`]+)`")
+
+
+def _read_atomic(target: str) -> str:
+    """Baseline: directly read the routed file (atomic shape)."""
+    path = COMMANDS / f"council-{target}.md"
+    text = path.read_text(encoding="utf-8")
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        raise RuntimeError(f"no frontmatter in {path}")
+    return text
+
+
+def _read_cluster(target: str) -> str:
+    """Cluster: read dispatcher, parse routing table, then read routed file."""
+    dispatcher = (COMMANDS / "council.md").read_text(encoding="utf-8")
+    routes = dict(TABLE_ROW_RE.findall(dispatcher))
+    routed = routes.get(target)
+    if routed is None:
+        raise RuntimeError(f"no route for {target!r} in dispatcher")
+    text = (COMMANDS / routed).read_text(encoding="utf-8")
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        raise RuntimeError(f"no frontmatter in {routed}")
+    return text
+
+
+def _bench(fn, target: str, n: int) -> list[float]:
+    samples: list[float] = []
+    for _ in range(n):
+        t0 = time.perf_counter()
+        fn(target)
+        samples.append((time.perf_counter() - t0) * 1000.0)
+    return samples
+
+
+def _summary(name: str, samples: list[float]) -> None:
+    samples = sorted(samples)
+    p50 = statistics.median(samples)
+    p95 = samples[int(len(samples) * 0.95)]
+    p99 = samples[int(len(samples) * 0.99)]
+    mean = statistics.mean(samples)
+    print(f"  {name:18s}  mean={mean:6.3f}ms  p50={p50:6.3f}ms  p95={p95:6.3f}ms  p99={p99:6.3f}ms")
+
+
+def main() -> int:
+    print(f"Phase 4.3.1 — council cluster dispatch latency  (n={N_ITER} per probe)")
+    print()
+
+    overruns = 0
+    for target in ("pr", "design"):
+        print(f"target = /council {target}")
+
+        # warm cache
+        _read_atomic(target)
+        _read_cluster(target)
+
+        baseline = _bench(_read_atomic, target, N_ITER)
+        cluster = _bench(_read_cluster, target, N_ITER)
+
+        _summary("atomic   (baseline)", baseline)
+        _summary("cluster  (dispatcher)", cluster)
+
+        delta_mean = statistics.mean(cluster) - statistics.mean(baseline)
+        delta_p95 = sorted(cluster)[int(N_ITER * 0.95)] - sorted(baseline)[int(N_ITER * 0.95)]
+        verdict = "PASS" if delta_p95 <= 100.0 else "FAIL"
+        marker = "✅" if verdict == "PASS" else "❌"
+        print(f"  delta-mean = {delta_mean:+.3f}ms  delta-p95 = {delta_p95:+.3f}ms  threshold = +100ms  {marker} {verdict}")
+        print()
+
+        if delta_p95 > 100.0:
+            overruns += 1
+
+    if overruns:
+        print(f"❌  {overruns} probe(s) exceeded +100ms p95 threshold.")
+        return 1
+    print("✅  All probes within +100ms p95 threshold.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/_one_off_phase6_trigger_jaccard.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Phase 6.1 — chat-history-* trigger overlap (Jaccard).
+
+Source of truth per rule = frontmatter `description:` field
+(the trigger surface that decides when an `auto` rule activates).
+Tokens = lowercased alphanum words length ≥ 3, minus a small
+stop-list of file-name fragments and connective words that carry
+no trigger signal.
+
+Output: pairwise Jaccard + branch verdict per roadmap § 6.1.
+"""
+from __future__ import annotations
+
+import re
+from itertools import combinations
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+RULES_DIR = ROOT / ".agent-src.uncompressed/rules"
+
+RULES = [
+    "chat-history-cadence",
+    "chat-history-ownership",
+    "chat-history-visibility",
+]
+
+STOP = {
+    "the", "and", "for", "with", "from", "via", "per", "not",
+    "into", "onto", "out", "off", "any", "all", "this", "that",
+    "agent", "chat", "history",
+    "agentchathistory", "chathistory",
+    "rule", "rules", "file", "files",
+}
+
+DESC_RE = re.compile(r'^description:\s*"([^"]+)"', re.MULTILINE)
+TOKEN_RE = re.compile(r"[a-z][a-z0-9_]{2,}")
+
+
+def tokens(rule_id: str) -> set[str]:
+    text = (RULES_DIR / f"{rule_id}.md").read_text(encoding="utf-8")
+    m = DESC_RE.search(text)
+    if not m:
+        raise RuntimeError(f"no description in {rule_id}")
+    desc = m.group(1).lower()
+    raw = TOKEN_RE.findall(desc)
+    return {t for t in raw if t not in STOP}
+
+
+def jaccard(a: set[str], b: set[str]) -> float:
+    union = a | b
+    if not union:
+        return 0.0
+    return len(a & b) / len(union)
+
+
+def main() -> int:
+    sets = {r: tokens(r) for r in RULES}
+
+    print(f"Phase 6.1 — trigger Jaccard (source: frontmatter `description:`)")
+    print()
+    for r, ts in sets.items():
+        print(f"  {r}  ({len(ts)} tokens)")
+        print(f"    {sorted(ts)}")
+        print()
+
+    print("Pairwise Jaccard:")
+    print()
+    print(f"  {'pair':55s}  intersect  union  Jaccard")
+    pairs_above = 0
+    for a, b in combinations(RULES, 2):
+        inter = sets[a] & sets[b]
+        union = sets[a] | sets[b]
+        j = jaccard(sets[a], sets[b])
+        marker = " **" if j >= 0.30 else ""
+        print(f"  {a + ' × ' + b:55s}  {len(inter):>8d}  {len(union):>5d}  {j:>6.3f}{marker}")
+        print(f"    intersection: {sorted(inter)}")
+        if j >= 0.30:
+            pairs_above += 1
+    print()
+
+    if pairs_above >= 2:
+        print(f"VERDICT: ≥ 30% on {pairs_above}/3 pairs → PROCEED to 6.2 (unified shape).")
+        return 0
+    if pairs_above == 1:
+        print(f"VERDICT: mixed ({pairs_above}/3 pairs ≥ 30%) → ESCALATE to council.")
+        return 0
+    print(f"VERDICT: < 30% on all 3 pairs → STOP at 6.1 (orthogonal — current shape optimal).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/_phase2_shim_helper.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""One-shot helper: add `superseded_by:` + `deprecated_in:` + warning
+banner to Phase 2 atomic-command shims.
+
+Idempotent — if a file already has `superseded_by:` set, it is skipped.
+"""
+from __future__ import annotations
+import sys
+from pathlib import Path
+
+# (file-stem, "<cluster> <sub>")  — "<cluster> --flag" for flag-based
+PHASE2_SHIMS: list[tuple[str, str]] = [
+    # chat-history cluster
+    ("chat-history-resume",     "chat-history resume"),
+    ("chat-history-clear",      "chat-history clear"),
+    ("chat-history-checkpoint", "chat-history checkpoint"),
+    # agents cluster
+    ("agents-audit",   "agents audit"),
+    ("agents-cleanup", "agents cleanup"),
+    ("agents-prepare", "agents prepare"),
+    # memory cluster
+    ("memory-add",     "memory add"),
+    ("memory-full",    "memory load"),
+    ("memory-promote", "memory promote"),
+    ("propose-memory", "memory propose"),
+    # roadmap cluster
+    ("roadmap-create",  "roadmap create"),
+    ("roadmap-execute", "roadmap execute"),
+    # module cluster
+    ("module-create",  "module create"),
+    ("module-explore", "module explore"),
+    # tests cluster
+    ("tests-create",  "tests create"),
+    ("tests-execute", "tests execute"),
+    # context cluster
+    ("context-create",   "context create"),
+    ("context-refactor", "context refactor"),
+    # override cluster
+    ("override-create", "override create"),
+    ("override-manage", "override manage"),
+    # copilot-agents cluster
+    ("copilot-agents-init",     "copilot-agents init"),
+    ("copilot-agents-optimize", "copilot-agents optimize"),
+    # judge cluster (do-and-judge / do-in-steps now sub-commands)
+    ("do-and-judge", "judge on-diff"),
+    ("do-in-steps",  "judge steps"),
+    # commit / create-pr — flag-based clusters
+    ("commit-in-chunks",     "commit --in-chunks"),
+    ("create-pr-description", "create-pr --description-only"),
+]
+
+DEPRECATED_IN = "1.17.0"
+COMMANDS_DIR = Path(".agent-src.uncompressed/commands")
+
+
+def patch_file(stem: str, target: str) -> str:
+    path = COMMANDS_DIR / f"{stem}.md"
+    if not path.exists():
+        return f"SKIP {stem}: not found"
+    text = path.read_text(encoding="utf-8")
+    if "superseded_by:" in text.split("---", 2)[1] if text.startswith("---") else False:
+        return f"SKIP {stem}: already shimmed"
+
+    if not text.startswith("---\n"):
+        return f"SKIP {stem}: no frontmatter"
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return f"SKIP {stem}: malformed frontmatter"
+    fm_block = text[4:end]
+    body = text[end + len("\n---\n"):]
+
+    if "superseded_by:" in fm_block:
+        return f"SKIP {stem}: already shimmed"
+
+    new_fm_lines = fm_block.rstrip("\n").splitlines()
+    new_fm_lines.append(f"superseded_by: {target}")
+    new_fm_lines.append(f'deprecated_in: "{DEPRECATED_IN}"')
+    new_fm = "\n".join(new_fm_lines)
+
+    is_flag = target.startswith(("commit ", "create-pr "))
+    if is_flag:
+        cluster_invocation = f"/{target}"
+    else:
+        cluster_invocation = f"/{target}"
+    banner = (
+        f"> ⚠️  /{stem} is deprecated; use {cluster_invocation} instead.\n"
+        f"> This shim is retained for one release cycle "
+        f"({DEPRECATED_IN} → next minor) and forwards to the same "
+        f"instructions below. See "
+        f"[`docs/contracts/command-clusters.md`]"
+        f"(../../docs/contracts/command-clusters.md).\n\n"
+    )
+
+    new_text = f"---\n{new_fm}\n---\n\n{banner}{body.lstrip(chr(10))}"
+    path.write_text(new_text, encoding="utf-8")
+    return f"OK   {stem} → {target}"
+
+
+def main() -> int:
+    results = []
+    for stem, target in PHASE2_SHIMS:
+        results.append(patch_file(stem, target))
+    for r in results:
+        print(r)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/agent-config

@@ -48,6 +48,10 @@ Commands:
   roadmap:progress-check     Fail if agents/roadmaps-progress.md is stale (for CI)
   hooks:install              Install the pre-commit roadmap-progress hook
                              (use --print to dump it, --force to overwrite an existing hook)
+  keys:install-anthropic     Install the Anthropic API key for the AI Council
+                             (interactive, /dev/tty only, writes ~/.config/agent-config/anthropic.key 0600)
+  keys:install-openai        Install the OpenAI API key for the AI Council
+                             (interactive, /dev/tty only, writes ~/.config/agent-config/openai.key 0600)
   first-run                  Guided first-run setup — cost profile, settings, tooling
   implement-ticket           Drive the work_engine Python engine on a ticket envelope
                              (Option-A loop; called by the /implement-ticket command)
@@ -66,6 +70,8 @@ Commands:
                              Usage: chat-history:hook --platform <claude|augment|cursor|cline|windsurf|gemini>
   chat-history:checkpoint    Append a phase-boundary entry to .agent-chat-history
                              (CHECKPOINT fallback for platforms without native hooks)
+  roadmap-progress:hook      PostToolUse hook entry point (read JSON from stdin)
+                             Regenerates roadmaps-progress.md when a tool wrote under agents/roadmaps/
   telemetry:record           Append one artefact-engagement event (default-off)
   telemetry:status           Print artefact-engagement telemetry status (read-only)
   telemetry:report           Aggregate the engagement log into a quartile report
@@ -78,6 +84,8 @@ Examples:
   ./agent-config mcp:check
   ./agent-config roadmap:progress
   ./agent-config hooks:install
+  ./agent-config keys:install-anthropic
+  ./agent-config keys:install-openai
   ./agent-config first-run
   ./agent-config implement-ticket --state-file .work-state.json
   ./agent-config work --state-file .work-state.json --prompt-file prompt.txt
@@ -310,6 +318,13 @@ cmd_chat_history_hook() {
   exec python3 "$script" hook-dispatch "$@"
 }
 
+cmd_roadmap_progress_hook() {
+  require_python3
+  local script
+  script="$(resolve_script "scripts/roadmap_progress_hook.py")" || return 1
+  exec python3 "$script" "$@"
+}
+
 cmd_chat_history_checkpoint() {
   require_python3
   local script
@@ -390,6 +405,21 @@ HELP
   echo "    To uninstall: rm $target"
 }
 
+# Wrap the interactive key installers under a stable CLI entry. The shell
+# scripts themselves enforce /dev/tty, 0600, and atomic write — this is
+# pure routing so consumers never have to know the package layout.
+cmd_keys_install_anthropic() {
+  local script
+  script="$(resolve_script "scripts/install_anthropic_key.sh")" || return 1
+  exec bash "$script" "$@"
+}
+
+cmd_keys_install_openai() {
+  local script
+  script="$(resolve_script "scripts/install_openai_key.sh")" || return 1
+  exec bash "$script" "$@"
+}
+
 main() {
   local cmd="${1-}"
   [[ $# -gt 0 ]] && shift || true
@@ -400,6 +430,8 @@ main() {
     roadmap:progress)        cmd_roadmap_progress "$@" ;;
     roadmap:progress-check)  cmd_roadmap_progress_check "$@" ;;
     hooks:install)           cmd_hooks_install "$@" ;;
+    keys:install-anthropic)  cmd_keys_install_anthropic "$@" ;;
+    keys:install-openai)     cmd_keys_install_openai "$@" ;;
     first-run)               cmd_first_run "$@" ;;
     implement-ticket)        cmd_implement_ticket "$@" ;;
     work)                    cmd_work "$@" ;;
@@ -413,6 +445,7 @@ main() {
     refine-ticket:detect)    cmd_refine_ticket_detect "$@" ;;
     chat-history:hook)       cmd_chat_history_hook "$@" ;;
     chat-history:checkpoint) cmd_chat_history_checkpoint "$@" ;;
+    roadmap-progress:hook)   cmd_roadmap_progress_hook "$@" ;;
     telemetry:record)        cmd_telemetry_record "$@" ;;
     telemetry:status)        cmd_telemetry_status "$@" ;;
     telemetry:report)        cmd_telemetry_report "$@" ;;

package/scripts/ai_council/__init__.py

@@ -0,0 +1,39 @@
+"""ai_council — external-AI consultation module.
+
+The host agent uses this to poll independent models (OpenAI, Anthropic)
+for second opinions on roadmaps, diffs, free-form prompts, or file sets.
+Council members never see the host agent's reasoning — only the artefact
+plus a neutral system prompt asking for an independent critique.
+
+Architecture:
+    clients.py      — ExternalAIClient ABC + concrete OpenAI/Anthropic
+                      impls + 0600 key loaders (no env-var fallback).
+    bundler.py      — Context bundling with redaction + size guard.
+    orchestrator.py — Parallel fan-out, error normalisation, cost cap.
+    prompts.py      — Neutrality system-prompt templates per input mode.
+
+Trust boundary: this module makes networked, paid calls. Tokens come
+exclusively from ~/.config/agent-config/<provider>.key (mode 0600). The
+module never edits files, never opens PRs, never merges — output is
+text only, advisory.
+"""
+
+from scripts.ai_council.clients import (
+    AnthropicClient,
+    CouncilResponse,
+    ExternalAIClient,
+    KeyGateError,
+    OpenAIClient,
+    load_anthropic_key,
+    load_openai_key,
+)
+
+__all__ = [
+    "AnthropicClient",
+    "CouncilResponse",
+    "ExternalAIClient",
+    "KeyGateError",
+    "OpenAIClient",
+    "load_anthropic_key",
+    "load_openai_key",
+]

package/scripts/ai_council/_default_prices.py

@@ -0,0 +1,41 @@
+"""Shipped baseline prices for the AI Council.
+
+This file is the bootstrap source for `.agent-prices.md` when the
+runtime file is missing. It is also the network-fallback source for
+`scripts/update_prices.py` when the upstream feed (LiteLLM) is
+unreachable.
+
+Prices are USD per **1 000 000** tokens. Models are identified by the
+exact `model:` string the user puts into `.agent-settings.yml`.
+
+Numbers below are a hand-curated snapshot — they will drift. The
+runtime never reads them directly once `.agent-prices.md` exists; the
+weekly refresh and user edits are the live source of truth.
+"""
+
+from __future__ import annotations
+
+# YYYY-MM-DD of when this table was last hand-edited. Keep in sync with
+# the test_default_prices freshness assertion if you bump this.
+LAST_UPDATED = "2026-04-29"
+
+# (provider, model)  ->  (input_per_1m_usd, output_per_1m_usd)
+DEFAULT_PRICES: dict[tuple[str, str], tuple[float, float]] = {
+    # ── Anthropic ────────────────────────────────────────────────────
+    ("anthropic", "claude-sonnet-4-5"): (3.00, 15.00),
+    ("anthropic", "claude-opus-4-1"): (15.00, 75.00),
+    ("anthropic", "claude-haiku-4-5"): (1.00, 5.00),
+    # ── OpenAI ───────────────────────────────────────────────────────
+    ("openai", "gpt-4o"): (2.50, 10.00),
+    ("openai", "gpt-4o-mini"): (0.15, 0.60),
+    ("openai", "o1"): (15.00, 60.00),
+    ("openai", "o3-mini"): (1.10, 4.40),
+}
+
+
+def as_rows() -> list[tuple[str, str, float, float]]:
+    """Return the table sorted (provider, model) for stable Markdown output."""
+    return [
+        (provider, model, prices[0], prices[1])
+        for (provider, model), prices in sorted(DEFAULT_PRICES.items())
+    ]