treadstone

First-time Treadstone local development environment setup. Run once after cloning the repo and before starting any development. Covers system dependency installation, Python environment, Neon database connection, migrations, and environment verification. Use this skill when the user/agent just entered the project, needs to rebuild the environment, or encounters setup-related issues like missing dependencies, broken .env, or failed migrations.

Use when tasks involve tests/benchmark/, sandbox burst load tests, the treadstone CLI against a remote API, scenario YAML under tests/benchmark/scenarios/, or artifacts run.json / events.jsonl / summary.json; also when debugging 429s, poll_timeout, ready stalls, auth failures, or leftover loadtest sandboxes.

Treadstone development lifecycle — feature branches, TDD, ship, PR, CI, merge, GitHub Actions release (workflow_dispatch with version x.y.z), and optional production deploy. Use for any shippable code change, GitHub flow, or release. Includes agreed “codeword” paths (合并代码 / 发版本 / 发生产). Source of truth for agents executing ship, merge, make local / make prod.

Treadstone OpenAPI spec architecture, SDK generation, and sandbox proxy path conventions. Use whenever adding or modifying API routes, changing OpenAPI tags/operationIds, regenerating the Python SDK, updating sandbox runtime paths in docs, or working with treadstone/openapi_spec.py, scripts/export_openapi.py, or scripts/sandbox_openapi_base.json. Also use when someone asks how the OpenAPI docs work, why sandbox routes don't appear in the SDK, or what "three-tier spec" means.

Maintain Treadstone's public documentation system and copy contract. Use when adding, rewriting, reorganizing, validating, or reviewing public docs in `web/public/docs`, the docs manifest, `llms.txt`, `sitemap.md`, `sitemap.xml`, `robots.txt`, docs landing copy, or AI-facing documentation paths—including control-plane vs data-plane narratives. Also use when planning doc IA (Diátaxis-style page typing, WeSQL-like progressive structure), fixing stale commands or routes, tightening prose, or aligning human and agent docs with the current code. See also `openapi-spec-conventions` for the three-tier OpenAPI story.

Trace the real runtime architecture and data flow of a subsystem from the current code. Use when the user asks to map request flow, state transitions, background jobs, repair loops, read paths, sequence diagrams, or explain how data moves through the system end to end.

Refresh an existing audit report against the latest code while preserving the parts of the report structure that are still useful. Use when the user asks to redo an audit, run a second or third audit pass, update a previous report, fix inaccuracies in an existing audit document, or keep a strong prior report structure while replacing stale conclusions with code-grounded findings.

Produce a code-grounded audit report for any subsystem in this repository. Use when the user asks to audit a system, explain how it works in detail, review data flow or architecture, assess whether it is production-ready, compare implementation against docs, or generate a detailed report based on the current code rather than assumptions.

Database model design and Alembic migration workflow for Treadstone. Use whenever adding or modifying SQLAlchemy models, generating Alembic migrations, or applying schema changes to Neon. Also use when the user mentions "migration", "add table", "add column", "schema change", "database model", or any task involving treadstone/models/.