ite-workflows/README.md

# Tool Catalog

This README catalogs the tools and resources in this directory. It is intended for humans and LLM agents to quickly identify what is available and when to use it.

## Jurisdiction (set by member, 2026-09-01)

- `workflows/` = **ICM** (Interpretable Context Methodology, per `workflows/ICM.md`). Member invokes these by name; human review gates between stages. MARI never applies ICM structure to live trade execution.
- `runbooks/` = **MARI-native execution procedures.** This is how MARI runs when the member says "go" — no stage gates except the platform's own (Arm/Enter trade-action cards). Per MEMORY.md RUN RULES, the relevant runbook is read as the FIRST tool call at T+0 of any execution.

## Catalog

| Tool / Folder | Purpose | Key Files | When to Use |
| --- | --- | --- | --- |
| `runbooks/spy-0dte-scalp.md` | MARI-native e2e scalp procedure — T+0 gate, recon burst, schema-exact record, arm handoff, manage, stale-kill, post-mortem discipline. | `runbooks/spy-0dte-scalp.md` | FIRST tool call of every live scalp (per MEMORY.md RUN RULES). Not ICM — no stage gates. |
| `workflows/tool-catalog-maintainer/` | Creates and maintains catalog READMEs for directories of tools/resources. | `SKILL.md`, `CONTEXT.md`, `references/catalog-format.md` | Use when asked to catalog, index, or update documentation for a folder of tools. |
| `workflows/research-dfns/` | DFNS research folder — alerts logs, chat log, and TODO tracking from July 27, 2026. | `TODO.md`, `AlertsLog_*.txt`, `ChatLog_*.txt` | Use when reviewing or continuing DFNS research. |
| `workflows/backtest-strategy/` | Orchestrates rules-based strategy backtesting for core styles using TTG data and a pure-Python engine. | `CLAUDE.md`, `CONTEXT.md`, `_config/`, `stages/`, `shared/`, `pyproject.toml` | Use when backtesting trading strategies needing review-gated workflow, data caching, and honest reporting. |
| `workflows/scan-watchlist-for-equities/` | Scans equities for trade setups with confluence using a mechanical data-fetch script. | `CLAUDE.md`, `CONTEXT.md`, `_config/`, `shared/scripts/fetch_scan_data.py`, `stages/` | Use when scanning equities for confluence, generating mechanical data briefs, then interpreting for trade plans. |
| `workflows/scan-watchlist-for-options/` | Scans options for trade setups with confluence using a mechanical data-fetch script. | `CLAUDE.md`, `CONTEXT.md`, `_config/`, `shared/` (CSV watchlists, `scan-watchlist.md`), `stages/` | Use when scanning options for confluence, generating mechanical data briefs, then interpreting for trade plans. |
| `sources/260731-1330-credit-spread.md` | SPY Bull Put Credit Spread trade plan (0DTE, July 31, 2026). Sell $740 put / Buy $738 put spread. | `260731-1330-credit-spread.md` | Use for today's SPY options trade — bullish slow grind thesis. |
| `sources/iron-condor-45dte.md` | SPX Iron Condor trade plan — 45DTE entry, 21DTE time exit, Schwab broker. | `iron-condor-45dte.md` | Use when setting up or managing SPX iron condor spreads. |
| `sources/cha-martin-watchlist.ms.csv` | Cha Martin watchlist export (CSV) for ticker reference or scan filtering. | `cha-martin-watchlist.ms.csv` | Use for ticker watchlist reference or scan filtering. |
| `sources/2026-08-11-SFY-IC-Debrief.md` | Debrief of a SPY Iron Condor trade on 2026-08-11 with observations and key takeaways. | `2026-08-11-SFY-IC-Debrief.md` | Use for reviewing past iron condor trades to learn and improve. |
| `sources/HANDOFF_scan_workflow_scripts.md` | Documentation of the mechanical data-fetch script for scan workflows (API, MCP, output format). | `HANDOFF_scan_workflow_scripts.md` | Use when understanding or implementing the fetch_scan_data.py script. |
| `sources/servers.md` | List of MCP servers available in the MARI environment (ttg-stocks, ttg-benzinga, etc.). | `servers.md` | Use when referencing which data servers are available for MCP tool calls. |
| `sources/misc/` | Miscellaneous files of interest that may be used as sources (e.g., trade plans, analysis). | Various files (e.g., `xpon-squeeze-2026-08-24.md`) | For referencing miscellaneous source-like files. |
| `tos-short-squeeze/` | Contains a TSV file for short squeeze scanning. | `ShortSqueezeScanner.tsv` | Use for scanning short squeeze opportunities using the provided TSV data. |
| `backtest-workflow-PLAN.md` | Draft plan for a backtesting workflow (approved and built) describing architecture and stages. | `backtest-workflow-PLAN.md` | Use for understanding the design of the backtest-strategy workspace. |
| `build-watcher.md` | Build spec/prompt for a scheduled 9EMA×VWAP cross alert watcher on MESU6 futures. | `build-watcher.md` | Use when building, reviewing, or resuming the MESU6 9EMA/VWAP cross scheduled-alert watcher (or as a template for a similar cross-based futures alert). |

## Tools

### `workflows/tool-catalog-maintainer/`

**Purpose:**  
Creates and maintains a `README.md` catalog for a directory containing subfolders of tools, prompts, scripts, docs, workflows, skills, or other reusable resources. The README is a living catalog that improves over time.

**Contents:**  
- `SKILL.md` — skill definition and workflow  
- `CONTEXT.md` — full context: inputs, process, outputs, verification  
- `references/catalog-format.md` — catalog README structure and cataloging rules  
- `output/` — generated artifacts  

**Use when:**  
You need to catalog, index, summarize, or update documentation for a folder of tools so humans or LLM agents can quickly choose the right resource.

**Setup / dependencies:**  
None noted. Works with file read/write tools.

**Notes:**  
Always use this tool when asked to catalog a directory — inspect subfolders, read their key files, and write the README using `references/catalog-format.md`.

### `workflows/research-dfns/`

**Purpose:**  
Research folder for DFNS (Digital Frontier Acquisition Corp.) — contains alert logs, chat transcripts, and tracking notes from July 27, 2026.

**Contents:**  
- `TODO.md` — research tracking tasks  
- `AlertsLog_Mon Jul 27 2026*.txt` — alert logs (3 files)  
- `ChatLog_Mon Jul 27 2026.txt` — chat transcript  

**Use when:**  
Reviewing or continuing DFNS research. Note: per ticker tracking rule, DFNS should not be actively tracked unless a fresh positive reason arises.

**Setup / dependencies:**  
None noted.

### `workflows/backtest-strategy/`

**Purpose:**  
Orchestrates rules-based strategy backtesting for core styles (SPY 0DTE credit spreads, single-leg equity/options day trades) using TTG data servers as the only market-data source and a local pure-Python engine.

**Contents:**  
- `CLAUDE.md` — workspace identity and entry point  
- `CONTEXT.md` — workspace-level routing and stage description  
- `_config/` — stable references: `risk-params.md`, `strategy-spec-TEMPLATE.md`  
- `stages/` — five stage folders (00_clarify_strategy through 04_report) each with review gates  
- `shared/` — data cache (`shared/data/`) and engine scripts (`shared/scripts/`)  
- `pyproject.toml` — zero dependencies (stdlib-only)  

**Use when:**  
Backtesting trading strategies using TTG data, needing a review-gated workflow with data caching, honest reporting, and no look-ahead.

**Setup / dependencies:**  
None noted (stdlib-only, zero installs; the operator manages packaging with `uv`). Market data comes ONLY from TTG data servers.

**Notes:**  
Follows ICM.md — every stage ends at a review gate. Output is read and optionally edited before the next stage runs. Pure Python 3.12 stdlib (json, csv, sqlite3, statistics, math, datetime, urllib). No historical greeks/IV series; backtests are price/levels-driven.

### `workflows/scan-watchlist-for-equities/`

**Purpose:**  
Scans tickers for trade setups with confluence, using a mechanical data-fetch script to gather price/volume/bars/S-R data from TTG, producing a data brief for interpretation.

**Contents:**  
- `CLAUDE.md` — workspace identity  
- `CONTEXT.md` — workspace routing and stage description  
- `_config/` — references such as ticker list, default parameters  
- `shared/scripts/fetch_scan_data.py` — stdlib-only Python script for fetching and computing mechanical data  
- `shared/` — watchlist CSVs (e.g., `cha-martin-watchlist.ms.csv`, date-named CSVs)  
- `stages/` — five stage folders (00_clarify through 04_summary_card)  

**Use when:**  
Scanning equities for trade setups with confluence, generating mechanical data briefs (no interpretation), then interpreting the brief for trade plans.

**Setup / dependencies:**  
Python 3.11+, access to TTG data API via `MARI_MCP_CONFIG` environment variable. The fetch script is stdlib-only (urllib, json, etc.).

**Notes:**  
The workflow includes a mechanical script (`fetch_scan_data.py`) that fetches and computes data without interpretation. Stages: 00_clarify (ask clarifying questions), 01_broad_filter (runs the script), 02_confluence_analysis, 03_trade_plan, 04_summary_card. The script writes `data_brief.md` and `raw_data.json` to `stages/01_broad_filter/output/`.

### `workflows/scan-watchlist-for-options/`

**Purpose:**  
Scans options tickers for trade setups with confluence using a mechanical data-fetch script similar to the equities version.

**Contents:**  
- `CLAUDE.md` — workspace identity  
- `CONTEXT.md` — workspace routing and stage description (identical to equities version)  
- `_config/` — `trade_plan_template.md`  
- `shared/` — CSV watchlists (e.g., `cha-martin-watchlist.ms.csv`, date-named CSVs) and `scan-watchlist.md`  
- `stages/` — five stage folders (00_clarify through 04_summary_card)  

**Use when:**  
Scanning options for trade setups with confluence, generating mechanical data briefs, then interpreting the brief for trade plans.

**Setup / dependencies:**  
Python 3.11+, access to TTG data API via `MARI_MCP_CONFIG` environment variable. The fetch script is stdlib-only.

**Notes:**  
Very similar to the equities workflow but focused on options. The shared folder contains CSV watchlists and a `scan-watchlist.md` file. The mechanical script (if present) would fetch options data; verify the exact script name and location.

### `sources/260731-1330-credit-spread.md`

**Purpose:**  
Active trade plan for a SPY Bull Put Credit Spread (0DTE, July 31, 2026). Sell $740 put / Buy $738 put spread, targeting 20%+ profit with bullish slow grind thesis.

**Contents:**  
- `260731-1330-credit-spread.md` — trade plan with entry, exit, profit target, stop loss, and monitoring notes.

**Use when:**  
Executing or monitoring today's SPY options trade (July 31, 2026).

**Setup / dependencies:**  
None noted. Trade-specific, not reusable.

### `sources/iron-condor-45dte.md`

**Purpose:**  
Trade plan for SPX Iron Condor through Schwab broker. 45DTE entry, 30-point wings, forced close at 21DTE. Includes profit target (25% of net credit), stop loss (50% of max loss), and monitoring cadence.

**Contents:**  
- `iron-condor-45dte.md` — trade plan with entry, exit, risk management, and monitoring details.

**Use when:**  
Setting up or managing SPX iron condor spreads with Schwab broker.

**Setup / dependencies:**  
Schwab broker session required.

### `sources/cha-martin-watchlist.ms.csv`

**Purpose:**  
CSV export of a Cha Martin watchlist — likely contains tickers for scanning or monitoring.

**Contents:**  
- `cha-martin-watchlist.ms.csv` — plain CSV with one ticker per line (or columns).

**Use when:**  
Referencing tickers for scans, short squeeze candidates, or watchlist filtering.

**Setup / dependencies:**  
None noted.

### `sources/2026-08-11-SFY-IC-Debrief.md`

**Purpose:**  
Debrief of a SPY Iron Condor trade on 2026-08-11, summarizing trade details, observations, key takeaways, and next times.

**Contents:**  
- `2026-08-11-SFY-IC-Debrief.md` — trade summary, plan, observations, asymmetric structure notes, NL3 feed issue, key takeaways.

**Use when:**  
Reviewing past iron condor trades to learn from observations and improve future trades.

**Setup / dependencies:**  
None noted.

### `sources/HANDOFF_scan_workflow_scripts.md`

**Purpose:**  
Documentation of a mechanical data-fetch script for the scan-watchlist-for-equities workflow, detailing API facts, script design, environment, MCP protocol, verified responses, output format, and integration notes.

**Contents:**  
- `HANDOFF_scan_workflow_scripts.md` — detailed handoff covering goal, design, environment facts, MCP-over-HTTP protocol, verified response shapes, data brief format, stitching into CONTEXT.md, verification targets, pitfalls, resume checklist, and current state.

**Use when:**  
Understanding or implementing the `fetch_scan_data.py` script, or integrating mechanical data fetching into scan workflows.

**Setup / dependencies:**  
None noted.

### `sources/servers.md`

**Purpose:**  
List of MCP servers available in the MARI environment for tool calls (e.g., market data, news, chat, etc.).

**Contents:**  
- `servers.md` — plain list of server names: `chrome-devtools`, `mari-cell`, `ttg-benzinga`, `ttg-chat`, `ttg-crypto`, `ttg-economy`, `ttg-finviz-elite`, `ttg-forex`, `ttg-futures`, `ttg-holygrail`, `ttg-indices`, `ttg-options`, `ttg-platform`, `ttg-stocks`, `ttg-uw`.

**Use when:**  
Referencing which data servers are available for MCP tool calls in workflows or scripts.

**Setup / dependencies:**  
None noted.

### `sources/misc/`

**Purpose:**
Miscellaneous files of interest that may be used as sources (e.g., trade plans, analysis, data dumps). These are not primary source files but could be referenced for insights or as starting points.

**Contents:**
- `xpon-squeeze-2026-08-24.md` — XPON Short Squeeze — Premarket signal reconstruction (2026-08-24) documenting a micro-cap short squeeze setup with volume spike, range break, premarket gap, and squeeze mechanics.
- Various JSON files containing live trading cockpit data, error fixes, and trade plans from September 2026.

**Use when:**
Referring to miscellaneous source-like files for reference, analysis, or as a starting point for creating new sources.

**Setup / dependencies:**
None noted.

### `tos-short-squeeze/`

**Purpose:**  
Contains a TSV file for short squeeze scanning, likely a precomputed list of candidates.

**Contents:**  
- `ShortSqueezeScanner.tsv` — tab-separated values with columns likely including ticker, metrics, etc.

**Use when:**  
Scanning for short squeeze opportunities using the provided TSV data as input or reference.

**Setup / dependencies:**  
None noted.

### `backtest-workflow-PLAN.md`

**Purpose:**  
Draft plan for a backtesting workflow (approved and built) describing the architecture, stages, and rules for backtesting core styles using TTG data and a pure-Python engine.

**Contents:**  
- `backtest-workflow-PLAN.md` — goal, architecture (data, engine, reporting layers), proposed workspace layout, stage contracts, decision points, known limitations, credit/cost profile, and out-of-scope items.

**Use when:**  
Understanding the design of the `backtest-strategy` workspace or as a reference for building similar review-gated backtesting workflows.

**Setup / dependencies:**  
None noted.

### `build-watcher.md`

**Purpose:**  
Prompt/spec for building a scheduled-alert watcher that fires on a 9EMA×VWAP cross for MESU6 (MES Sep 2026 front month). Signal: 9EMA on 3-minute bar closes (built from 1-minute bars) crossing session VWAP anchored at the 9:30 AM ET open. Cross up = long trigger, cross down = short trigger. Explicitly scoped as a scheduled-alert build, not a Holy Grail analysis.

**Contents:**  
- `build-watcher.md` — signal definition, data-source rules, alert discipline, schedule parameters, and credit-cost note.

**Use when:**  
Building, reviewing, or resuming work on the MESU6 9EMA/VWAP cross scheduled alert, or as a template for a similar cross-based futures alert watcher.

**Setup / dependencies:**  
Requires the TTG futures MCP server (`futures_aggs` for bars, `futures_snapshot` for last price) and a Scheduled job runner. The SCHEDULE section (active window, hard stop, fire cap) contains bracketed placeholders in the current draft — these must be filled in before a job is created, and the confirm card must be reviewed and approved before creation.

**Notes:**  
Fires only on an actual state change (no re-alerts); permanently silent after the watch ends or the fire cap is hit. Job pause/delete is user-owned via the Scheduled sidebar — the agent must never pause/delete it itself. Each fired alert costs ~50 Active Trader credits; polls are free.

## Maintenance Notes

When adding or updating a tool folder, update this README with:

- purpose
- key files and entry points
- usage guidance
- setup requirements
- notable changes or cautions