Anforderungsdefinition: Vollautomatischer Artikel-Workflow

Spezifikation für Cody · 23. Juni 2026 · Stand: final

1. Ziel

Eine Pipeline, die aus einem beliebigen Input (Thema, PDF, URL, Stichwort) einen QC-geprüften, publikationsfertigen HTML-Artikel produziert. Basti gibt den Auftrag — der Rest läuft autonom.

2. Eingabe-Schnittstelle

Input: {
  topic: string,            // "Gamegenic wird Partner von Tolarian Community College"
  sources: string[],         // ["/pfad/pm.pdf", "https://icv2.com/...", "https://gamegenic.com"]
  category_id: number,      // Joomla-Rubrik (default: 61 = Korrektur)
  rubric: string,           // "Neuerscheinungen" | "Crowdfunding" | "Nachrichten" | ...
  image_urls: string[],     // optionale Bild-URLs aus PM
  deadline: string | null   // optional: ISO-Timestamp für zeitkritische Artikel
}

Input-Quellen-Erkennung (automatisch)

Input	Quelle
PDF	Pfad aus `~/.hermes/cache/documents/`
URL	Direkt übernehmen
Nur Thema	Sub-Agent recherchiert selbstständig Quellen

3. Pipeline-Stufen

STAGE 0
Input Prep → STAGE 1
Research → STAGE 2
Write → STAGE 3
QC → STAGE 4
Deliver

Dauer: ~10–15 Minuten von Input bis fertigem Artikel

STAGE 0: Input Preparation

Basti (nicht Sub-Agent)

PDFs OCRen: python3 -c "import pymupdf; doc=pymupdf.open('…'); [print(page.get_text()) …]"
Prompt bauen aus Input + OCR-Text + Quellen-URLs
Skills-Array: ["journalistic-article-writing", "korrekturschleife", "article-management"]
Toolsets: ["web", "terminal", "file", "search", "skills"]

Output: Fertiger Prompt für Stage 1

STAGE 1: Research

Sub-Agent #1 (Leaf, delegate_task)

Feld	Wert
Skills	journalistic-article-writing
Toolsets	web, terminal, file, search, skills

Alle Quellen abrufen (web_extract, curl, web_search)
Jede Quelle bewerten: AAA (Primär) / AA (Sekundär) / A (schwach)
Fehlende Fakten ergänzen:
- BGG-Eintrag suchen: web_search site:boardgamegeek.com SPIELNAME
- Autor/Illustrator/Verlag verifizieren
- Preise, Daten, Awards gegenprüfen

Output: research_brief.md

# Research Brief: THEMA
## Quellenbewertung
| Quelle  | Stufe   | URL                   |
|---------|---------|-----------------------|
| PM      | AAA     | https://gamegenic.com |

## Fakten
- Fakt 1 (Quelle: URL, AAA)
- Fakt 2 (Quelle: URL, AA)

## Offene Punkte
- Punkt X konnte nicht verifiziert werden → STREICHEN

Exit-Codes: 0 = vollständig · 1 = unvollständig (Abbruch, an Basti melden)

STAGE 2: Write

Sub-Agent #2 (Leaf, delegate_task)

Feld	Wert
Skills	journalistic-article-writing, korrekturschleife, article-management
Toolsets	web, terminal, file, search, skills
Context	Research Brief + Original-Prompt

❌ KEINE "XML API v2" → klickbare BGG-Links

❌ KEIN "Betriebsgeheimnis"

❌ Quellen = <a href="…" target="_blank">

❌ <span><strong>Quellen</strong></span>

❌ KEINE Emojis/Icons

❌ Datei endet mit </html>

Output: /home/hermes/workspace/artikel_NAME_DATUM.html

Pflicht-Elemente im HTML:

<head>
  <meta charset="UTF-8">
  <title>TITEL</title>
  <meta name="description" content="…">
  <meta name="keywords" content="…">
</head>
<body>
  <article>
    <h1>TITEL</h1>
    <p class="meta">DATUM · Lesezeit: ca. N Minuten</p>
    <!-- Inhalt -->
    <hr id="system-readmore" />
    <span style="…"><strong>Quellen</strong></span>
    <ol>
      <li><a href="URL" target="_blank">Name</a> — Beschreibung</li>
    </ol>
    <p class="qc"><!-- QC: Quelle1=AAA|URL, … --></p>
  </article>
</body>
</html>

Exit-Codes: 0 = Artikel geschrieben · 1 = Fehler

STAGE 3: Quality Control

Sub-Agent #2 (gleicher Agent, nach dem Schreiben)

bash /home/hermes/workspace/verify_article.sh artikel_NAME.html

13 Checks (Stand 23.06.2026)

#	Check	Kriterium
1	Read-More	Genau 1 × `<hr id="system-readmore">`
2	br nach Read-More	Kein `<br>` direkt danach
3	p.meta	`<p class="meta">` (nicht `<div>`)
4	Emojis	Keine im Body
5	Dateiende	Endet mit `</html>`
6	Meta im Body	Keine doppelte Datum·Lesezeit-Zeile
7	Quellen-Überschrift	Kein `<h2>Quellen</h2>`
8	Links target	Alle mit `target="_blank"`
9	Meta-Description	Vorhanden und nicht leer
10	QC-Zeile	In `<p class="qc">`
11	BGG-Autorencheck	Designer gegen BGG verifizieren
12	XML-API-Referenzen	Keine "XML API" / "Betriebsgeheimnis"
13	Quellen verlinkt	Quellen-Block hat `<a href>` Links

Fehlerbehandlung:

Exit 0 → Stage 4
Exit 1 → Korrigieren, erneut verify → max 3 Versuche → ABBRUCH, an Basti melden
CHECK 11 (BGG-Autoren) Warnung → dokumentieren, nicht blocken

STAGE 4: Deliver

Basti

Git-Commit: git add artikel_NAME.html && git commit -m "artikel: THEMA"
Article-Server prüfen: Direkt-URL testen
curl "http://185.162.249.159:8890/artikel_NAME.html?key=…" | head -3
Meldung:

✅ Artikel THEMA fertig
📄 /home/hermes/workspace/artikel_NAME.html
🔗 http://185.162.249.159:8890/artikel_NAME.html?key=…
📊 verify: 0 Fehler

4. Fehlermodi & Recovery

Fehler	Erkennung	Recovery
PDF nicht OCR-bar	pymupdf wirft Exception	Basti manuell OCRen, Text in Prompt geben
Quelle nicht erreichbar	curl/web_extract Timeout/404	5-Stufen-Eskalation: curl → wget+UA → Wayback → Tavily → Google Cache
Keine AAA-Quelle für Kern-Fakt	Research-Gap	Fakt streichen → "unvollständig" an Basti
verify_article.sh fail	Exit ≠ 0	3 Korrekturversuche → Abbruch
BGG-Autorencheck uneindeutig	check_authors.py Warnung	Dokumentieren, Basti entscheidet
Article-Server down	curl auf :8890 Timeout	Server neu starten via `python3 article_server.py &`

5. Cronjob-Integration

Der Workflow läuft als One-Shot-Cronjob mit deliver="local":

cronjob(
  action="create",
  schedule="1m",
  repeat=1,
  deliver="local",
  skills=["journalistic-article-writing", "korrekturschleife", "article-management"],
  enabled_toolsets=["web", "terminal", "file", "search", "skills", "delegation"],
  prompt="…"  // Stage-0-Output
)

Wichtig: deliver="local" — der Cronjob meldet sich NICHT bei Daniel. Basti pollt das Ergebnis.

6. Batch-Modus

Für mehrere Artikel: Parallele Cronjobs (max 3 gleichzeitig via delegation.max_concurrent_children). Jeder Cronjob bekommt denselben Prompt-Aufbau, nur mit anderem Input.

7. Was Cody bauen muss

7.1 `article_pipeline.py` — Orchestrator-Script

Input entgegennimmt (JSON oder CLI-Args)
Stage 0 ausführt (PDF-OCR, Prompt-Bau)
Zwei delegate_task-Aufrufe (Stage 1 Research, Stage 2 Write+QC)
Stage 4 ausführt (Git-Commit, Verify)
Exit-Code zurückgibt

7.2 Integration

Als Cronjob-Script lauffähig (no_agent=false Modus)
ODER: Als Hermes-Skill article-pipeline registrierbar

7.3 Config

Element	Pfad / Wert
Workspace	`/home/hermes/workspace/`
verify_article.sh	`/home/hermes/workspace/verify_article.sh`
article_server.py	`/home/hermes/workspace/article_server.py`
PDF-Cache	`~/.hermes/cache/documents/`
Skills	journalistic-article-writing, korrekturschleife, article-management

8. Aufruf-Beispiele

# Variante A: Thema + PDF
python3 article_pipeline.py \
  --topic "Gamegenic wird Partner von Tolarian Community College" \
  --pdf "/home/hermes/.hermes/cache/documents/GG_Press_release.pdf" \
  --rubric "Nachrichten" \
  --category-id 9

# Variante B: Nur Thema (autonome Recherche)
python3 article_pipeline.py \
  --topic "Neue Kennerspiel-Nominierungen 2026" \
  --rubric "Nachrichten"

# Variante C: Batch
python3 article_pipeline.py --batch topics.json

9. Erfolgskriterium

🎯 Basti gibt ein Thema ein → nach ~10 Minuten liegt ein Artikel im Workspace mit

verify_article.sh: 0 Fehler

Kein manuelles Eingreifen. Kein Nachbessern. Kein "XML API v2".

Anhang: Skills-Dokumentation

Folgende Skills werden im Workflow verwendet. Cody muss ihre Schnittstellen kennen:

Skill	Typ	Funktion
`journalistic-article-writing`	Writing	HTML-Template, Quellenregeln, Sprachregeln, Formatvorgaben
`korrekturschleife`	QC	Zweistufiger Workflow (Write + Fact-Check), Writer-Fehler-Tabelle, Quellenbewertung AAA/AA/A
`article-management`	Deploy	Article-Server (Port 8890), Joomla-API, verify_article.sh, VG-Wort