Make bad strategic decisions expensive to make.
StormGrill is an open-source dual-protocol orchestrator that pairs verified multi-agent research (the Storm) with real-time adversarial interrogation (the Grill) to help decision-makers — CTOs, Lead Architects, Heads of Product — stress-test a decision against facts, not intuition.
Most strategic decisions are made on a mix of intuition, incomplete research, and confirmation bias. StormGrill doesn't replace the decision-maker. It:
- Surfaces confirmation bias in real time
- Forces a confrontation between intuition and verified facts
- Documents the chain of evidence behind every decision
- Produces a single, executable report (dated actions, open questions)
┌─────────────┐ cache (hourglass pipeline) ┌─────────────┐
│ STORM │ ────────────────────────────────▶ │ GRILL │
│ 5 expert │ filtered gateway, one-way only │ adversarial │
│ agents, │ (Storm never sees the chat; │ interrogation │
│ parallel │ Grill only sees verified Storm output)│ on your plan │
│ research │ │ │
└─────────────┘ └─────────────┘
│ │
└──────────────────────┬──────────────────────────────────┘
▼
┌─────────────────┐
│ FUSION n│
│ single HTML │
│ report, end of │
│ session, < 60s │
└─────────────────┘
```text
**Core principles validated during design (see [docs/protocol.md](docs/protocol.md)):**
| Branch | Decision | Guarantee |
|---|---|---|
| A — Context isolation | Storm blind; Grill sees Storm via a filtered gateway | No contamination; Kill & Fork |
| B — Async delivery | Single fused HTML report at session end, < 60s | Section-based merge (Insights, Guide, Action) |
| C — Resource priority | Grill has network preemption; Storm runs "Hourglass" | < 8s latency on Grill turns |
| D — Contradiction resolution | Storm facts injected async, next turn | Triage: SLA > Performance > Cost |
## Status
🚧 **Pre-V0 / scaffold.** Architecture defined, protocol validated by stress-test and one real-world execution run.
Implementation starts at [V0](docs/roadmap.md#v0--proof-of-concept).
## Roadmap
See [docs/roadmap.md](docs/roadmap.md) for the full V0 → V3 plan.
| Phase | Deliverable | Success criterion |
|---|---|---|
| V0 | CLI orchestrator, 5-agent Storm on a fixed topic + Phase 4b verification | Verified HTML report in < 5 min |
| V1 | Grill module (decision tree, 4 stress-tests, fatigue audit) | 30-min interactive session with a test CTO |
| V2 | Unified Storm + Grill HTML report | Report contains both grill trace and verified facts |
| V3 | Web mode, configurable profiles, PDF export, CI/CD integration | Used by 5 teams in closed beta |
## Installation
```bash
git clone git@github.com:valorisa/stormgrill.git
cd stormgrill
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
stormgrill storm "state of vector databases in production, 2026" --agents 5 --out reports/
stormgrill grill --plan my_decision.yaml
stormgrill fuse --storm reports/latest.json --grill sessions/latest.json --out report.html
```text
## Project structure
```text
stormgrill/
├── src/stormgrill/
│ ├── core/ # Orchestrator, Hourglass Pipeline, Framing Sentinel, Kill & Fork
│ ├── grill/ # Adversarial engine, decision tree, fatigue audit
│ ├── storm/ # Multi-agent research, source verification (Phase 4b)
│ ├── fusion/ # HTML report generation (Jinja2)
│ └── monitoring/ # Context-leak audit, pivot log
├── templates/ # HTML/CSS report templates (Navy/Orange/Cream)
├── tests/
└── docs/- Protocol specification — the four decision branches and their stress-test results
- Roadmap
- Contributing
MIT — see LICENSE.
Bertrand (@valorisa) — designed through a double-loop meta-analysis: a stress-test of the orchestration protocol itself, followed by a real-world execution run.