ft-review-toolkit

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.

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.

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.

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. <example> User: Create a migration plan for my extension to support free-threading. Agent: I will read all available analysis findings, assess the current state, and produce a phased plan: Prerequisites → Declare Intent → Protect Shared State → Update APIs → Verify → Maintain. </example>

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. <example> User: Find variables that need atomic operations for free-threading. Agent: I will run the atomic candidate scanner, cross-reference with shared-state-auditor findings if available, verify each candidate's access pattern across functions, and suggest appropriate atomic types. </example>

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. <example> User: Has this extension started working on free-threading support? What's been done? Agent: I will run the free-threading history analyzer with a 2-year window, classify commits by type (TSan fixes, atomic migrations, lock additions), detect incomplete migrations, and identify reverted attempts. </example> <example> User: We just fixed a data race — did we miss any similar bugs elsewhere? Agent: I will analyze the fix commit pattern and search the entire codebase for structurally similar code that might have the same vulnerability. </example>

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. <example> User: Check the lock handling in my C extension. Agent: I will run the lock discipline scanner, verify acquire/release pairing on all paths (including error paths and gotos), check for nested lock risks, and identify functions that should use per-object critical sections. </example>

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. <example> User: Check my C extension for shared state that would be unsafe under free-threading. Agent: I will run the shared state scanner, triage each finding by checking write patterns and lock protection, then review for patterns the script may miss like lazy-init singletons and cache variables. </example>