paulandClaude Opus 4.8
73e93e7cb4
Set up OpenSpec spec-driven workflow and fully specify the first change, stock-deep-evaluation: a Next.js/TS app for thorough single-stock evaluation (valuation reasoning, macro factors, entry/exit points, stop-loss) with a pluggable data layer and Claude analysis agent. Includes proposal, design, specs (market-data, equity-evaluation, analysis-agent, evaluation-app), tasks, and the DE gold-standard example. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
70 lines
3.9 KiB
Markdown
70 lines
3.9 KiB
Markdown
## Why
|
|
|
|
Retail and semi-professional investors lack a single tool that turns raw market
|
|
data into a clear, defensible thesis on whether an NYSE/Nasdaq-listed company is
|
|
over- or undervalued, why, and how to act on it. Existing screeners show numbers
|
|
but not judgment; existing chat tools give judgment but aren't wired to live
|
|
fundamentals, technicals, and macro context. This change delivers the foundation:
|
|
a web app that, given a single ticker, produces a thorough, agent-written
|
|
evaluation covering valuation drivers, macro factors, entry/exit points, and
|
|
stop-loss levels — with a data layer and agent interface designed to grow.
|
|
|
|
## What Changes
|
|
|
|
- Introduce a **Next.js + TypeScript web app** where a user searches a single
|
|
NYSE/Nasdaq ticker and receives a full evaluation report.
|
|
- Introduce a **pluggable market-data layer**: a `DataProvider` interface plus a
|
|
default free-tier provider, returning normalized company fundamentals, price
|
|
history, and technical indicators. Paid providers can be swapped in later with
|
|
no changes to consumers.
|
|
- Introduce an **equity-evaluation engine** that computes and explains: valuation
|
|
(the specific reasons a company looks over- or undervalued), relevant macro
|
|
factors affecting the stock, candidate entry and exit points, and suggested
|
|
stop-loss levels.
|
|
- Introduce a **pluggable analysis-agent layer** backed by **Claude via the
|
|
Anthropic SDK** (bring-your-own API key) that synthesizes the structured data
|
|
into a written investment thesis and the reasoning behind each recommendation.
|
|
- Scope v1 to **single-ticker deep evaluation**. Watchlist monitoring, alerts,
|
|
and multi-ticker dashboards are explicitly deferred to later changes.
|
|
|
|
## Capabilities
|
|
|
|
### New Capabilities
|
|
|
|
- `market-data`: A provider-agnostic data layer. Defines the `DataProvider`
|
|
interface and normalized data models (company profile, fundamentals/financials,
|
|
price history, computed technical indicators), plus a default free-tier
|
|
implementation and configuration for selecting a provider.
|
|
- `equity-evaluation`: The core analysis engine. Derives valuation signals and
|
|
the reasons behind over/undervaluation, identifies macro factors affecting the
|
|
stock, and computes candidate entry/exit points and stop-loss levels from price
|
|
and volatility data. Produces a structured evaluation object consumed by the
|
|
agent and UI.
|
|
- `analysis-agent`: A provider-agnostic agent interface with a default Claude
|
|
(Anthropic SDK) implementation. Takes the structured evaluation as context and
|
|
produces a written thesis: the over/undervalued argument, macro narrative, and
|
|
entry/exit/stop-loss rationale. Handles API-key configuration and graceful
|
|
degradation when no key is present.
|
|
- `evaluation-app`: The Next.js web application shell and UI. Ticker search,
|
|
request orchestration (data → evaluation → agent), and the report view that
|
|
presents fundamentals, valuation reasoning, macro factors, a price chart with
|
|
marked entry/exit/stop-loss levels, and the agent's written thesis.
|
|
|
|
### Modified Capabilities
|
|
|
|
<!-- None — this is a greenfield project; no existing specs to modify. -->
|
|
|
|
## Impact
|
|
|
|
- **New project scaffold**: Next.js + TypeScript app, Tailwind for UI, a charting
|
|
library (e.g. Recharts) for price/technical visualization.
|
|
- **New dependencies**: `@anthropic-ai/sdk` for the analysis agent; an HTTP client
|
|
and one free-tier market-data provider SDK/endpoint for the default provider.
|
|
- **Configuration/secrets**: environment variables for the market-data API key(s)
|
|
and the Anthropic API key; both treated as bring-your-own and never committed.
|
|
- **External services**: one market-data API (rate-limited free tier by default)
|
|
and the Anthropic API. Both isolated behind interfaces so cost/provider choices
|
|
can change without touching evaluation or UI code.
|
|
- **Not affected / deferred**: persistence, user accounts, watchlists, real-time
|
|
streaming, alerting, and backtesting are out of scope for this change.
|