feat: multi-agent Polymarket opportunity scanner + dashboard artifact - #1
Merged
Conversation
Add JSON Schema if/then conditional requiring price field for limit orders. Add test coverage: limit orders must have price, market orders don't need it. Add tests pinning auto-execute labels in strategy specs (structural arbs: yes, directional: no). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Self-contained multi-tab HTML dashboard (Markets / Recommendations / Account) rendered as an agent artifact. build_data.py is a pure/stdlib bridge mapping a scan run (universe + gated opportunities + enrichment + account) into the template DATA object: it merges a 24h "trending" popularity list and coerces an empty account to null so the Account tab renders wallet-setup steps. Wired into SKILL.md (visualize trigger) and orchestration.md (Step 7. Emit).
README: add a "Load the Polymarket MCP" quickstart step (claude mcp add, bearer token redacted) and the symlink dev-install note. CLAUDE.md: add the build_data dashboard command and the fetch-free invariant gotcha.
There was a problem hiding this comment.
Pull request overview
Adds a multi-agent “opportunity scan” workflow to the polymarket skill (scout → six strategy specs → synthesize → deterministic risk gate) plus a self-contained HTML dashboard artifact pipeline (run payload → DATA mapping → template injection), with extensive pytest coverage and supporting documentation.
Changes:
- Introduces a deterministic, configurable risk gate (
assets/risk_gate.py) with schema validation + CLI, and adds tests for boundary/safety behavior. - Adds an MCP-over-HTTP transport helper (
assets/poly-mcp.sh) and documents the MCP calling workaround. - Adds a dashboard artifact system (
assets/build_data.py+assets/dashboard-template.html+ docs) with tests covering mapping, trending merge, and injection correctness.
Reviewed changes
Copilot reviewed 32 out of 33 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_validate_opportunity.py | Tests Opportunity JSON-schema validation behavior (required fields, enums, limit vs market order pricing). |
| tests/test_strategy_specs.py | Structural tests ensuring each strategy spec contains required sections and auto-execute markers. |
| tests/test_skill.py | Ensures SKILL.md/README.md mention scanning triggers and orchestration reference. |
| tests/test_risk_gate.py | Unit tests for risk-gate decision ordering and boundary conditions (caps, liquidity, depth, confidence). |
| tests/test_risk_gate_cli.py | CLI-level tests for risk_gate.py decide/validate over stdin. |
| tests/test_poly_mcp.py | Basic behavior tests for the MCP helper script (usage, missing token error). |
| tests/test_orchestration_doc.py | Sanity check that orchestration doc covers key flow/tooling terms. |
| tests/test_config.py | Tests config loader defaults + partial override merge semantics. |
| tests/test_build_data.py | Tests deterministic mapping from scan payload → dashboard DATA, trending merge behavior, and injection invariants. |
| tests/fixtures/opportunity.valid.json | Canonical valid Opportunity fixture reused across tests. |
| tests/conftest.py | Adds assets/ to sys.path so tests can import helper modules. |
| SKILL.md | Updates skill description + adds “Opportunity scanning” and “Dashboard artifact” procedures and triggers. |
| reference/strategies/spread-capture.md | New strategy spec for spread capture (always escalate). |
| reference/strategies/smart-money.md | New strategy spec for smart-money flow following (always escalate). |
| reference/strategies/risk-free-arb.md | New strategy spec for structural arb (auto-exec eligible). |
| reference/strategies/multi-outcome-arb.md | New strategy spec for multi-outcome basket arb (auto-exec eligible). |
| reference/strategies/momentum.md | New strategy spec for momentum (always escalate). |
| reference/strategies/mean-reversion.md | New strategy spec for mean reversion (always escalate). |
| reference/orchestration.md | New orchestration playbook describing scout → parallel strategies → synthesize → gate → execute → report → artifact. |
| reference/opportunity.schema.json | Adds Opportunity JSON Schema, including conditional price requirement for limit orders. |
| reference/mcp.md | Documents MCP helper usage and rationale for the Accept-header workaround. |
| reference/config.md | Documents risk-gate configuration keys, defaults, and safety notes. |
| reference/config.example.json | Example config file with conservative defaults. |
| reference/artifacts.md | Defines dashboard DATA schema, procedure, and mapping rules for scan runs → dashboard. |
| README.md | Adds MCP setup instructions and documents the new “scan” capability and dev symlink workflow. |
| docs/superpowers/specs/2026-06-28-polymarket-multi-agent-scanner-design.md | Design spec for the multi-agent scanner and risk gating approach. |
| docs/superpowers/plans/2026-06-28-polymarket-multi-agent-scanner.md | Detailed implementation plan for the scanner components and tests. |
| CLAUDE.md | Developer context and commands, documenting the “only code” helpers and key safety invariants. |
| assets/risk_gate.py | Implements schema validation, config loading, deterministic decision logic, and CLI entrypoint. |
| assets/poly-mcp.sh | Implements MCP-over-HTTP handshake and tools/call with the required Accept header. |
| assets/dashboard-template.html | Adds the standalone dashboard UI template and embedded placeholder DATA block. |
| assets/build_data.py | Deterministic payload→DATA mapper and template injector for dashboard artifact generation. |
| .gitignore | Adds ignores for superpowers directories and Python caches. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+7
to
+9
| <link rel="preconnect" href="https://fonts.googleapis.com"> | ||
| <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin> | ||
| <link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&family=IBM+Plex+Mono:wght@400;500;600&display=swap" rel="stylesheet"> |
Comment on lines
+27
to
+34
| def load_config(path=None): | ||
| """Return DEFAULTS merged with the JSON config file (file wins). Missing file -> DEFAULTS copy.""" | ||
| cfg = copy.deepcopy(DEFAULTS) | ||
| resolved = os.path.expanduser(path or _DEFAULT_CONFIG_PATH) | ||
| if os.path.isfile(resolved): | ||
| with open(resolved) as fh: | ||
| cfg.update(json.load(fh)) | ||
| return cfg |
Comment on lines
+55
to
+61
| pa = opportunity["proposed_action"] | ||
| lc = opportunity["liquidity_check"] | ||
| size = pa["size_usd"] | ||
| conf = opportunity["confidence"] | ||
| strat = opportunity["strategy"] | ||
| mkt_liq = lc.get("market_liquidity_usd", 0) | ||
| depth = lc.get("depth_usd_at_price", 0) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a multi-agent opportunity scanner to the
polymarketskill — a scout-then-specialistspipeline that screens the market universe, fans out to six strategy agents, and runs every candidate
through a deterministic, money-guarding risk gate before anything auto-executes — plus a
self-contained HTML dashboard artifact to visualize a run (Markets / Recommendations / Account).
It stays an instruction-only skill: strategy logic lives in Markdown specs, not code. The only
executable code is three thin, unit-tested helpers —
risk_gate.py,poly-mcp.sh,build_data.py.What's included
Risk gate — the single point that authorizes real money (
assets/risk_gate.py)skip/escalate/auto; first match wins.risk-free-arb,multi-outcome-arb);every directional call escalates for human approval.
~/.config/polymarket/agent.json. stdlib-only; boundary tests pin every threshold.Orchestration + strategies (the "logic", as prose)
reference/orchestration.md— scout → 6 strategy agents (parallel) → synthesize → gate → report → emit.reference/strategies/*.md— momentum, mean-reversion, multi-outcome-arb, spread-capture,risk-free-arb, smart-money.
reference/opportunity.schema.json+ validator (limit orders must carry a price).MCP transport (
assets/poly-mcp.sh)tools/callwith the correctAcceptheader (works around an ECChealth-check false positive that 406s the healthy server). Documented in
reference/mcp.md.Dashboard artifact (
assets/build_data.py+assets/dashboard-template.html+reference/artifacts.md)template
DATAand injects it into the sandboxed HTML.account(no wallet) renders wallet-setup steps insteadof a blank tab.
Docs —
SKILL.md(scan + visualize triggers),README.md(MCP setup with redacted token + devsymlink note),
CLAUDE.md(dev context),reference/config.md.Safety
place; every directional call escalates. Test runs are report-only.
<YOUR_BEARER_TOKEN>placeholder; the walletprivate key is never printed, echoed, or logged.
Test plan
uv run --with pytest --with jsonschema pytest tests/ -v→ 58 passing (risk-gateboundaries, Opportunity validator, config loader, MCP helper, strategy-spec completeness,
build_data mapping / trending / account-null, orchestration + skill doc checks).
decide/validateover stdin.build_data.py --injectemits exactly one validDATAblock;account: null→ setup steps.