Options OS documentation

Ask the coding agent to explain how Options OS works:

Explain the Options OS system, its architecture, construction model, libraries and development workflow

Or run the /explain-component skill for a structured explanation. In Codex, replace the leading / with $.

The trading engine intent covers:

• Trading universe
• Engine and strategy identity
• Market idea
• Observable market behaviour
• Market, venue and derived inputs
• Data freshness and quality
• Setups and signals
• Candidate selection
• Option structures
• Entry and placement policy
• Position sizing
• Portfolio allocation
• Risk and mandates
• Hedging
• Exit and settlement
• Orders and partial fills
• Engine-instance state
• Restart and recovery
• Reconciliation
• Operator commands
• Runtime modes
• Monitoring and evidence

A definition is incomplete when two independent engineers could implement different behaviour from it.

The trading engine intent separates the following responsibilities:

Risk may override strategy and execution.

Execution may determine how to place an accepted intent. It may not invent strategy logic.

Runtime may schedule declared behaviour. It may not create new business rules.

Venue adapters may translate canonical instructions. They may not redefine the strategy, risk policy or financial meaning of the engine.

Repository authority flows in one direction:

trading engine intent
    ↓
accepted specifications
    ↓
INVARIANTS.md
    ↓
mechanical enforcement policy
    ↓
CLAUDE.md and AGENTS.md
    ↓
hooks, tests and CI
    ↓
implementation and generated evidence

Read authority in this order before changing behaviour:

1. INVARIANTS.md
2. PROFILE.md
3. The applicable specification
4. The current implementation
5. Generated code maps and verification evidence

Code is implementation evidence. It is not the source of financial or operational meaning.

When code conflicts with an accepted specification, correct the code.

When a generated artifact conflicts with its source, correct the generator or regenerate the artifact.

When an enforcement rule conflicts with its owning invariant, correct the rule at its source.

Reusable code follows the framework construction model:

primitives ← enums ← objects ← algebra ← morphisms ← pipelines ← programs
     ↑          ↑         ↑         ↑          ↑           ↑
     └──────────┴─────────┴─────────┴──────────┴───────────┤
                                                        interpreter → effects
                                                             ↑           ↑
                                                             └── runtime ┘

Effects begin at the interpreter boundary.

Financial calculations must remain testable without connecting to a venue, database, clock or filesystem.

Not every package requires every layer. Empty pass-through layers are not permitted.

The repository supplies four mechanisms for coding-agent work:

Skills cover:

• Trading-intent translation
• Buildable specification writing
• Architecture
• Implementation planning
• Plan execution
• Venue adapters and probes
• Unit and end-to-end test design
• Test verification
• Implementation and financial audits
• Defect tracing and repair
• Runtime evidence evaluation

Invoke the skill required by the current task. Do not combine unrelated lifecycle stages into one prompt.

Repository workflows coordinate complete engineering activities:

• build-system
• change-system
• correct-defect
• certify-trading-build
• release-readiness

Use a workflow when the task crosses several specifications, libraries, adapters or verification stages.

Workflow identifiers retain their repository names even when their target is an engine.

Hooks enforce repository rules at session, prompt, tool, edit, configuration-change and stop boundaries.

They reject operations such as:

• Destructive repository changes
• Test weakening
• Failure suppression
• Unauthorized changes to semantic authority
• Invalid database access
• Incomplete work reported as complete

Hooks enforce declared rules. They do not decide which feature or correction should be built.

Assembly requires explicit direction.

Tell the coding agent which existing libraries satisfy each required capability. Point it to their specifications and implementations.

Example:

Use the existing quant-greeks library for Greek meaning and exposure
calculation. Do not introduce engine-local Greek types or calculations.

Use quant-cost for fees, spread, slippage, funding and hedge-cost
representation. Do not create another cost model inside the engine.

Use adapter-core as the exchange-integration substrate and
adapter-deribit as the concrete Deribit implementation.

Do not ask the agent to “use the repository where appropriate.” That leaves library selection open to interpretation.

Without explicit bindings, coding agents commonly rebuild capabilities that already exist. This wastes context and implementation time, creates conflicting semantics and produces an engine that is more difficult to verify.

Correcting a duplicated or incorrectly integrated implementation is usually more difficult than building the correct path from the start. Coding agents are weaker at semantic correction across an existing engine than at bounded construction from accepted specifications.

Resolve library, venue and infrastructure bindings before creating the implementation plan.

specifications
    ↓
types and schemas
    ↓
invariants and architecture rules
    ↓
unit and property tests
    ↓
integration and contract tests
    ↓
lifecycle and acceptance scenarios
    ↓
static analysis and quality gates
    ↓
runtime evidence
    ↓
conformance

Different evidence answers different questions:

A similarly named module is not proof that a requirement was implemented.

Evidence must preserve the required inputs, units, calculations, state transitions, failure behaviour and invariants.

Generate a repository tree:

$make tree DIR=<path>

Generate structural code maps:

$make codemap

Flatten a subsystem into one reviewable document:

$make flatten-libs || make flatten-adapter-core || make flatten-skills || make flatten-hooks || make flatten-lint

Generated trees, flattened views and code maps allow coding artifacts to be transported to a web-based reasoning model for evaluation and audit.

They provide current codebase evidence without requiring the reviewer to infer the repository from conversation history.

Use different model capabilities for different stages:

Use the strongest available model for work that establishes meaning:

• Trading-intent translation
• Specification writing
• Architecture
• Assembly
• Cross-engine decisions
• Financial and semantic audits

Once the specifications, architecture and bindings are accepted, implementation packets can usually be assigned to less expensive models.

Do not move to a less capable implementation model while trading meaning, architecture or assembly decisions remain unresolved.

Implementation quality is bounded by the quality of the accepted definition. A coding agent cannot repair missing trading intent by generating more code.

Use a clean session when:

• The agent repeatedly reopens accepted decisions
• The conversation is dominated by previous failed attempts
• The agent argues against the authorized scope
• Old implementation state is treated as current
• The agent repeatedly stops before satisfying acceptance criteria
• Corrections produce more interpretation instead of forward progress

A handoff must describe:

• Current state
• Desired state
• Constraints
• Remaining work
• Verification evidence

It should not reproduce the narrative history of the session.

• Complete and accept the trading engine intent before running /translate-trading-intent.
• Use a capable web-based reasoning model for the initial definition.
• Run Claude Code or Codex from the repository root.
• Start engine-definition work in the repository with /translate-trading-intent.
• Accept the engine, operations and scenario specifications before architecture work.
• Define architecture and assembly before implementation planning.
• Point the agent to existing libraries explicitly.
• Read the applicable specification before changing behaviour.
• Do not infer financial meaning from implementation alone.
• Do not add venue-native types to engine code.
• Do not perform effects inside pure libraries.
• Do not weaken tests to make a change pass.
• Do not hand-edit generated policy files.
• Do not report a verification command as passing unless it ran successfully.
• Do not begin implementation while required engine decisions remain unresolved.
• Keep strategy, risk, execution, adapter, book and runtime responsibilities separate.