From 8c05a1706787a6cbaf633759cfed4f42bcba9c8c Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 17 Nov 2025 23:25:47 +0000 Subject: [PATCH] chore(github): add PR template, CODEOWNERS, and AI handoff docs - Add PR template with OpenSpec compliance checklist - Enforces spec-first workflow and lifecycle commands - Includes accessibility, privacy, security gates - Requires platform parity verification - Add CODEOWNERS for automated review routing - Routes a11y changes to accessibility reviewers - Routes PHI/PII changes to compliance + security - Routes API/backend changes to security reviewers - Placeholder @fullsizemalt (expand to teams later) - Add AI_HANDOFF.md for agent collaboration - Documents current session state and decisions - Provides context for future AI collaborators - Lists next steps and open questions --- .github/AI_HANDOFF.md | 277 +++++++++++++++++++++++++++++++ .github/CODEOWNERS | 195 ++++++++++++++++++++++ .github/pull_request_template.md | 119 +++++++++++++ 3 files changed, 591 insertions(+) create mode 100644 .github/AI_HANDOFF.md create mode 100644 .github/CODEOWNERS create mode 100644 .github/pull_request_template.md diff --git a/.github/AI_HANDOFF.md b/.github/AI_HANDOFF.md new file mode 100644 index 0000000..9dc3dff --- /dev/null +++ b/.github/AI_HANDOFF.md @@ -0,0 +1,277 @@ +# 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= +/apply spec=openspec/specs/privacy-compliance.md pr= +/apply spec=openspec/specs/accessibility.md pr= +/apply spec=openspec/specs/migration-wix.md pr= +``` + +After applying, execute the **archive phase**: + +```bash +# Mark each proposal as complete: +/archive reason="accepted and applied to spec" 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) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..3f98385 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,195 @@ +# CODEOWNERS for morethanadiagnosis-hub +# +# This file defines code ownership and automated review routing. +# GitHub will automatically request reviews from the listed owners when files are changed. +# +# Syntax: [path pattern] @owner1 @owner2 @team-name +# +# For more info: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# ============================================================================== +# DEFAULT OWNERS +# ============================================================================== +# All files require at least one review unless more specific rules apply +* @fullsizemalt + +# ============================================================================== +# OPENSPEC GOVERNANCE +# ============================================================================== +# OpenSpec core files require architecture and compliance sign-off +/openspec/project.md @fullsizemalt +/openspec/ai-commands.md @fullsizemalt +/openspec/README.md @fullsizemalt + +# All proposals require initial review from program leads +/openspec/changes/ @fullsizemalt + +# Proposal template changes require broad consensus +/openspec/templates/ @fullsizemalt + +# ============================================================================== +# OPENSPEC SPECS (Applied/Approved Specifications) +# ============================================================================== +# Architecture specs require architecture and security review +/openspec/specs/architecture.md @fullsizemalt + +# Privacy/compliance specs MUST be reviewed by compliance and security teams +/openspec/specs/privacy-compliance.md @fullsizemalt +/openspec/specs/data-model.md @fullsizemalt +/openspec/specs/migration-wix.md @fullsizemalt + +# Accessibility specs require accessibility specialist review +/openspec/specs/accessibility.md @fullsizemalt + +# Feature specs require relevant domain owners +/openspec/specs/feature-*.md @fullsizemalt + +# ============================================================================== +# GITHUB WORKFLOWS & CONFIGURATION +# ============================================================================== +# Changes to CI/CD, automation, and GitHub config require infra review +/.github/workflows/ @fullsizemalt +/.github/CODEOWNERS @fullsizemalt +/.github/pull_request_template.md @fullsizemalt +/.github/ISSUE_TEMPLATE/ @fullsizemalt + +# ============================================================================== +# MOBILE PLATFORMS +# ============================================================================== +# Android changes require mobile and accessibility review +/android/ @fullsizemalt +/android/**/accessibility/ @fullsizemalt + +# iOS changes require mobile and accessibility review +/ios/ @fullsizemalt +/ios/**/Accessibility/ @fullsizemalt + +# React Native/Expo (if used) requires mobile review +/mobile/ @fullsizemalt +/app/ @fullsizemalt + +# ============================================================================== +# WEB PLATFORM +# ============================================================================== +# Web frontend changes require web and accessibility review +/web/ @fullsizemalt +/frontend/ @fullsizemalt +/src/components/ @fullsizemalt + +# Accessibility-specific web components require accessibility review +/web/**/accessibility/ @fullsizemalt +/web/**/a11y/ @fullsizemalt +/src/components/**/*Accessible* @fullsizemalt + +# ============================================================================== +# BACKEND & APIs +# ============================================================================== +# API changes require backend and security review +/api/ @fullsizemalt +/backend/ @fullsizemalt +/server/ @fullsizemalt + +# Authentication/authorization changes require security review +/api/auth/ @fullsizemalt +/backend/auth/ @fullsizemalt +/server/middleware/auth* @fullsizemalt + +# Data access and models require data and compliance review +/api/models/ @fullsizemalt +/backend/models/ @fullsizemalt +/server/db/ @fullsizemalt +/database/ @fullsizemalt +/migrations/ @fullsizemalt + +# ============================================================================== +# COMPLIANCE-SENSITIVE AREAS +# ============================================================================== +# PHI/PII handling code requires compliance AND security review +/**/*phi* @fullsizemalt +/**/*pii* @fullsizemalt +/**/*health* @fullsizemalt +/**/*medical* @fullsizemalt +/**/*hipaa* @fullsizemalt +/**/*gdpr* @fullsizemalt + +# Logging and telemetry (must not leak PHI/PII) +/**/logging/ @fullsizemalt +/**/telemetry/ @fullsizemalt +/**/analytics/ @fullsizemalt + +# Data export/import (DSR workflows) +/**/export/ @fullsizemalt +/**/import/ @fullsizemalt +/**/migration/ @fullsizemalt + +# ============================================================================== +# DESIGN SYSTEM & ACCESSIBILITY COMPONENTS +# ============================================================================== +# Design system changes require design and accessibility review +/design-system/ @fullsizemalt +/packages/ui/ @fullsizemalt +/shared/components/ @fullsizemalt + +# ============================================================================== +# DOCUMENTATION +# ============================================================================== +# User-facing documentation requires accessibility review (plain language) +/docs/ @fullsizemalt +/README.md @fullsizemalt +/CONTRIBUTING.md @fullsizemalt + +# API documentation requires backend review +/docs/api/ @fullsizemalt + +# ============================================================================== +# INFRASTRUCTURE & SECURITY +# ============================================================================== +# Infrastructure as code requires infra and security review +/terraform/ @fullsizemalt +/infrastructure/ @fullsizemalt +/.infra/ @fullsizemalt +/k8s/ @fullsizemalt +/kubernetes/ @fullsizemalt + +# Docker configurations require infra review +/Dockerfile* @fullsizemalt +/docker-compose*.yml @fullsizemalt +/.dockerignore @fullsizemalt + +# Security configurations require security review +/security/ @fullsizemalt +/.security/ @fullsizemalt +/SECURITY.md @fullsizemalt + +# Dependency changes (potential security impact) +/package.json @fullsizemalt +/package-lock.json @fullsizemalt +/yarn.lock @fullsizemalt +/Gemfile @fullsizemalt +/Gemfile.lock @fullsizemalt +/Pipfile @fullsizemalt +/requirements.txt @fullsizemalt +/build.gradle @fullsizemalt +/Podfile @fullsizemalt + +# ============================================================================== +# TESTING +# ============================================================================== +# Accessibility test changes require accessibility review +/**/*.a11y.test.* @fullsizemalt +/**/*.accessibility.test.* @fullsizemalt +/tests/accessibility/ @fullsizemalt +/e2e/accessibility/ @fullsizemalt + +# ============================================================================== +# NOTES FOR FUTURE EXPANSION +# ============================================================================== +# As the team grows, replace @fullsizemalt with actual team handles: +# - @morethanadiagnosis/accessibility-team +# - @morethanadiagnosis/compliance-team +# - @morethanadiagnosis/security-team +# - @morethanadiagnosis/mobile-team +# - @morethanadiagnosis/web-team +# - @morethanadiagnosis/backend-team +# - @morethanadiagnosis/data-team +# - @morethanadiagnosis/infra-team diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..da8b9ce --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,119 @@ +# Pull Request + +## Description + + +## OpenSpec Compliance + +**Related Spec/Proposal:** + +- [ ] This PR links to an approved OpenSpec change proposal +- [ ] OR this is an OpenSpec proposal itself (propose phase) + +**Spec File:** `openspec/specs/[filename].md` or `openspec/changes/[date-title]/proposal.md` + +## OpenSpec Lifecycle Commands + + + +**For Proposals (propose phase):** +``` +/review areas=[accessibility,compliance,security,mobile,web,backend,data] +``` + +**For Applying Specs (apply phase):** +``` +/apply spec=openspec/specs/[target-file].md pr=[this PR link] +``` + +**For Archiving (archive phase):** +``` +/archive reason="[accepted|rejected|superseded]" link=[PR link] +``` + +## Type of Change + + +- [ ] OpenSpec proposal (new change proposal) +- [ ] OpenSpec spec update (applying an approved proposal) +- [ ] Feature implementation (requires approved spec link) +- [ ] Bug fix (link to issue) +- [ ] Documentation +- [ ] Infrastructure/tooling +- [ ] Data migration + +## Compliance & Quality Checklist + +### Privacy & Data Protection +- [ ] No new PHI/PII fields introduced OR properly classified in data-model.md +- [ ] No PHI/PII logged or exposed in errors/telemetry +- [ ] DSR (Data Subject Rights) impact assessed +- [ ] Encryption requirements met (TLS 1.3 in transit, AES-256 at rest) +- [ ] HIPAA/GDPR compliance verified + +### Accessibility (WCAG 2.2 AA+) +- [ ] Keyboard navigation tested +- [ ] Screen reader tested (VoiceOver/TalkBack for mobile, NVDA/JAWS for web) +- [ ] Color contrast meets 4.5:1 minimum +- [ ] Dynamic type/large fonts supported +- [ ] Reduced motion preferences respected +- [ ] Focus indicators visible +- [ ] Semantic HTML/native components used (web) +- [ ] Accessibility labels provided (mobile) + +### Security +- [ ] Input validation and sanitization implemented +- [ ] No SQL injection, XSS, or command injection vulnerabilities +- [ ] Authentication/authorization properly enforced +- [ ] Rate limiting applied where appropriate +- [ ] Secrets not committed (use env vars or secret management) +- [ ] OWASP Top 10 considerations addressed + +### Platform Parity +- [ ] Feature parity across Android/iOS/Web OR exceptions documented +- [ ] Responsive design tested on multiple screen sizes +- [ ] Cross-browser testing completed (if web) +- [ ] Platform-specific adaptations follow design system + +### Testing +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated (if applicable) +- [ ] E2E tests added/updated (if applicable) +- [ ] Accessibility automated tests passing (axe, lint rules) +- [ ] Manual testing completed + +### Observability +- [ ] Structured logging added (no PHI/PII) +- [ ] Error handling and user-facing messages clear +- [ ] Performance impact assessed +- [ ] Monitoring/alerting considerations documented + +## Migration/Rollout Plan + + +- [ ] No migration needed +- [ ] Migration plan documented in proposal +- [ ] Rollback procedure defined +- [ ] Feature flag strategy defined (if applicable) + +## Screenshots/Demos + + + +## Reviewers Needed + + +- [ ] Accessibility review (@accessibility-team) +- [ ] Compliance review (@compliance-team) +- [ ] Security review (@security-team) +- [ ] Mobile review (@mobile-team) +- [ ] Web review (@web-team) +- [ ] Backend review (@backend-team) +- [ ] Data review (@data-team) + +## Additional Context + + +--- + +**Remember:** All code changes must link to an approved OpenSpec spec. Use OpenSpec lifecycle: **propose → review → apply → archive**