Skip to content

About

Orchestration repo for xstockstrat

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

1,608 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

xstockstrat

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.


Quick Links

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

Service Registry

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.


Bootstrap

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 services

See docs/setup/getting-started.md for prerequisites, environment file setup, and verification steps.


Agentic Development

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.

How it works

  1. A human writes a one-line user story. Something like "add IBKR account support" or "remove the n8n webhook layer".
  2. 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.
  3. 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-cited design.md.
  4. 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.
  5. 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.
  6. Status updates are mechanical, not discretionary — CI flips a feature from code-completed to launched automatically when its commit lands on main.

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.

Why it matters

  • The spec is the contract. When an agent picks up a feature in a fresh session days later, it re-reads context.md and continues exactly where the previous session stopped. No conversation memory required.
  • Drift is detectable. buf breaking blocks contract regressions; the CI proto-freshness job 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.

What's checked in

  • 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.

About

Orchestration repo for xstockstrat

Resources

Contributing

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages