coulomb/email-connect
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: register with state hub

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-02 00:36:01 +02:00
parent 4dbf0b074a
commit 23c6a9aef0
4 changed files with 472 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

188
AGENTS.md Normal file
View File

@@ -0,0 +1,188 @@
# email-connect — Agent Instructions
## Repo Identity
**Purpose:** Headless, provider-neutral email communication and evidence service
for sending, tracking, diagnosing, and normalizing email-channel events without
overclaiming delivery, awareness, or result satisfaction.
**Domain:** custodian
**Repo slug:** email-connect
**Topic ID:** `cee7bedf-2b48-46ef-8601-006474f2ad7a`
**Workplan prefix:** `EMAIL-WP-`
---
## Repo Orientation
This repository is currently in planning/specification shape. Treat
`INTENT.md` as the canonical product intent and
`spec/ProductRequirementsDocument.md` as the detailed requirements source until
implementation architecture is added.
Preserve the core principle: email events are evidence, not result
satisfaction. Provider acceptance, MX acceptance, inbox placement, opens,
clicks, replies, complaints, suppressions, and bounces must remain distinct.
Do not collapse them into "delivered", "read", "accepted", or any similar
business conclusion.
Keep the product provider-neutral and adapter-friendly. It should be useful as
a standalone email communication/evidence service and as the reference
`coordination-engine` adapter. It should not drift into newsletter campaign
management, broad marketing automation, or legal/business outcome adjudication.
There is no runtime stack committed yet. Any stack, API, storage, or provider
choice should be introduced through a workplan and anchored in the current
intent/PRD.
---
## State Hub Integration
The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
there is no MCP server for Codex agents.
| Context | URL |
|---------|-----|
| Local workstation | `http://127.0.0.1:8000` |
| Remote via tunnel | `http://127.0.0.1:18000` |
### Orient at session start
```bash
# Offline brief, when present
test -f .custodian-brief.md && cat .custodian-brief.md
# Active workstreams for this domain
curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=email-connect&unread_only=true" \
| python3 -m json.tool
```
Mark a message read:
```bash
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
```
### Log progress (required at session close)
```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
-H "Content-Type: application/json" \
-d '{
"summary": "what was done",
"event_type": "note",
"author": "codex",
"workstream_id": "<uuid>",
"task_id": "<uuid>"
}'
```
Omit `workstream_id` / `task_id` when not applicable.
### Update task status
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"status": "progress"}'
# values: wait | todo | progress | done | cancel
```
### Flag a task for human review
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"needs_human": true, "intervention_note": "reason"}'
```
---
## Session Protocol
**Start:**
1. `test -f .custodian-brief.md && cat .custodian-brief.md` — domain goal and open workstreams, when present
2. Check inbox: `GET /messages/?to_agent=email-connect&unread_only=true`; mark read
3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
4. Check human-needed tasks: `GET /tasks/?needs_human=true`
**During work:**
- Update task statuses in workplan files as tasks progress
- Record significant decisions via `POST /decisions/`
**Close:**
1. Update workplan file task statuses to reflect progress
2. Log: `POST /progress/` with a summary of what changed
3. Note for the custodian operator: after workplan file changes, run from
`~/state-hub`:
```bash
make fix-consistency REPO=email-connect
```
This syncs task status from files into the hub DB.
---
## Workplan Convention (ADR-001)
Work items originate as files in this repo — not in the hub. The hub is a
read/cache/index layer that rebuilds from files.
**File location:** `workplans/EMAIL-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-EMAIL-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
the completion/archive date; the frontmatter `id` does not change.
**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use
this only for low-risk work completed directly; create a normal workplan for
anything needing analysis, design, approval, dependencies, or multiple phases.
**Frontmatter:**
```yaml
---
id: EMAIL-WP-NNNN
type: workplan
title: "..."
domain: custodian
repo: email-connect
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # written by fix-consistency — do not edit
---
```
Use `proposed` for a new draft, `ready` after review against current repo
state, and `finished` after implementation. `stalled` and `needs_review` are
derived health labels, not frontmatter statuses.
**Task block format** (one per `##` section):
```
## Task Title
` ` `task
id: EMAIL-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # written by fix-consistency — do not edit
` ` `
Task description text.
```
Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
To create a new workplan:
1. Write the file following the format above
2. Notify the custodian operator to run `make fix-consistency REPO=email-connect`
(or send a message to the hub agent via `POST /messages/`)

20
CLAUDE.md Normal file
View File

@@ -0,0 +1,20 @@
# email-connect - Claude Code Instructions
This repository uses `AGENTS.md` as the canonical local agent instruction file.
Claude Code agents should read `AGENTS.md` first and follow the same State Hub
identity, workplan convention, and repo-specific semantic guardrails.
State Hub identity:
- Domain: `custodian`
- Repo slug: `email-connect`
- Topic ID: `cee7bedf-2b48-46ef-8601-006474f2ad7a`
- Workplan prefix: `EMAIL-WP-`
Core product rule: email events are evidence, not result satisfaction. Do not
treat provider acceptance, MX acceptance, inbox placement, opens, clicks,
replies, complaints, or suppressions as proof of human awareness or business
outcome completion.
Start with `INTENT.md`, then `spec/ProductRequirementsDocument.md`, then the
active files under `workplans/`.

140
SCOPE.md Normal file
View File

@@ -0,0 +1,140 @@
# SCOPE
## One-liner
`email-connect` is a headless, provider-neutral email communication and
evidence service for sending, tracking, diagnosing, and normalizing email
events.
---
## Core Idea
Email is useful evidence, but it is not proof of human awareness or business
result satisfaction. This repository exists to model email as an uncertain
communication channel: preserve raw provider events, normalize email-native
facts, classify weak or suspicious engagement signals conservatively, and emit
coordination-compatible evidence for downstream orchestration.
The product should be useful both as a standalone operational email service and
as the first reference adapter for `coordination-engine`.
---
## In Scope
- Provider-neutral transactional and notification email send API.
- Message, attempt, raw event, and timeline records.
- Provider webhook/event ingestion and native status mapping.
- Normalized email evidence events for coordination workflows.
- Bounce, deferral, complaint, unsubscribe, and suppression handling.
- Endpoint quality signals for email addresses and recipient endpoints.
- Conservative open, click, reply, scanner, proxy, and privacy classification.
- Adapter descriptor, capability profile, evidence ceiling, and health reporting.
- Generic APIs and future UI surfaces for operators, support teams, agents, and developers.
---
## Out of Scope
- Newsletter campaign management or broad marketing automation.
- Claiming inbox placement, human reading, authenticated recipient action, or legal acceptance from email telemetry alone.
- Evaluating whether the intended business result was satisfied; that belongs to `coordination-engine`.
- Becoming a provider-specific dashboard clone.
- Owning non-email communication channels.
---
## Relevant When
- A system needs to send transactional or coordination-related email without binding directly to one provider.
- Operators need to inspect what happened to a message across provider, MX, bounce, suppression, open, click, and reply events.
- Agents or services need queryable email-channel evidence with explicit uncertainty.
- `coordination-engine` needs an email adapter that emits normalized evidence events and declares evidence ceilings.
---
## Not Relevant When
- The goal is bulk marketing, newsletter design, campaign segmentation, or growth automation.
- The system needs proof of recipient awareness, legal acceptance, or business outcome completion.
- A single provider dashboard is sufficient and provider-neutral modeling is unnecessary.
- The work is about another notification channel such as SMS, push, chat, or postal mail.
---
## Current State
- Status: concept / planning
- Implementation: intent and PRD only
- Stability: evolving
- Usage: none yet
The repository currently contains product intent and requirements. No runtime
stack, API implementation, persistence model, provider integration, or UI has
been committed yet.
---
## How It Fits
- Upstream dependencies: email providers, provider webhooks, adapter interface expectations, coordination evidence vocabulary.
- Downstream consumers: `coordination-engine`, automation agents, product systems, operators, support users, audit/compliance reviewers.
- Often used with: State Hub workplans, future `coordination-engine` adapter contracts, provider-specific email integrations.
---
## Terminology
- Preferred terms: email evidence, message timeline, provider acceptance, MX acceptance, deferral, hard bounce, soft bounce, suppression, complaint, privacy open, scanner click, unverified interaction, evidence ceiling.
- Also known as: email adapter, email evidence service, provider-neutral email layer.
- Potentially confusing terms: "delivered" must be decomposed into provider/MX facts; "opened" must not imply human reading; "clicked" must not imply authenticated recipient action.
---
## Related / Overlapping
- `coordination-engine` - expected downstream evaluator of intended results and consumer of normalized email evidence.
- `llm-connect` - sibling `*-connect` style adapter/service pattern in the custodian domain.
- `state-hub` - tracks repo registration, workplans, progress, and consistency for this repository.
---
## Getting Oriented
- Start with: `INTENT.md`.
- Key files / directories: `spec/ProductRequirementsDocument.md`, `workplans/`, `AGENTS.md`.
- Entry points: no code entry points yet.
---
## Provided Capabilities
```capability
type: service
title: Provider-neutral email communication
description: Send transactional and coordination-related email through a stable provider-neutral interface while preserving provider-specific evidence for diagnosis.
keywords: [email, transactional-email, notification, provider-neutral, communication]
```
```capability
type: evidence
title: Email event normalization
description: Normalize raw provider events into conservative email-channel evidence, distinguishing acceptance, deferral, bounce, suppression, complaint, open, click, and reply signals.
keywords: [email, evidence, normalization, bounce, suppression, tracking]
```
```capability
type: adapter
title: coordination-engine email adapter
description: Provide the adapter descriptor, capability profile, evidence ceiling, health reporting, and normalized evidence events needed by coordination-engine.
keywords: [coordination-engine, adapter, evidence-ceiling, notification, email]
```
---
## Notes
The core product discipline is semantic restraint: report what the email channel
knows, preserve uncertainty, and leave result evaluation to downstream
coordination logic.

124
workplans/EMAIL-WP-0001-repo-onboarding.md Normal file
View File

@@ -0,0 +1,124 @@
---
id: EMAIL-WP-0001
type: workplan
title: "Repository Onboarding and Implementation Foundation"
domain: custodian
repo: email-connect
status: active
owner: codex
topic_slug: custodian
created: "2026-06-02"
updated: "2026-06-02"
state_hub_workstream_id: "4533ceb6-bd86-49ee-a014-cffd68f84fbb"
---
# EMAIL-WP-0001 - Repository Onboarding and Implementation Foundation
## Goal
Bring `email-connect` from intent and PRD into an implementation-ready,
State-Hub-indexed repository while preserving the product's semantic guardrail:
email events are evidence, not result satisfaction.
## Context
The repository currently contains product intent and a product requirements
document. It is registered under the `custodian` domain because its primary
strategic role is to serve as a provider-neutral email evidence service and the
reference `coordination-engine` adapter for email.
This workplan covers repository onboarding and the first implementation
foundation. It should not choose a runtime stack or provider-specific design
without first recording the architecture rationale.
## T01 - Complete State Hub Registration Artifacts
```task
id: EMAIL-WP-0001-T01
status: done
priority: high
state_hub_task_id: "f3c64208-b8da-45c3-88cf-e1be7ed51e72"
```
Register the repo with State Hub and add the local coordination files needed by
future agents.
Done when:
- the State Hub repo record has domain, local path, host path, remote URL,
fingerprint, description, and topic ID;
- `AGENTS.md` describes the repo identity and State Hub workflow;
- `SCOPE.md` declares scope boundaries and provided capabilities;
- `.custodian-brief.md` is generated by consistency sync.
## T02 - Define The Initial Runtime Architecture
```task
id: EMAIL-WP-0001-T02
status: todo
priority: high
state_hub_task_id: "fdfd8b96-7326-414f-8126-79bb3a21b950"
```
Select and document the first implementation architecture.
The architecture note should cover:
- API shape and first service boundaries;
- persistence model for messages, attempts, raw events, timelines, suppressions,
and endpoint quality;
- provider abstraction boundaries;
- webhook ingestion and event authenticity checks;
- how normalized email evidence maps into `coordination-engine`;
- local development, test, and migration commands.
## T03 - Model The Email Evidence Canon
```task
id: EMAIL-WP-0001-T03
status: todo
priority: high
state_hub_task_id: "ef1eb769-dfa0-4b46-8633-274d90962423"
```
Turn the intent/PRD evidence distinctions into a concrete domain model.
The model should distinguish at least:
- provider acceptance;
- recipient MX acceptance;
- temporary deferral;
- hard and soft bounce;
- provider drop;
- suppression;
- complaint and unsubscribe;
- privacy/proxy open;
- scanner or bot click;
- unverified click;
- human-like reply;
- out-of-office response.
Done when the model explicitly prevents treating technical delivery, open, or
click telemetry as proof of human awareness or result satisfaction.
## T04 - Create The First Service Skeleton
```task
id: EMAIL-WP-0001-T04
status: todo
priority: medium
state_hub_task_id: "4b94e544-5aad-4c38-8fe3-eed17af79971"
```
Create the initial code skeleton after T02 and T03 have enough shape to avoid a
throwaway implementation.
Expected first slice:
- package/module layout;
- configuration loading;
- health/status endpoint or CLI equivalent;
- test harness;
- placeholder provider interface;
- first message/timeline domain objects;
- README update with actual development commands.