---

name: st-develop description: Anything related to coroutines, State Threads (ST), or SRS's concurrency model. Use when discussing coroutine concepts, updating coroutine knowledge (srs-coroutines.md), developing/debugging/porting ST source code, porting ST to new CPU architectures or OSes, debugging coroutine context switching, analyzing ST scheduler behavior, adding new platform assembly, fixing ASAN/Valgrind/SEH issues, or understanding ST internals (sched, stk, sync, key, io, event, context switch ASM).

ST Development

State Threads (ST) is a C coroutine library. Source lives in trunk/3rdparty/st-srs/ inside the SRS repo.

Default SRS repo path is ~/git/srs, but do not hardcode this path. Always resolve SRS_ROOT dynamically:

1. If SRS_ROOT env is set and contains trunk/3rdparty/st-srs, use it.
2. Else, if current workspace (or its git root) contains trunk/3rdparty/st-srs, use that.
3. Else, if ~/git/srs/trunk/3rdparty/st-srs exists, use ~/git/srs.
4. Else, ask the user for the SRS repo root.

All ST source paths below are relative to $SRS_ROOT.

Setup: Load Knowledge Base (MANDATORY)

Before any ST work, use the read tool to load the knowledge base. Do NOT use memory_search — read the full file directly.

• memory/srs-coroutines.md

Loading ST Source Code (ON REQUEST)

When the user asks to load the ST codebase (or needs you to work directly with the source), load ALL ST source files — no partial loads.

All under $SRS_ROOT/trunk/3rdparty/st-srs/:

Headers: public.h, common.h, md.h

Core C: sched.c, stk.c, sync.c, key.c, io.c, event.c, common.c

Platform ASM: md_darwin.S, md_linux.S, md_linux2.S, md_cygwin64.S

Build: Makefile

Load every single file listed above — no shortcuts, no skipping.

Unit Tests (utest)

ST has a Google Test-based unit test suite in $SRS_ROOT/trunk/3rdparty/st-srs/utest/:

• st_utest.cpp / st_utest.hpp — Test main and shared helpers
• st_utest_coroutines.cpp — Coroutine tests (start, params, multiple coroutines, addition across yields)
• st_utest_tcp.cpp — TCP connection test
• gtest-fit/ — Embedded Google Test framework

Build targets (in the ST Makefile):

• darwin-debug-utest — macOS debug build + utest
• linux-debug-utest — Linux debug build + utest
• cygwin64-debug-utest — Cygwin64 debug build + utest

Coverage variants: darwin-debug-gcov, linux-debug-gcov (adds -fprofile-arcs -ftest-coverage).

The build compiles ST as a static library first, then builds and links the utest binary at obj/st_utest.

Verifying Changes

After any ST change (including utest-only changes), run the verifier script in this skill folder (not in the ST codebase):

• scripts/verify.sh

This script must resolve SRS_ROOT dynamically and run unit tests in $SRS_ROOT/trunk/3rdparty/st-srs. Always run verification before considering a change complete.