json-firs-fnnc-cli-patt

JSON-first Financial CLI Patterns

Applicable:

• External financial CLI / trading CLI / paper trading CLI evaluation
• Absorb the exchange CLI's agent contract, rather than directly connecting to live trading
• Design a json-first adapter, stable error taxonomy, and paper-first workflow for ict-engine / Hermes

Not applicable:

• Directly placing real orders
• Blindly trusting live-trading integration based on the README

Core principles

1. Security review first, then functionality.
2. Absorb the "agent contract" by default, do not absorb "live execution" by default.
3. Prioritize extracting:
   • JSON-first subprocess contract
   • stable error categories
   • paper/sim before live
   • machine-readable tool catalog
   • workflow skill/recipe packaging
4. If a tool can touch real funds, accounts, withdrawals, or leverage: treat it as high risk.

Absorption checklist

1. JSON-first subprocess contract

Goal: stdout contains only structured payload; stderr contains only diagnostics; exit codes express success/failure.

Recommended pattern:

somecli <command> ... -o json 2>/dev/null

Requirements:

• success -> stdout valid JSON
• failure -> stdout JSON error envelope
• exit code 0 success, non-zero failure
• Do not route based on human-facing prompt text

2. Stable error taxonomy

Extract at least into stable categories:

• api
• auth
• network
• rate_limit
• validation
• config
• io
• parse

Rules:

• Routing looks at category, not message wording
• retry is only enabled for explicitly retryable categories

3. Paper-first workflow

If an external tool has both live and paper/sim sides:

• Default to paper first
• Any live path requires additional confirmation and permission isolation
• In a research system, paper/sim is first-class, not an auxiliary script

4. Machine-readable tool contract

Prioritize looking for:

• tool-catalog.json
• error-catalog.json
• CONTEXT.md
• AGENTS.md
• CLAUDE.md

Absorption purpose:

• Parameter schema
• dangerous flags
• auth requirements
• output contracts
• retry guidance

5. Workflow skills / recipes

If upstream has already packaged multi-step processes into skills/recipes:

• Extract workflow boundary
• Extract safety boundary
• Extract reusable sequence
• Do not blindly port the trading strategy itself

Implementation recommendations for ict-engine

Prioritized absorbable surfaces:

1. Unify the JSON envelope of external market-data / exchange adapters
2. Unify adapter error classification
3. Symmetrize paper/backtest/sim with any future live path
4. Package common research flows as skills/prompts, rather than just piling up CLI flags
5. If a tool catalog is exposed in the future, make it a machine-readable catalog

Not recommended for default absorption:

• live order execution
• withdrawal / transfer / staking
• shared MCP trading server
• Any dangerous command without explicit user approval

Evaluation conclusion template

• Verdict: learn / absorb / install / reject
• Absorb:
  • json contract
  • error taxonomy
  • paper-first symmetry
  • skill packaging
• Reject:
  • unsafe live automation by default

Artifact recommendations

If the task hits repo/documentation absorption:

• Write a repo docs note
• Write an architecture boundary rule
• Only do actual live integration when the user explicitly requests it