# GitHub Spec Kit Workflow > For the complete documentation index, see [llms.txt](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/llms.txt). TraderX baseline generation now follows a root-canonical GitHub Spec Kit flow. ## Canonical Locations * `.specify/**` for constitution and templates * `specs/001-baseline-uncontainerized-parity/**` for baseline requirements, stories, plan, tasks, and contracts * `pipeline/**` for generation and validation orchestration Each state pack under `specs/NNN-*` must include: * `research.md` * `data-model.md` * `quickstart.md` Convergence states must also include: * `system/convergence-rationale.md` Browse in docs: * `/specs/baseline-uncontainerized-parity` * `/specs/baseline-uncontainerized-parity/system/system-requirements` * `/specs/baseline-uncontainerized-parity/system/user-stories` * `/specs/baseline-uncontainerized-parity/system/acceptance-criteria` * `/specs/baseline-uncontainerized-parity/system/requirements-traceability` * `/specs/baseline-uncontainerized-parity/system/end-to-end-flows` * `/specs/baseline-uncontainerized-parity/system/architecture` * `/docs/spec-kit/state-docs` * `/docs/learning` * runtime API explorer route: `/api/docs` (via running state ingress/edge) * `/specify` ## Input Evidence For Requirements * `specs/001-baseline-uncontainerized-parity/system/architecture.model.json` * `specs/001-baseline-uncontainerized-parity/system/end-to-end-flows.md` * `specs/001-baseline-uncontainerized-parity/system/system-requirements.md` * `docs/README.md` * `README.md` ## Baseline Generation Flow 1. Validate Spec Kit readiness and requirement coverage. 2. Compile component manifests from Spec Kit artifacts. 3. Synthesize generated components from manifest + templates. 4. Start generated overlays and run smoke tests/parity checks. ## Derived-State Generation Flow For states `002+`, generation follows: 1. Generate parent state output. 2. Apply ordered patch set from `specs//generation/patches/*.patch`. 3. Regenerate architecture docs and run state smoke checks. ## Convergence-State Policy * Prefer new state proposals from the nearest suitable convergence state (`C0/C1/C2/C3`). * Keep `previous` single-parent for publish lineage. * Use `dottedParents` only for convergence states. * If convergence-state metadata/content changes, update that state's `system/convergence-rationale.md`. * Reference: [`/docs/spec-kit/convergence-states`](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/docs/spec-kit/convergence-states.md) ## LLM Feature-Add Implementation Contract When implementing a new state delta with an LLM: 1. Generate the parent state (`bash pipeline/generate-state.sh `). 2. Make only the intended child-state edits against generated output. 3. Capture patch set (`bash pipeline/create-state-patchset.sh [target-path]`). 4. Keep state hook as parent-generation + `apply-state-patchset.sh` only. 5. Update `specs//generation/generation-hook.md` with parent, patch path, and refresh commands. 6. Do not introduce or keep large file-payload heredoc generators for derived states. 7. Keep patch payloads clean: exclude build/restored artifacts (`.gradle`, `build`, `target`, `bin`, `obj`, `dist`, `coverage`, `node_modules`) and template-owned wrapper artifacts; include lockfile deltas only when Node manifests change. ## Generation Concurrency Run generation sequentially by default. `pipeline/generate-state.sh` writes to shared output roots (`generated/code/target-generated`, `generated/code/components`), so parallel invocations can race. Use isolated `TRADERX_GENERATED_ROOT` directories only when intentionally running multiple generation sessions in separate workspaces. ## Validation Commands ```bash bash pipeline/refresh-state-docs.sh --checkbash pipeline/validate-state-doc-consistency.shbash pipeline/validate-state-pack-artifacts.shbash pipeline/validate-template-version-consistency.shbash pipeline/validate-generated-branch-dependency-consistency.shbash pipeline/validate-generated-dependency-targets.sh generated/code/components generated/code/target-generatedbash pipeline/validate-sail-pin-contract.sh./pipeline/speckit/validate-speckit-readiness.sh./pipeline/speckit/verify-spec-expressiveness.shbash pipeline/speckit/compile-all-component-manifests.sh./pipeline/validate-regeneration-readiness.sh./pipeline/verify-spec-coverage.sh ``` ## Generated-State CI Preflight For generated-code branch publish, prepublish CI-parity gating is executed by default by `pipeline/publish-generated-state-branch.sh`. Run it manually when you need a standalone check: ```bash bash pipeline/prepublish-generated-state-gate.sh ``` Use `--skip-prepublish-gate` only as an explicit temporary override. See: [`/docs/spec-kit/generated-state-ci`](https://deploy-preview-472--lucky-concha-f3599f.netlify.app/docs/spec-kit/generated-state-ci.md) ## Docusaurus CI Compatibility When changing Docusaurus, docs plugins, or website build configuration: 1. Keep `website/package-lock.json` committed and updated with the dependency change. 2. Use `npm --prefix website ci --no-audit --no-fund` (not `npm install`) for CI parity. 3. Validate docs build with GitHub Pages settings: ```bash DOCUSAURUS_URL=https://traderx.finos.org \DOCUSAURUS_BASE_URL=/ \bash pipeline/refresh-state-docs.shDOCUSAURUS_URL=https://traderx.finos.org \DOCUSAURUS_BASE_URL=/ \npm --prefix website run clearDOCUSAURUS_URL=https://traderx.finos.org \DOCUSAURUS_BASE_URL=/ \npm --prefix website run build ``` `TRADERX_SITE_ROOT` controls the docs-route prefix used when regenerating `/docs/learning-paths` Mermaid click links. Keep it empty for root deployment (`/`) and set it only when publishing under a subpath. 4. If dependency changes alter transitive Webpack behavior, pin and re-lock before merge. 5. Run AFDocs checks for agent-friendliness: ```bash # local preview (while docusaurus start runs)npx afdocs check http://localhost:3000 --format scorecardnpx afdocs check http://localhost:3000 --format json --score# published docs URLnpx afdocs check https://traderx.finos.org/ --format scorecard ``` Use AFDocs scorecards to prioritize high-impact fixes. Prefer improvements via docs build/pipeline/plugins (for example llms outputs) before broad manual content rewrites. Learning-path catalog policy: * `catalog/state-catalog.json` is the source for state lineage. * Derived artifacts are regenerated together by: * `bash pipeline/refresh-state-docs.sh` * Derived artifacts include: * `catalog/learning-paths.yaml` * `catalog/learning-paths.md` * `/docs/learning-paths` * `/docs/spec-kit/state-docs` * `/docs/learning/index` * `/docs/learning/state-*.md` ## Generation Commands Generate any state: ```bash bash pipeline/generate-state.sh ``` These commands also regenerate state architecture docs from `specs/*/system/architecture.model.json`. State docs (`/docs/spec-kit/state-docs`) are generated from `catalog/state-catalog.json`. Scaffold a new planned state pack: ```bash bash pipeline/scaffold-state-pack.sh --title "" --previous <prior-state-id> --track <prelude|baseline|architecture|nonfunctional|functional|devex> ``` Run the state-change playbook (refresh docs -> gates -> generate -> optional publish/push): ```bash bash pipeline/state-playbook.sh --state <state-id> --publish-neighborhood --push-generated ``` Dependency maintenance refresh contract: 1. Start from the earliest implemented state impacted by the dependency change. 2. Run forward through downstream implemented states. 3. Require smoke-test pass evidence before publish. Sail-specific maintenance checks (state `014`): ```bash # local pin contract checkbash pipeline/validate-sail-pin-contract.sh# upstream drift check (fails if tracking ref moved beyond the pinned commit)bash pipeline/check-sail-pin-drift.sh --fail-on-drift ``` Sail pin metadata source: * `specs/014-fdc3-intent-interoperability/generation/sail-pin.env` Generated outputs: * `generated/code/components/*-specfirst` * `generated/manifests/*.manifest.json` * `generated/code/target-generated/**` (assembled at startup) Run generated baseline stack: ```bash CORS_ALLOWED_ORIGINS=http://localhost:18093 ./scripts/start-base-uncontainerized-generated.sh --build-onlyCORS_ALLOWED_ORIGINS=http://localhost:18093 ./scripts/start-base-uncontainerized-generated.sh ``` Run generated containerized stack (state `004`): ```bash ./scripts/start-state-004-containerized-generated.sh./scripts/start-state-004-containerized-generated.sh --skip-build./scripts/status-state-004-containerized-generated.sh./scripts/test-state-004-containerized.sh./scripts/stop-state-004-containerized-generated.sh ``` Ingress endpoint: `http://localhost:8080` ## Full Parity Gate Run end-to-end parity validation (generation + startup + all baseline smoke tests): ```bash bash pipeline/speckit/run-full-parity-validation.sh ``` ## API Explorer API explorer generation is runtime-centric and decoupled from the docs portal. It is installed during state generation by: ```bash bash pipeline/install-generated-api-explorer.sh <state-id> ``` ## Compare Generation Output To compare a single component generated output between a legacy script revision and current Spec Kit-driven generation: ```bash bash pipeline/speckit/compare-component-generation.sh <component-id> <legacy-ref> ``` Example: ```bash bash pipeline/speckit/compare-component-generation.sh reference-data HEAD ``` ## Iterating Learning-Path States After baseline parity is green: 1. add FR/NFR deltas in the next feature pack under `specs/NNN-*` 2. update contracts if interfaces change 3. update and capture state patch set: ```bash bash pipeline/create-state-patchset.sh <state-id> <parent-state-id> [target-path] ``` 4. rerun conformance + parity gates This keeps each learning-path state reproducible from requirements instead of from copied source.