arch-scaffold-worker

Scaffolds a Python worker role with claim, lease, and drain-first shutdown over a work queue.

89|10|Updated Sep 15, 2026
One-click install
npx skills add https://github.com/baristaze/swe_guidelines --skill arch-scaffold-worker-baristaze
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: arch-scaffold-worker
Source: https://github.com/baristaze/swe_guidelines/tree/main/skills/arch-scaffold-worker
Command: npx skills add https://github.com/baristaze/swe_guidelines --skill arch-scaffold-worker-baristaze

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Building a background worker that correctly claims items from a work queue, renews leases, fences stale holders, and shuts down cleanly involves many interlocking pieces that are easy to get wrong. This Skill generates the entire worker role and, when needed, the underlying work namespace, following a prescribed architecture. ## Core Features & Use Cases - Work Namespace Scaffolding: Creates the work namespace with manager, storage interfaces, Postgres and memory implementations, migrations, and contract, unit, and integration tests when it does not yet exist. - Worker Role Generation: Writes the worker distribution with settings, handler, container, claim-handle-complete loop, lease renewal with self-fencing, liveness heartbeat, drain-first shutdown, maintenance sweep, Dockerfile, and tests. - Infrastructure Wiring: Updates Terraform modules per environment, deploy workflows, docker-compose, workspace members, and arch-check configuration so the new worker passes the fast gate. - Use Case: Run the skill with shipment-notifier NOTIFY_SHIPMENT to produce a complete worker that claims NOTIFY_SHIPMENT items, renews leases, and integrates with the outbox relay and deployment pipeline. ## Quick Start Ask the AI to create a worker named shipment-notifier for the work kind NOTIFY_SHIPMENT using this scaffold skill.

Frequently Asked Questions about arch-scaffold-worker

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I scaffold a background worker for a work queue in Python?▼

Invoke the skill with a worker name in snake case and a work kind in CamelCase, for example `shipment-notifier NOTIFY_SHIPMENT`. It generates the handler, claim loop, lease renewal, shutdown logic, image, and tests under `workers/<worker-name>/`.

How does the worker prevent two workers from processing the same queue item?▼

Each claim mints a claim token, and complete, fail, defer, release, and lease extension are conditional on that token in the storage statement itself. A stale holder's write is refused with Conflict and the item is handed back without spending an attempt.

What happens when the work namespace does not exist yet?▼

The skill creates the `work` namespace first, including the manager, storage interfaces with Postgres and memory implementations, the queue table migration, outbox relay branch, and tests, then scaffolds the worker on top of it.

How does the worker handle shutdown and liveness checks?▼

Shutdown stops claiming, cancels tasks, returns items to the queue, stops the heartbeat, and marks the worker offline. The /healthz endpoint answers from the loop's in-memory beat with no I/O, and a failed liveness publish never pauses claiming.

What infrastructure changes does the worker scaffold include?▼

It adds one Terraform service module instance per environment with autoscaling and alarms, image build and promotion steps in the staging and production deploy workflows, workspace membership in pyproject.toml, settings in .env.example, and an optional docker-compose entry.