QuantDinger agent workflow
When this applies
Use this skill whenever you change code or docs under this repository as a coding agent (Cursor, Claude Code, Codex, or similar), especially:
backend_api_python/ (Flask API, services, routes)
- Strategy / backtest / trading-adjacent logic
docker-compose.yml, scripts/, env.example
docs/agent/ (keep English only)
Read first
docs/agent/AGENT_ENVIRONMENT_DESIGN.md - SSOT for three layers: documentation contract -> command contract -> optional HTTP/MCP.
docs/agent/AI_INTEGRATION_DESIGN.md - How external AI agents consume QuantDinger as a product (Agent Gateway, scopes, MCP, trading safety). Read this before adding any new endpoint or tool that an AI agent might call.
docs/agent/AGENT_QUICKSTART.md - Operator/integrator walkthrough; mirrors the implemented /api/agent/v1 surface.
docs/agent/agent-openapi.json - Machine-readable contract; update it whenever you add or change an /api/agent/v1/... route.
docs/agent/README.md - Index of agent-facing docs.
Implemented surface (truth)
The Agent Gateway is mounted at /api/agent/v1 by app/routes/agent_v1/.
- Auth:
app/utils/agent_auth.py (@agent_required(scope=...)). Tokens are
hashed at rest in qd_agent_tokens; never log or persist the raw token.
- Async jobs:
app/utils/agent_jobs.py writes to qd_agent_jobs; backtests
and experiment pipelines submit here and clients poll /jobs/{id} or
subscribe to GET /jobs/{id}/stream (SSE: snapshot / progress /
ping / result). Long-running runners can opt in by adding a second
positional on_progress parameter. submit_job will detect it and pipe
events to live SSE subscribers AND persist the latest snapshot.
- Audit: every call (success and denial) is appended to
qd_agent_audit.
- Trading:
quick_trade.py enforces paper-only by default; live execution
requires both paper_only=false on the token AND env
AGENT_LIVE_TRADING_ENABLED=true. Do not weaken this without explicit ask.
- MCP:
mcp_server/ is a thin Python wrapper over R + W + B endpoints (no
trading), with three transports selected by QUANTDINGER_MCP_TRANSPORT: stdio (default,
desktop IDEs), sse, and streamable-http (cloud agents / remote IDEs;
also bind QUANTDINGER_MCP_HOST / QUANTDINGER_MCP_PORT). Add new tools
there only after exposing the underlying capability via REST.
- Admin UI: the Vue project at
QuantDinger-Vue-src/ ships Profile -> My Agent Token
for every logged-in user (src/views/profile/components/ProfileAgentTokens.vue,
API /api/agent/v1/me/tokens). Admins retain /agent-tokens for audit.
API client lives in src/api/agent.js.
Do not treat the marketing-heavy root README.md as the only onboarding doc; use it for user install paths and link out.
Red Lines
- Never commit real secrets, production
.env, API keys, or DB passwords. Use env.example patterns and placeholders in examples.
- Do not add live trading or order placement automation that bypasses human review unless explicitly requested and scoped.
- Prefer linking to
docs/STRATEGY_DEV_GUIDE*.md over duplicating long strategy guide text inside agent-only docs.
Repository Anchors
| Area |
Path |
| Backend |
backend_api_python/ |
| Frontend (prebuilt UI) |
frontend/ |
| Compose stack |
docker-compose.yml, scripts/ |
| Strategy guides |
docs/STRATEGY_DEV_GUIDE.md (and localized variants) |
Verification
- Backend tests live in
backend_api_python/tests/; run with python -m pytest tests/ -q from backend_api_python/.
- Agent Gateway tests:
tests/test_agent_v1.py (token auth, scopes, rate limit, generator format).
- For human stack changes, follow the Docker Compose flow already documented in the root
README.md (PowerShell or Bash).
Language
All new agent-facing prose (this skill, docs/agent/*) must be English so the same material works across locales and tools.
1---2name: quantdinger-agent-workflow3description: >-4 QuantDinger repo workflow for coding agents: layered contracts, safety5 boundaries, and where backend, strategies, and Docker live. Use when editing6 Python API, strategies, deployment, or docs/agent.7metadata:8 source: https://skillmd.com/skills/openbyteinc/quantdinger-agent-workflow9---1011# QuantDinger agent workflow1213## When this applies1415Use this skill whenever you change code or docs under this repository as a **coding agent** (Cursor, Claude Code, Codex, or similar), especially:1617- `backend_api_python/` (Flask API, services, routes)18- Strategy / backtest / trading-adjacent logic19- `docker-compose.yml`, `scripts/`, `env.example`20- `docs/agent/` (keep **English only**)2122## Read first23241. **`docs/agent/AGENT_ENVIRONMENT_DESIGN.md`** - SSOT for three layers: documentation contract -> command contract -> optional HTTP/MCP.252. **`docs/agent/AI_INTEGRATION_DESIGN.md`** - How external AI agents consume QuantDinger as a product (Agent Gateway, scopes, MCP, trading safety). Read this **before** adding any new endpoint or tool that an AI agent might call.263. **`docs/agent/AGENT_QUICKSTART.md`** - Operator/integrator walkthrough; mirrors the implemented `/api/agent/v1` surface.274. **`docs/agent/agent-openapi.json`** - Machine-readable contract; update it whenever you add or change an `/api/agent/v1/...` route.285. **`docs/agent/README.md`** - Index of agent-facing docs.2930## Implemented surface (truth)3132The Agent Gateway is mounted at **`/api/agent/v1`** by `app/routes/agent_v1/`.3334- Auth: `app/utils/agent_auth.py` (`@agent_required(scope=...)`). Tokens are35 hashed at rest in `qd_agent_tokens`; never log or persist the raw token.36- Async jobs: `app/utils/agent_jobs.py` writes to `qd_agent_jobs`; backtests37 and experiment pipelines submit here and clients poll `/jobs/{id}` or38 subscribe to **`GET /jobs/{id}/stream`** (SSE: `snapshot` / `progress` /39 `ping` / `result`). Long-running runners can opt in by adding a second40 positional `on_progress` parameter. `submit_job` will detect it and pipe41 events to live SSE subscribers AND persist the latest snapshot.42- Audit: every call (success **and** denial) is appended to `qd_agent_audit`.43- Trading: `quick_trade.py` enforces paper-only by default; live execution44 requires both `paper_only=false` on the token AND env45 `AGENT_LIVE_TRADING_ENABLED=true`. Do not weaken this without explicit ask.46- MCP: `mcp_server/` is a thin Python wrapper over R + W + B endpoints (no47 trading), with three transports selected by `QUANTDINGER_MCP_TRANSPORT`: `stdio` (default,48 desktop IDEs), `sse`, and `streamable-http` (cloud agents / remote IDEs;49 also bind `QUANTDINGER_MCP_HOST` / `QUANTDINGER_MCP_PORT`). Add new tools50 there only after exposing the underlying capability via REST.51- Admin UI: the Vue project at `QuantDinger-Vue-src/` ships **Profile -> My Agent Token**52 for every logged-in user (`src/views/profile/components/ProfileAgentTokens.vue`,53 API `/api/agent/v1/me/tokens`). Admins retain `/agent-tokens` for audit.54 API client lives in `src/api/agent.js`.5556Do not treat the marketing-heavy root `README.md` as the only onboarding doc; use it for user install paths and link out.5758## Red Lines5960- Never commit real **secrets**, production **`.env`**, API keys, or DB passwords. Use `env.example` patterns and placeholders in examples.61- Do not add **live trading** or **order placement** automation that bypasses human review unless explicitly requested and scoped.62- Prefer **linking** to `docs/STRATEGY_DEV_GUIDE*.md` over duplicating long strategy guide text inside agent-only docs.6364## Repository Anchors6566| Area | Path |67|------|------|68| Backend | `backend_api_python/` |69| Frontend (prebuilt UI) | `frontend/` |70| Compose stack | `docker-compose.yml`, `scripts/` |71| Strategy guides | `docs/STRATEGY_DEV_GUIDE.md` (and localized variants) |7273## Verification7475- Backend tests live in `backend_api_python/tests/`; run with `python -m pytest tests/ -q` from `backend_api_python/`.76- Agent Gateway tests: `tests/test_agent_v1.py` (token auth, scopes, rate limit, generator format).77- For human stack changes, follow the Docker Compose flow already documented in the root `README.md` (PowerShell or Bash).7879## Language8081All **new** agent-facing prose (this skill, `docs/agent/*`) must be **English** so the same material works across locales and tools.