magnus/agent-skills
1
1
Fork 0
Code Issues Pull requests Projects Releases 5 Packages Wiki Activity Actions

feat: add agent-council — multi-agent structured debate system #87

Merged
jasper merged 7 commits from feat/agent-council into main 2026-07-10 01:03:50 -04:00
Conversation 0 Commits 7 Files changed 28 +2325
jasper commented 2026-07-09 22:55:59 -04:00
Contributor
Copy link

Summary

Adds agent-council, a new agentskills.io-compatible skill for structured multi-agent debate. Built on PydanticAI + PydanticGraph, ships as a pip-installable Python package.

Key capabilities

  • 5-phase debate protocol: compose, premortem, position, cross-examination (iterative, eval-driven), synthesis
  • Convergence-aware iteration: measures confidence dispersion, argument novelty, concession rate
  • Typed Pydantic output schemas for every phase, consumable as JSON or markdown
  • Cross-platform CLI tool compatible with any agentskills.io harness
  • Bootstrap detection: installs from skill directory with sys.executable fallback

Files

24 new files in agent-council/ including SKILL.md, pyproject.toml, 11 Python modules, scripts, templates, and reference docs. Updates to AGENTS.md (trigger table) and README.md (skill index).

## Summary Adds **agent-council**, a new agentskills.io-compatible skill for structured multi-agent debate. Built on PydanticAI + PydanticGraph, ships as a pip-installable Python package. ## Key capabilities - 5-phase debate protocol: compose, premortem, position, cross-examination (iterative, eval-driven), synthesis - Convergence-aware iteration: measures confidence dispersion, argument novelty, concession rate - Typed Pydantic output schemas for every phase, consumable as JSON or markdown - Cross-platform CLI tool compatible with any agentskills.io harness - Bootstrap detection: installs from skill directory with sys.executable fallback ## Files 24 new files in agent-council/ including SKILL.md, pyproject.toml, 11 Python modules, scripts, templates, and reference docs. Updates to AGENTS.md (trigger table) and README.md (skill index).
Spawns a panel of expert agents to debate any question with
convergence-aware iteration and typed synthesis output.

- PydanticAI + PydanticGraph-based Python package
- 5-phase debate protocol: compose → premortem → position →
  cross-examine (iterative, eval-driven) → synthesis
- Convergence detection: confidence dispersion, argument
  novelty, concession rate — stops when diminishing returns
- Typed output schemas (Pydantic models) for every phase
- CLI tool with markdown and JSON output modes
- Custom persona file support
- Bootstrap detection: sys.executable -m pip install fallback
- agentskills.io compatible SKILL.md with triggers

Signed-off-by: Magnus Hedemark <magnus919@pm.me>
- Adds stdlib-only .env loader (no python-dotenv dependency)
- Env vars always take precedence over .env values
- Updates SKILL.md with .env usage example
- Updates configuration reference

Signed-off-by: Magnus Hedemark <magnus919@pm.me>
- Each phase now prints completion status to stdout immediately
- Phase output files written to /tmp/agent-council/<ts>/ as they complete
- Users see real-time progress: persona count, phase timing,
  cross-examination metrics per round, convergence verdict
- Synthesis still printed at end as primary deliverable
- Full intermediate output available in /tmp/agent-council/ for inspection

Signed-off-by: Magnus Hedemark <magnus919@pm.me>
Two-layer defense against fabricated factual claims:

1. Prompt-level guardrail (FACTUAL_CLAIM_GUARDRAIL) injected into every
   debate agent's system prompt — tells agents not to assert specific
   verifiable facts they cannot know (domain availability, package
   namespace status, pricing, etc.)

2. Post-synthesis verification eval — an LLM-based QA pass that scans
   the narrative synthesis for unsubstantiated factual claims and
   appends a 'Claims Not Verified' section to the output with specific
   quotes, claim types, and explanations.

Both layers are self-contained — no search or external tools required.

Signed-off-by: Magnus Hedemark <magnus919@pm.me>
Instead of the compose phase fabricating personas with fake backgrounds,
the council now draws from 39 real professional profiles via a git
submodule (https://github.com/magnus919/hermes-profiles).

Key changes:
- New select phase reads SOUL.md + profile.yaml from profiles submodule
- Auto-updates submodule before selection via git submodule update --remote
- --profiles flag for explicit selection (comma-separated names)
- Auto-selection by keyword overlap with profile descriptions when omitted
- Each agent's identity is their real SOUL.md — actual methodology,
  values, and operating principles, not invented backgrounds
- Falls back to composed personas if profile library is unavailable
- Real profiles produce genuine methodological disagreement (debugger
  said 'unanswerable without a verified process' to naming question)

Signed-off-by: Magnus Hedemark <magnus919@pm.me>
Epoch 1 — Prominence:
- Add --profiles flag to Command Reference
- Add Profile Selection section documenting 39 real profiles,
  auto-selection, and explicit --profiles selection
- Add Claims Verification section to Output documentation
- Add Pitfalls table for common issues

Epoch 2 — Decision Intelligence:
- Add Choosing a Profile Source decision table
- Add Reading the Convergence Diagnostic interpretation guide
  with 8 pattern→meaning→action mappings

Epoch 3 — Pattern Expansion:
- Add JSON output schema reference to Output section
- Add ai-frameworks and hermes-profiles to Related Skills

Signed-off-by: Magnus Hedemark <magnus919@pm.me>
Signed-off-by: Magnus Hedemark <magnus919@pm.me>
jasper merged commit 6e46876a09 into main 2026-07-10 01:03:50 -04:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
community-feedback
Originates from community review

  
enhancement
New feature or request

  
skill-upgrade
Skill enhancement or refactor

No labels
community-feedback
enhancement
skill-upgrade
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
magnus/agent-skills!87
No description provided.