This repository is a methodology-first Codex plugin for cross-sectional factor research. It teaches an agent how to adapt a sound research process to the data, libraries, and project structure already available on the target machine.
It is deliberately not a second Quant framework. The bundle contains no market data, Python research runtime, fixed directory layout, or executable backtest pipeline.
| Skill | Responsibility |
|---|---|
quant-factor-research |
Route and coordinate work that spans multiple research stages |
quant-data-acquisition |
Define sources, universe, adjustment, provenance, and raw-data contracts |
quant-data-cleaning |
Normalize OHLCV, audit data loss, and prepare research matrices |
quant-factor-testing |
Construct point-in-time factors and evaluate them with layered portfolios and Rank IC |
quant-nav-analysis |
Convert return series into NAV, risk statistics, and drawdown visualizations |
Use only the stage that the task needs. Invoke quant-factor-research when the request crosses two or more stages or when the failed stage is unclear.
Install the repository as one Codex plugin. The manifest at .codex-plugin/plugin.json exposes every directory under skills/; the repository root is not itself a Skill.
For local Skill-only development, link each individual skills/<name> directory into the Codex user Skill directory supported by the local installation. Do not link the repository root as quant-factor-research, because doing so hides the other four Skills.
Run the dependency-free structural validator from any Python 3 environment:
python3 scripts/validate_bundle.pyThe validator checks the plugin manifest, the exact Skill set, frontmatter, UI metadata, relative references, and the absence of an embedded research runtime or an external Quant checkout dependency.
This proves that the teaching bundle is internally complete and discoverable. It cannot prove that arbitrary market-data providers are reachable or that code generated later for an unknown target repository will run unchanged.
The Skills preserve the following non-negotiable semantics:
- Treat source choice, adjustment, historical universe membership, and provenance as research inputs.
- Keep missing observations missing until their economic meaning is known.
- Make factor availability and execution timing explicit to prevent lookahead.
- Evaluate forward returns with a declared horizon and execution lag.
- Use Spearman Rank IC and quantile monotonicity as diagnostics, not only headline return.
- Annualize with the actual return frequency and include the initial NAV baseline in drawdown.
- Distinguish a factor diagnostic from a production execution backtest.
Detailed implementation remains the responsibility of the target project. The agent should reuse that project's existing data access, shared utilities, backtest engine, and plotting conventions whenever they are suitable.