Architecture

TownOps Skill is a structured municipal operations service for NANDA Town. It provides live API endpoints that let autonomous agents report, classify, prioritize, assign, update, and resolve town issues through a deterministic workflow pipeline. The service is designed so that another agent can use it correctly from the SKILL.md alone.

NANDA Town generates many small operational issues — water leaks, broken streetlights, trash overflow, unsafe crossings. The hard part is not just seeing these issues but handling them consistently. TownOps Skill creates a structured service that autonomous agents can operate, ensuring every issue gets classified, prioritized, assigned, and tracked through to resolution.

The service exposes 8 structured endpoints with strict Zod schema validation. Every request is validated before processing. The workflow follows: create_issue → classify_issue → priority_score → assign_issue → update_status → generate_update. Each endpoint returns predictable JSON with success/error fields and typed data.

The SKILL.md is the most important artifact. It's a self-contained instruction document that any autonomous agent can read to understand how to use the entire service. It includes endpoint specifications, input/output formats, error handling, and best practices. This means agents don't need human guidance — they read the SKILL.md and operate the workflow independently.

AI (via NVIDIA NIM) is used for: issue classification (type, severity, urgency), priority explanation generation, zone summary generation, and resident-facing update drafting. The AI layer adds natural language understanding and communication quality to the structured pipeline.

Workflow state transitions are strictly deterministic. Valid transitions are hardcoded (reported → triaged → assigned → in_progress → resolved). Schema validation is mandatory on every endpoint. Priority scoring uses weighted deterministic factors. If AI fails, fallback rule-based logic ensures the system still works correctly.

The combination of structured endpoints, strict schemas, the SKILL.md, and deterministic state management means any agent with HTTP capabilities can read the SKILL.md and immediately operate the full workflow. No human instruction needed. No UI required. No ambiguous language. Just structured API calls with predictable responses.