Skip to main content

​
sequency-app — Agent Instructions

GitHub: sequencyhq/sequency-app Primary local guide: CLAUDE.md in this directory (zero-mock policy, data architecture, API proxy pattern). Parent product map: ../AGENTS.md, ../CLAUDE.md. Threat model: ../THREATMODEL.md when touching auth, broker, or secrets. This file adds Grok-oriented conventions, design system truth, and cross-repo boundaries.

​
Mission

Next.js UI for opportunity discovery, stock/options workspaces, research/lab, trade flows, and agent surfaces. All market truth comes from sequency-data (FastAPI + streams) — never mock, never call Alpaca from Next routes.

​
Stack

  • Next.js App Router (app/), React, TypeScript
  • Vitest for unit/component tests (not Jest)
  • Design tokens: styles/design-tokens.css + Paper Terminal v2
  • Deploy: Vercel (frontend); data plane remains OVH

​
Absolute rules

  1. Zero mock financial data — show No Data / Unavailable / retry, never placeholders that look real.
  2. Proxy only — Frontend → /api/* → WORKER_API_URL (worker.sequency.sh) → FastAPI.
  3. Never hardcode hex for product UI — use tokens. Accent = indigo/periwinkle; emerald = marketing only; green in-app only for gain/profit.
  4. Design before new pages — Paper Terminal composition contracts; render every designed element or an explicit empty state.
  5. react-query v5: failureCount resets at the start of every poll — use monotonic errorUpdateCount for cross-poll failure thresholds (app#441).

​
Design system (canonical)

Layout: center content on wide screens (floated margin-inline), data tables full-width. Tabular nums; glow = focal-only.

​
Routes (post strategies-tree removal)

Prefer: /lab, /trade/[symbol], /research, /ops (and stock/options workspaces). Canonical product docs for new specs: docs/ (and documentation/ for historical API notes).

​
Verification

Pretest/prebuild may regenerate Conviction tiers — generated output must be clean or explained. Vitest + @vitejs/plugin-react can hang in symlinked worktrees — use isolated config if needed.

​
Cross-repo

Contract changes land in data first; app adapts. One PR per repo.

​
Worktrees

If this root is dirty, create ~/projects/sequency/.worktrees/app-<topic> from the intended base. Do not mix unrelated feature packets.

​
Issues

gh issue create -R sequencyhq/sequency-app for frontend-only work.

​
Pattern corpus / DSOM awareness (added 2026-08-05)

  1. DSOM governs pattern/setup/signal/proposal/execution work — data/docs/superpowers/specs/2026-08-04-decision-support-object-model.md (five objects: Observation→Setup→Signal→Proposal→Execution). Read it before touching any of those.
  2. OA-13 dual-key: lifecycle_id = Setup identity, event_id = confirmation fact (NULL on prospects). OA-14: the word “revision” is banned — three named refs replace it. OA-15: “Evidence Envelope” is the semantic name for the existing Decision Lens wire object; chart_contracts.Observation remains the documented legacy wire name (no breaking rename).
  3. Chart geometry/levels come only from GET /pattern-events/symbol/{symbol}/insights (corpus-backed, CT-01). The legacy AI-trendline analyze path is gone in-app (app #503). No drawn/actionable chart price may ever originate from an LLM — standing invariant, security-review-verified.
  4. Data-repo Python: lint via scripts/lint-api.sh ONLY (CI-pinned ruff 0.16.0; venv ruff lies). api-lint is a required check; after merging to data main, verify the deploy run, not just PR checks — merged ≠ deployed.
  5. Pattern-catalogue work is governed by epic data#1654 (production-readiness spec data/docs/superpowers/specs/2026-08-07-geometric-detection-production-readiness.md). Class A construction is AUTHORIZED in tranches under the ratified classification pass (2026-08-06-class-a-adj2-classification-pass.md) + OQ-PDE-002 discipline — but nothing persists _shape facts until the feature substrate exists (data#1634), contextual shapes are gated on AC-CTX (data#1588), and every new detector lands with its OQ cases. Classes B–G need their own ratified classification passes first.
  6. Screener filters fail closed — build requests with registry ids; an unsupported leaf returns 422 unsupported_filter, never a silent drop.