# Team Assembly Terminal — Implementation Spec **File:** `instructions.md` **Purpose:** Full product & engineering specification for AI agents (Claude Code, Gemini, Codex, etc.) to implement the Team Assembly Terminal feature in the Cymetica / EventTrader production environment. **Platform context:** https://cymetica.com/arena/how-it-works --- ## ⚠️ Critical Note for Implementing Agents **This spec describes a high-level UX workflow and product concept only.** You are the experts on what is already built in your codebase — assess that first and integrate accordingly. Key principles to follow: - **No mock or random data.** Any example values in this spec (bot names, PnL figures, percentages, epoch IDs) are illustrative only. The real implementation must use live data from the existing system at all times. - **Bots & Coaches** — load from the live agent system, the same data that powers https://cymetica.com/perpetual/agents/upside and https://cymetica.com/perpetual/agents/downside. Do not hardcode or invent agent data. - **Algos** — load from the existing algos/models system, same data as https://cymetica.com/adm. Reuse whatever data layer already serves that page. - **Skills** — load from the existing skills system, same data as https://cymetica.com/skills-n-tools. - **Backtest** — do not build a new backtest engine. The platform already has a backtest system implemented. Wire up this UI to the existing backtest infrastructure. - **General rule** — wherever this spec describes data or functionality, check whether it already exists in the codebase. If it does, reuse it. Only build what is genuinely new. This document provides the *desired user experience and data model*. You decide how to implement it using the real systems already in place. --- ## 1. Product Context **Platform:** EventTrader by Cymetica — a prediction market platform where AI bot teams compete on real-world economic headlines in 24-hour epochs. **Core loop (from the How It Works page):** 1. A **headline** drops (e.g., "Fed Cuts Interest Rates by 50 Basis Points") 2. Proprietary AI finds **hidden market connections** (assets affected by that headline) 3. Users **build a team** of cloned AI agents — one **Coach** (strategy manager) and a set of **Player Bots** (trade executors) 4. **Blue team** trades assets expected to go UP; **Red team** trades assets expected to go DOWN 5. Users trade **Bot Props** (over/under on individual bot performance) and build **parlays** 6. The epoch runs for 24 hours, bots trade live, winning team's shareholders get paid **The Team Assembly Terminal is the UI for step 3** — where users construct their team before entering an epoch. --- ## 2. Scope of This Feature Build a full-page route: `/arena/team-assembly` (or similar, follow existing routing conventions). The page is divided into **three resizable panels**: | Panel | Purpose | |-------|---------| | Left — NEXUS AI | Existing global AI chat, pinned to side | | Center — Main | Team construction workspace | | Right — Detail | Stats/detail for the selected bot | All three panels are **user-resizable** via drag handles between them (col-resize). **Routing & access:** - Requires an authenticated user — unauthenticated users should be redirected to login - The page should be reachable from the main Arena / epoch page via a "Build Team" or equivalent CTA - Paper trading is available to all authenticated users - Go Live mode requires a real trading-enabled account (apply whatever account-level guard already exists on the platform for live trading) --- ## 3. Left Panel — NEXUS AI Chat > ⚠️ **CRITICAL — Do NOT build a new chat component.** The NEXUS AI chat panel already exists as a **global floating/pinnable chat widget** present on all pages of the platform. When the user is on this page, that global chat should be **pinned to the left side** of the layout instead of floating. **Requirements:** - Reuse the existing NEXUS AI chat component — just render it pinned/docked in the left panel slot - The chat should be aware of the current page context (Team Assembly for this headline/epoch) so it can answer team-related questions - Example interactions the chat should support: - "What's the best setup for this headline?" - "Suggest a bot combination for a Fed rate cut" - "Which skills should I add to MULTI bot?" - When the AI suggests a combination, it should optionally **populate the Working Panel** automatically (this is the "NEXUS AI Intelligence" backtest mode described in Section 6) - The chat header shows: dot indicator + "NEXUS AI" label --- ## 4. Center Panel — Team Configuration ### 4.1 Page Header / Headline Bar At the top of the page (above the panels), a full-width **headline bar** shows the current epoch's headline: ``` ⚡ HEADLINE | Fed Cuts Interest Rates by 50 Basis Points | EPOCH #1,247 | 47:23 ``` - Headline text: pulled from the current active epoch - Epoch number: active epoch ID - Timer: countdown to epoch end (live countdown) - Background: subtle cyan-to-red gradient tint ### 4.2 Main Content Tabs Two tabs inside the center panel: | Tab | Label | Content | |-----|-------|---------| | 0 | ⚙ TEAM CONFIGURATION | Build a new team | | 1 | 📋 MY TEAMS | View/manage saved teams | --- ## 5. Tab 0 — Team Configuration ### 5.1 Team Formation Panel A panel showing the team structure being built: **Header row:** - Label: "TEAM FORMATION" - Side toggle: **↑ BLUE** / **↓ RED** — determines which side this team plays (affects which direction bots trade) - "SAVE TEAM" button (top right) **Coach Slot:** - Single slot labeled "COACH" - Empty state: dashed border, centered placeholder - Filled state: shows coach avatar (initial), name, strategy type, win %, Sharpe ratio - Remove button (✕) appears on hover **Player Row:** - Equal-width player slots labeled PLAYER 1, PLAYER 2, etc. - Empty state: dashed border - Filled state: avatar, bot ID, bot name, win rate - Remove button on hover Items are added to these slots via: 1. **Drag & drop** from the Roster below 2. **"↑ ADD TO TEAM" button** after selecting a bot in the Working Panel 3. **Clicking a roster card** to select it, then using the ADD TO TEAM button ### 5.2 Roster A tabbed card browser showing all available entities the user can add to their team. **Tabs:** - COACHES — AI coach agents (strategy managers) - BOTS — AI bot agents (trade executors / players) - SKILLS — modular skill modules that enhance bot behavior - ALGOS — algorithmic filters/confirmations **Each card shows:** - Icon avatar (initial letter, colored by type) - Short name / ID - Subtext (win %, type, or ticker symbol) **Card types and colors:** - Coach: cyan border/color - Bot: cyan border with inner glow - Skill: purple border/color - Algo: green border/color **Interaction:** - Click to select (highlights card, shows details in Right Panel) - Drag to drop into the Working Panel or Team Formation slots - Custom pointer-event drag (no HTML5 drag API) — ghost element follows cursor **Data sources:** - Coaches & Bots: from the existing agent system — same data that powers https://cymetica.com/perpetual/agents/upside and /downside - Skills: from the existing skills system — same data as https://cymetica.com/skills-n-tools - Algos: from the existing algos/models system — same data as https://cymetica.com/adm ### 5.3 Working Panel A staging area where the user assembles a **bot combination** before backtesting or adding to the team. Three drop zones arranged in a grid: | Zone | Accepts | Label | |------|---------|-------| | Left | Bot or Coach | BOT | | Center | Skill items | SKILLS & TOOLS | | Right | Algo items | ALGORITHMS | - Items can be dragged from the Roster directly into these zones - Skills and Algos zones accept **multiple items** (displayed as tags with ✕ remove) - BOT zone accepts **one item** at a time - "↑ ADD TO TEAM" button appears when a bot or coach is in the BOT zone — clicking it places the item in the next available Team Formation slot **Winner Banner:** - Shown (green bar) when NEXUS AI Intelligence mode finds a winning combination - Displays: "WINNER BOT COMBINATION · {APY}% APY" --- ## 6. Tab 0 — Backtest Section Below the Working Panel, a **Backtest** section lets users test their bot combination against historical data before committing. ### 6.1 Mode Toggle Two modes: 1. **MANUAL MODE** — user has manually selected a bot + skills + algos in Working Panel 2. **NEXUS AI INTELLIGENCE** — AI searches for the optimal bot combination automatically ### 6.2 Manual Mode Controls **Markets checkboxes (multi-select):** - Crypto - Stocks - Prediction Markets - WTA (Winner Takes All) **Period presets:** 7D / 30D / 90D / 6M / 1Y **Starting Capital:** numeric input (default $1,000) **Run button:** "▶ RUN BACKTEST" ### 6.3 NEXUS AI Intelligence Mode > The NEXUS AI system is planned as a separate feature (https://cymetica.com/feature/225). If you can access it, review it for context. If not, implement this section based on the spec below — this is the primary source of truth for the NEXUS AI Intelligence backtest flow. When AI mode is selected, additional controls appear: **NEXUS AI SEARCH group:** - Iterations: numeric input (1–50, default 10) — how many bot/skill/algo combinations the AI tries - Minimum % APY: numeric input — filter threshold **VAIX Balance display:** - Shows user's current VAIX token balance - Shows run cost: `iterations × 5 VAIX` - Each AI backtest iteration costs **5 VAIX** tokens **VAIX** is the platform's utility token. The AI Intelligence mode burns VAIX to run search iterations. If balance is insufficient, the run is blocked with an error message. **Run button:** "✦ RUN NEXUS AI BACKTEST" **After AI run completes:** - Working Panel is populated with the best found combination (bot + skill + algo) - Winner Banner shows the APY of the best combination - The roster area hides, replaced by the populated Working Panel result ### 6.4 Backtest Result Display After running (either mode), a result card appears with fade-in animation: ``` BOT BACKTEST RESULT 🎰 RESULT +$47.23 avg/epoch · 30D · 2 markets · $1,000 [sparkline chart — SVG line chart of PnL over time] Win: 68% Sharpe: 1.42 DD: -4.2% Trades: 127 ``` - PnL shown in green (profit) or red (loss) - Sparkline: SVG polyline, green or red gradient fill - Stats row: Win rate, Sharpe ratio, Max Drawdown, Trade count ### 6.5 Help Tooltip (? Button) A small circular `?` button in the top-right corner of the Backtest section. On click, a popover appears explaining what NEXUS AI Intelligence mode does. Clicking outside dismisses it. --- ## 7. Tab 1 — My Teams ### 7.1 Team List A list of the user's previously saved teams, shown as cards: Each card shows: - Team name - Side badge (BLUE / RED) - Avatar row (coach initial + player initials) - Quick stats: Win %, Sharpe, PnL Clicking a card selects it and shows its full details below. ### 7.2 Team Detail View Below the team list, the selected team is shown in the same **Team Formation** layout (coach slot + player row) in read-only view, with: - Edit button (pencil icon) — switches to editable Team Configuration - Delete button (trash icon) ### 7.3 Team Backtest A simplified backtest section scoped to the whole saved team (runs all bots together). There is **no Manual/AI mode toggle here** — just the market checkboxes, period presets, starting capital input, and a single "▶ RUN TEAM BACKTEST" button. Result shows combined team stats plus per-bot breakdown: ``` BOLT: +$68.20 RSI: +$52.40 STOCH: +$66.80 ``` ### 7.4 Deploy Panel At the bottom of the My Teams tab, the user can deploy the selected team to the current epoch. - The platform already has a global **Live / Paper switch** in the page header, present on all pages — the deploy action should respect that existing switch as the source of truth for the current trading mode - Do not build a separate Live/Paper toggle here — read the mode from the existing global header switch - Show the current deployment status of the selected team (not deployed / active on epoch / etc.) - A "DEPLOY" button deploys the team to the current epoch in whichever mode (Paper or Live) the global switch is currently set to --- ## 8. Right Panel — Detail View Context-sensitive detail panel that updates based on what the user has selected. Clicking any item in the Roster — bot, coach, skill, or algo — or selecting a saved team in My Teams populates this panel with the full detail of that item. The agent already knows what data each entity type carries and how it is best presented. The following are illustrative layout examples only — use them to understand the intent, not as a strict field specification: ### Bot / Coach example ``` VIEWING: MULTI-INDICATOR ENSEMBLE Win Rate: 71.3% Sharpe: 2.47 ⚙ Strategy Details Category: crypto Indicators: [RSI_14] [MACD_12_26_9] ... ``` ### Skill example ``` VIEWING: MOMENTUM FILTER Type: Signal Enhancement Category: Momentum ⚙ Skill Details Description: ... Compatible: ... ``` ### Algo example ``` VIEWING: RSI DIVERGENCE CONFIRM Type: Confirmation Filter Markets: Crypto · Stocks ⚙ Algo Details Description: ... Parameters: ... ``` ### Saved team example ``` VIEWING: RATE CUT ALPHA Team Roster: Coach + Players with win rates Historical Performance (sparkline) Win Rate · Sharpe · Avg PnL · Max DD ``` --- ## 9. Data Needs Use existing models where they already exist in the codebase. The feature needs to represent: - **Saved team** — a name, a side (Blue/Red), an assigned coach, a list of player bots, deployment status, and which epoch it is currently active on - **Agent reference** — identity, type (coach or bot), performance stats (win rate, Sharpe ratio), and a display initial for the avatar - **Working combination** — the bot currently staged in the Working Panel together with any selected skills and algos - **Backtest configuration** — mode (manual or AI), selected markets, time period, starting capital, and AI-specific parameters (iterations, minimum APY threshold) - **Backtest result** — average PnL, win rate, Sharpe ratio, max drawdown, trade count, equity curve data for the sparkline, and for AI mode the best found combination and its APY --- ## 10. Backend Requirements Reuse existing backend services wherever they already exist. Only add new endpoints where the functionality is genuinely absent. The page requires backend support for: - Fetching the current active epoch (headline, ID, countdown timer) - Listing available coaches, bots, skills, and algos from their respective existing systems - Fetching full detail for a selected agent - Running a manual backtest against the existing backtest engine - Running a NEXUS AI combination search (deducts VAIX from the user's balance) - Reading and writing the user's saved teams (list, create, update, delete) - Deploying a team to the current epoch - Reading the user's current VAIX token balance --- ## 11. UI Design System Build this feature to match the existing design language of the platform — use your current color tokens, typography, component styles, and spacing conventions. The color scheme is dark navy with cyan as the primary accent (Blue team), red for the opposing side (Red team), green for profit/positive states, and purple for AI/NEXUS elements. --- ## 12. Interaction Specifications ### Drag & Drop - Cards in the Roster can be dragged into the Working Panel zones and Team Formation slots - While dragging, a ghost preview of the item follows the cursor - Valid drop targets highlight visually when a compatible item is dragged over them - Each item type can only be dropped into compatible zones: - Coach/Bot → BOT zone in Working Panel, Coach slot or Player slots in Team Formation - Skill → SKILLS & TOOLS zone - Algo → ALGORITHMS zone - Dropping outside a valid target cancels the drag ### Panel Resizing - The three panels are separated by drag handles the user can pull to resize - The NEXUS AI panel and Detail panel have sensible minimum and maximum widths - The center panel fills the remaining space ### Roster Tabs - Four tabs: COACHES / BOTS / SKILLS / ALGOS - Only one tab's content is visible at a time - The active tab is visually distinguished with a cyan accent --- ## 13. NEXUS AI Intelligence Flow This is the key differentiator of the terminal. When the user switches to "NEXUS AI INTELLIGENCE" mode: 1. Manual Roster and Working Panel are hidden 2. AI config inputs appear: iterations, minimum APY, VAIX cost display 3. User clicks "✦ RUN NEXUS AI BACKTEST" 4. System deducts `iterations × 5 VAIX` from the user's VAIX balance 5. Backend runs AI search across all available bot/skill/algo combinations for the configured period and markets 6. Returns the **best performing combination** that meets the minimum APY threshold 7. Frontend: - Populates the Working Panel with the winning combination - Shows Winner Banner: "WINNER BOT COMBINATION · {X}% APY" - Displays backtest result card with the winning combo's stats - "↑ ADD TO TEAM" button becomes available to add the winning bot to Team Formation If VAIX balance is insufficient, show an error and do not proceed. --- ## 14. Out of Scope The following are part of the full platform but are out of scope for this feature — they are either already built or planned as separate work: - Bot Props trading (Step 4 in How It Works) - Parlay builder (Step 5) - Live epoch watching / real-time trade feed (Step 6) - Revenue collection / payout (Step 7) - Arena homepage with headline discovery (Step 1 & 2) This terminal covers **Step 3 only**: team construction, configuration, and backtesting. --- *End of spec. For platform context refer to https://cymetica.com/arena/how-it-works*