council-of-hats

Council of Hats

Structured, multi-perspective decision-making for Hermes Agent (and any AI agent). Convene the hats a decision actually needs — trade-offs, failure modes, end-to-end integrity, ethics, reversibility, pre-mortem, second-order effects, agent trajectory — interrogate it through each in parallel, then synthesize a decision-readiness verdict. Eight deterministic hats, no LLM in the decision path (so it can't drift), backed by a local, searchable decision log.

Part of the antharmaya ecosystem. Works alongside Memory Bridge for full decision traceability.

What You Get

8 Hats — multi-perspective deliberation

Expert hats

Universal lenses (any high-stakes decision)

Convene → Deliberate → Synthesize

• convene(decision) — the conductor picks the hats this decision needs (high-stakes/irreversible calls always get Reversibility + Pre-Mortem) and lays out their questions. Answer each independently (parallel thinking).
• synthesize(answers) — a deterministic decision-readiness verdict: a score, flags (blind spots), blockers (hard stops — e.g. user data with no consent), and a recommendation (READY / CAUTION / NOT READY / BLOCKED). No LLM, so it can't hallucinate or drift.

Tools & CLI

• Python API on tools.question_engine.QuestionEngine: convene, synthesize, get_questions (one hat), log_decision, search_decisions (typo-tolerant FTS over the log).
• CLI: council convene "<decision>" · council search "<q>" · council patterns · council stats · council review.

Privacy & Ethics Checklist

Mandatory pre-build gate before any feature touching user data. Integrated as a Hermes skill for automatic detection and prompting.

Decision Log

Every decision is logged to ~/.hermes/decisions/decision_log.db with pattern, question, answer, context, session ID, confidence, and review status.

Installation

Direct install (pinned release)

curl -fsSL https://raw.githubusercontent.com/antharmaya/council-of-hats/v0.2.1/install.sh | bash

The installer downloads the v0.2.1 release archive (no git history), installs council-decision-layer and privacy-ethics-checklist into ~/.hermes/skills/, and replaces any previous copy as a whole, so re-running it is safe. Set COUNCIL_VERSION to install a different tag.

From a clone

git clone --branch v0.2.1 https://github.com/antharmaya/council-of-hats.git
cd council-of-hats
./install.sh

Requirements:

• Hermes Agent v0.16.0+
• Python 3.11+ (stdlib only)
• No API keys needed
• No external services

Usage

Once installed, Hermes loads the skill when it detects decision-relevant context (see trigger_on in SKILL.md). There is no hermes tool subcommand; call the council in one of these ways:

# Inside Hermes: preload the skill for a session or a one-off query
hermes chat -s council-decision-layer -q "Convene the council: Cloudflare vs Vercel for the API"

# From the shell: the bundled CLI
COUNCIL="python3 $HOME/.hermes/skills/council-decision-layer/tools/cli.py"
$COUNCIL convene "Cloudflare vs Vercel for the API"
$COUNCIL patterns          # list the 8 hats
$COUNCIL search "vercel"   # search the decision log
$COUNCIL review            # decisions awaiting review

The question engine will:

1. Present 3-5 structured questions per hat
2. Log answers (via log_decision) to ~/.hermes/decisions/decision_log.db
3. Track review status for follow-up

Project Structure

council-of-hats/
├── SKILL.md                          # Main Hermes skill definition
├── patterns/
│   ├── tradeoff_matrix.md            # Systems trade-off analysis
│   ├── failure_modes.md              # Distributed failure analysis
│   ├── end_to_end.md                 # End-to-end integrity
│   ├── ethics_triage.md              # Privacy & ethics review
│   └── agentops_trajectory.md        # Agent trajectory evaluation
├── privacy-ethics-checklist/
│   └── SKILL.md                      # Pre-build privacy gate
├── tools/
│   ├── __init__.py
│   └── question_engine.py            # Deterministic question engine + SQLite log
├── tests/
│   ├── __init__.py
│   └── test_question_engine.py       # 45 comprehensive tests
├── references/
│   ├── source_mapping.md             # Which discipline → which pattern
│   └── README.md                     # Decision log schema reference
├── README.md
└── install.sh

Development

Running Tests

pip install pytest
python3 -m pytest -q
bash -n install.sh

Adding a New Pattern

1. Create patterns/your_pattern.md with structured questions
2. Register it in tools/question_engine.py in the PATTERNS dict
3. Add it to references/source_mapping.md
4. Write tests in tests/test_question_engine.py

Integration with Memory Bridge

The Council Decision Layer shares pattern names with Memory Bridge (framework_used enum). Decisions made via this layer are tracked in the bridge's structured_decisions table for outcome verification.

Together they form a closed loop:

1. Decide (Council Layer) — structured questions with rationale
2. Remember (Memory Bridge) — decisions extracted and stored
3. Verify (Memory Bridge cron) — check if past decisions worked out

License

MIT — antharmaya