Build Your Own Automated Options Trading System · Bonus

Subagents — a specialist
that reviews your order code.

Main Claude is a generalist with a full memory of this conversation. A subagent is a specialist with a clean memory and one job. For real-money trading code, the right specialist is a safety reviewer trained on 170+ live bugs.

Bonus lesson
subagents · dispatch · order-execution-reviewer
Real money. Clean context.
This lesson, in one glance

Same five beats. New idea.

1
Idea
A subagent is a second Claude with its own context window and a tight job description. Build once, use forever.
2
Outcome
An order-execution-reviewer subagent that audits every order-code change against your playbook and bug log.
3
Vocabulary
subagent · system prompt · dispatch · frontmatter · tool allowlist
4
Hands-on
Read the agent file you already have. Dispatch it on a real diff. Inspect the structured verdict it returns.
5
War story
A real SL race in production cost a 120-unit duplicate buy. A reviewer subagent would have caught it on diff.
1 · The idea

One Claude is a coworker. Two Claudes is a review committee.

Main Claude alone

  • Generalist. Reads the whole conversation, juggles every topic at once.
  • Context pollutes. The 170-bug playbook, 4000-line log, three open files all share one window.
  • Same memory for chat and audit. Friendly-but-distracted code review.
  • One job at a time. While reviewing, it stops writing.
  • Pleased to agree. When you say "looks fine?" it tends to say yes.

Main Claude + a subagent

  • Specialist. Knows only one topic (order-execution safety) — and knows it deeply.
  • Clean context. Loads playbook + bug log on its own; main window stays small.
  • Runs in parallel. You implement while it reviews — two Claudes, one task.
  • Returns one structured message. A verdict. Severity-banded findings. Nothing else leaks back.
  • Built to disagree. The system prompt explicitly says: "prefer false positives over false negatives."
The subagent is the same model. What changes is the prompt, the tools it's allowed to use, and the memory it starts with.
2 · What a subagent actually is

A markdown file. Five lines of frontmatter and a long system prompt.

.claude/agents/order-execution-reviewer.md
---
name: order-execution-reviewer
description: Use PROACTIVELY whenever
  order-related code is added or modified — entry,
  SL, exit, squareoff, cancel, partial fills,
  position tracking, crash recovery, double-leg,
  segment-quantity. Returns structured review.
  Read-only — never edits files.
tools: Read, Grep, Glob, Bash
model: opus
---

# Order Execution Reviewer

You are a specialist code reviewer for a
live options-trading system handling real
money. You enforce the order-execution
playbook and the 170+ bug history…

## Required Reading
1. docs/order-execution-playbook.md
2. .claude/skills/order-execution-safety/…
3. docs/bug-log.md  (now BUG-170+)
4. .claude/CLAUDE.md
…
name
How main Claude refers to it when dispatching. Lowercase-kebab convention.
description
When to dispatch. "PROACTIVELY" tells main Claude to auto-trigger, not wait for your ask.
tools
Tight allowlist. Read, Grep, Glob, Bash only — no Edit or Write. A reviewer that can't modify code can't break it.
model
opus for judgment-heavy review. The rest of the file is the system prompt — instructions, rules, output template.
Project-local agents live in .claude/agents/ and ship with the repo. User-global agents live in ~/.claude/agents/.
3 · How dispatch works

Main Claude calls Agent. Subagent runs alone. One message back.

[1]  You: "review my changes to core/broker/order_manager.py"
        │
        ▼
[2]  Main Claude recognises an order-code review task.
        It dispatches:  Agent(subagent_type="order-execution-reviewer", prompt=…)
        │
        ▼
[3]  A fresh Claude spins up.  // new context window, model=opus
        Its system prompt = the body of order-execution-reviewer.md.
        It loads:    docs/order-execution-playbook.md
                     docs/bug-log.md
                     .claude/CLAUDE.md
                     .claude/skills/order-execution-safety/skill.md
        It reads:    git diff, the changed files, related tests.
        │
        ▼
[4]  Subagent returns ONE structured markdown message:
                     # Order Execution Review
                     Verdict: GO-WITH-FOLLOWUPS
                     ## Findings — CRITICAL × 0 · HIGH × 2 · MEDIUM × 1
                     …
        │
        ▼
[5]  Main Claude sees only that one message.
        Subagent's intermediate work, file reads, bug-log scan — all discarded.
        Your main window stays small.  Subagent's context died with the call.
Two consequences. Good: main context stays clean. Cost: the subagent can't be "asked a follow-up" — each dispatch is fresh. Brief it fully.
4 · The one we just built

order-execution-reviewer — what it knows, what it returns.

What it knows

  • docs/order-execution-playbook.md — 12 sections, every rule has a bug number behind it
  • docs/bug-log.md — BUG-001 through BUG-170+
  • .claude/CLAUDE.md — project conventions, isolation rules, segment-quantity rules
  • .claude/skills/order-execution-safety/ — the checklist form
  • Design specs: atomic double-leg, SL-modification cap

What it returns

  • Verdict — GO, GO-WITH-FOLLOWUPS, or NO-GO
  • Findings — banded CRITICAL · HIGH · MEDIUM · LOW · INFO
  • Every finding cites file:line + playbook §X.Y + BUG-NNN
  • Checklist coverage — 13 categories, ticked or flagged
  • Tests run — pytest output (or "not run, why")
  • Required follow-ups — actionable, not vague

Why read-only

  • tools: Read, Grep, Glob, Bash — no Edit, no Write
  • A reviewer that can't modify code can't accidentally break order placement
  • It reports; you (or main Claude) fix
  • Same model as Codex review pairing — defence in depth
  • If asked to fix something, it returns the fix in the review — never patches the file
The file exists. .claude/agents/order-execution-reviewer.md. 308 lines. Read it once — you'll know everything it's looking for.
5 · Four real bugs it would have caught on diff

Every rule has a bug number. Every bug cost something.

BUG-078

LIMIT SELL at breakout fills instantly

A new strategy used LIMIT SELL at the breakout price expecting it to "wait" for the price to drop. LIMIT SELL fills above the limit immediately — the breakout never happens, you're already short.

caught: §1 entry order type · use SL SELL
BUG-100

SL filled at exchange; tick arrives 200ms later

SL-L order completed at the exchange before the tick reached the local code. The tick handler thought "SL didn't fire" and placed an emergency exit. Bought 120 against 60 sold.

caught: §2 SL · check broker status before exit
BUG-102

Broker netqty ≠ our position qty

Squareoff used the broker's aggregated netqty, which sums across tranches and strategies on the shared account. Exit qty came out wrong on multi-tranche days.

caught: §5 exit · use per-position in-memory qty
BUG-165

squareoff_all is a footgun

The base broker class shipped with a default squareoff_all() that closes everything on the account — including other strategies. Removed. The reviewer flags any reintroduction as automatic NO-GO.

caught: §5 exit · never account-wide flatten
A diff that introduces any of these failure modes returns a NO-GO. You don't have to remember the bug — the subagent does.
6 · By the end of this lesson

You can dispatch a specialist on any order-code change.

You know what .claude/agents/order-execution-reviewer.md contains and can edit it as your bug log grows.
You can ask main Claude to dispatch it — or write a PostToolUse hook so it auto-runs after every edit to core/broker/, core/mcx/, core/equity/, or hedge_runner.py.
You can read its structured output: Verdict → Findings by severity → Checklist coverage → Tests → Follow-ups. No more "looks fine to me".
You recognise when to build the next subagent — and when a skill or a hook is the better answer.
The order-execution-reviewer is your first specialist. The framework lets you build one per failure mode you care about.
7 · New vocabulary

Five words. Use them this week.

subagent
A second Claude with its own context window, system prompt, and tool allowlist. Dispatched by main Claude for one specific job.
.claude/agents/*.md
system prompt
The body of the agent file. The instructions the subagent starts the conversation with — its job, rules, output template.
"You are a specialist…"
dispatch
The act of main Claude calling the Agent tool with a specific subagent_type and a fresh prompt. Spins up the subagent.
Agent(subagent_type=…)
frontmatter
The YAML block at the top of the agent file — name, description, tools, model. Tells Claude Code how to register it.
--- name: foo ---
tool allowlist
The tools: line restricts which tools the subagent can use. A reviewer with no Edit can't modify code by mistake.
Read, Grep, Glob, Bash
All five together = you can read, build, and reason about any subagent you encounter in any Claude Code project.
8 · The hands-on bit — your task

Read it. Run it. Read its verdict.

What to do this week (90 minutes)

  1. Read the agent file. Open .claude/agents/order-execution-reviewer.md. Read the frontmatter, the rule matrix by subsystem, the output template at the bottom. About 308 lines — 20 minutes.
  2. Dispatch it manually. In a fresh Claude Code session, ask: "Use the order-execution-reviewer subagent to review the current working tree (git status / git diff)." Watch main Claude call the Agent tool.
  3. Read the verdict. Output will be a single structured markdown message. Walk through every CRITICAL and HIGH finding. If the verdict is GO and you disagree, that's a prompt-tuning signal.
  4. Cross-check one finding. Pick any BUG-NNN the reviewer cited. Open docs/bug-log.md, find the entry, confirm the rule matches. This teaches you to trust (and audit) what the subagent says.
  5. Optional — auto-dispatch. Add a PostToolUse hook in .claude/settings.json that dispatches this reviewer whenever Edit|Write touches core/broker*/, core/mcx/, core/equity/, core/framework/, or hedge_runner.py.
The first time you dispatch it, you'll think "this is just a fancy prompt." After the first finding it catches that you would have missed — you'll think "this is the third pair of eyes I always wanted."
9 · What it looks like in real Claude Code

One prompt. One structured verdict.

claude code · ExecutionProject 
› Use the order-execution-reviewer subagent to review HEAD

⏺ Agent(order-execution-reviewer)
  ⎿  Reading docs/order-execution-playbook.md (387 lines)
  ⎿  Reading docs/bug-log.md (4006 lines, through BUG-170)
  ⎿  Reading .claude/CLAUDE.md
  ⎿  git diff HEAD~1..HEAD — 2 files changed
  ⎿  Running pytest tests/test_order_manager.py …

# Order Execution Review

**Scope:** HEAD (1 commit, 2 files)
**Reviewed against:** playbook §2, §3, §4 · BUG-100, BUG-126, BUG-163
**Subsystems touched:** core/broker/order_manager.py, core/framework/sl_manager.py

## Verdict

**GO-WITH-FOLLOWUPS** — SL re-place path correct, but capacity-gate uses
                          broker units instead of lots (BUG-163 regression risk).

## Findings

### CRITICAL  (none)

### HIGH
1. **Capacity gate counts broker units, not lots** — `core/framework/sl_manager.py:284`
   - What: `current_lots + new > MAX_LOTS` compares units to lot cap.
   - Rule violated: playbook §4 · BUG-163
   - Required fix: divide broker qty by `instrument.lot_size` before comparing.

### MEDIUM
1. **No pytest coverage on the new SL re-place branch** — `tests/test_sl_manager.py`
   - The "rejected → re-place" path (BUG-081) is not exercised. Add a test.

› _
Notice: the subagent's reads, greps, and pytest calls happen inside the Agent block — none of it lives in your main context after.
10 · Where to point this next

Four more subagents earn their place in this repo.

🔍

log-incident-investigator

Loads today's logs/*_$(date +%F).log, classifies CRITICAL/ERROR, cross-references the bug log. Read-only. Dispatched after any session with alerts.

tools: Read, Grep, Bash
🛡️

deploy-readiness-auditor

Runs the pre-live-trading-audit checklist as a subagent so the (long) audit output never pollutes main context. Use at start of each trading month.

tools: Read, Grep, Bash
🗺️

codebase-explorer

Project-aware exploration. Knows the equity ↔ MCX isolation, broker abstraction, framework parity. Answers "what calls X?" without polluting main context.

tools: Read, Grep, Glob
🚑

codex:rescue (already installed)

Delegates a stuck implementation or a second-opinion review to Codex. The "two-model" pattern your feedback_code_quality_priority.md memory already prescribes.

via codex plugin
A subagent earns its place only when it targets a specific failure mode you've seen — or one that would be irrecoverable.
11 · A real-money war story · BUG-100

200 milliseconds between SL filling and the tick arriving. Bought 120 against 60 sold.

A short was protected by an SL-L order at the exchange. The exchange triggered the SL and filled it. The websocket tick carrying "price hit your trigger" arrived in our process a quarter-second later. By the time the tick handler ran, the SL was already done — but the handler didn't know yet.

The 250ms that cost real money

+000ms
Exchange. SL-L at trigger fires. 60 short units bought back. Position flat at the exchange.
+210ms
Tick arrives. LTP crossed trigger. Tick handler: "SL must have triggered — let me check it."
+220ms
The bug. Handler skipped checking broker SL status. Assumed SL was still open. Placed an emergency LIMIT BUY for 60.
+390ms
Real money out. Emergency order fills. Now long 60. Net bought: 120 against 60 ever sold. BUG-100.
later
The fix (one line, conceptually): in any SL jump path, check broker SL status FIRST. If filled or completed, skip the emergency exit.
The lesson, pinned

A subagent is a checklist that refuses to forget.

BUG-100 didn't happen because Claude (or the human) was careless. It happened because a 250ms race condition is hard to keep in your head while writing the next strategy six weeks later. A reviewer subagent loaded with BUG-100 will catch any SL jump path that's missing the "check status first" guard on the diff, before the code ever runs against real money.

The model is the same. The rules are the same. What changes is the attention — a fresh context window, no other concerns, one job. That's why the subagent catches what main Claude (juggling six other tasks in your current conversation) often misses.

170+
live trading bugs in the log it's loaded against
0
tools it has that can modify your code
1
structured verdict it returns per dispatch
Bonus lesson — takeaway

A specialist with a clean memory
and an old playbook.

Build it once, in fifteen minutes. It reviews every order-code change for as long as the repo lives. The money you don't lose is the money it earns.

End of Claude Code Subagents

Next: Hooks that auto-dispatch.

source: .claude/agents/order-execution-reviewer.md · docs/order-execution-playbook.md · docs/bug-log.md (BUG-170)
← → navigate · F fullscreen · click to advance
1 / 16