morethanadiagnosis-hub/.github/AI_HANDOFF.md

AI Collaborator Handoff: OpenSpec Baseline Proposals

Session ID: 01VV1HE36eVggi1CwLFF6WKf Date: 2025-11-17 AI Agent: Claude (Sonnet 4.5) Branch: claude/openspec-baseline-proposals-01VV1HE36eVggi1CwLFF6WKf

Session Summary

This session initialized the OpenSpec governance structure for the morethanadiagnosis.com community hub and created four foundational baseline proposals.

What Was Accomplished

1. OpenSpec Repository Structure

   • Scaffolded complete OpenSpec directory structure
   • Created project conventions (openspec/project.md)
   • Defined AI slash commands workflow (openspec/ai-commands.md)
   • Established proposal template (openspec/templates/proposal-template.md)

2. Four Baseline Proposals Created

   • ✅ Architecture Baseline → openspec/changes/2025-11-17-architecture-baseline/proposal.md
   • ✅ Privacy & Compliance Baseline → openspec/changes/2025-11-17-privacy-compliance-baseline/proposal.md
   • ✅ Accessibility Baseline → openspec/changes/2025-11-17-accessibility-baseline/proposal.md
   • ✅ Wix Migration Plan → openspec/changes/2025-11-17-wix-migration-plan/proposal.md

3. GitHub Workflow Enhancements

   • ✅ PR template with OpenSpec compliance checklist (.github/pull_request_template.md)
   • ✅ CODEOWNERS for automated review routing (.github/CODEOWNERS)
   • ✅ AI Handoff documentation (this file)

4. Git Workflow

   • ✅ Branch created and pushed: claude/openspec-baseline-proposals-01VV1HE36eVggi1CwLFF6WKf
   • 🔄 PR ready to be created (see instructions below)

Current State

Branch Status

Branch: claude/openspec-baseline-proposals-01VV1HE36eVggi1CwLFF6WKf
Status: Pushed to remote
Commits: 2
  - cd53606 chore: OpenSpec scaffold
  - 36fb186 chore(openspec): seed initial proposals

Files Changed

.github/CODEOWNERS                                          # NEW
.github/pull_request_template.md                           # NEW
.github/AI_HANDOFF.md                                      # NEW (this file)
openspec/README.md                                          # NEW
openspec/project.md                                         # NEW
openspec/ai-commands.md                                     # NEW
openspec/templates/proposal-template.md                     # NEW
openspec/specs/*.md                                         # NEW (10 spec files)
openspec/changes/2025-11-17-architecture-baseline/          # NEW
openspec/changes/2025-11-17-privacy-compliance-baseline/    # NEW
openspec/changes/2025-11-17-accessibility-baseline/         # NEW
openspec/changes/2025-11-17-wix-migration-plan/             # NEW

Next Steps

Immediate Actions Required (Human)

1. Create Pull Request

   • Visit: https://github.com/fullsizemalt/morethanadiagnosis-hub/pull/new/claude/openspec-baseline-proposals-01VV1HE36eVggi1CwLFF6WKf
   • Use title: OpenSpec Baseline Proposals: Architecture, Privacy/Compliance, Accessibility, and Wix Migration
   • Copy PR description from the comprehensive template prepared by Claude
   • Base branch: main

2. Request Reviews

   • Tag domain experts for each proposal:
     • Architecture: security, mobile, web, backend teams
     • Privacy/Compliance: compliance, security teams
     • Accessibility: accessibility team
     • Wix Migration: data, compliance teams

3. Review & Approve

   • Each proposal needs approval from its domain reviewers
   • Use GitHub review comments to address questions
   • Mark proposals as approved in PR conversation

Follow-Up Actions (AI or Human)

Once proposals are approved, execute the apply phase:

# For each approved proposal, run:
/apply spec=openspec/specs/architecture.md pr=<PR_LINK>
/apply spec=openspec/specs/privacy-compliance.md pr=<PR_LINK>
/apply spec=openspec/specs/accessibility.md pr=<PR_LINK>
/apply spec=openspec/specs/migration-wix.md pr=<PR_LINK>

After applying, execute the archive phase:

# Mark each proposal as complete:
/archive reason="accepted and applied to spec" link=<PR_LINK>

AI Collaboration Context

OpenSpec Workflow Rules

CRITICAL: All AI agents must follow these rules:

1. Lifecycle Adherence

   • ONLY follow: propose → review → apply → archive
   • NO code changes without an approved spec link
   • ALL proposals must use the template in openspec/templates/proposal-template.md

2. Compliance Gates

   • Accessibility: WCAG 2.2 AA+ mandatory
   • Privacy: HIPAA/GDPR controls for PHI/PII
   • Security: No PHI/PII in logs, proper encryption, auth
   • Platform Parity: Android/iOS/Web feature parity

3. Slash Commands

   • Use /review areas=... to request domain reviews
   • Use /apply spec=... to merge approved proposals into specs
   • Use /archive link=... to close proposals with traceability

4. File Structure

   • Proposals: openspec/changes/YYYY-MM-DD-title/proposal.md
   • Applied specs: openspec/specs/[domain].md
   • Never modify specs directly; always go through proposal → apply flow

Key Files to Anchor

When resuming work, AI agents should read these files first:

1. Project Context

   • openspec/project.md - Repository conventions and guardrails
   • openspec/ai-commands.md - Slash command reference
   • openspec/README.md - OpenSpec overview

2. Current Proposals

   • openspec/changes/2025-11-17-*/proposal.md - The four baseline proposals

3. Target Specs (will be updated via /apply)

   • openspec/specs/architecture.md
   • openspec/specs/privacy-compliance.md
   • openspec/specs/accessibility.md
   • openspec/specs/migration-wix.md

Domain Areas

When proposals reference review areas, map them to these domains:

Area	Scope	Key Concerns
accessibility	WCAG 2.2 AA+, screen readers, keyboard nav	VoiceOver/TalkBack parity, contrast, dynamic type
compliance	HIPAA/GDPR, PHI/PII, DSRs	Data classification, retention, consent
security	Auth, encryption, OWASP	OAuth2/OIDC, TLS 1.3, no injection vulns
mobile	Android/iOS apps	Platform parity, native components
web	Web frontend	Responsive, semantic HTML, browser compat
backend	APIs, services, databases	API standards, data models, migrations
data	Migrations, imports, ETL	Idempotency, validation, rollback

Technical Decisions Made

Architecture

• Modular domain-driven design with clear boundaries
• API-first approach using OpenAPI specifications
• OAuth2/OIDC for authentication (not yet implemented, just specified)
• Platform parity mandate: Android/iOS/Web must have equivalent features

Privacy & Compliance

• Three data classes: Public, PII, PHI
• Encryption: TLS 1.3 in transit, AES-256 at rest
• Access control: RBAC + ABAC where needed
• Logging: Structured, no PHI/PII, with redaction
• DSR workflows: Export, deletion, consent management

Accessibility

• WCAG 2.2 AA+ as the baseline standard
• Assistive tech testing: VoiceOver, TalkBack, NVDA/JAWS required
• Platform-specific guidance: iOS, Android, Web have tailored requirements
• CI automation: axe (web), lint rules (mobile)

Migration

• Wix content inventory as first step
• Idempotent import jobs to prevent duplicates
• Redirect management to preserve SEO and user bookmarks
• Data classification during migration to respect privacy rules

Open Questions & Decisions Needed

These questions are documented in the proposals and need stakeholder input:

1. Architecture Baseline

   • React Native/Expo vs Flutter for mobile?
   • Next.js vs Flutter Web for web platform?
   • Backend framework choice (not specified yet)?

2. Privacy & Compliance

   • Key management service vendor?
   • SIEM/logging platform choice?
   • Subprocessor list and agreements?

3. Accessibility

   • Brand-level design system decisions (colors, typography)?
   • Accessibility testing service/vendor?

4. Wix Migration

   • Timeline and rollout phases?
   • Content freeze date?
   • Stakeholder sign-off process?

Testing & Validation Strategy

Automated Checks (to be implemented)

• OpenAPI linting for API specs
• axe for web accessibility
• React Native/Flutter lint rules for mobile accessibility
• Data classification linter for PHI/PII detection in code
• Log redaction tests to prevent leaks

Manual Review Requirements

• Accessibility smoke tests with assistive tech before each release
• Compliance review for any PHI/PII-touching changes
• Security review for auth, encryption, and sensitive data flows

Resources & References

OpenSpec Standard

• Official spec: https://github.com/Fission-AI/OpenSpec
• This implementation follows OpenSpec conventions

Compliance Standards

• WCAG 2.2: https://www.w3.org/WAI/WCAG22/quickref/
• HIPAA Security Rule: https://www.hhs.gov/hipaa/for-professionals/security/
• GDPR: https://gdpr.eu/

Project Context

• Website: https://morethanadiagnosis.com
• Purpose: Multi-platform community hub for chronically/terminally ill individuals
• Platforms: Android, iOS, Web (feature parity required)

Communication Protocols

For AI Agents Resuming Work

1. Read this handoff first to understand current state
2. Check PR status at the GitHub URL above
3. Read the four proposals to understand baseline requirements
4. Follow OpenSpec lifecycle strictly - no shortcuts
5. Ask for human clarification if domain decisions are needed

For Human Reviewers

1. Review each proposal independently using the /review areas=... commands
2. Leave GitHub PR comments for questions or requested changes
3. Approve when satisfied with the proposal content
4. Notify AI or execute /apply when ready to merge into specs

For Stakeholders

• All foundational decisions are documented in the proposals
• Open questions are clearly marked in each proposal
• Changes follow a transparent, traceable process
• Compliance and accessibility are enforced at the process level

Version History

Date	Session ID	Agent	Changes
2025-11-17	01VV1HE36eVggi1CwLFF6WKf	Claude Sonnet 4.5	Initial OpenSpec setup, 4 baseline proposals, GitHub workflow enhancements

---

Status: Ready for PR creation and review Next AI Agent: Should create the PR using the URL above, or wait for human to create it and then monitor for approvals to execute /apply phase. Blockers: None - awaiting PR creation and reviews Estimated Time to Apply Phase: Depends on review cycle (1-7 days typical)