runfoo-org/morethanadiagnosis-hub
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
morethanadiagnosis-hub/.github/AI_HANDOFF.md
Claude 8c05a17067
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
2025-11-17 23:25:47 +00:00

277 lines
10 KiB
Markdown
Raw Blame History

# 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)
Reference in a new issue View git blame Copy permalink