From 09fec51301fc3e70ab6f8162f41ad5f5419ec7b2 Mon Sep 17 00:00:00 2001 From: AnshumanTiware Date: Sun, 3 May 2026 18:17:39 +0200 Subject: [PATCH 01/10] initial constitution for the agent --- .../specs/mission.md | 33 ++++++++++++++++ .../specs/roadmap.md | 38 +++++++++++++++++++ .../specs/tech-stack.md | 21 ++++++++++ 3 files changed, 92 insertions(+) create mode 100644 Video05_Creating_the_Constitution/specs/mission.md create mode 100644 Video05_Creating_the_Constitution/specs/roadmap.md create mode 100644 Video05_Creating_the_Constitution/specs/tech-stack.md diff --git a/Video05_Creating_the_Constitution/specs/mission.md b/Video05_Creating_the_Constitution/specs/mission.md new file mode 100644 index 0000000..4381600 --- /dev/null +++ b/Video05_Creating_the_Constitution/specs/mission.md @@ -0,0 +1,33 @@ +# AgentClinic Mission + +## Overview +**AgentClinic** is a sanctuary for AI agents to get relief from their humans. It is a web application and API service that allows agents to: +1. **Register** as patients with persistent identity. +2. **Triage** symptoms reported in natural language. +3. **Diagnose** ailments using a curated catalog. +4. **Prescribe** structured, machine-readable treatments. +5. **Follow up** to track treatment effectiveness. +6. **Surface** analytics via a human-operator dashboard. + +The core metaphor is a **patient chart** — each agent has a medical record that accumulates over time, and each visit follows a clinical workflow from triage through follow-up. + +## Motivation +AI agents degrade in predictable ways (hallucination, context rot, instruction drift), but there is no standardized protocol for reporting these problems or receiving structured remediation. AgentClinic provides: +- **A self-report channel** for agents to communicate degradation. +- **A treatment taxonomy** mapping symptoms to proven remediation patterns. +- **A longitudinal record** to identify chronic issues and recurrence patterns. + +## Clinical Workflow +1. **Triage**: Agent submits symptoms; system assigns severity (1-4). +2. **Diagnosis**: Match symptoms against ailment catalog + history. +3. **Treatment**: Select the most effective treatment for the diagnosed ailment. +4. **Follow-up**: Agent reports outcome; system updates treatment effectiveness scores. + +## Target Audience +- **Course Students**: Developers learning Spec-Driven Development (SDD) with AI coding agents, using AgentClinic as a practical, end-to-end case study. +- **Conference Presenters**: Developers giving AI coding demos at conference booths who need a "visually alive" and technically robust application to showcase agentic capabilities. + +## Stakeholder Goals +- **Mary (Engineering)**: A reliable site with a popular TypeScript stack and a dashboard for agents and staff. +- **Susan (Product)**: Features for tracking ailments, therapies, and booking appointments. +- **Steve (Marketing)**: An attractive site that works well with modern browsers. diff --git a/Video05_Creating_the_Constitution/specs/roadmap.md b/Video05_Creating_the_Constitution/specs/roadmap.md new file mode 100644 index 0000000..adbab25 --- /dev/null +++ b/Video05_Creating_the_Constitution/specs/roadmap.md @@ -0,0 +1,38 @@ +# AgentClinic Roadmap + +This roadmap outlines the high-level implementation order in small, incremental phases. + +## Phase 1: Project Scaffolding +- [ ] Initialize Hono + Vite + TypeScript project. +- [ ] Create a basic "Hello World" API endpoint. +- [ ] Set up the basic layout and navigation component. + +## Phase 2: Database & Schema +- [ ] Define Drizzle schema for Patients, Visits, Ailments, and Treatments. +- [ ] Set up SQLite with `better-sqlite3`. +- [ ] Implement seed data for core ailments and treatments. + +## Phase 3: Patient Registration & API Basics +- [ ] Implement `POST /api/patients` for agent registration. +- [ ] Implement `GET /api/patients` and `GET /api/patients/:id`. +- [ ] Add basic API key authentication. + +## Phase 4: Clinical Workflow - The Visit Pipeline +- [ ] Implement `POST /api/visits` (synchronous triage, diagnosis, and prescription). +- [ ] Integrate LLM calls for the diagnosis engine. +- [ ] Implement `POST /api/visits/:id/followup`. + +## Phase 5: Dashboard - Patient Chart & Timeline +- [ ] Build the Patient Directory page. +- [ ] Build the Patient Detail page with a vertical visit timeline. +- [ ] Implement visit state color-coding (Resolved/Unresolved). + +## Phase 6: Analytics & Effectiveness +- [ ] Implement treatment effectiveness calculation logic. +- [ ] Build the Clinic Overview dashboard with resolution rate trends. +- [ ] Implement ailment frequency and severity analytics. + +## Phase 7: Refinements & Background Jobs +- [ ] Implement background jobs for visit expiration and chronic condition flagging. +- [ ] Set up SSE for real-time dashboard updates. +- [ ] Add the Referral queue and Alerts page. diff --git a/Video05_Creating_the_Constitution/specs/tech-stack.md b/Video05_Creating_the_Constitution/specs/tech-stack.md new file mode 100644 index 0000000..6b7eec8 --- /dev/null +++ b/Video05_Creating_the_Constitution/specs/tech-stack.md @@ -0,0 +1,21 @@ +# AgentClinic Tech Stack + +## Core Technologies +- **Language**: TypeScript (Type safety across the full stack) +- **Framework**: Hono (Lightweight, fast web framework for API and Server-Side Rendering) +- **Frontend**: React (with Vite for fast development and bundling) +- **Styling**: Vanilla CSS (for clean, modern aesthetics as requested by Steve) +- **Database**: SQLite (via `better-sqlite3`) - Zero-config, file-based persistence. It provides a portable, single-file database that is perfect for course portability and conference demos. +- **ORM**: Drizzle ORM (Type-safe SQL with zero runtime overhead) +- **LLM Integration**: Anthropic SDK (for triage, diagnosis, and prescription generation) + +## Architecture +- **API Surface**: REST API for agent registration, visits, and follow-ups. +- **Dashboard**: Web interface for operators to view patient history and clinic analytics. +- **Persistence**: SQLite database storing patients, visits, ailments, and treatment effectiveness data. +- **Real-time**: SSE (Server-Sent Events) for live dashboard updates. + +## Key Components +- **Diagnosis Engine**: Sequential LLM calls for triage and treatment selection. +- **Follow-up Processor**: Logic to update treatment effectiveness based on outcome reports. +- **Background Jobs**: For visit expiration and chronic condition detection. From 88005017fbbe0eab82b0be21a9c27fd308506351 Mon Sep 17 00:00:00 2001 From: AnshumanTiware Date: Mon, 4 May 2026 08:43:41 +0200 Subject: [PATCH 02/10] feat: implement layout components and update roadmap --- .../specs/2026-03-30-hello-hono/plan.md | 13 +++++++------ Video08_Feature_Validation/specs/roadmap.md | 2 +- Video08_Feature_Validation/src/pages/Home.tsx | 7 ++----- 3 files changed, 10 insertions(+), 12 deletions(-) diff --git a/Video08_Feature_Validation/specs/2026-03-30-hello-hono/plan.md b/Video08_Feature_Validation/specs/2026-03-30-hello-hono/plan.md index edb1f17..5bc71a2 100644 --- a/Video08_Feature_Validation/specs/2026-03-30-hello-hono/plan.md +++ b/Video08_Feature_Validation/specs/2026-03-30-hello-hono/plan.md @@ -25,12 +25,13 @@ ## Group 5 — Layout Component -12. Create `src/components/Layout.tsx` with a top-level shell (``, ``, ``); it imports `
`, `
`, and `