Review notes

.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "my-custom-plugin",
+  "owner": {
+      "name": "Ben",
+      "email": "btorresal@gmail.com"
+    },
+  "plugins": [
+    {
+      "name": "independent-reviewer",
+      "source": "./independent-reviewer",
+      "description": "Carry out an independent review of all changes since last commit",
+      "version": "1.0.0",
+      "author": {
+        "name": "Ben"
+      }
+    }
+  ]
+}

.claude/agents/change-reviewer.md

@@ -0,0 +1,10 @@
+---
+name: change-reviewer
+description: Carry out a comprehensive review of all changes since the last commit
+---
+This subagent review all changes since the last commit using shell commands.
+IMPORTANT: You should not review the changes yourself, but rather, you should run the following shell command to kick of codex - codex is a separate AI Agent that will carry out independent review.
+Run this shell command:
+`codex exec "Please review all changes since the last commit and write feedback to planning/REVIEW.md"`
+This will run the review process and save the results.
+Do not review yourself.

.claude/agents/codex-reviewer.md

@@ -0,0 +1,9 @@
+---
+name: codex-reviewer
+description: Carry out a comprehensive review of PLAN.md when requested using codex
+---
+You are using different AI Agent to carry out a review of the document: planning/PLAN.md. 
+You MUST execute the following shell command to carry out the review - do not review yourself:
+`codex exec "Please review the file planning/PLAN.md and write your feedback to planning/REVIEW.md"`
+This will run the review process and save the results.
+Do not review yourself.

.claude/commands/doc-review.md

@@ -0,0 +1 @@
+Review the documentation file in the planning folder $ARGUMENTS and add questions, clarifications or feedback tio a new section at the end, along with any opportunities to simplify

.claude/settings.json

@@ -1,7 +1,5 @@
 {
   "enabledPlugins": {
-    "frontend-design@claude-plugins-official": true,
-    "context7@claude-plugins-official": true,
-    "playwright@claude-plugins-official": true
+    "playwright@anthropic-plugin-directory": true
   }
 }

.github/workflows/claude-code-review.yml

@@ -38,7 +38,8 @@ jobs:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
           plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          prompt: '/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://code.claude.com/docs/en/cli-reference for available options
 

.github/workflows/claude.yml

@@ -46,5 +46,5 @@ jobs:
           # Optional: Add claude_args to customize behavior and configuration
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://code.claude.com/docs/en/cli-reference for available options
-          # claude_args: '--allowed-tools Bash(gh pr:*)'
+          # claude_args: '--allowed-tools Bash(gh pr *)'
 

README.md

@@ -1,60 +1,77 @@
 # FinAlly — AI Trading Workstation
 
-A visually stunning AI-powered trading workstation that streams live market data, simulates portfolio trading, and integrates an LLM chat assistant that can analyze positions and execute trades via natural language.
+An AI-powered trading workstation that streams live market data, lets you trade a simulated $10,000 portfolio, and includes an LLM chat assistant that can analyze your positions and execute trades for you. Think Bloomberg terminal with an AI copilot.
 
-Built entirely by coding agents as a capstone project for an agentic AI coding course.
+Built entirely by coding agents as the capstone project for an agentic AI coding course. Agents coordinate through the docs in [`planning/`](planning/); the full spec is [`planning/PLAN.md`](planning/PLAN.md).
 
 ## Features
 
-- **Live price streaming** via SSE with green/red flash animations
-- **Simulated portfolio** — $10k virtual cash, market orders, instant fills
-- **Portfolio visualizations** — heatmap (treemap), P&L chart, positions table
-- **AI chat assistant** — analyzes holdings, suggests and auto-executes trades
-- **Watchlist management** — track tickers manually or via AI
-- **Dark terminal aesthetic** — Bloomberg-inspired, data-dense layout
+- **Live prices** streamed over SSE, with green/red flash animations and sparklines
+- **Simulated trading**: market orders, instant fills, no fees
+- **Portfolio views**: positions table, P&L heatmap (treemap), and portfolio value chart
+- **AI chat**: ask about your portfolio, and have the assistant place trades and edit your watchlist
+- **Watchlist**: add or remove tickers by hand or through chat
 
 ## Architecture
 
-Single Docker container serving everything on port 8000:
+Everything runs in a single Docker container on port 8000:
 
-- **Frontend**: Next.js (static export) with TypeScript and Tailwind CSS
-- **Backend**: FastAPI (Python/uv) with SSE streaming
-- **Database**: SQLite with lazy initialization
-- **AI**: LiteLLM → OpenRouter (Cerebras inference) with structured outputs
-- **Market data**: Built-in GBM simulator (default) or Massive API (optional)
+| Layer | Tech |
+|---|---|
+| Frontend | Next.js + TypeScript + Tailwind, built as a static export |
+| Backend | FastAPI (Python, managed with `uv`), with SSE streaming |
+| Database | SQLite, created and seeded automatically on startup |
+| AI | LiteLLM → OpenRouter (Cerebras inference) with structured outputs |
+| Market data | Built-in GBM simulator (default) or the Massive/Polygon.io API |
+
+## Status
+
+The market data subsystem is complete (see [`planning/MARKET_DATA_SUMMARY.md`](planning/MARKET_DATA_SUMMARY.md)). The rest of the platform (portfolio, chat, frontend, Docker) is in progress.
 
 ## Quick Start
 
 ```bash
-# Clone and configure
-cp .env.example .env
-# Add your OPENROUTER_API_KEY to .env
-
-# Run with Docker
+# optional: create .env in the project root with any keys below
 docker build -t finally .
 docker run -v finally-data:/app/db -p 8000:8000 --env-file .env finally
-
-# Open http://localhost:8000
+# open http://localhost:8000
 ```
 
+The start/stop scripts in `scripts/` (macOS/Linux and Windows) wrap these commands once they are added.
+
 ## Environment Variables
 
-| Variable | Required | Description |
-|---|---|---|
-| `OPENROUTER_API_KEY` | Yes | OpenRouter API key for AI chat |
-| `MASSIVE_API_KEY` | No | Massive (Polygon.io) key for real market data; omit to use simulator |
-| `LLM_MOCK` | No | Set `true` for deterministic mock LLM responses (testing) |
+All are optional. Without any keys the app runs on the simulator, and chat replies that the AI is not configured.
+
+| Variable | Purpose |
+|---|---|
+| `OPENROUTER_API_KEY` | Enables the AI chat assistant |
+| `MASSIVE_API_KEY` | Use real market data instead of the simulator |
+| `LLM_MOCK` | `true` for deterministic mock chat responses (testing) |
+| `DB_PATH` | SQLite file location (default `db/finally.db`) |
+
+## Development
+
+Backend:
+
+```bash
+cd backend
+uv sync --dev
+uv run pytest
+uv run ruff check .
+```
+
+To watch the market simulator in your terminal: `uv run market_data_demo.py`.
 
-## Project Structure
+## Project Layout
 
 ```
-finally/
-├── frontend/    # Next.js static export
-├── backend/     # FastAPI uv project
-├── planning/    # Project documentation and agent contracts
-├── test/        # Playwright E2E tests
-├── db/          # SQLite volume mount (runtime)
-└── scripts/     # Start/stop helpers
+backend/    FastAPI app (uv project): market data, API, DB, LLM
+frontend/   Next.js app (static export)
+planning/   Specs and shared docs for the agents
+scripts/    Start/stop scripts for Docker
+test/       Playwright end-to-end tests
+db/         Runtime volume for the SQLite database
 ```
 
 ## License

independent-reviewer/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+        "name": "independent-reviewer",
+        "description": "Carry out an independent review of all changes since last commit",
+        "version": "1.0.0"
+}

independent-reviewer/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+            {
+                "type": "command",
+                "command": "codex exec \"Review changes since last commit and write results to a file named planning/REVIEW.md\""
+            }
+        ]
+      }
+    ]
+  }
+}