ft-review-toolkit

Plugin ft-review-toolkit in ReviewToolkits/ft-review-toolkit. Commands read from the repo's manifest — 1 month ago.

Slash commands (3)

• /ft-review-toolkit:assess

  Quick free-threading readiness scorecard. Use when the user asks for a quick overview, readiness score, or assessment of how close a C extension is to being free-threading safe.

• /ft-review-toolkit:explore

  Full free-threading thread-safety analysis. Finds data races, unprotected shared state, unsafe API usage, lock discipline issues, and atomic candidates. Use when the user wants a comprehensive analysis or to find thread-safety bugs.

• /ft-review-toolkit:plan

  Produce a phased migration plan for adopting free-threading in a C extension. Runs all analysis agents, then the migration-planner to create an actionable plan. Use when the user asks for a migration plan, how to add free-threading support, or how to get started with free-threading.

Subagents (10)

• atomic-candidate-finder

  Use this agent to find shared variables in C extension code that should use atomic operations for free-threading safety — non-atomic bools, counters, and pointers accessed across threads.\n\n<example>\nUser: Find variables that need atomic operations for free-threading.\nAgent: I will run the atomic

• ft-history-analyzer

  Use this agent for temporal analysis of a C extension's free-threading migration journey — finding free-threading related commits, incomplete migrations, reverted attempts, TSan fix patterns, and similar unfixed patterns. Uses a 2-year window to capture the full PEP 703 era.\n\n<example>\nUser: Has

• lock-discipline-checker

  Use this agent to audit lock acquire/release pairing in C extension code — missing releases on error paths, nested lock risks, and functions that should use Py_BEGIN_CRITICAL_SECTION.\n\n<example>\nUser: Check the lock handling in my C extension.\nAgent: I will run the lock discipline scanner, verif

• migration-planner

  Use this agent to produce a phased migration plan for adopting free-threaded Python in a C extension. Consumes findings from all other agents and produces actionable steps organized into phases.\n\n<example>\nUser: Create a migration plan for my extension to support free-threading.\nAgent: I will re

• shared-state-auditor

  Use this agent to find global/static shared mutable state in C extension code that becomes unsafe under free-threaded Python. Identifies unprotected global PyObject* variables, non-atomic shared flags, static types, and module state stored in globals.\n\n<example>\nUser: Check my C extension for sha

• stop-the-world-advisor

  Use this agent to identify operations in C extension code that may require StopTheWorld synchronization vs per-object critical sections vs PyMutex — GC interactions, interpreter state traversal, global registry modifications.\n\n<example>\nUser: My extension walks the GC object list. What synchroniz

• stw-safety-checker

  Use this agent to verify that code running during _PyEval_StopTheWorld does not invoke Python code, trigger GC, or set exceptions. Builds intra-file call graphs to detect transitive violations. Essential for extensions doing heap traversal (like guppy3).\n\n<example>\nUser: My extension uses _PyEval

• tsan-report-analyzer

  Use this agent to triage ThreadSanitizer (TSan) reports for C extensions — deduplicates races, separates extension code from CPython internals, classifies severity, and suggests fixes.\n\n<example>\nUser: I ran my extension tests under TSan and got hundreds of data race warnings. Help me make sense

• tsan-stress-generator

  Use this agent to generate concurrent stress test scripts that trigger ThreadSanitizer data race detection in C extensions. Reads the extension's API surface and source code, identifies thread-interesting operations, and produces a self-contained Python script that hammers shared state from multiple

• unsafe-api-detector

  Use this agent to find Python/C API calls that are unsafe under free-threaded Python — API calls in GIL-released regions, borrowed references without protection, container mutations on shared objects, and deprecated thread-unsafe APIs.\n\n<example>\nUser: Check my C extension for API usage that woul