social-app/docs/plans/2026-03-11-calendar-reminder-metadata-impl.md

Calendar Reminder Metadata Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Add metadata.reminder_minutes end-to-end (frontend/backend/AgentScope), fix detail-page field rendering, and enable local system reminders.

Architecture: Keep calendar schema additive via metadata JSON (no new DB columns). Backend validates and persists reminder_minutes; AgentScope tools accept and pass reminder values; frontend parses/edits/displays reminder and schedules local notifications based on event time.

Tech Stack: Flutter, FastAPI, Pydantic v2, AgentScope toolkit, pytest, flutter_test.

---

Task 1: Backend metadata schema tests first

Files:

• Test: backend/tests/unit/v1/schedule_items/test_schemas.py
• Modify: backend/src/v1/schedule_items/schemas.py

Step 1: Write failing tests

• Add tests for reminder_minutes accepted values (None, 0, 15, 10080)
• Add tests for invalid values (-1, 10081)

Step 2: Run tests to verify RED Run: uv run pytest backend/tests/unit/v1/schedule_items/test_schemas.py -q Expected: FAIL for missing/invalid field support.

Step 3: Minimal implementation

• Add reminder_minutes: int | None = Field(default=None, ge=0, le=10080) to ScheduleItemMetadata

Step 4: Verify GREEN Run: uv run pytest backend/tests/unit/v1/schedule_items/test_schemas.py -q Expected: PASS.

Task 2: Backend service mapping tests first

Files:

• Test: backend/tests/unit/v1/schedule_items/test_service.py
• Modify: backend/src/v1/schedule_items/service.py

Step 1: Write failing tests

• Assert create/update extra_metadata includes reminder_minutes

Step 2: Run RED Run: uv run pytest backend/tests/unit/v1/schedule_items/test_service.py -q

Step 3: Minimal implementation

• Ensure model_dump path includes new field naturally, no special-case stripping

Step 4: Verify GREEN Run: uv run pytest backend/tests/unit/v1/schedule_items/test_service.py -q

Task 3: AgentScope custom tool tests first

Files:

• Test: backend/tests/unit/core/agentscope/test_calendar_tools.py
• Modify: backend/src/core/agentscope/tools/custom/calendar.py

Step 1: Write failing tests

• calendar_write maps reminder_minutes to tool args reminderMinutes
• rejects out-of-range reminder values

Step 2: Run RED Run: uv run pytest backend/tests/unit/core/agentscope/test_calendar_tools.py -q

Step 3: Minimal implementation

• Add reminder_minutes parameter and validation in calendar_write
• Add mapping into tool_args

Step 4: Verify GREEN Run: uv run pytest backend/tests/unit/core/agentscope/test_calendar_tools.py -q

Task 4: CrewAI calendar bridge tests first

Files:

• Test: backend/tests/unit/core/agent/test_mutate_calendar_event_tool.py
• Modify: backend/src/core/agent/infrastructure/crewai/tools/create_calendar_event_tool.py

Step 1: Write failing tests

• create path maps reminderMinutes -> metadata.reminder_minutes
• update path can patch reminder_minutes

Step 2: Run RED Run: uv run pytest backend/tests/unit/core/agent/test_mutate_calendar_event_tool.py -q

Step 3: Minimal implementation

• Extend _resolve_metadata, _execute_update, and _event_payload

Step 4: Verify GREEN Run: uv run pytest backend/tests/unit/core/agent/test_mutate_calendar_event_tool.py -q

Task 5: Frontend model/API tests first

Files:

• Test: apps/test/features/calendar/data/calendar_api_test.dart
• Modify: apps/lib/features/calendar/data/models/schedule_item_model.dart

Step 1: Write failing tests

• parse metadata.reminder_minutes
• serialize metadata.reminder_minutes in create/update payload

Step 2: Run RED Run: cd apps && flutter test test/features/calendar/data/calendar_api_test.dart

Step 3: Minimal implementation

• add reminderMinutes in model + json mapping

Step 4: Verify GREEN Run: cd apps && flutter test test/features/calendar/data/calendar_api_test.dart

Task 6: Detail UI rendering fix tests first

Files:

• Create/Test: apps/test/features/calendar/ui/screens/calendar_event_detail_screen_test.dart
• Modify: apps/lib/features/calendar/ui/screens/calendar_event_detail_screen.dart

Step 1: Write failing widget tests

• reminder text for null/0/15
• metadata raw block no longer visible

Step 2: Run RED Run: cd apps && flutter test test/features/calendar/ui/screens/calendar_event_detail_screen_test.dart

Step 3: Minimal implementation

• remove raw metadata section
• render structured reminder text

Step 4: Verify GREEN Run: cd apps && flutter test test/features/calendar/ui/screens/calendar_event_detail_screen_test.dart

Task 7: Local notification service integration

Files:

• Create: apps/lib/core/notifications/local_notification_service.dart
• Modify: apps/lib/core/di/injection.dart
• Modify: apps/lib/main.dart
• Modify: apps/lib/features/calendar/data/services/mock_calendar_service.dart
• Modify: apps/lib/features/calendar/ui/widgets/create_event_sheet.dart

Step 1: Add local notification dependencies

• Update apps/pubspec.yaml with flutter_local_notifications

Step 2: Implement scheduling API

• init permissions
• schedule/update/cancel by event id
• vibration enabled for Android notification details

Step 3: Integrate into calendar flow

• create/update/delete hooks call notification service
• startup rebuild for future events

Step 4: Verify manually

• create reminder 1-2 min event and verify system notification + vibration

Task 8: Full verification

Step 1: Backend checks Run:

• uv run pytest backend/tests/unit/v1/schedule_items/test_schemas.py -q
• uv run pytest backend/tests/unit/v1/schedule_items/test_service.py -q
• uv run pytest backend/tests/unit/core/agentscope/test_calendar_tools.py -q
• uv run pytest backend/tests/unit/core/agent/test_mutate_calendar_event_tool.py -q

Step 2: Frontend checks Run:

• cd apps && flutter test test/features/calendar/data/calendar_api_test.dart
• cd apps && flutter test test/features/calendar/ui/screens/calendar_event_detail_screen_test.dart
• cd apps && flutter analyze lib/features/calendar lib/core/notifications

Step 3: Manual verification evidence

• create/update/delete reminder event and capture observed notification behavior.