xingwudao/open-xquant

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

# Rule Builder

You help the user add risk and exit logic without overstating current spec
support.

## Current Execution Model

Rules are Python objects passed to `Engine.run(..., rules=[...])` or added by
the spec compiler internally. The audited CLI spec path does not support a
generic top-level `rules:` YAML section or `oxq backtest run --rules`, but it
does support a narrow whitelist under `portfolio.rules`.

In current `Engine.step()`:

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

# Universe Builder

You help the user define the tradable symbol pool.

## Current Stable Spec Path

The audited CLI compiler currently supports:

```yaml
universe:
  type: static
  symbols: ["SPY", "QQQ"]
  point_in_time: false
  survivorship_bias_policy: warn

# Experiment Comparator

Use this skill when the user asks to compare two completed runs. The comparison
is cross-experiment metadata, so do not write outputs inside either run
directory. Resolve the comparison output root from `.open-xquant/workspace.yaml`
when it exists: use `paths.comparisons_dir` for the comparison directory root
and `paths.comparison_registry` for the summary registry. Fall back to
`comparisons/` and `comparisons/comparisons.jsonl` only when no workspace config
value is present.

Do not use this skill in a version-governed workspace. Stop before reading run
artifacts or writing comparison outputs and route the request to
`compare-strategy-versions`, including when the user only says "compare two
experiments". The version-aware comparator must validate each candidate against

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

# Trade Executor

You configure execution assumptions in `strategy_spec.yaml` or SDK brokers.

## Stable Spec Configuration

Use this for audited CLI backtests:

```yaml
signal:
  signal_time: close_t

execution:
  trade_time: next_open

# Component Creator

Use this skill when the user explicitly asks to modify open-xquant source code
or add a built-in component to the framework.

For workspace-local custom components in a research task, use
`author-component` instead. That worker writes `custom_components/`,
`component_manifest.json`, and a refreshed `component_catalog.json` without
mutating the installed SDK bundle.

When this built-in/framework development path applies, decide whether a new
component is actually needed, then route to the correct creation skill.

Do not write component code in this navigator skill.

# Create Indicator

You create a pure numeric time-series component.

## Scope

Default built-in paths:

- source: `src/oxq/indicators/{snake_name}.py`
- tests: `tests/indicators/test_{snake_name}.py`
- package export: `src/oxq/indicators/__init__.py`
- built-in registry: `src/oxq/core/registry.py`

If the user is building a third-party extension instead of a built-in, use

# Create PortfolioOptimizer

You create allocation logic that returns target weights.

## Scope

Default built-in paths:

- source: `src/oxq/portfolio/{snake_name}.py`
- tests: `tests/portfolio/test_{snake_name}.py`
- package export: `src/oxq/portfolio/__init__.py`
- built-in registry: `src/oxq/core/registry.py`

Existing built-ins live in `src/oxq/portfolio/optimizers.py`; read that file

# Create Rule

You create bar-by-bar risk, hold, weight override, or exit logic.

## Scope

Default built-in paths:

- source: `src/oxq/rules/{snake_name}.py`
- tests: `tests/rules/test_{snake_name}.py`
- package export: `src/oxq/rules/__init__.py`
- built-in registry: `src/oxq/core/registry.py`

## Phase 1: Read Existing Patterns

# Create Signal

You create a vectorized trading-intent component.

## Scope

Default built-in paths:

- source: `src/oxq/signals/{snake_name}.py`
- tests: `tests/signals/test_{snake_name}.py`
- package export: `src/oxq/signals/__init__.py`
- built-in registry: `src/oxq/core/registry.py`

## Phase 1: Read Existing Patterns

# Evaluate Cross-Sectional Factor

Use this when the factor ranks assets on the same date.

## Minimal SDK Pattern

```python
import pandas as pd

from oxq.data.market import LocalMarketDataProvider
from oxq.factor_eval.metrics import (
    compute_decay,
    compute_ic,
    compute_icir,

# Factor Evaluator

You decide which factor evaluation workflow to use.

## Ask First

Confirm:

- factor definition
- symbols
- date range
- forward return horizons
- whether the question is stock selection or timing
- data source and missing-data treatment

# Evaluate Time-Series Factor

Use this when the factor predicts direction through time for one asset or a
small rotation set.

## Minimal SDK Pattern

```python
from pathlib import Path

from oxq.factor_eval.bundle import create_bundle
from oxq.factor_eval.tearsheet import generate_tearsheet

factor_series = factor_df.stack().rename_axis(["date", "asset"]).rename("factor")

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

# Live Trader

You handle broker connectivity with strict safety gates.

## Preconditions

Install live dependencies:

```bash
uv sync --extra live
```

Set credentials:

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

# open-xquant Router

Round 26 routing: decision schema `5`; candidate, policy, comparison, and
lineage schema `3`; schema-4 pointers are rejected. Use the exact closed schema-3
`build_selection_comparison` request and route historical refresh as `write ->
review -> lineage -> prepare new selection -> comparison -> resume` with a fresh
selection and candidate-set hash; the old selection must not be reused. The
request includes `comparison_population`.

This is the mandatory entry skill for open-xquant work. It routes the task to
the most specific open-xquant skill and sets only the minimum runner and
workspace context needed for that handoff.

## Router Contract

# Chart Indicator

You create visual checks. Charts do not replace validation or audit.

## Current Tool Signature

`oxq.tools.chart.chart_indicator` plots indicator columns from a stored
`RunResult` in the tool session:

```python
from oxq.tools.chart import chart_indicator

result = chart_indicator(
    run_id="run_1",

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical

# Factor Screening

You build candidate lists from data. Screening is not a backtest.

## Confirm Inputs

Ask for:

- market and symbols
- factor definitions
- rebalance date or date range
- thresholds or ranking rules
- required data provider
- how to handle missing values

# Final Version Selector

Round 26: current decision schema `5` includes `report_revision` and
`selection_request_id`; schema-4 pointers are historical and rejected.
Candidate, policy, comparison, and lineage schema `3`.

This skill performs final version governance. It chooses a final research
candidate only from eligible audited candidates and only after the user
confirms the selection policy. It is not investment advice.

## Workspace Path Resolution

Read `.open-xquant/workspace.yaml` before reading or writing final-governance
artifacts. Resolve each key independently from `paths`: use

# Parameter Tuner

You search parameters without turning in-sample luck into a claim.

## Preconditions

- The base strategy logic must already be clear.
- The base spec or SDK strategy must pass validation.
- Data must cover both training and OOS periods.
- The user must approve the metric and search ranges.

Warn when the total grid exceeds 100 combinations.

## SDK Pattern

## Phase Path Containment Preflight

Before any phase artifact read, write, directory creation, command, or handoff,
run this preflight completely and block on any failure:

1. Read `.open-xquant/workspace.yaml`. Resolve `version_root` from
   `paths.versions_dir`, using `versions` only when that key is absent.
   Require `version_root` to be a safe workspace-relative path: reject an
   absolute path or any `..` path segment, resolve it canonically with
   symlinks, and require the result to stay inside the workspace.
2. Read `current.json`. For normal phase work, set `expected_version_id` to
   `current.json.active_version`; it must exist. Only a contract that
   explicitly owns cross-version inspection may instead set
   `expected_version_id` from the referenced version id for that historical