# 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)

1. PDFs OCRen: `python3 -c "import pymupdf; doc=pymupdf.open('…'); [print(page.get_text()) …]"`
2. Prompt bauen aus Input + OCR-Text + Quellen-URLs
3. Skills-Array: `["journalistic-article-writing", "korrekturschleife", "article-management"]`
4. 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

1. Alle Quellen abrufen (`web_extract`, `curl`, `web_search`)
2. Jede Quelle bewerten: AAA (Primär) / AA (Sekundär) / A (schwach)
3. 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

1. Git-Commit: `git add artikel_NAME.html && git commit -m "artikel: THEMA"`
2. Article-Server prüfen: Direkt-URL testen
   `curl "http://185.162.249.159:8890/artikel_NAME.html?key=…" | head -3`
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