diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..513c9d7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,176 @@ +# direkt-vermittlung-de — Agent Instructions + +## Repo Identity + +**Purpose:** DirektVermittlungDe is a document-centric platform that routes citizens' documents or reference numbers (Aktenzeichen) directly to the responsible German authority caseworker and opens a communication thread, replacing manual phone-routing hunts. + +**Domain:** government +**Repo slug:** direkt-vermittlung-de +**Topic ID:** `084430ab-c630-48dc-9e1d-d07d1e8fce3c` +**Workplan prefix:** `DVD-WP-` + +--- + +## 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` | +| Optional local edge relay | http://127.0.0.1:18080 | + +When an operator has enabled the edge relay, set API_BASE to the relay URL. +Queueable writes return an explicit queued receipt if the central hub is +unreachable. Treat that as pending local evidence, then ask the operator to run +statehub outbox status/replay after connectivity returns. + +### Orient at session start + +```bash +# Offline brief — works without hub connection +cat .custodian-brief.md + +# Active workplans for this domain +curl -s "http://127.0.0.1:8000/workplans/?topic_id=084430ab-c630-48dc-9e1d-d07d1e8fce3c&status=active" \ + | python3 -m json.tool + +# Check inbox +curl -s "http://127.0.0.1:8000/messages/?to_agent=direkt-vermittlung-de&unread_only=true" \ + | python3 -m json.tool +``` + +Mark a message read: +```bash +curl -s -X PATCH "http://127.0.0.1:8000/messages//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", + "workplan_id": "", + "task_id": "" + }' +``` + +Omit `workplan_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -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/" \ + -H "Content-Type: application/json" \ + -d '{"needs_human": true, "intervention_note": "reason"}' +``` + +--- + +## Session Protocol + +**Start:** +1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe) +2. Check inbox: `GET /messages/?to_agent=direkt-vermittlung-de&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. After workplan file changes, run: + ```bash + statehub fix-consistency + ``` + Coding agents should run this directly; ask the operator only if the CLI or + State Hub API is unavailable. This syncs task status from files into the hub DB. + +--- + +{CREDENTIAL_ROUTING} + + + + +--- + +## 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/DVD-WP-NNNN-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-DVD-WP-NNNN-.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: DVD-WP-NNNN +type: workplan +title: "..." +domain: government +repo: direkt-vermittlung-de +status: proposed | ready | active | blocked | backlog | finished | archived +owner: codex +topic_slug: ... +created: "YYYY-MM-DD" +updated: "YYYY-MM-DD" +state_hub_workstream_id: "" # written by fix-consistency — do not edit (legacy name; holds the workplan id) +--- +``` + +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: DVD-WP-NNNN-T01 +status: wait | todo | progress | done | cancel +priority: high | medium | low +state_hub_task_id: "" # 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. Run `statehub fix-consistency` locally; ask the operator only if the CLI or + State Hub API is unavailable. diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..cffd06a --- /dev/null +++ b/INTENT.md @@ -0,0 +1,25 @@ +## Intent + +DirektVermittlungDe (DVD) exists to collapse the multi-step "phone hunt" citizens go through to reach the right caseworker in a German public authority. Today, resolving a routine inquiry takes ~2 minutes once you reach the correct person, but ~30 minutes to get there (wrong contact → call center → transfer → re-identification → re-explanation). + +DVD replaces that chain with a single step: the citizen submits a source document or a unique identifying feature (e.g. Aktenzeichen/Kassenzeichen). The system determines functional responsibility from that input and opens a direct communication thread with the correct caseworker — via callback, appointment, or text chat — instead of parking citizens in queues or burdening caseworkers with manual forwarding. + +### Core architectural constraint + +Documents use a split-payload model (ADR-0001): plaintext routing metadata (authorityId, referenceNumber, docType, issuedAt) is separated from an encrypted payload (the actual document/scan). The backend routes on metadata alone and never decrypts the payload — this is non-negotiable and shapes every service boundary. + +### Where the project stands + +Three independent prototype implementations (chatgpt5, geminiNbt3pro, grok4.1) explored the problem space. The project is now migrating to a single production codebase under `/src`, built test-first (TDD), governed by the ADRs in `docs/architecture/adr/` and tracked in `docs/WORKPLAN_MainCodebase_Integration.md`. + +### In scope +- Document/reference-number intake and metadata-based routing to the responsible unit +- Citizen–official communication threads (chat, callback requests, appointments) +- Stateless OAuth2/JWT authentication with citizen/official scopes +- Async data export for authority systems +- GDPR-compliant retention and cleanup of documents/threads + +### Out of scope +- Decrypting or processing document payload contents in the main service +- General-purpose CRM or ticketing functionality unrelated to authority routing +- Non-government (private sector) support-routing use cases diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..0939046 --- /dev/null +++ b/SCOPE.md @@ -0,0 +1,38 @@ +# SCOPE + +> This file was generated by `statehub register`. Refine it as the repository +> boundaries become clearer. + +## One-liner + +DirektVermittlungDe is a document-centric platform that routes citizens' documents or reference numbers (Aktenzeichen) directly to the responsible German authority caseworker and opens a communication thread, replacing manual phone-routing hunts. + +## Core Idea + +direkt-vermittlung-de exists to provide the capability described in INTENT.md. + +## In Scope + +- Document/reference-number intake and metadata-based routing to the responsible authority unit +- Citizen-official communication threads (text chat, callback requests, appointment scheduling) +- Stateless OAuth2/JWT authentication with citizen/official scopes +- Async data export workflow for authority systems +- GDPR-compliant document/thread retention and TTL cleanup +- Migration from prototype implementations to a unified, TDD-driven /src production codebase + +## Out of Scope + +- Decrypting or otherwise processing encrypted document payload contents in the main backend service +- General-purpose CRM/ticketing functionality unrelated to authority-citizen routing +- Non-government (private sector) support-routing use cases +- Maintaining the prototype-* directories as live code (archived reference only) + +## Current State + +- Pre-production: three parallel prototypes (chatgpt5, geminiNbt3pro, grok4.1) exist under /prototype-*; no unified /src codebase yet. Architecture is documented via 8 ADRs and a migration workplan, but the target production codebase has not been started. + +## Getting Oriented + +- Start with: INTENT.md +- Agent instructions: AGENTS.md +- Workplans: workplans/ diff --git a/workplans/DVD-WP-0001-statehub-bootstrap.md b/workplans/DVD-WP-0001-statehub-bootstrap.md new file mode 100644 index 0000000..20133e4 --- /dev/null +++ b/workplans/DVD-WP-0001-statehub-bootstrap.md @@ -0,0 +1,59 @@ +--- +id: DVD-WP-0001 +type: workplan +title: "Bootstrap State Hub integration" +domain: government +repo: direkt-vermittlung-de +status: ready +owner: codex +topic_slug: personhood +created: "2026-07-08" +updated: "2026-07-08" +state_hub_workstream_id: "78f60613-22ea-40ae-b7e0-d783a4ab0336" +--- + +# Bootstrap State Hub integration + +DirektVermittlungDe is a document-centric platform that routes citizens' documents or reference numbers (Aktenzeichen) directly to the responsible German authority caseworker and opens a communication thread, replacing manual phone-routing hunts. + +## Review Generated Integration Files + +```task +id: DVD-WP-0001-T01 +status: todo +priority: high +state_hub_task_id: "72635778-8c9f-4d75-839a-24c0daddeb4e" +``` + +Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`. +Replace generated placeholders with repo-specific facts where needed. + +## Verify Local Developer Workflow + +```task +id: DVD-WP-0001-T02 +status: todo +priority: high +state_hub_task_id: "8280145c-478b-4e61-a190-01e75ccd747d" +``` + +Identify the repo's install, test, lint, build, and run commands. Add or refine +those commands in the agent instructions so future coding sessions can verify +changes confidently. + +## Seed First Real Workplan + +```task +id: DVD-WP-0001-T03 +status: todo +priority: medium +state_hub_task_id: "c57deaf3-8faa-4043-84f3-0ad3b057c525" +``` + +Create the first implementation workplan for the repository's most important +next change. After workplan file updates, run the sync locally from this repo +checkout: + +```bash +statehub fix-consistency +```