Skip to main content

Why TraderX Was Reworked Around SpecKit

Mission​

TraderX was reworked around SpecKit to make multi-state learning paths practical to maintain.

The primary goal is to support multiple parallel and sometimes conflicting state progressions (for example, different platform, DevOps, or messaging choices) while still giving developers clear, runnable jump-off points.

Browse the state landscape directly:

Problem With The Old Code-First Model​

When code was the main maintained artifact, each new state incarnation increased maintenance overhead and drift risk.

  • Parallel tracks were hard to keep aligned.
  • Conflicting directions were expensive to review and merge.
  • It was difficult to preserve clear relationships between states.
  • Maintainers spent too much effort on code deltas instead of intent and outcomes.

What SpecKit Changes​

TraderX now treats specs as the system of record and code as a generated by-product.

  • Canonical intent, requirements, stories, and governance live in:
    • .specify/**
    • specs/**
  • State transitions are captured as explicit spec deltas.
  • Generation pipelines synthesize runnable code from those deltas.
  • Conformance and parity checks verify generated output against spec intent.

This gives us an understandable and documented relationship between states while reducing overhead for maintainers.

Main Consequence For Contribution Flow​

Feedback into the project is modeled as a spec/state change first, not as ad-hoc source edits first.

  • Proposed improvements become state-oriented spec updates.
  • Review focuses on requirements, contracts, and traceability.
  • Code is regenerated from accepted spec changes.

In short: we preserve specs; the code follows.

What A Developer Needs To Know​

  1. Start from baseline state 001-baseline-uncontainerized-parity.
  2. Read system context, requirements, and flows under specs/001-*/system/**.
  3. Regenerate code using pipeline/generate-state.sh <state-id> (or component generators where needed).
  4. Run with state runtime scripts under scripts/.
  5. Validate with SpecKit/conformance gates under pipeline/speckit/**.

Where Is All The Code?​

All TraderX state code lives in this same repository. The canonical source is specs in main, and runnable code snapshots are published as generated-state branches and tags.