Curaway — Spec-Driven Development¶

Why specs?¶

Every feature gets a spec before code is written. Specs are not documentation — they are contracts that define what the system must do, why, and how to verify it.

Structure¶

Each spec follows three sections:

Rules¶

1. No branch without a spec file committed first.
2. Specs are living documents — update them when implementation reveals new constraints.
3. Assertions are pass/fail. If the Langfuse trace or system behavior matches the assertion, it works. If not, it's a bug.
4. Keep specs scoped. One feature per file. If a spec grows beyond ~80 lines, split it.

Naming¶

specs/<feature-slug>.md

Examples: sse-upload-progress.md, intake-agent.md, timezone-conversion.md

Workflow¶

1. Write spec → commit to branch
2. Implement against spec tasks (in order)
3. Verify assertions (manual or automated)
4. Update spec if implementation diverged (with a note on why)
5. Merge

Curaway Platform — Specs & Implementation Guide¶

MVP Use Case: Clinical Match Engine v1 Upload Medical Report → AI Clinical Understanding → FHIR Record → Provider Match → Explainable Reasoning

How This Directory Works¶

sdd-mvp/ — Software Design Documents (The What)¶

Modular markdown specs, one file per domain. Claude Code reads the relevant spec file(s) at the start of each session for context. Each file is self-contained, version-controlled, and updated surgically per session.

ai-steer/ — Implementation Session Guides (The How)¶

Paste-ready Claude Code prompts, each covering one implementation session across both repos. Each steer doc references its spec file(s) for context and includes a verification checklist.

deferred/ — Design-Complete, Implementation-Deferred Specs¶

Full design specs for features that are architecturally scoped but not yet scheduled for implementation. Each spec has a clear dependency chain and effort estimate. When ready to build, the spec moves into active implementation with an accompanying steer doc.

SDD Spec Index¶

AI Steer Doc Index (Implementation Order)¶

Repos¶

Demo Context¶

• Patient: Aisha (UAE, Arabic-speaking, TKR case ICD M17.11)
• Tenant: tenant-apollo-001
• Procedure: Total Knee Replacement (CPT 27447), Kellgren-Lawrence Grade 4
• Comorbidities: Type 2 diabetes (E11), mild hypertension (I10)