# 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**:

```bash
# 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**:

```bash
# 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)