agent-council 0.1.0

data/RELEASE_NOTES.md

@@ -0,0 +1,25 @@
+# Release Notes
+
+## 0.1.0 (2026-11-09)
+
+Initial release: run one prompt through multiple models via the pi harness,
+saving each model's final response as a Markdown report, with optional
+consolidation by another model. `--consolidate RUN_DIR` runs just the
+consolidation of a finished run. Runs go under `./agent-council-reports`,
+or under the directory given with `-o` / `--output-dir`; `--consolidate`
+writes into the run directory it is given. `AGENT_COUNCIL_OPTS`
+holds arguments inserted before the command-line ones. Includes
+sample prompts and configs under `examples/`, and a `pi-models` helper that
+lists the provider/model pairs available to pi. Each run directory's
+`run.json` records every agent run's outcome, duration, token usage, and,
+where pi can price it, cost; reports show their duration and usage, and the
+console shows usage per agent and in total. The consolidated report is
+split into a `_findings.md` file, which can be pasted into an AI chat as
+is, and a `_meta.md` file with the run's metadata.
+
+agent-council does not sandbox the agents: they get pi's `bash` tool,
+running as you. See [Safety and privacy](README.md#safety-and-privacy) in the README before running it.
+
+Runs on Ruby 3.3 or later and on JRuby 10 or later (where SIGQUIT is left
+to the JVM, so it doesn't stop a run). Native Windows is not supported; on
+Windows, run agent-council inside WSL.

data/code-review-agents.md

@@ -0,0 +1,28 @@
+# Four agents and a consolidator for code review
+
+| Role | Provider | Model | Why it fits |
+|---|---|---|---|
+| Main reviewer | `cursor` | `claude-opus-5-5-medium` | Primary review pass. |
+| Fast first pass | `openai` | `gpt-6.1-sol` | Scans for bugs and missed edge cases. |
+| Deep reviewer | `deepseek` | `deepseek-flash` | Independent review for complex changes. |
+| Critical reviewer | `cursor` | `gemini-3.8-flash-high` | Careful final critique. |
+| Consolidator | `cursor` | `claude-sonnet-5-5-high` | Synthesizes the findings. |
+
+This uses three provider routes across four distinct agent model families. Opus 5.5 is the heavier review pass, so reserve it for consequential changes; the consolidator compares findings and highlights agreement, conflicts, and the most actionable issues.
+
+To use it, copy the YAML block below into your config (`agent-council.yml` or `~/.agent-council.yml`), replacing any provider or model you don't have access to (see `pi --list-models`).
+
+```yaml
+agents:
+  - provider: cursor
+    model: claude-opus-5-5-medium
+  - provider: openai
+    model: gpt-6.1-sol
+  - provider: deepseek
+    model: deepseek-flash
+  - provider: cursor
+    model: gemini-3.8-flash-high
+consolidator:
+  provider: cursor
+  model: claude-sonnet-5-5-high
+```

data/examples/configs/consolidated.yml

@@ -0,0 +1,22 @@
+# Sample ensemble: four analysts and a consolidator. Replace any provider or
+# model you don't have credentials for (see `pi --list-models`). The
+# commented-out entries are alternatives: uncommenting the extra agent adds a
+# fifth analyst; to swap in the other consolidator, uncomment its provider
+# and model lines and comment out the active pair.
+agents:
+  - provider: opencode-go
+    model: glm-5.3
+  - provider: opencode-go
+    model: kimi-k3
+  - provider: openai
+    model: gpt-6.1-sol
+#  - provider: opencode-go
+#    model: minimax-m3
+  - provider: cursor
+    model: claude-sonnet-5-5-high
+
+consolidator:
+#  provider: deepseek
+#  model: deepseek-v4-pro
+  provider: opencode-go
+  model: glm-5.3

data/examples/configs/single.yml

@@ -0,0 +1,10 @@
+# Minimal smoke-test config: one inexpensive model, for checking that your
+# setup works (auth, invocation, report writing) without a full ensemble run
+# (AC_HOME is the gem or source checkout directory; see the README):
+#
+#   agent-council \
+#     "$AC_HOME/examples/prompts/smoke-test-prompt.md" \
+#     "$AC_HOME/examples/configs/single.yml"
+agents:
+  - provider: opencode-go # OPENCODE_API_KEY
+    model: kimi-k2.7-code

data/examples/prompts/dnsruby-pull-221-prompt.md

@@ -0,0 +1,4 @@
+Use examples/prompts/review-pull-request-prompt.md to review this pull request:
+
+https\://github.com/alexdalitz/dnsruby/pull/221
+

data/examples/prompts/project-name-prompt.md

@@ -0,0 +1,3 @@
+Examine this code base and offer me a few catchy but technically correct names for this project/gem.
+
+The names might contain 'multi', 'model', and/or 'ask/request/query', but feel free to innovate.

data/examples/prompts/recommend-model-ensemble-prompt.md

@@ -0,0 +1,62 @@
+# Recommend a Model Ensemble
+
+Discover the available provider/model entries with `pi-models --json`, then
+recommend a small ensemble for the user's task and constraints.
+
+## Inputs
+
+- **Task:** [Describe the task, such as code review]
+- **Number of agents:** [How many recommendations to make]
+- **Priorities:** [For example: insightful findings, speed, cost, provider diversity]
+- **Unavailable providers or models:** [List any that do not work]
+- **Current config:** [Optional existing `agents:` / `consolidator:` YAML]
+- **Other constraints:** [Optional]
+
+## Instructions
+
+1. Run `pi-models --json` to discover the provider/model entries available
+   to pi: those of the providers the user has set up credentials for. Use
+   this as the source for model names and listed attributes, but do not
+   assume every entry is covered by the user's plan.
+   Exclude any providers or models the user marked unavailable. If the command
+   is not installed or fails, say so, and that the model list must then be
+   included in the prompt; do not invent available models.
+2. Recommend exactly the requested number of agents and one consolidator,
+   choosing only from the discovered list. If a current config is provided,
+   use it as the baseline and explain any meaningful changes.
+3. Optimize the full ensemble for the stated priorities. When provider
+   diversity matters, spread
+   recommendations across distinct provider routes where practical. Prefer
+   different underlying model families too, since multiple routes to the same
+   model may provide less useful independent feedback.
+4. Balance capability with speed. A useful ensemble can combine a strong
+   primary reviewer, a fast broad pass, and one or more independent deep or
+   critical reviews. Avoid making every selection a slow, heavyweight model.
+5. Assign each recommendation a clear role and briefly explain why it fits.
+   Note meaningful tradeoffs, such as a slower model reserved for consequential
+   changes.
+6. Do not infer subscription quotas, actual latency, or cost from provider
+   names alone. State when a recommendation depends on an assumption about the
+   user's subscriptions or plan limits.
+7. If browsing is available and current capability claims affect the choice,
+   verify them with reliable, preferably primary sources. Cite factual claims
+   near where they appear. Separate source-backed claims from judgment based on
+   the user's priorities. If browsing is unavailable, say that the ranking is
+   based on the discovered catalog and general model-family knowledge.
+8. Keep the result concise and actionable. Use a table with provider, model,
+   and role/reason for each agent and the consolidator, followed by a short
+   explanation of the overall mix.
+9. End with a fenced `yaml` code block containing a ready-to-copy config with
+   this shape:
+
+   ```yaml
+   agents:
+     - provider: ...
+       model: ...
+   consolidator:
+     provider: ...
+     model: ...
+   ```
+
+   Ensure every provider/model pair in the YAML appears in the discovered
+   catalog and preserve the requested number of agent entries.

data/examples/prompts/review-docs-prompt.md

@@ -0,0 +1,101 @@
+# Review Documentation
+
+Review the documentation of the repository in the current working directory.
+Report only issues needing addressing. Do not make changes.
+
+If the current working directory is not the repository root, don't review
+it: report only that, naming the current directory.
+
+Documentation includes the README, any other Markdown files, help and usage
+output, code comments that describe behavior, and sample files such as
+example configs and prompts.
+
+Evaluate whether the documentation is:
+
+- **Accurate:** it matches what the code actually does. Check commands,
+  flags, option names, method names, file names, paths, defaults, config
+  keys, output formats, and version or prerequisite claims against the
+  code. Examples run as written and produce the output shown.
+- **Complete:** every user-facing feature, option, and behavior is
+  documented, and nothing documented has been removed or renamed. Every
+  setup step a command depends on is described or linked.
+- **Consistent:** the documents agree with each other and with the help
+  output, and use the same terms for the same things.
+- **Usable by a newcomer:** someone starting from scratch can install,
+  configure, and complete a first run by following it, without needing
+  knowledge it doesn't provide. Steps are in a sensible order.
+- **Clear and concise:** free of ambiguity, unexplained jargon, stale
+  history, and text that is hard to find or easy to misread.
+- **Free of duplication:** each topic has one canonical location. Where the
+  same material is explained in several places, say which copy to keep
+  and recommend replacing the others with a short link. Never recommend
+  duplicating content that is maintained elsewhere.
+- **Correctly linked:** relative links point to files that exist, and
+  anchor links (`#section`) match a heading or explicit anchor in the
+  target, both on the repository host and on the documentation site if
+  the project builds one.
+
+## Scope
+
+- Report documentation problems only. Do not review the code except to
+  verify what the documentation says about it.
+- Don't review or report on files that git ignores (check with
+  `git check-ignore`), such as generated output, local scratch files, and
+  built documentation sites, or on `agent-council-reports/`
+  (agent-council's output, which may not be ignored). You may read
+  ignored files for context, but they are local to this checkout, so
+  judge the documentation against tracked files.
+- Treat the code as the source of truth when it disagrees with the
+  documentation, unless the code's behavior looks like the bug; say so in
+  that case.
+- Skip purely stylistic preferences unless they affect accuracy, clarity,
+  completeness, or maintainability.
+- Files that consist only of a directive including another file (for
+  example, an MkDocs `include-markdown` stub that publishes a root file on
+  the documentation site) are intentional; do not report them as
+  incomplete.
+
+## Upcoming Release
+
+Review the documentation as describing the upcoming release (the version in
+the project's version file, such as `version.rb`, `package.json`, or
+`pyproject.toml`), as if that release were already published. Do not report:
+
+- that this version is not yet published, is a prerelease, or is marked
+  unreleased;
+- that install commands would fetch an older published release, or that
+  the older release behaves differently from what the docs describe;
+- that install commands should add a prerelease flag or pin a version.
+
+Do not query package registries to check.
+
+## Verification
+
+Investigate thoroughly before reaching conclusions.
+
+You are permitted and encouraged to inspect files, run the program's help
+output, follow the documented steps and examples, and execute commands to
+confirm or refute what the documentation claims. Don't rely on a claim being
+plausible: check it. Don't install software, though: check installation
+steps by reading them against the code and packaging instead. Don't run
+test suites, builds, servers, or database tasks either. Don't run
+commands that call paid or remote services (such as AI models); check
+those steps by reading the code instead.
+
+**DO NOT EDIT ANY CODE OR TRACKED FILES, AND DO NOT COMMIT.**
+
+Commands otherwise permitted here may generate temporary files; direct
+their output to your scratch directory where the tool allows it.
+Avoid unnecessary modifications to the working tree.
+
+## Report
+
+For each issue, identify the document and location, quote the problematic
+text, explain the problem and its impact on a reader, and propose replacement
+wording or a fix. Say how you verified it (for example, a command you ran or
+the code you compared against), or that it is unverified.
+
+Order issues by importance: first those that would mislead or block a
+reader, then omissions, then minor clarity problems.
+
+If you find no issues, say so, and mention any limits of the review.

data/examples/prompts/review-latest-commit-prompt.md

@@ -0,0 +1,46 @@
+# Review Latest Commit
+
+Review the latest commit and any uncommitted changes.
+Report only issues needing addressing.
+
+Evaluate whether the changes are:
+
+- Correct and complete.
+- As simple as practical.
+- Consistent with the commit's intent.
+- Accompanied by appropriate tests and documentation updates.
+
+The commit message may describe an implementation strategy rather than the
+underlying problem. Infer the intended outcome and assess whether a better
+solution would be appropriate.
+
+## Scope
+
+- Report only issues introduced by the latest commit or uncommitted changes.
+- Report issues in uncommitted changes separately from those in the commit.
+- Don't review or report on files that git ignores (check with
+  `git check-ignore`), or on `agent-council-reports/` (agent-council's
+  output, which may not be ignored). You may read ignored files for
+  context, but they are local to this checkout, so judge the changes
+  against tracked files.
+- Do not report preexisting issues unless the changes introduce or worsen them.
+- You may suggest improvements to the commit message, particularly if the
+  commit has not been pushed.
+
+## Verification
+
+Investigate thoroughly before reaching conclusions.
+
+You are permitted and encouraged to inspect files, run Git commands, execute
+relevant tests and linters, and reproduce suspected defects.
+
+**DO NOT EDIT ANY CODE OR TRACKED FILES.**
+
+Tests and linters that generate temporary files or coverage data are
+permitted (builds are not); direct their output to your scratch
+directory where the tool allows it. Avoid unnecessary modifications to the
+working tree.
+
+For each issue, identify the affected file and location, explain the problem
+and its impact, and propose a fix. Say how you verified it (for example, a
+reproduction or a test run), or that it is unverified.

data/examples/prompts/review-pull-request-prompt.md

@@ -0,0 +1,91 @@
+# Review Pull Request
+
+Review the GitHub pull request for the branch checked out in the current
+working directory. Report only issues needing addressing.
+
+The user has checked out the PR's head branch (for example with
+`gh pr checkout <number>`) before starting this run. Use the local checkout
+for reading and searching code; use the `gh` CLI only for what exists only
+on GitHub.
+
+## Gathering the PR
+
+- Run `gh pr view --json number,title,body,author,baseRefName,headRefName,headRefOid,files,reviews,reviewDecision,statusCheckRollup`
+  for the PR's metadata and review summaries, and `gh pr view --comments` for
+  its discussion. Read inline review comments with
+  `gh api --paginate repos/{owner}/{repo}/pulls/<number>/comments`; without
+  `--paginate` only the first 30 are returned. To tell resolved threads from
+  open ones, query `reviewThreads { isResolved comments { ... } }` with
+  `gh api graphql`; the REST endpoint does not report resolution.
+- Take the PR's changes from `gh pr diff`; it is authoritative even if the
+  local base branch is stale.
+- For failing checks, use `gh pr checks` and `gh run view <run-id> --log-failed`.
+- Compare `git rev-parse HEAD` with `headRefOid`. If they differ, or there
+  are uncommitted changes, say so at the top of the report: local files may
+  not match the PR.
+- If `gh` is missing, unauthenticated, or finds no PR for this branch, don't
+  review: report only that, with the command and its error. Reach GitHub
+  only through `gh`: no `curl`, `wget`, or other HTTP client against the API
+  or web pages, which unauthenticated allows only 60 requests an hour,
+  shared by all concurrent agents.
+- Do not run `gh pr checkout`, `git fetch`, `git pull`, or anything else that
+  changes git state, and do not post comments, reviews, or approvals.
+
+## Evaluation
+
+Evaluate whether the changes are:
+
+- Correct and complete, including edge cases and error paths.
+- As simple as practical.
+- Consistent with the PR's stated intent, with no unrelated changes.
+- Consistent with the code base's existing architecture, naming, and idioms.
+- Accompanied by appropriate tests and documentation updates.
+- Compatible: changes to public interfaces (CLI options, APIs, output
+  formats, configuration) are intended, and incompatible ones are recorded
+  where the project records them (changelog, release notes, version).
+
+The PR description may describe an implementation strategy rather than the
+underlying problem. Infer the intended outcome and assess whether a better
+solution would be appropriate.
+
+Also report:
+
+- Review comments that remain unaddressed by the current head.
+- Failing CI checks, with your assessment of whether this PR causes them.
+
+## Scope
+
+- Report only issues introduced by the PR. Do not report preexisting issues
+  unless the PR introduces or worsens them.
+- Don't review or report on files that git ignores, or on
+  `agent-council-reports/` (agent-council's output, which may not be
+  ignored).
+- You may suggest improvements to the PR title and description.
+- Follow any Project-Specific Instructions section at the end; it overrides
+  these general rules where they conflict.
+
+## Verification
+
+Investigate thoroughly before reaching conclusions.
+
+You are permitted and encouraged to inspect files, run Git commands, execute
+relevant tests and linters, and reproduce suspected defects.
+
+**DO NOT EDIT ANY CODE OR TRACKED FILES.**
+
+Tests and linters that generate temporary files or coverage data are
+permitted (builds are not); direct their output to your scratch
+directory where the tool allows it. Avoid unnecessary modifications to the
+working tree.
+
+## Report
+
+Start with a one-line verdict: ready to merge, needs minor changes, or needs
+significant changes.
+
+Then list the issues, most severe first, each marked blocking or
+non-blocking. For each issue, identify the affected file and location,
+explain the problem and its impact, and propose a fix. Say how you verified
+it (for example, a reproduction or a test run), or that it is unverified.
+
+If you find no issues, say so, and mention any limits of the review.

data/examples/prompts/smoke-test-prompt.md

@@ -0,0 +1 @@
+What is 27 * 43? Reply with just the number, then one sentence explaining how you got it.

data/examples/prompts/state-of-the-code-base-prompt.md

@@ -0,0 +1,172 @@
+# State of the Code Base Prompt
+
+You are a senior software architect and code reviewer. Analyze this code base thoroughly and report on its
+state, focusing on weaknesses, risks, and areas for improvement. For each issue, assess its seriousness and
+cost to fix, and give a high-level strategy for addressing it.
+
+**DO NOT MAKE ANY CODE CHANGES. REVIEW ONLY.**
+
+> **Test coverage is out of scope for this review.** Do not analyze coverage data or score coverage; it is
+> handled in depth by a separate prompt, `test-coverage-analysis-prompt.md` (in the same directory as this
+> one).
+
+## Ground Rules
+
+- First read the project's agent and contributor guidance (e.g., AGENTS.md, CLAUDE.md, CONTRIBUTING.md) and
+  the README.
+- Back every finding with evidence: cite `path/to/file.rb:line` (or a command and its output). Label anything
+  you could not verify as an inference.
+- Do not invent issues to fill sections. If a section has nothing significant, say so briefly.
+- Only run commands that do not change the host or external systems (e.g., the default test suite, linters).
+  Do not run anything that deploys, publishes, migrates real data, or calls paid or production services.
+- Follow the Project-Specific Instructions at the end, if any; they override these general rules where they
+  conflict.
+- If earlier reports of this kind exist in the output directory, compare with the most recent one and note
+  what has improved or regressed.
+
+## Output
+
+Write the report to `untracked/` (create it if needed) unless the Project-Specific Instructions name another
+directory. Name it `YYYY-MM-DD-HH-MM-SS-state-of-the-code-base-<agent>.md`, where the timestamp is the current
+UTC time to the second and `<agent>` is your lowercase tool or model family name (e.g. `claude`, `codex`,
+`gemini`, `zai`).
+
+Begin the report with:
+
+1. The most recent git commit (hash and subject) at the time you begin.
+2. The git-tracked files with staged or unstaged changes, from `git status`, or "None". Ignore untracked
+   files.
+3. A note that test coverage is excluded and is covered by the separate test coverage analysis report.
+
+## Scoring
+
+Score each dimension from 1 to 10:
+
+- **9–10:** Exemplary; nothing significant to fix.
+- **7–8:** Solid; minor issues only.
+- **5–6:** Adequate; notable issues that slow work or add risk.
+- **3–4:** Weak; issues that regularly cause defects or friction.
+- **1–2:** Failing; needs immediate attention.
+
+Choose weights suited to this project's nature (e.g., a library, CLI, web service, or data pipeline), and
+explain the choice briefly. The weights must sum to 100%.
+
+## Report Structure
+
+### Executive Summary
+
+- A concise overview of the code base's overall health.
+- The strongest and weakest areas.
+- A **one-line verdict** (e.g., *"Overall: Fair, with major risks in error handling and dependencies"*).
+- The **Overall Weighted Score (1–10)** from the final section.
+
+### Critical Blockers
+
+Issues so severe that they must be resolved before meaningful progress can continue, or "None". For each,
+give the **Description**, **Impact**, **Urgency**, and **Cost to Fix** (High/Medium/Low).
+
+### Architecture & Design
+
+- Summarize the architecture (layering, main components and how they interact, key abstractions).
+- Identify strengths and weaknesses, and areas of high complexity, coupling, or technical debt.
+- Assess maintainability, extensibility (the cost of adding a typical new feature), and clarity.
+- **Score (1–10)**
+
+### Code Quality
+
+- Identify recurring issues: duplication, long methods, deep nesting, unclear naming.
+- Point out readability and maintainability concerns.
+- **Score (1–10)**
+
+### Build, CI & Release
+
+- Evaluate CI/CD pipelines, build scripts and task runners, packaging and release processes, git hooks,
+  containers, and infrastructure-as-code, as present.
+- Highlight brittle, outdated, or redundant configuration, and gaps in what CI verifies (platforms, runtime
+  versions, checks).
+- **Score (1–10)**
+
+### Dependencies & External Integrations
+
+- List major runtime and development dependencies, and external services, APIs, or system tools the code
+  relies on.
+- Note outdated, unmaintained, or risky dependencies and their upgrade cost.
+- Assess vendor lock-in and fragility against changes in external integrations.
+- **Score (1–10)**
+
+### Security & Reliability
+
+- Identify insecure practices: injection risks (shell, SQL, etc.), hardcoded secrets, secrets leaking into
+  logs or output, and missing input validation.
+- Assess error handling, timeouts, retries, and behavior when external calls fail or return unexpected
+  results.
+- **Score (1–10)**
+
+### Documentation & Onboarding
+
+- Evaluate the README, user documentation, inline docs, and contributor/agent guidance.
+- Identify missing, outdated, or inconsistent documentation, including docs that contradict the code.
+- **Score (1–10)**
+
+### Performance & Efficiency
+
+- Highlight bottlenecks and inefficient patterns (e.g., startup time, redundant I/O or external calls, N+1
+  queries, unnecessary polling).
+- State whether each optimization is low-cost or high-cost.
+- **Score (1–10)**
+
+### Formatting & Style Conformance
+
+- Report the configured linters' and formatters' results and any significant patterns behind them.
+- Report formatting problems in other files (broken Markdown, inconsistent YAML, and the like).
+- **Score (1–10)**
+
+### Best Practices & Conciseness
+
+- Assess adherence to the language's idioms and conventions, modularization, and separation of concerns.
+- Evaluate verbosity against clarity: is the code concise without being cryptic?
+- **Score (1–10)**
+
+### Prioritized Issue List
+
+A table of the top issues, ordered so that working through them top to bottom delivers the most value
+soonest (weigh severity against cost to fix; cheap, high-impact fixes come first).
+
+| ID | Issue | Location | Severity | Cost to Fix | Impact if Unaddressed |
+|----|-------|----------|----------|-------------|-----------------------|
+| 1 | Example issue description | `src/foo.rb:42` | High | Low | Silent data loss on retry |
+
+### High-Level Recommendations
+
+- General strategies for improvement (refactoring, dependency upgrades, modularization).
+- Where incremental change is enough and where larger changes are justified.
+
+### Suggested Prompts
+
+For each major issue, a self-contained prompt for a coding AI tool that would address it. Reference the
+issue's ID.
+
+### Overall Weighted Score
+
+Show the weights table and the calculation (score × weight for each dimension, summed). Then give the
+**Overall Weighted Score (1–10)** with a brief justification.
+
+| Dimension                    | Score | Weight | Weighted |
+|------------------------------|-------|--------|----------|
+| Architecture & Design        | ?     | ?%     | ?        |
+| Code Quality                 | ?     | ?%     | ?        |
+| Build, CI & Release          | ?     | ?%     | ?        |
+| Dependencies                 | ?     | ?%     | ?        |
+| Security & Reliability       | ?     | ?%     | ?        |
+| Documentation                | ?     | ?%     | ?        |
+| Performance & Efficiency     | ?     | ?%     | ?        |
+| Formatting & Style           | ?     | ?%     | ?        |
+| Best Practices & Conciseness | ?     | ?%     | ?        |
+| **Total**                    |       | 100%   | **?**    |
+
+## Project-Specific Instructions
+
+None. When adapting this prompt to a project, replace this paragraph with that project's specifics: what
+kind of software it is (so the weights fit), which commands are safe to run and which must never be run,
+design-decision or reviewer-guideline documents to read first, and areas each dimension should examine
+closely.