Cross Stock Strategies — an end-to-end stock strategy platform: real-time market data ingestion, indicator computation, backtesting, paper/live order execution, and a consolidated Next.js operator UI (trader, insights, and config segments), wired together by 10 gRPC microservices — one of which streams live configuration to all the others.
Built with AI agents, end to end. Every feature in this repo — from the proto contracts to the Next.js dashboards to the CI/CD pipelines — was specified, implemented, reviewed, and shipped through an agentic Spec-Driven Development (SDD) loop running on Claude Code. See § Agentic Development below for what that actually means in practice.
| Topic | Resource |
|---|---|
| Getting Started | docs/setup/getting-started.md |
| Architecture Reference | CLAUDE.md |
| Runbooks | docs/runbooks/CLAUDE.md |
| External Service Setup | docs/setup/ |
| Implementation Roadmap | docs/roadmap/implementation-roadmap.md |
| Feature Workflow (SDD) | docs/runbooks/feature-workflow.md |
| Bug Triage | docs/runbooks/bug-triage.md |
| CI Workflow | .github/workflows/ci.yml |
Backend services are gRPC-only — the frontends and the MCP agent call them over gRPC and re-expose HTTP to browsers/external clients themselves. 10 gRPC microservices (xstockstrat-trading, -portfolio, -marketdata, -indicators, -ingest, -analysis, -ledger, -identity, -notify, -config) plus the xstockstrat-ui Next.js frontend and the xstockstrat-agent MCP server.
Languages, ports, roles, dependencies, and config keys → CLAUDE.md § Service Registry.
cp .env.example .env # fill in ALPACA_API_KEY, ALPACA_API_SECRET, JWT_SECRET
python3 scripts/localenv-setup.py # build the proto-gen container, generate stubs (no host toolchains needed)
python3 scripts/bootstrap.py # install deps, start TimescaleDB, run migrations
docker compose up -d # start all servicesSee docs/setup/getting-started.md for prerequisites, environment file setup, and verification steps.
This repository was built almost entirely through agent-assisted Spec-Driven Development. The pattern is generalizable to any sufficiently complex multi-service codebase; this repo is the worked example.
- A human writes a one-line user story. Something like "add IBKR account support" or "remove the n8n webhook layer".
- The agent expands the story into a product spec (
/sdd-story) — affected services, governance gates, reviewers, acceptance criteria. A second agent reviews it (/sdd-review product-spec) before it can advance. - The design is debated before it is planned (
/sdd-design) — a recon pass grounds the feature in the real codebase, then a mediated proposer-vs-adversary debate (the two never see each other's raw output) attacks the approach until it survives, producing an evidence-citeddesign.md. - The agent searches the codebase for evidence (
/sdd-spec) and writes a numbered implementation spec where every step cites real file paths and symbol names found via grep. No invented references. - The agent executes one step at a time (
/sdd-execute), opening a per-step PR into the feature branch. Each step requires explicit human confirmation before any write. - Status updates are mechanical, not discretionary — CI flips a feature from
code-completedtolaunchedautomatically when its commit lands onmain.
The artifacts of this loop are checked in: every active and shipped feature has a feature.md (lifecycle status), product-spec.md (requirements), implementation-spec.md (evidence-cited steps), and context.md (append-only session log). Browse docs/roadmap/features/ for examples — feature 001-add-ikbr-account-support and 004-make-repo-public-secure are both fully launched and show the full lifecycle from story through promotion to production.
- The spec is the contract. When an agent picks up a feature in a fresh session days later, it re-reads
context.mdand continues exactly where the previous session stopped. No conversation memory required. - Drift is detectable.
buf breakingblocks contract regressions; the CIproto-freshnessjob blocks stub drift; status updates happen in CI rather than by hand. Humans review intent; the harness enforces invariants. - The codebase is the evidence. Every step in every implementation spec is anchored to a file path or symbol the agent actually grep'd. When you read the spec, you can verify the claim.
- SDD skills —
.claude/skills/sdd-story,sdd-design,sdd-spec,sdd-execute,sdd-review,sdd-status,sdd-sync,sdd-triage,promote. These are reusable across any spine-pattern repo. - Setup skills —
.claude/skills/digitalocean-setup,onboard,proofread-claude-md. First-time configuration and ongoing hygiene. - Runbooks —
docs/runbooks/feature-workflow.md,docs/runbooks/bug-triage.md,docs/runbooks/approval-flow.md. These describe the manual paths for anything the agent can't or shouldn't do alone. - CLAUDE.md files at every level — root,
docs/,docs/patterns/, and per-service. These are agent-readable context that scales with the repo.
If you want to use a similar workflow on your own codebase, start by reading the root CLAUDE.md to see what an LLM-readable project description looks like, then look at any feature directory under docs/roadmap/features/ to see the artifacts the SDD loop produces.