QuantDinger — Multi-Agent Runtime Environments (Design)¶

1. Background and goals¶

1.1 Background¶

When multiple coding agents and IDE assistants (Cursor, Claude Code, OpenAI Codex, CLI/sandbox bots) work in the same repository without shared conventions, teams often see:

• Agents re-reading a very long README, wasting context and misreading intent;
• Guessed HTTP paths and payloads that do not match the backend;
• Accidental touches to secrets, production databases, or money-adjacent paths;
• Per-tool documentation that drifts from the repo.

1.2 Goals¶

Without locking into a single vendor, make this repository stable and predictable for many agent environments:

1. Code collaboration — When changing strategies, fixing bugs, or adding APIs, agents can quickly find directories and verification commands.
2. Capability discovery — Humans and machines can learn what is allowed, what is forbidden, and how to validate changes.
3. Optional extensions — MCP, OpenAPI, and similar layers can be added later without replacing this structure.

1.3 Non-goals (explicit for this phase)¶

• Not every agent product must support MCP.
• No real secrets, internal-only URLs, or production credentials in design docs.
• No promise of fully unattended live trading in v1; live and capital flows stay behind human review and explicit strategy boundaries.

2. Design principles¶

3. Architecture — three layers¶

┌─────────────────────────────────────────────────────────────┐
│  Layer 1 — Documentation contract (humans + agents)         │
│  Repo map, red lines, recommended workflow, pointers to 2/3 │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  Layer 2 — Command contract (terminal / CI / CLI agents)    │
│  Stable scripts or Make: install, lint, test, docker compose │
└───────────────────────────┬─────────────────────────────────┘
                            │
┌───────────────────────────▼─────────────────────────────────┐
│  Layer 3 — Machine interfaces (HTTP / MCP, optional)        │
│  OpenAPI or equivalent schema; optional MCP tools (narrow)   │
└─────────────────────────────────────────────────────────────┘

3.1 Layer 1 — Documentation contract¶

Role: Any agent that can read repo text knows where to start and how to self-check without calling the network.

Suggested structure (may be split across files; one index is mandatory):

• Top-level directory roles (backend_api_python/, frontend/, docs/, scripts/).
• Indicator and strategy entry points (link to docs/trading/INDICATOR_DEV_GUIDE.md and docs/trading/STRATEGY_DEV_GUIDE.md — avoid duplicating long excerpts).
• Red lines — Never commit .env; never put secrets in docs or examples; money/live changes require human review.
• Happy path — e.g. “Python-only strategy change → how to bring up Docker → how to run backend tests” in 3–5 steps.

Relationship to the root README — README keeps user-facing install and product story; add a short “For coding agents” pointer to docs/agent/.

3.2 Layer 2 — Command contract¶

Role: Every action that should reproduce locally or in CI is exposed as a small set of stable commands, not ad-hoc shell one-liners.

Implementation choices (Make, npm scripts, invoke, etc.) are up to maintainers:

Constraint: One official entry per goal; if two spellings exist (docker-compose vs docker compose), document the recommended one and compatibility notes.

3.3 Layer 3 — Machine interfaces (optional evolution)¶

Role: When an agent or external tool must drive product behavior (health, listings, backtests), it must not rely on guessing HTTP.

• HTTP + OpenAPI (or equivalent) — Machine-consumable contract for REST; update the contract when routes change.
• MCP (Model Context Protocol) — Expose narrow, auditable operations as tools (e.g. read-only health, read-only strategy list). Write and trading tools need separate review and allowlists.

Principle: Layer 3 is additive; agents without MCP should still complete most code tasks via Layers 1 + 2.

4. Mapping to agent environments¶

Product names evolve; map by capability, not brand-only details.

Note: For specific products (e.g. OpenClaw, NanoBot), add one appendix row at rollout: product → config / protocol → which layer(s). No separate architecture fork.

5. Security and compliance boundaries¶

5.1 Data and secrets¶

• Keys, API tokens, and DB passwords come only from environment variables or local .env (and .env is gitignored).
• Design docs, agent rules, and AGENTS.md-style files must not contain real secrets or production connection strings; use placeholders in examples.

5.2 Capital and live trading¶

• Order placement, transfers, and exchange credential changes are not in unattended agent flows by default.
• If a subset is ever exposed via MCP, require auth, audit logs, rate limits, human toggles, and document in Layer 1.

5.3 Strategy code and multi-tenancy¶

• For multi-user deployments, distinguish platform core paths from user strategy / plugin paths so agents do not rewrite shared security logic.

6. Repository anchors (facts)¶

Keep implementation aligned with the current tree (update this section if layout changes):

7. Phased roadmap (suggested)¶

Phases are independently reviewable; P0 does not depend on P2/P3.

8. Document and file checklist (for implementation)¶

• [x] docs/agent/AGENT_ENVIRONMENT_DESIGN.md — this design (English SSOT).
• [x] .cursor/skills/quantdinger-agent-workflow/ — project Cursor skill (English) pointing agents here.
• [x] docs/agent/README.md — short Layer 1 index for docs/agent/.
• [ ] Root README.md — dedicated “For coding agents” subsection pointing to the index above.
• [ ] (Optional) Root AGENTS.md — industry-style filename; may forward to docs/agent/.
• [ ] (Optional) .cursor/rules/ — repo-specific terms and red lines only; avoid duplicating Layer 1 at length.
• [ ] Layer 2 — scripts/agent-*.sh or Makefile targets (names TBD at implementation).
• [ ] Layer 2 — Windows PowerShell + Bash notes (consistent with root README).
• [ ] P2/P3 — OpenAPI location, MCP package location (separate ADR acceptable).

9. Open questions (for review)¶

1. OpenAPI source — Generate static JSON from Flask at runtime, or generate in CI and commit? Tradeoff: drift vs build deps.
2. MCP packaging — Monorepo next to the API vs small standalone repo for MCP-only installs?

Resolved: Agent-facing documentation and project .cursor/skills/ are English only; human product docs may remain multilingual elsewhere in docs/.

10. Revision history¶