From b1667471c958b3f651336d879b41c32d2e1719c7 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Sat, 9 May 2026 20:28:28 -0700 Subject: [PATCH] =?UTF-8?q?chore(workflows):=20improve=20onboard-trading-p?= =?UTF-8?q?roduct=20=E2=80=94=20relative=20paths,=20push=20steps,=20idempo?= =?UTF-8?q?tency,=20git=20guards?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../workflows/onboard-trading-product.md | 179 +++++++++++------- 1 file changed, 115 insertions(+), 64 deletions(-) diff --git a/.windsurf/workflows/onboard-trading-product.md b/.windsurf/workflows/onboard-trading-product.md index b155c04..75fabcd 100644 --- a/.windsurf/workflows/onboard-trading-product.md +++ b/.windsurf/workflows/onboard-trading-product.md @@ -6,17 +6,39 @@ description: Onboard ByteLyst Trading into the common platform product registry Fully registers the `invttrdg` product in the ByteLyst ecosystem. Run this once to close the onboarding gap. -**Pre-requisites:** Both repos must be checked out as siblings: +**Idempotency:** Safe to re-run — file creates are upserts, commits skip if tree is clean, push is a no-op if already up-to-date. + +**Pre-requisites:** +- Both repos checked out as siblings under the same parent directory - `learning_ai_invt_trdg` (this repo) - `learning_ai_common_plat` (common platform) +- pnpm installed (`pnpm -v` works) + +**Path variables used below:** +``` +TRADING_ROOT = (this repo root — cwd for all relative commands) +COMMON_ROOT = ../learning_ai_common_plat +``` --- ## Phase 1 — Create the canonical product manifest in common platform -### 1. Create `products/invttrdg/product.json` in the common platform +### 1. Confirm common-plat repo is accessible -Create the file `../learning_ai_common_plat/products/invttrdg/product.json` with the full product manifest. The manifest MUST include all of the following sections derived from the trading repo's actual codebase: +// turbo + +```bash +ls ../learning_ai_common_plat/products/ | head -5 +``` + +Expect: Existing product directories listed (chronomind, efforise, etc.). If this fails, the sibling repo is not checked out. + +### 2. Create `products/invttrdg/product.json` in the common platform + +Create the file `../learning_ai_common_plat/products/invttrdg/product.json` with the full product manifest below. If the file already exists, verify it matches and update any missing fields. + +The manifest MUST include ALL of the following sections (derived from the trading repo's actual codebase): **Identity:** - `productId`: `"invttrdg"` @@ -31,7 +53,7 @@ Create the file `../learning_ai_common_plat/products/invttrdg/product.json` with - `primarySurface`: `"web"` - `mobileCompanion`: `true` -**Theme** (use the ByteLyst default palette — same as LysnrAI): +**Theme** (ByteLyst default brand palette): ```json { "primary": "#5AE68C", @@ -62,7 +84,7 @@ Create the file `../learning_ai_common_plat/products/invttrdg/product.json` with } ``` -**Cosmos containers** (13 containers, derived from actual backend repository constants): +**Cosmos containers** (13 containers from backend repository constants): ```json { "containers": [ @@ -107,42 +129,46 @@ Create the file `../learning_ai_common_plat/products/invttrdg/product.json` with - `envVarPrefix`: `"TRADING"` - `packageName`: `"bytelyst-trading"` -### 2. Verify the manifest validates against the ProductManifest Zod schema +### 3. Spot-check the manifest completeness // turbo ```bash -cd /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat && node -e " +node -e " const fs = require('fs'); - const raw = fs.readFileSync('products/invttrdg/product.json', 'utf-8'); + const raw = fs.readFileSync('../learning_ai_common_plat/products/invttrdg/product.json', 'utf-8'); const json = JSON.parse(raw); - console.log('productId:', json.productId); - console.log('displayName:', json.displayName); - console.log('containers:', json.cosmos?.containers?.length || 0); - console.log('flags:', json.flags?.length || 0); - console.log('features:', Object.keys(json.features || {}).length); - console.log('theme keys:', Object.keys(json.theme || {}).length); - console.log('ports:', JSON.stringify(json.ports)); - console.log('✅ Manifest looks complete'); + const checks = [ + ['productId=invttrdg', json.productId === 'invttrdg'], + ['displayName', json.displayName === 'ByteLyst Trading'], + ['containers>=13', (json.cosmos?.containers?.length || 0) >= 13], + ['flags>=4', (json.flags?.length || 0) >= 4], + ['features>=10', Object.keys(json.features || {}).length >= 10], + ['theme=9keys', Object.keys(json.theme || {}).length === 9], + ['ports.service=4018', json.ports?.service === 4018], + ]; + checks.forEach(([k, ok]) => console.log(ok ? '✅' : '❌', k)); + if (!checks.every(([, ok]) => ok)) process.exit(1); + console.log('All manifest checks passed'); " ``` -Expect: productId=invttrdg, 13 containers, 4 flags, 10 features, 9 theme keys, ports with service=4018. +Expect: All ✅. If any ❌, go back to Step 2 and fix the missing field. --- ## Phase 2 — Enrich the trading repo's local product.json -### 3. Update `shared/product.json` in the trading repo +### 4. Update `shared/product.json` in the trading repo -Sync the trading repo's `shared/product.json` to match the canonical manifest created in Step 1. Add the missing `theme`, `cosmos`, `flags`, `features`, and `ports` sections. Keep `id` as an alias for `productId` if it already exists. +Sync `shared/product.json` to match the canonical manifest from Step 2. Add the missing `theme`, `cosmos`, `flags`, `features`, and `ports` sections. Preserve the existing `productId`, `displayName`, `bundleId`, `platforms`, `licensePrefix`, `configDirName`, `envVarPrefix`, `packageName` fields. -### 4. Verify the updated local manifest +### 5. Verify the updated local manifest // turbo ```bash -cd /Users/saravana/BytelystAI/learning_ai/learning_ai_invt_trdg && node -e " +node -e " const fs = require('fs'); const raw = fs.readFileSync('shared/product.json', 'utf-8'); const json = JSON.parse(raw); @@ -155,8 +181,8 @@ cd /Users/saravana/BytelystAI/learning_ai/learning_ai_invt_trdg && node -e " ['ports', json.ports?.service === 4018], ]; checks.forEach(([k, ok]) => console.log(ok ? '✅' : '❌', k)); - if (checks.every(([, ok]) => ok)) console.log('All checks passed'); - else { console.error('Some checks failed'); process.exit(1); } + if (!checks.every(([, ok]) => ok)) { console.error('FAILED'); process.exit(1); } + console.log('Local manifest complete'); " ``` @@ -164,81 +190,105 @@ cd /Users/saravana/BytelystAI/learning_ai/learning_ai_invt_trdg && node -e " ## Phase 3 — Generate AGENTS.md for the trading repo -### 5. Generate AGENTS.md +### 6. Generate AGENTS.md -Create `AGENTS.md` in the trading repo root. Follow the same structure as other ByteLyst product repos (MindLyst, ChronoMind, NoteLett). The AGENTS.md must include: +Create `AGENTS.md` in the trading repo root. Use the same structure as other ByteLyst product repos (`../learning_ai_common_plat/products/` siblings like ChronoMind, NoteLett). The file MUST include these sections: -- Project overview (ByteLyst Trading — AI-assisted trading operations) -- Repo layout tree (backend/, web/, mobile/, shared/, scripts/, docs/) -- Tech stack table (Fastify 5 backend, Vite + React web, Expo mobile) -- Critical rules (productId, Cosmos conventions, commit format, code style) -- Build & run commands (`pnpm build`, `pnpm test`, `pnpm typecheck`, `pnpm verify`) -- Coding conventions (MUST follow / MUST NOT do) +1. **Project Identity table** — productId, displayName, bundleIds, domain, ecosystem, runtime, package manager, test runner +2. **Repo Layout** — accurate tree of `backend/`, `web/`, `mobile/`, `shared/`, `scripts/`, `docs/`, `vendor/` +3. **Tech Stack table** — Fastify 5 + TypeScript ESM backend (port 4018), Vite + React 19 + TailwindCSS web, React Native + Expo mobile +4. **Coding Conventions** — MUST follow: productId in every Cosmos doc, commit format `type(scope): description`, `req.log`/`app.log` never `console.log`, ESM everywhere +5. **Build & Run Commands** — `pnpm build`, `pnpm test`, `pnpm typecheck`, `pnpm verify`, `pnpm dev`, `docker compose up` +6. **Critical Rules** — MUST NOT: hardcode colors, use npm, modify tests to make them pass, delete comments -Scan the actual repo structure to populate the layout tree accurately. Reference: -- `backend/src/` modules and services -- `web/src/` components, views, backtest, assets -- `mobile/` app, components, store -- `shared/` product.json, feature-flags.ts, control-plane.ts, platform-clients.ts +Scan the actual repo with `find` and `ls` to populate the layout tree accurately rather than guessing. Key directories to document: +- `backend/src/config/`, `backend/src/connectors/`, `backend/src/domain/`, `backend/src/services/`, `backend/src/strategies/`, `backend/src/backtest/` +- `web/src/components/`, `web/src/views/`, `web/src/backtest/`, `web/src/assets/` +- `mobile/app/`, `mobile/components/`, `mobile/services/` +- `shared/` — product.json, feature-flags.ts, control-plane.ts, platform-clients.ts, backend-control-config.ts -### 6. Verify AGENTS.md exists and has minimum content +### 7. Verify AGENTS.md exists and has minimum content // turbo ```bash -cd /Users/saravana/BytelystAI/learning_ai/learning_ai_invt_trdg && wc -l AGENTS.md && head -5 AGENTS.md +test -f AGENTS.md && echo "✅ AGENTS.md exists ($(wc -l < AGENTS.md) lines)" || echo "❌ AGENTS.md missing" +head -3 AGENTS.md ``` -Expect: File exists with 100+ lines. First line should be `# AGENTS.md`. +Expect: File exists with 100+ lines. First line contains `# AGENTS.md`. --- ## Phase 4 — Update common platform ecosystem references -### 7. Add trading to the common platform AGENTS.md product consumer list +### 8. Add trading to the common platform AGENTS.md product consumer list -In `../learning_ai_common_plat/AGENTS.md`, find the `Product consumers` row in the Project Identity table and add `[ByteLyst Trading](../learning_ai_invt_trdg)` to the list. +In `../learning_ai_common_plat/AGENTS.md`, locate the `Product consumers` row in the Project Identity table and append `[ByteLyst Trading](../learning_ai_invt_trdg)` to the comma-separated list. -### 8. Verify the AGENTS.md update +### 9. Verify the common platform AGENTS.md update // turbo ```bash -grep -c 'learning_ai_invt_trdg\|ByteLyst Trading\|invttrdg' /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/AGENTS.md +grep -c 'learning_ai_invt_trdg\|ByteLyst Trading' ../learning_ai_common_plat/AGENTS.md ``` -Expect: At least 1 match. +Expect: At least 1 match. If 0, Step 8 was not applied correctly. --- -## Phase 5 — Commit and verify +## Phase 5 — Commit, verify, and push -### 9. Commit the common platform changes - -```bash -cd /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat && git add products/invttrdg/product.json AGENTS.md && git commit -m "feat(products): onboard ByteLyst Trading (invttrdg) into product registry" -``` - -### 10. Commit the trading repo changes - -```bash -cd /Users/saravana/BytelystAI/learning_ai/learning_ai_invt_trdg && git add shared/product.json AGENTS.md && git commit -m "feat(onboard): add full product manifest and AGENTS.md" -``` - -### 11. Run trading repo verification +### 10. Check for unrelated uncommitted changes in both repos // turbo ```bash -cd /Users/saravana/BytelystAI/learning_ai/learning_ai_invt_trdg && pnpm typecheck +echo "=== Trading repo ===" && git status --short +echo "=== Common platform ===" && git -C ../learning_ai_common_plat status --short ``` -### 12. Final ecosystem check — verify all 9 products exist +Review output. If there are unrelated changes, stash or commit them separately before proceeding. + +### 11. Commit the common platform changes + +```bash +cd ../learning_ai_common_plat && git add products/invttrdg/product.json AGENTS.md && git commit -m "feat(products): onboard ByteLyst Trading (invttrdg) into product registry" +``` + +### 12. Commit the trading repo changes + +```bash +git add shared/product.json AGENTS.md && git commit -m "feat(onboard): add full product manifest and AGENTS.md" +``` + +### 13. Run trading repo typecheck // turbo ```bash -ls -1 /Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/products/ | sort +pnpm typecheck +``` + +Expect: Exit 0. If it fails, fix the issue before pushing. + +### 14. Push both repos + +```bash +git push origin main +``` + +```bash +cd ../learning_ai_common_plat && git push origin main +``` + +### 15. Final ecosystem check — verify all 9 products exist + +// turbo + +```bash +echo "Products in registry:" && ls -1 ../learning_ai_common_plat/products/ | sort ``` Expect: 9 directories — chronomind, efforise, invttrdg, jarvisjr, lysnrai, mindlyst, nomgap, notelett, peakpulse. @@ -248,9 +298,10 @@ Expect: 9 directories — chronomind, efforise, invttrdg, jarvisjr, lysnrai, min ## Completion Checklist After all steps pass: -- [ ] `products/invttrdg/product.json` exists in common platform with full schema +- [ ] `products/invttrdg/product.json` exists in common platform with full schema (13 containers, 4 flags, 10 features, 9 theme keys, ports) - [ ] `shared/product.json` in trading repo enriched with theme, cosmos, flags, features, ports -- [ ] `AGENTS.md` exists in trading repo root +- [ ] `AGENTS.md` exists in trading repo root (100+ lines) - [ ] Common platform `AGENTS.md` lists ByteLyst Trading as a product consumer -- [ ] Both repos committed cleanly +- [ ] Both repos committed and pushed cleanly - [ ] `pnpm typecheck` passes in trading repo +- [ ] 9 total products visible in `products/` directory