pedrobraiti/vizier-trading-skill
vizier
VerifiedVIZIER — the multi-horizon trading brain of the Scout/Valet/Vizier stack. Use whenever the user wants market research, a portfolio review or health check, a thesis on a stock/ETF/crypto, or to actually buy/sell across US equities & ETFs (Interactive Brokers) and crypto spot (CCXT). It orchestrates the Scout (data) and Valet (execution) MCP servers, decides with conviction-sized risk discipline, remembers theses between sessions, and executes only under explicit intent — confirmation by default, autonomy strictly opt-in. Triggers on: "research/analyze X", "what's happening in the market", "analyze the market and bring me recommendations" / "find the best opportunities" (→ manager breadth sweep), "is my portfolio healthy", "buy/sell $N of X", "invest $N across N ideas", an empty/vague call (→ read-only market sweep), or "should I buy/sell X".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 41.4 KB |
| agents/vizier-research-envoy.md | markdown | 3.1 KB |
| references/anchor-example.md | markdown | 8.4 KB |
| references/autonomy-and-safety.md | markdown | 9.8 KB |
| references/execution-mechanics.md | markdown | 15.8 KB |
| references/output-template.md | markdown | 9.2 KB |
| references/pipeline.md | markdown | 29.3 KB |
references/autonomy-and-safety.md
View on GitHub# Autonomy & safety — the §B discipline
> **`python -m vizier …` = the core interpreter resolved in SKILL.md** (the skill's bundled `.venv`
> python), never bare system `python`.
Autonomy is the dangerous mode. It is **opt-in only** (the user explicitly says "execute without
asking"), and arming it is a checklist, not a vibe. The deterministic core (`python -m vizier`) holds
the math; this file is the order in which you call it and the Valet, and the rules around it.
> **What these guards are for, and how binding they actually are (be precise).** The §B ceilings and the
> drawdown-kill exist to **catch the ROBOT going haywire while no human is watching** — they are a
> failure-prevention backstop for armed, unattended autonomy, **not** a brake on a human's confirmed
> explicit order. They never apply to the confirmation path; do not let them clamp or second-guess a named
> human order. And on bindingness, don't overstate it: Vizier's ceilings + drawdown-kill are
> **advisory/bookkeeping — they only bind if the skill actually CALLS `autonomy-gate` each candidate and
> feeds it an honest live NAV.** The arithmetic is exact and self-latching in code, but nothing in Vizier
> can physically stop an order the LLM never routed through the gate. The **one hard, code-enforced dollar
> backstop is the Valet's `MAX_DAILY_VALUE`** (rejected at the executor regardless of what the skill does)
> — which is exactly why arming is FORBIDDEN until it is set. Treat Vizier's gate as the disciplined
> bookkeeper and the Valet env caps as the hard floor under it.
> **Why this exists:** the per-run cap alone does NOT stop a loop from draining the account — each round
> mobilizes a fresh slice of what's left. So there are TWO ceilings, both code-enforced from the
> decision log and both anchored to the SAME FIXED start-of-day baseline:
> - **per-run** (`per_run_pct` = 33% of NAV **OR** `per_run_max_trades`) — caps a single autonomous
> round; resets every `begin-run`.
> - **cumulative-daily** (`daily_cumulative_pct` = 50% of NAV **OR** `daily_max_trades`) — caps the whole
> 24h window; keeps accumulating across runs (the drain fix).
> Plus a **drawdown kill**. The `autonomy-gate` command composes per-run + daily + kill + armed into one
> verdict. Your job is to feed it honestly — `begin-run` each round and journal every fill.
---
## Arming checklist (do ALL of this, in order, before the first autonomous order)
1. **Fix the day baseline.** Read NAV (`account_summary.net_liquidation` for the venue) and:
```bash
python -m vizier arm-autonomy --json '{"nav": <NAV>}'
```
This writes the fixed baseline + 24h window to private memory. It is also the **manual re-arm**
point after a kill.
2. **Set/confirm the Valet backstops** (a second, independent line — the Valet's guards are
per-order/stateless, default-off): `MAX_DAILY_VALUE` (it defaults to *no cap* — SET it),
`DUPLICATE_WINDOW_SECONDS`, `MAX_ORDER_VALUE`. **Autonomy is FORBIDDEN if `MAX_DAILY_VALUE` is still
at its default (no cap).**
3. **Confirm the venue-specific live gate** (arming one venue does NOT arm the other):
- IBKR: `TRADING_ALLOW_LIVE=true` (+ `TRADING_DRY_RUN` as intended).
- Crypto: `CRYPTO_ALLOW_LIVE=true` + `CRYPTO_TRADING_MODE=live` + consciously `CRYPTO_DRY_RUN=false`.
(Not every exchange has a sandbox — in `live`, even with dry-run, you are one step from real money.)
4. **Assert paper/live truth** via `session_status` and confirm **`account_type`** (`"PAPER"`/`"LIVE"` —
the field present and identically named on both venues; do not key off the venue-specific `isPaper`/
`is_paper` boolean) matches the mode you intend. The "shadow" run must not think it's paper while
logged into LIVE.
> **Re-arm discipline (the drain trap), now CODE-enforced.** Re-arming mid-window would reset the day
> baseline and wipe `spent_today`, handing a fresh 50%-of-NAV budget — defeating the cumulative ceiling.
> So **`arm-autonomy` REFUSES** while a window is active: it returns `{"ok": false, ...,
> "error_type": "AutonomyAlreadyArmedError"}` and does not touch the state. A legitimate re-arm runs only
> after an explicit **`disarm-autonomy`** (the post-kill path disarms first) or after the 24h window
> expires — there is deliberately no force-override. When you DO re-arm post-kill at a depressed NAV, the
> drawdown-kill floor moves DOWN (15% of the lower NAV): state the new kill level and have the user
> acknowledge the kill cause is resolved before continuing.
## Per-round + per-candidate loop (while armed)
**At the start of EACH autonomous round** (batch of candidates), mark the run — this resets the per-run
counter; without it the gate refuses (no run marker = no per-run safety):
```bash
python -m vizier begin-run --json '{}'
```
Then, **for each candidate in the round:**
1. **Re-verify** `session_status` (assert `account_type`) and **re-check the circuit `breaker`** — the
breaker is **separate** from `autonomy-gate` (the gate does not see VIX/monthly-drawdown), so it is a
distinct call here, every candidate.
2. **Reconcile** (`reconcile`) own sent orders ∪ positions (build the input per
`references/execution-mechanics.md`); if a buy for this ticker is in-flight, poll its fill first.
3. **Gate the candidate** with a FRESH live NAV read from `account_summary.net_liquidation` (never reuse
the baseline or a cached value — the drawdown kill is only as honest as this number):
```bash
python -m vizier autonomy-gate --json '{"candidate_value": <USD>, "current_nav": <FRESH live NAV>}'
```
`allowed:false` → **do not send**; surface the `blocks` (`not_armed`, `per_run_ceiling`,
`cumulative_ceiling`, `drawdown_kill`) and stop the relevant scope. A `per_run_ceiling` with "no
active run" means you skipped `begin-run`. **A `drawdown_kill` block is NOT a skip-and-continue** —
see "When something trips" below: abandon the rest and disarm. `allowed:true` → proceed to the venue
order flow (`references/execution-mechanics.md`). (`autonomy-state` shows both the daily and per-run
numbers.)
4. **Journal the fill — non-negotiable, before gating the NEXT candidate.** Immediately after the order
fills, append it with the exact execution schema, because this is what BOTH ceilings read next. Add a
per-order `timestamp` (the fill time) and `status` so the row is also `reconcile`-ready:
```bash
python -m vizier append-decision --json '{"intent":"buy AAA","mode":"autonomy","executed_orders":[{"side":"BUY","ticker":"AAA","value":200.0,"venue":"ibkr","order_id":"<id>","timestamp":"<fill ISO-8601>","status":"filled"}]}'
```
**If you don't journal fills, the §B guarantee goes hollow again** — the gate will under-count spend
and re-authorize slices it shouldn't. Only `side:"BUY"` value consumes the spend ceiling; any executed
order counts as a trade. The order is strict: **gate → send → confirm fill → journal → only then gate
the next candidate** (never batch the journaling to the end of the round). This journal-per-leg
discipline is not autonomy-specific — SKILL.md requires it for ANY multi-leg batch, confirmation
mode included (a crash mid-batch must leave journaled fills, not phantom positions).
## When something trips mid-batch
- **`drawdown_kill`** (NAV fell past the kill threshold from the day baseline): the gate returns it as a
`block` but **does NOT disarm for you** — it looks like any other `allowed:false`. You must branch on
`block.type == "drawdown_kill"`: **abandon ALL remaining candidates in the batch, call
`python -m vizier disarm-autonomy`, escalate to manual.** This is different from a `cumulative_ceiling`/
`per_run_ceiling` block (which only stops the current scope, autonomy stays armed). Autonomy requires a
deliberate `arm-autonomy` re-arm — never auto-continue, never auto-re-arm (and re-arm only per the
re-arm discipline above).
- **Circuit breaker trips** in autonomy: same — abandon remaining orders, log, escalate. (In
confirmation mode the breaker asks once instead.)
- **Any Valet rejection / SafetyError:** hard stop, log "blocked, not executed", no auto-retry.
## Shadow / paper-first ladder (the birth posture — don't skip rungs)
1. **Shadow** — decide fully, **journal the decision instead of sending** (or send with `CRYPTO_DRY_RUN`/
`TRADING_DRY_RUN` on). Forward-test for weeks; compare against the real market.
2. **Paper / testnet** — execute against the paper account / exchange sandbox (`isPaper` true). Confirm
the plumbing end to end.
3. **Live read-only validation** — point at the live account but read-only; confirm balances/quotes/
session behave.
4. **Real-money autonomy** — only after 1-3 earn confidence, with the full arming checklist, and even
then ideally small. This is a conscious promotion, command by command — never the default.
## Confirmation mode (the default — no arming, human gates)
No `arm-autonomy`, no daily ceiling needed (the human is the gate). Still do the per-order safety:
re-verify session (`account_type`), re-check the breaker (it asks **once** on an explicit order — "market in
panic, still want the 3?"), reconcile, run the data-sufficiency + limits gates, show the decision, wait
for the OK. Calibration stays: "buy $3 of AAPL" executes after the gates without re-confirming the
obvious; only REAL ambiguity pauses to ask.
**Breadth discovery does not change the gates.** The Stage B envoys are research-only (they cannot
trade), and every survivor still passes data-sufficiency → limits → breaker → (if armed) autonomy-gate
**per candidate on the main thread**. The funnel ranks and prunes; it never pre-authorizes a trade.
## Precedence (when rules collide)
**Risk rules (stop, breaker) > anti-churn > horizon tags.** A pre-committed stop firing is never churn.
The kill and the breaker outrank an explicit order (they confirm/abandon, they don't obey blindly).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |