OSN-2026

This repository accompanies a conference talk titled "Spec First, Agents Second: Engineering AI Systems with Discipline," presented at Open Source North 2026. The talk's central argument is that AI coding tools produce better results when given precise written specifications to work from, rather than vague natural-language prompts. The slides are included in the repository.

The repository also contains the source code for a live demo system called MDAM, short for Medication Dose Alert Monitor. MDAM tracks scheduled medication doses in a care setting, detects any dose that goes unacknowledged past a configurable time threshold (the default is 15 minutes), alerts the care team, and then escalates to a charge nurse if the alert is still open after another window (10 minutes by default). Every state change is written to an append-only audit log before the change commits, and closing any alert requires authenticated acknowledgment.

The talk uses this system specifically because it concentrates several engineering challenges into a small surface area: timing constraints with clear boundaries, strict state transitions, safety-critical behavior where silent failure is the worst outcome, and real accountability obligations. The README includes a direct comparison between how a vague prompt would produce this system versus how a specification-driven prompt does, showing the concrete differences in code structure, testability, and traceability.

The demo walks through a tool called SpecKit, which generates a project constitution (non-negotiable principles and safety constraints), numbered requirements, an architecture plan, and an implementation task list. From those artifacts, an AI coding agent implements the code, and every exported function is annotated with the requirement number it satisfies. The test suite is also organized by requirement number.

The code is TypeScript, written with strict typing, pure functions, and timestamps injected as arguments so the business logic has no hidden dependencies on the system clock.