Developing a py-worker
After generating
Section titled “After generating”Generation copied .env.example to .env, created .venv, installed
requirements.txt into it, and made the first commit.
-
Set
HOME_PATHin.envto the project’s absolute path (pwdin the project directory). -
Point it at the API’s services:
DB_*andREDIS_*exactly as the API has them. With the API’syarn dc:uprunning, the defaults match. -
Model the tables you need under
models/, mirroring the API’s Prisma schema, usingBaseand the mixins inmodels/mixins.py. -
Run it:
Terminal window source .venv/bin/activatepython worker.py -
Send it a job on the
helloqueue from the API, and watchlogs/workers/hello.log.
Adding a job type
Section titled “Adding a job type”The project’s own task skills carry the full steps for each of these.
- Create
workers/<name>/process.pywith anasync def <name>_process(job, job_token). - Start it in
worker.py:create_worker("<queue>", <name>_process), and addawait <worker>.close()to the cleanup block. - Produce to the same queue name from the API.
Temporal locally
Section titled “Temporal locally”With --with temporal, the worker connects to localhost:7233 (the dev server
in the API’s compose.yml) and polls task queue python:
temporal workflow execute --type example --task-queue python \ --workflow-id try-py --input '{"name":"python"}'Add a workflow class to temporal/workflows.py and an activity to
temporal/activities.py, then register both in the lists in
utils/temporal.py. Workflow code must be deterministic: use workflow.now()
and workflow.random(), never I/O.
Dependencies
Section titled “Dependencies”requirements.txt pins every package. Add one with
.venv/bin/pip install <pkg> and pin its version in requirements.txt; the
Docker image installs exactly that file.
Building with Claude Code
Section titled “Building with Claude Code”The project ships its own guidance for Claude Code, generated with it and stripped to the features it has:
CLAUDE.mdat the root: the worker’s commands, layout and rules (models mirror the API’s tables by hand, queue names match the producer, its own Temporal task queue). Claude Code loads it in every session in the project.- Task skills in
.claude/skills/<name>/SKILL.md: step-by-step recipes that point at the template’s own example code. Ask for the task in plain words (“add an endpoint for invoices”) and the matching skill loads.
| Skill | Ships with | What it does |
|---|---|---|
add-worker | Every project | Add a BullMQ job handler to this Python worker for a queue the Node API produces to — the handler, its registration and its shutdown. |
add-model | database | Add a SQLAlchemy model to this Python worker that mirrors one of the API's Prisma tables, so a job handler can read or write it. |
add-workflow | temporal | Add a Temporal workflow and its activities to this Python worker — durable, multi-step work in Python that the API starts by name. |
A skill that belongs to a feature arrives with it: adding the feature later
with stack add brings its skill and its
CLAUDE.md sections too. Both are yours to edit as the project grows its own
conventions. See Building with Claude Code for
the whole workflow, from a design to a backlog.