From f1f00d56170548a7ab25a11976066593a0e63102 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 27 Feb 2026 16:27:33 +0000 Subject: [PATCH] docs(openspec): add change artifacts for email-reply-to-addresses Specifies Reply-To header behavior for the two outbound email types: - Confirmation emails to parents: Reply-To set to admin address (spielgruppen@familien-verein.ch) - Registration notification emails to leaders/admin: Reply-To set to parent's email https://claude.ai/code/session_014NynTjALA5TeP85mbr5ZA8 --- .../email-reply-to-addresses/.openspec.yaml | 2 + .../email-reply-to-addresses/design.md | 47 +++++++++++++++++++ .../email-reply-to-addresses/proposal.md | 21 +++++++++ .../specs/email-channel/spec.md | 15 ++++++ .../specs/registration-notifications/spec.md | 18 +++++++ .../changes/email-reply-to-addresses/tasks.md | 19 ++++++++ 6 files changed, 122 insertions(+) create mode 100644 openspec/changes/email-reply-to-addresses/.openspec.yaml create mode 100644 openspec/changes/email-reply-to-addresses/design.md create mode 100644 openspec/changes/email-reply-to-addresses/proposal.md create mode 100644 openspec/changes/email-reply-to-addresses/specs/email-channel/spec.md create mode 100644 openspec/changes/email-reply-to-addresses/specs/registration-notifications/spec.md create mode 100644 openspec/changes/email-reply-to-addresses/tasks.md diff --git a/openspec/changes/email-reply-to-addresses/.openspec.yaml b/openspec/changes/email-reply-to-addresses/.openspec.yaml new file mode 100644 index 0000000..d1c6cc6 --- /dev/null +++ b/openspec/changes/email-reply-to-addresses/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-02-27 diff --git a/openspec/changes/email-reply-to-addresses/design.md b/openspec/changes/email-reply-to-addresses/design.md new file mode 100644 index 0000000..fb1d54e --- /dev/null +++ b/openspec/changes/email-reply-to-addresses/design.md @@ -0,0 +1,47 @@ +## Context + +The system sends emails in two directions with two different purposes: + +- **Outbound to parents**: The AI agent sends conversational replies and, upon registration completion, a confirmation email summarising the registration and next steps. +- **Outbound to admins/leaders**: The system sends a notification email to the relevant playgroup leader(s) and Markus Graf (CC) immediately after a registration is completed. + +Email clients use the `Reply-To` header (falling back to `From`) to determine where a reply is directed. Without explicit `Reply-To` headers, all replies from both parents and admins flow back to the registration system's inbox — which is correct for ongoing conversation but wrong for post-completion follow-up. + +## Goals / Non-Goals + +**Goals:** +- Ensure parent replies to completion confirmation emails reach the admin (Markus Graf) rather than the agent pipeline +- Ensure admin/leader replies to registration notification emails reach the registering parent directly +- Formally specify `Reply-To` behavior in the relevant capability specs + +**Non-Goals:** +- Changing the `From` address of any email +- Modifying conversational email behavior (mid-registration agent ↔ parent exchanges — these correctly use the registration address as both From and effective reply target) +- Introducing any new email addresses beyond what is already configured + +## Decisions + +### 1. Confirmation Email Reply-To: Admin Address + +**Decision**: Set `Reply-To: spielgruppen@familien-verein.ch` (Markus Graf) on all confirmation emails sent to parents after registration completion. + +**Rationale**: Once registration is complete, the conversation is over. Any parent reply is a human follow-up question — it should reach a human admin, not re-enter the agent pipeline. Markus Graf is the designated central admin contact and is already CC'd on all notifications. + +**Alternatives considered**: +- No Reply-To (default to From): Parent replies re-enter the agent inbox and may trigger unwanted agent responses post-completion. +- Reply-To the relevant playgroup leader (Andrea/Barbara): More targeted, but leaders vary by registration type and parents may not know who they're reaching. The central admin address is simpler and consistent. + +### 2. Notification Email Reply-To: Parent Address + +**Decision**: Set `Reply-To: ` on all registration notification emails sent to admins/leaders. + +**Rationale**: The primary reason admins reply to a notification is to contact the parent (e.g., to confirm a spot, ask a clarifying question, or provide further instructions). Pre-filling Reply-To with the parent's address eliminates a copy-paste step and reduces errors. This is already noted informally in `notification-template.md` — this change formalises it as a spec requirement. + +**Alternatives considered**: +- No Reply-To (default to From/registration inbox): Admins must manually copy the parent's email to reply, adding friction. + +## Risks / Trade-offs + +**Admin confirmation email replies go to Markus, not directly to the leader**: For outdoor registrations, the leader is Barbara Gross, but parent replies to confirmation go to Markus Graf. This is acceptable — Markus can forward as needed, and having a single consistent Reply-To is simpler than routing by playgroup type. + +**Mid-registration vs. post-registration distinction**: Conversational emails (mid-registration) should NOT set Reply-To to the admin — they must continue flowing back to the registration inbox so the agent can process them. The implementation must apply the admin Reply-To only to the final confirmation email, not to all outbound agent emails. diff --git a/openspec/changes/email-reply-to-addresses/proposal.md b/openspec/changes/email-reply-to-addresses/proposal.md new file mode 100644 index 0000000..94e253f --- /dev/null +++ b/openspec/changes/email-reply-to-addresses/proposal.md @@ -0,0 +1,21 @@ +## Why + +The system sends two distinct types of emails to different audiences with different needs for follow-up communication. Currently, the Reply-To behavior for these emails is either unspecified or inconsistent: + +1. **Confirmation emails to parents** — sent by the agent after registration is complete. If a parent replies to this email, that reply should reach the admin (Markus Graf), not bounce back into the agent's inbox for further automated processing. + +2. **Registration notification emails to playgroup leaders/admins** — sent to Andrea Sigrist, Barbara Gross, and Markus Graf when a new registration is submitted. If an admin wants to follow up with the parent directly, their reply must go to the parent's email, not back to the registration system. + +Without explicit Reply-To configuration, email clients will default to replying to the From address (the registration system's email). This creates confusion: parent replies to confirmation emails enter the agent pipeline instead of reaching a human admin, and admin replies to notification emails go to the registration inbox rather than the parent. + +## What Changes + +- **Confirmation emails**: Add a `Reply-To` header set to the admin email address (`spielgruppen@familien-verein.ch`) so parent replies reach a human directly +- **Admin notification emails**: Confirm and formally specify that `Reply-To` is set to the parent's email address so admins can respond to parents directly from their email client + +## Capabilities + +### Modified Capabilities + +- `email-channel`: Add Reply-To specification for confirmation emails sent to parents after registration completion +- `registration-notifications`: Formally specify Reply-To for admin notification emails (parent's email address) diff --git a/openspec/changes/email-reply-to-addresses/specs/email-channel/spec.md b/openspec/changes/email-reply-to-addresses/specs/email-channel/spec.md new file mode 100644 index 0000000..592c6d9 --- /dev/null +++ b/openspec/changes/email-reply-to-addresses/specs/email-channel/spec.md @@ -0,0 +1,15 @@ +## MODIFIED Requirements + +### Requirement: Confirmation email sets Reply-To to admin address + +The system SHALL set the `Reply-To` header to the admin email address (`spielgruppen@familien-verein.ch`) on the registration completion confirmation email sent to the parent. + +#### Scenario: Parent replies to confirmation email +- **WHEN** the agent sends a registration completion confirmation email to a parent +- **THEN** the email SHALL include a `Reply-To` header set to `spielgruppen@familien-verein.ch` +- **AND** a parent reply SHALL be delivered to the admin, not to the registration system's inbox + +#### Scenario: Mid-registration emails are unaffected +- **WHEN** the agent sends a conversational email during an ongoing registration (not the final confirmation) +- **THEN** the email SHALL NOT set `Reply-To` to the admin address +- **AND** parent replies SHALL continue to be routed back to the registration system for processing diff --git a/openspec/changes/email-reply-to-addresses/specs/registration-notifications/spec.md b/openspec/changes/email-reply-to-addresses/specs/registration-notifications/spec.md new file mode 100644 index 0000000..e42cea2 --- /dev/null +++ b/openspec/changes/email-reply-to-addresses/specs/registration-notifications/spec.md @@ -0,0 +1,18 @@ +## MODIFIED Requirements + +### Requirement: Notification email sets Reply-To to parent address + +The system SHALL set the `Reply-To` header to the registering parent's email address on all registration notification emails sent to playgroup leaders and the admin. + +#### Scenario: Leader replies to notification email +- **WHEN** a registration notification email is sent to a playgroup leader (Andrea Sigrist or Barbara Gross) +- **THEN** the email SHALL include a `Reply-To` header set to the parent's email address (`registration.parentGuardian.email`) +- **AND** a leader reply SHALL be delivered directly to the parent + +#### Scenario: Admin (CC) replies to notification email +- **WHEN** Markus Graf replies to a registration notification email (received as CC) +- **THEN** the reply SHALL be delivered directly to the parent's email address + +#### Scenario: Reply-To applies to all notification routing types +- **WHEN** a notification is sent for an indoor-only, outdoor-only, or both registration +- **THEN** all recipient copies (To and CC) SHALL have `Reply-To` set to the parent's email address diff --git a/openspec/changes/email-reply-to-addresses/tasks.md b/openspec/changes/email-reply-to-addresses/tasks.md new file mode 100644 index 0000000..1bf2495 --- /dev/null +++ b/openspec/changes/email-reply-to-addresses/tasks.md @@ -0,0 +1,19 @@ +## 1. Confirmation Email Reply-To (Email Channel) + +- [ ] 1.1 Identify where the registration completion confirmation email is constructed in `src/` (email channel adapter / agent core) +- [ ] 1.2 Add `Reply-To: spielgruppen@familien-verein.ch` header to the confirmation email only (not to mid-registration conversational emails) +- [ ] 1.3 Add a unit test verifying the `Reply-To` header is present on the confirmation email +- [ ] 1.4 Add a unit test verifying mid-registration emails do NOT carry the admin `Reply-To` header + +## 2. Notification Email Reply-To (Registration Notifications) + +- [ ] 2.1 Identify where registration notification emails are constructed and sent +- [ ] 2.2 Set `Reply-To: ` header on all outgoing notification emails (indoor, outdoor, and both routing types) +- [ ] 2.3 Add a unit test verifying the `Reply-To` header equals the parent's email for indoor-only notification +- [ ] 2.4 Add a unit test verifying the `Reply-To` header equals the parent's email for outdoor-only notification +- [ ] 2.5 Add a unit test verifying the `Reply-To` header equals the parent's email when both leaders are notified + +## 3. Verification + +- [ ] 3.1 Run the full test suite and confirm all tests pass +- [ ] 3.2 Manually send a test registration through the email channel and verify reply routing behaves correctly