An AI agent spec for interactive spine-health Q&A, structured symptom/pain tracking, MRI/DICOM image review workflows, consultation preparation, and patient-facing reports.
Spine Harmony is a spine-specific AI-agent specification and workspace pattern. It helps individuals ask structured questions about their own spine-health materials, maintain structured symptom and pain diaries, convert user-owned MRI/DICOM files into high-resolution review images for non-clinical organization, prepare for appointments, and draft patient-facing reports for discussion with qualified clinicians.
Important safety warning: Spine Harmony is not medical software, not a medical device, not diagnosis, not treatment guidance, not emergency triage, not radiology interpretation, not clinical decision support, and not a substitute for professional medical care. Do not use it to make or delay medical decisions. For severe, new, progressive, or concerning symptoms, seek qualified medical care or emergency services. See DISCLAIMER.md and TERMS.md.
Spine Harmony provides reusable agent instructions, templates, documentation, and example workflows for building a personal spine-health research assistant around your own files and chosen AI runtime. It should not be assumed to keep medical data local or private once you use an LLM, vision model, hosted agent runtime, cloud workspace, or other external service.
It is intended for:
Spine Harmony is not:
Spine Harmony’s imaging workflow is a core feature. It can help users convert their own MRI/DICOM files into high-resolution review images and contact sheets, then use those images alongside reports, notes, symptom logs, and Q&A to prepare better clinician discussions.
The workflow may include:
The image-review text is generated by the user’s chosen LLM or vision model/runtime. Spine Harmony does not validate that model, certify its outputs, or convert those outputs into clinical advice. Imaging review must not be used instead of radiologist reporting, clinician interpretation, diagnosis, or treatment planning. Avoid wording such as “the MRI proves,” “you have,” “you need,” or “this is safe/reliable/clinically validated.”
DICOM files and derived images may contain personal medical information. Do not commit real imaging files, converted images, metadata dumps, or reports containing real patient information to a public repository.
Concrete conversion instructions and a reference export utility are included in docs/imaging-workflow.md and tools/dicom-export/.
One of Spine Harmony’s core patterns is structured back-and-forth Q&A. Users can ask the agent questions about their own spine-health notes, appointment summaries, imaging-report text, symptom logs, and draft reports.
Good Q&A use cases include:
Q&A outputs are for personal organization and clinician-discussion preparation only. They are not diagnosis, treatment advice, emergency triage, or clinical decision-making. A Spine Harmony agent must never tell a user to start/stop medication, delay care, ignore red flags, accept/reject surgery, or overrule a clinician.
Symptom and pain tracking is a core Spine Harmony feature. The agent can maintain a structured private diary that turns short user check-ins into a longitudinal trend record for clinician discussion.
Useful tracking patterns include:
The goal is not to diagnose the pain source, prove treatment response, or decide treatment. The goal is to preserve accurate daily facts, show cautious patterns over time, and help users ask better questions of qualified clinicians.
Full guidance, templates, and synthetic examples are included in docs/symptom-pain-tracking.md, templates/symptom-tracker.md, and examples/anonymized-symptom-tracking.md.
Spine Harmony reports should be structured, source-grounded, and visually clean. The repo includes explicit guidance for modular patient-facing reports with user-specific headings, such as executive summary, patient profile, longitudinal timeline, symptom mapping, imaging findings, official radiology report, clinical audit, procedure-specific analysis, doctor discussion points, prioritized action plan, and sources.
Use REPORTS.md, docs/report-generation.md, and templates/report.html as the baseline. Reports should use a restrained, professional HTML style: white background, strong hierarchy, card-based sections, clear caveats, print-aware CSS, and no decorative clutter.
If you are new to coding agents and want to run Spine Harmony, start here:
docs/openai-codex.mddocs/claude-code.mddocs/quickstart.mddocs/privacy-model.mdThe recommended novice setup is two folders: keep this public repository as the template/instruction pack, then create a separate private workspace for real medical notes. For OpenAI Codex, copy AGENTS.md into that private folder as AGENTS.md, initialize the private folder as a local-only git repo, and start Codex inside the private folder. For Claude, copy AGENTS.md into the private folder as CLAUDE.md. Both beginner guides give copy-and-paste commands plus no-terminal fallbacks.
Spine Harmony is designed to be runtime-agnostic. It can be adapted to agent systems that support persistent instructions, workspace files, and tool use.
Example target runtimes include:
OpenAI Codex compatibility note: this repository can be used as a project instruction/workspace pack for Codex by keeping AGENTS.md in a private local git workspace and keeping private patient files outside the public repository. Complete beginner instructions are in docs/openai-codex.md.
Claude Code / Claude Cowork compatibility note: this repository can be used as a project instruction/workspace pack for Claude by placing the core instructions in a project-level CLAUDE.md file and keeping private patient files outside version control. Complete beginner instructions are in docs/claude-code.md; broader runtime notes are in docs/runtime-compatibility.md.
.
├── AGENTS.md
├── IDENTITY.md
├── SOUL.md
├── REPORTS.md
├── DISCLAIMER.md
├── PRIVACY.md
├── SECURITY.md
├── TERMS.md
├── TRADEMARKS.md
├── NOTICE
├── CITATION.cff
├── docs/
│ └── symptom-pain-tracking.md
├── templates/
│ └── symptom-tracker.md
└── examples/
└── anonymized-symptom-tracking.md
The public repository contains only generic instructions, templates, and synthetic examples. It does not contain real medical records, imaging, transcripts, or patient identifiers.
However, actual use of Spine Harmony will often involve submitting sensitive medical information to whatever AI/runtime provider the user chooses. If you upload or paste medical records, MRI/DICOM-derived images, radiology reports, clinician letters, symptom logs, or generated reports into an LLM, vision model, hosted agent, chat service, cloud IDE, or cloud storage workflow, that information is not remaining purely local. It may be transmitted to and processed by third-party systems according to their own terms, retention rules, training policies, logging practices, and security controls.
A local workspace protects you from accidentally publishing private files in this repository. It does not by itself guarantee privacy from your chosen model provider or runtime. Users should assume that medical records and imaging shared with an external AI service are being disclosed to that service, and should only do so if they understand and accept the privacy implications.
Do not commit:
Do not deploy Spine Harmony as a public hosted chatbot, patient-facing service, clinical workflow, or tool that accepts real medical records unless appropriate legal, privacy, regulatory, clinical safety, and security review has been completed for the jurisdiction and use case. The open-source repository is a template/specification; hosted medical use is a separate risk category.
Spine Harmony is released under the MIT License.
Please preserve attribution to D2MA Limited when reusing or adapting this project. If you use it in public work, research, clinical-adjacent tooling, or derivative agents, we appreciate a link back to this repository.
Created by D2MA Limited.
Website: https://d2ma.com