lemonspace_app/components/agents/CLAUDE.md

components/agents/ - Agent Specs (Markdown)

Dieser Ordner enthaelt die menschenlesbaren Agent-Spezifikationen. Jede Datei ist gleichzeitig Produktdoku und kuratierte Prompt-Quelle.

---

Dual Model (verbindlich)

Die Agent-Runtime basiert auf zwei Quellen:

1. Struktur in TypeScript
   • lib/agent-definitions.ts
   • lib/agent-run-contract.ts
2. Kuratierte Prompt-Segmente in Markdown
   • components/agents/*.md
   • kompiliert via scripts/compile-agent-docs.ts
   • konsumiert aus lib/generated/agent-doc-segments.ts

Wichtig:

• convex/agents.ts liest kein Raw-Markdown zur Laufzeit.
• Nur markierte AGENT_PROMPT_SEGMENT-Bloecke wirken prompt-relevant.
• Unmarkierter Text ist Doku fuer Menschen.

---

Dateikonvention pro Agent

Dateiname muss dem Agent-Id-Muster folgen, z. B.:

• campaign-distributor.md fur campaign-distributor

Die Zuordnung passiert ueber docs.markdownPath in lib/agent-definitions.ts.

---

Frontmatter (Pflicht)

Jede Agent-Datei startet mit Frontmatter:

---
name: Campaign Distributor
description: ...
tools: WebFetch, WebSearch, Read, Write, Edit
color: yellow
emoji: lemon
vibe: ...
---

Hinweise:

• emoji soll als ASCII-Token gepflegt werden (z. B. lemon), nicht als Unicode-Zeichen.
• Frontmatter ist Referenz fuer Doku und muss mit der TS-Definition konsistent bleiben.

---

Prompt Segment Marker (Pflicht)

Aktuell required keys:

• role
• style-rules
• decision-framework
• channel-notes

Marker-Format:

<!-- AGENT_PROMPT_SEGMENT:role:start -->
Segment text
<!-- AGENT_PROMPT_SEGMENT:role:end -->

Regeln:

• Pro required key genau ein start- und ein end-marker.
• Kein leerer Segment-Inhalt.
• Marker-Namen muessen exakt passen.
• Segment-Reihenfolge in der Generierung folgt AGENT_PROMPT_SEGMENT_KEYS.

Optional zusaetzliche Segmenttypen sind erlaubt, muessen aber erst im Compiler/ Runtime-Prompting verankert werden, bevor sie Wirkung haben.

---

Schreibregeln fuer Segmente

• Schreibe handlungsorientiert und spezifisch.
• Keine versteckte Denkspur (kein chain-of-thought).
• Keine erfundenen Produktfakten, Statistiken oder Deadlines.
• Kanalregeln konkret, aber nicht auf fragile Einzelformate ueber-engineeren.
• Immer auf strukturierten Runtime-Output ausrichten (artifactType, sections, metadata, qualityChecks, previewText, body).

---

Nach jeder Aenderung

1. Prompt-Segmente kompilieren:

npx tsx scripts/compile-agent-docs.ts

2. Relevante Tests laufen lassen:

npm run test -- tests/lib/agent-doc-segments.test.ts tests/lib/agent-prompting.test.ts

3. Bei Struktur-Aenderungen zusaetzlich:

npm run test -- tests/lib/agent-definitions.test.ts tests/lib/agent-run-contract.test.ts

---

Wann andere Dateien mitziehen

• lib/agent-definitions.ts anpassen, wenn sich Inputs, Kanaele, Regeln, Blueprints oder Parameter aendern.
• lib/agent-prompting.ts anpassen, wenn neue Segmenttypen wirklich in Prompts einfliessen sollen.
• scripts/compile-agent-docs.ts anpassen, wenn required segment keys geaendert werden.
• messages/de.json / messages/en.json anpassen, wenn neue UI-Labels sichtbar werden.

---

Anti-Patterns

• Komplettes monolithisches Prompt-Dokument ohne Marker-Struktur.
• Raw-Markdown als Runtime-Input ohne Compile-Step.
• Agent-Output nur als Freitext ohne strukturierte Deliverables.
• Segment-Inhalte, die den TS-Contracts widersprechen.