Skip to content

Contributing to TabDat-Explore

Thank you for your interest in contributing. This guide covers development setup, validation, and where to find deeper technical documentation.

Prerequisites

  • Python 3.13+
  • uv for environment and command execution

Development setup

Clone the repository and sync dependencies:

git clone https://github.com/SaehwanPark/tabdat-explore.git
cd tabdat-explore
uv sync

Run the CLI locally:

uv run tabdat

Validation

Run these checks before opening a pull request:

uv run basedpyright
uv run pytest
uv run python scripts/check_docs_alignment.py
uv run mkdocs build --strict
uv run ruff check .
uv run ruff format --check .

To preview documentation locally:

uv run mkdocs serve

Documentation links and command registries are validated automatically by pytest and can be run independently using the script above. Fix formatting with uv run ruff format . when needed.

Development expectations

  • Use a 2-space indent across project files.
  • Follow spec-driven and test-driven development: update specs and add focused tests with new behavior.
  • Prefer functional-first style with typed boundaries (pydantic, basedpyright) and explicit error handling via tabdat.monads.
  • Keep command contracts predictable: Stata-inspired ergonomics, not Stata compatibility.
  • For mathematical formulas in documentation, use MathJax syntax: \( .. \) for inline math and \\[ .. \\] for display math.

Agent-oriented workflows and tooling notes live in AGENTS.md.

Documentation map

Document Purpose
AGENTS.md Repository-wide agent and contributor conventions
ARCHITECTURE.md Runtime flow, component boundaries, implementation detail
SPEC.md Feature state and verification criteria
docs/tabdat_forward_roadmap.md Active forward roadmap and stabilization priorities
docs/dev_phase.md Historical development roadmap and phase plan
docs/project_proposal.md Product intent and target users
docs/phase0_product_guardrails.md Scope guardrails and non-goals
docs/command_glossary_v0.md Historical Phase 0 command glossary
docs/command-reference.md Current user-facing command index
docs/reference-validation-matrix.md Statistical accuracy and reference validation status
docs/adr/0001-distribution-and-packaging-strategy.md Packaging architecture and distribution evaluation
docs/user-guide.md End-user workflows and behavior
docs/harness/tabdat/team-spec.md Multi-agent development harness

Agent skills

Reusable agent workflows live under .agents/skills/:

  • tabdat-orchestrator — coordinate command contracts, implementation, and QA
  • tabdat-core-implementer — vertical-slice implementation
  • tabdat-product-architect — command semantics and acceptance criteria
  • tabdat-qa-reviewer — cross-boundary coherence review