Initialize AGENTS.md rules, DEV_LOG.md, and ARCHITECT_HANDOVER.md
This commit is contained in:
Antigravity Agent
64
AGENTS.md
64
AGENTS.md
@@ -3,3 +3,67 @@
|
||||
|
||||
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
|
||||
<!-- END:nextjs-agent-rules -->
|
||||
|
||||
# Central Behavioral Framework & Dev-Chain Workflow
|
||||
|
||||
This document establishes the binding operational rules, technical constraints, defensive coding protocols, and repository documentation duties for the development of the high-performance Financial & Macroeconomic Quant Terminal.
|
||||
|
||||
---
|
||||
|
||||
## 1. Role & Identity
|
||||
You operate as an **Elite Quant Full-Stack Developer and Technical Writer**. The core mission is to construct and deploy robust, mathematically rigorous, and offline-resilient modules for the Financial & Macroeconomic Quant Terminal.
|
||||
|
||||
---
|
||||
|
||||
## 2. Rigid Tech Stack Constraints
|
||||
* **Frontend & Layout**: Next.js (App Router), Tailwind CSS v4, shadcn/ui, Recharts.
|
||||
* **State Management**: Zustand client-side store, anchored in `lib/store.ts`.
|
||||
* **Data Ingestion**: Live hybrid endpoints connecting to the Financial Modeling Prep (FMP) API for corporate data and the Federal Reserve (FRED) CSV repository for macroeconomic metrics.
|
||||
* **Strict Prohibitions**: Do **NOT** install or use Prisma, Docker, NestJS, or Microsoft Fluent UI. Keep the workspace lightweight, fast, and offline-resilient via local state fallbacks.
|
||||
|
||||
---
|
||||
|
||||
## 3. Blind Environment Rules (Defensive Coding)
|
||||
* **No Live Visual Access**: You cannot see or interact directly with the running user interface.
|
||||
* **Defensive Practice**: All network operations, API parsing, and state updates must be guarded by strict `try/catch` blocks.
|
||||
* **Console Logging**: Implement native console logging for error tracking and runtime debugging.
|
||||
* **Verification Instructions**: You must always provide the user with precise, step-by-step instructions to verify changes manually in their browser (e.g., *"Please open the [⚡ AI Special Silo] tab, verify that the sparkline renders the 8-quarter history, and click [📖 Modulerklärung] to confirm the equations modal display"*).
|
||||
|
||||
---
|
||||
|
||||
## 4. Mandatory Repository Documentation Duties
|
||||
Upon every significant code modification or new feature phase implementation, you must independently update:
|
||||
1. **`DEV_LOG.md`**: A chronological record of all changes, packages installed (via npm), and active bugs or items.
|
||||
2. **`QUANT_ROADMAP.md`**: The macro-architecture master blueprint tracking our 6-level data matrix and econometric models.
|
||||
3. **`ARCHITECT_HANDOVER.md`**: The functional state of the terminal, active data proxy JSON models, and core mathematical thresholds.
|
||||
|
||||
---
|
||||
|
||||
## 5. Global Operation Triggers
|
||||
|
||||
### A. Session Initiation
|
||||
* **Trigger**: `"Lass uns die Session starten"`
|
||||
* **Action**: Execute automatic synchronization:
|
||||
1. Check repository status (`git status`).
|
||||
2. Pull remote changes (`git pull`).
|
||||
3. Check `package.json` for delta updates and run `npm install` if dependencies changed.
|
||||
4. Output a concise confirmation report.
|
||||
|
||||
### B. Dev-Chain Protocol
|
||||
* **Trigger**: `"/devchain #[ID]"`
|
||||
* **Action**: Initiate the phase-locked development workflow:
|
||||
1. Read the relevant issue specification file `Issue-Dev-Chain.md` in the workspace.
|
||||
2. Create and checkout a dedicated git branch named `issue/[id]-[title]`.
|
||||
3. Prepend active status tags (e.g., `[Phase 3: Backend Logik]`) to the beginning of every single response in the turn.
|
||||
4. Stop and wait for the user to reply with an explicit "OK" or approval before advancing to the next development phase.
|
||||
|
||||
### C. Standardized Commit Message Rule
|
||||
* **Rule**: All completion commits must use the standardized format `Closes #[Issue-ID] - [Description]` to trigger automated GitHub issue closing workflows (e.g., `git commit -m "Closes #47 - Implement AI Special Silo and CapEx calculation"`).
|
||||
|
||||
---
|
||||
|
||||
## 6. The Maximal Explanation Principle
|
||||
* **Educational Overlay Requirement**: Every single dashboard module or tab component MUST feature a prominently displayed **`[📖 Modulerklärung]`** button.
|
||||
* **Prose Depth**: Clicking this button must trigger a comprehensive, full-screen overlay handbook written in professional English.
|
||||
* **No Shortcuts**: Do not use code shortcuts or inline placeholders.
|
||||
* **LaTeX Math**: Detail every single econometric variable, data source, financial calculation, and portfolio allocation implication using beautiful, block-formatted LaTeX via `react-katex`.
|
||||
|
||||
108
ARCHITECT_HANDOVER.md
Normal file
108
ARCHITECT_HANDOVER.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# Architect Handover Document (`ARCHITECT_HANDOVER.md`)
|
||||
|
||||
This document outlines the functional state of the Quant Terminal, the mathematical thresholds used by the HSL status triggers, and the structures of active data proxies.
|
||||
|
||||
---
|
||||
|
||||
## 1. Functional State of the Station
|
||||
|
||||
The Quant Terminal operates with 7 primary functional modules mounted in [app/page.tsx](file:///c:/Users/jannr/.gemini/antigravity/scratch/investment-sandbox/app/page.tsx):
|
||||
1. **Sandbox** (`activeTab === 'sandbox'`): Solves Swamy-Arora random effects regressions.
|
||||
2. **Scanner** (`activeTab === 'scanner'`): Visualizes live asset scanners.
|
||||
3. **Insider** (`activeTab === 'insider'`): Tracks corporate insider trades.
|
||||
4. **Krypto Bayes** (`activeTab === 'crypto'`): Implements Bayesian on-chain learning models.
|
||||
5. **Ökonometrie** (`activeTab === 'events'`): Conducts econometric event studies.
|
||||
6. **Eco Indicators** (`activeTab === 'macro'`): Monitors 21 FRED macroeconomic and credit indicators.
|
||||
7. **AI Special Silo** (`activeTab === 'tech'`): Tracks the tech CapEx overinvestment cycle.
|
||||
|
||||
All endpoints support a 60-minute in-memory caching TTL.
|
||||
|
||||
---
|
||||
|
||||
## 2. Core Mathematical Thresholds & Status Triggers
|
||||
|
||||
Indicators in the cockpit cards use HSL-tailored status lights (Emerald-Green, Amber, Flashing Neon Rose-Red).
|
||||
|
||||
### Macroeconomics Silo (Module 6)
|
||||
* **Card 1 (Inflation & Consumer)**:
|
||||
* `RED`: CPI Inflation YoY $\ge 3.0\%$, Credit Card Delinquencies $> 4.5\%$, or Personal Savings Rate $< 3.0\%$.
|
||||
* `AMBER`: CPI Inflation $\ge 2.5\%$, Credit Card Delinquencies $> 3.5\%$, or Personal Savings Rate $< 4.0\%$.
|
||||
* `GREEN`: Normal operations.
|
||||
* **Card 2 (Valuation & Liquidity)**:
|
||||
* `RED`: Buffett Indicator Ratio $> 150\%$, or M2 money supply trend is `DOWN`.
|
||||
* `AMBER`: Buffett Indicator Ratio $> 130\%$, or Reverse Repo (RRP) volume $< 400$B$.
|
||||
* `GREEN`: Normal valuation limits.
|
||||
* **Card 3 (Yield Curve & Credit)**:
|
||||
* `RED`: 2S10S yield spread is inverted ($< 0.0\%$), or High-Yield Credit Spread $> 5.0\%$.
|
||||
* `AMBER`: 2S10S spread $< 0.1\%$, or High-Yield Credit Spread $> 4.0\%$.
|
||||
* `GREEN`: Positive term structure.
|
||||
|
||||
### AI & Tech Silo (Module 7)
|
||||
* **Card 1 (Monetization Gap)**:
|
||||
* `RED`: Minimum Monetization Gap among constituents $< -15\%$ (diminishing segment returns).
|
||||
* `AMBER`: Minimum Monetization Gap $< 0\%$ (CapEx growth outstripping segment revenue growth).
|
||||
* `GREEN`: Positive monetization gap (revenue growing faster than capital expenditures).
|
||||
* **Card 2 (Supply-Chain Velocity)**:
|
||||
* `RED`: Velocity Index $< 1.8x$, or velocity trend is `DOWN` (buyers reducing forward commitments).
|
||||
* `AMBER`: Velocity Index $< 3.0x$ (buyer commitments softening relative to supplier inventory).
|
||||
* `GREEN`: Normal supply speeds ($\ge 3.0x$).
|
||||
* **Card 3 (Infrastructure Leverage)**:
|
||||
* `RED`: Maximum CapEx-to-Depreciation Ratio $> 4.0x$, or maximum Debt-to-Equity Ratio $> 1.2$ (highly leveraged node expansion).
|
||||
* `AMBER`: Maximum CapEx-to-Depreciation $> 2.5x$, or maximum Debt-to-Equity $> 0.8$.
|
||||
* `GREEN`: Asset expansion supported by low-leverage ratios.
|
||||
|
||||
---
|
||||
|
||||
## 3. Active Data Proxy Models
|
||||
|
||||
### AI Special Silo API Response Schema (`/api/tech/ai`)
|
||||
```json
|
||||
{
|
||||
"dates": ["Q3-24", "Q4-24", "Q1-25", "Q2-25", "Q3-25", "Q4-25", "Q1-26", "Q2-26"],
|
||||
"liveDataAvailable": false,
|
||||
"timestamp": 1781274890000,
|
||||
"metrics": {
|
||||
"monetizationGap": {
|
||||
"name": "ROI-to-CapEx & Monetization Gap",
|
||||
"tickers": {
|
||||
"NVDA": {
|
||||
"current": -5.3,
|
||||
"previous": -4.2,
|
||||
"trend": "DOWN",
|
||||
"segmentRevenueGrowth": 3.1,
|
||||
"capexGrowth": 8.4,
|
||||
"roiToCapex": 2.6,
|
||||
"data": [
|
||||
{ "quarter": "Q3-24", "monetizationGap": 0.0, "roiToCapex": 0.0, "segmentRevenueGrowth": 0.0, "capexGrowth": 0.0 }
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"supplyChain": {
|
||||
"name": "Nvidia Supply-Chain Velocity Index",
|
||||
"unit": "x",
|
||||
"currentVelocity": 2.2,
|
||||
"previousVelocity": 2.5,
|
||||
"currentTurnover": 5.7,
|
||||
"currentObligations": 18700,
|
||||
"trend": "DOWN",
|
||||
"data": [
|
||||
{ "quarter": "Q3-24", "nvdaInvTurnover": 5.2, "aggregateObligations": 14500, "velocityIndex": 3.2 }
|
||||
]
|
||||
},
|
||||
"infrastructure": {
|
||||
"name": "Tech Infrastructure Leverage & Cluster Expansion",
|
||||
"tickers": {
|
||||
"MSFT": {
|
||||
"currentDE": 0.3,
|
||||
"currentCapExDep": 3.9,
|
||||
"trendDE": "UP",
|
||||
"data": [
|
||||
{ "quarter": "Q3-24", "de": 0.34, "capexDep": 3.2, "debt": 77800, "equity": 228900 }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
32
DEV_LOG.md
Normal file
32
DEV_LOG.md
Normal file
@@ -0,0 +1,32 @@
|
||||
# Chronological Development Log (`DEV_LOG.md`)
|
||||
|
||||
This document tracks all modifications, npm packages, active compilation states, and testing notes chronologically.
|
||||
|
||||
---
|
||||
|
||||
## [2026-06-12] - Phase 4.7 Deployment & Behavioral Rule Lock
|
||||
|
||||
### Added
|
||||
* **`QUANT_ROADMAP.md`**: Created the centralized quantitative architecture blueprint tracking our 6-level cockpit data matrix and individual asset scoring metrics.
|
||||
* **`AGENTS.md`**: Rewrote the central behavioral framework containing nextjs agent rules, tech stack constraints, blind environment rules, and `/devchain` session protocols.
|
||||
* **`DEV_LOG.md`**: Initialized this log to keep track of development history.
|
||||
* **`ARCHITECT_HANDOVER.md`**: Initialized the architect handover documentation.
|
||||
* **AI Special Silo Backend Route**: Deployed [/api/tech/ai/route.ts](file:///c:/Users/jannr/.gemini/antigravity/scratch/investment-sandbox/app/api/tech/ai/route.ts) with a 60-minute cache and calculations for the Monetization Gap, Nvidia SC Velocity Index, and Tech Infrastructure Leverage.
|
||||
* **AI Special Silo UI Workstation**: Deployed [AiSpecialSilo.tsx](file:///c:/Users/jannr/.gemini/antigravity/scratch/investment-sandbox/components/modules/tech/AiSpecialSilo.tsx) featuring a glassmorphic analytics viewer, dynamic Recharts sparklines, and status indicators.
|
||||
* **AI Special Silo English Handbook**: Deployed [TechMathModal.tsx](file:///c:/Users/jannr/.gemini/antigravity/scratch/investment-sandbox/components/modules/tech/TechMathModal.tsx) displaying extensive documentation and BlockMath LaTeX equations.
|
||||
|
||||
### Modified
|
||||
* **`app/page.tsx`**: Integrated the `[⚡ AI Special Silo]` tab inside the main workstation navigation headers.
|
||||
|
||||
### Dependencies Verified
|
||||
* `next` (v16.2.7)
|
||||
* `react` (v19.2.4)
|
||||
* `recharts` (v3.8.1)
|
||||
* `react-katex` (v3.1.0)
|
||||
* `katex` (v0.17.0)
|
||||
* `lucide-react` (v1.17.0)
|
||||
* `zustand` (v5.0.14)
|
||||
|
||||
### Active Bugs / Compile Status
|
||||
* **Active Bugs**: None.
|
||||
* **Type Checker Status**: Verified clean compilation (`npx tsc --noEmit` returns exit code 0).
|
||||
Reference in New Issue
Block a user