Document agent workflow and harden the Just/PDF build recipes.

Add progressive-disclosure AGENTS files, align README with the bilder/ layout, and port justfile reliability fixes (resource-path, nonstopmode, diagrams recipe). Drop obsolete STYLE_GUIDE and root hy3-plan.
This commit is contained in:
grok-bot committed 2026-07-27 13:13:57 +02:00
1 parent ed9fc0212c
commit 80c22175bf
7 files changed
+239 -440

No files matched your search

+4
View File
@@ -4,6 +4,10 @@
build/
dist/
# Non-canonical import staging (raw pics before assets/ or bilder/)
# Convention ported from sister project ../ki-buch
_staging/
# Temporäre Vorschau-Bilder / Debug-Exports
dist/_*.png
**/_cover-preview.png
+70
View File
@@ -0,0 +1,70 @@
# AGENTS.md — Grok Build (Kant-Sachbuch)
**Projekt:** *Immanuel Kant – Das gesamte Werk verständlich erklärt* (Deutsch, Pandoc/LuaLaTeX).
**Progressive Disclosure:** Nur diese Datei ist die Root-Regel. Details **on demand** nachladen — nicht alles vorweg lesen.
Schwesterprojekt (ähnliche Just/PDF-Konventionen): `../ki-buch`.
---
## Source of Truth
| Editieren | Pfad |
|-----------|------|
| Manuskript | `buch/*.md` |
| Build-Assets (Cover/Parts/Diagramme, JPG) | `assets/cover/`, `assets/parts/`, `assets/diagrams/` |
| TikZ-Quellen (optional) | `assets/diagrams/src/*.tex` |
| Pics-Import | `scripts/import_pics_to_assets.py` (`bilder/pics` → JPG Q90) |
| Bild-Katalog / Stil / Gemini | `bilder/` |
| PDF-Pipeline | `pdf/`, `justfile`, `scripts/` |
| Redaktion / Fakten | `_hy3/style-sheet.md`, `_hy3/faktenblatt.md`, `quellen.md` |
| Nicht editieren | Pfad |
|-----------------|------|
| Assembliertes Buch | `build/book.md` |
| PDF-Output | `dist/*.pdf` (kanonisch: `dist/kant-sachbuch.pdf`) |
| Staging / Temp | `_staging/`, `tmp/`, `*.aux`, `*.log` (Diagramme) |
Kapitel **nie** unter `build/` ändern. Assemble-Reihenfolge nur aus `scripts/assemble_book.py` → `CHAPTER_ORDER`.
---
## Befehle
```bash
just pdf # → dist/kant-sachbuch.pdf
just pdf-sample # schnelle Roh-Vorschau
just pdf-sample-styled
just pdf-draft
just assemble # nur build/book.md
just diagrams # optional TikZ → assets/diagrams/*.pdf (PDF-Pfad nutzt JPG)
just qa
just clean
```
Optional: `devbox shell` (pandoc/just; LuaLaTeX vom Host-TeX Live).
---
## Harte Regeln
1. **Figure-Marker:** `<!-- figure: assets/diagrams/<id> caption="…" -->` (IDs: `bilder/ABBILDUNGEN.md`).
2. **Part-Pages** nur über Assembler/`partpages.lua` — nicht manuell im Fließtext.
3. **Zitation:** Werk + Jahr; **keine** erfundenen Kant-Zitate oder AA-Seitenzahlen.
4. **Fließtext-Stil:** `_hy3/style-sheet.md` (bei Manuskript-Arbeit laden).
5. **Bild-Palette:** Preußischblau `#1B3A4B`, Gold `#C4A35A`, Burgund `#6B2D3C`, Pergament `#F7F3EB`.
6. **Gemini-Prompts:** englischer Prompt-Block; Details nur bei Bildarbeit: `bilder/AGENTS.md`.
7. Keine Emojis im Buchtext; keine Meta-KI-Floskeln.
---
## On demand (nicht vorweg laden)
| Thema | Datei |
|-------|--------|
| Manuskript-Konventionen | `buch/AGENTS.md` |
| Bilder / Gemini | `bilder/AGENTS.md` |
| Abbildungs-Katalog | `bilder/ABBILDUNGEN.md` |
| Bild-Stil L1/L2 | `bilder/STYLE.md` |
| Mensch-README / Build-Doku | `README.md` |
| Hy3-Plan / Gates | `hy3-plan.md`, `_hy3/gates-w9.md` |
+34 -17
View File
@@ -41,6 +41,11 @@ mit Hilfe von Hy3-Subagenten (Tencent) nach dem `hy3-plan.md`.
- Sekundärliteratur: kuratierte Liste in Kap. 20 (nur Werke aus dem Faktenblatt).
- Das Buch richtet sich an Laien mit Gymnasialbildung, nicht an Fachphilosophen.
## Agenten / Repo-Map (Grok Build)
Zuerst Root-[`AGENTS.md`](AGENTS.md) (kurz, progressive Disclosure).
Bereichsregeln: [`buch/AGENTS.md`](buch/AGENTS.md), [`bilder/AGENTS.md`](bilder/AGENTS.md).
## PDF erzeugen
Das Buch wird über Pandoc + LuaLaTeX / KOMA-Script (`scrbook`) zu einem
@@ -76,13 +81,20 @@ ab PR 1 vor. Das finale Produkt ist `dist/kant-sachbuch.pdf`.
4. Nur zusammenbauen (ohne Build):
```sh
python3 scripts/assemble_book.py
just assemble
# oder: python3 scripts/assemble_book.py
```
Ergebnis: `build/book.md`.
5. Qualitätssicherung nach dem Build:
5. TikZ-Diagramme neu bauen:
```sh
python3 scripts/check_pdf.py
just diagrams
```
6. Qualitätssicherung nach dem Build:
```sh
just qa
# oder: python3 scripts/check_pdf.py
```
Prüft Existenz/Größe, schätzt die Seitenzahl, zählt eingebettete
Bilder (Cover + Part-Trenner + TikZ-Diagramme) und berichtet
@@ -91,35 +103,40 @@ ab PR 1 vor. Das finale Produkt ist `dist/kant-sachbuch.pdf`.
Direktaufruf (falls `just` fehlt):
```sh
python3 scripts/assemble_book.py
mkdir -p dist build
pandoc build/book.md \
--from=markdown+smart+pipe_tables+table_captions+fenced_code_attributes+link_attributes+raw_attribute+header_attributes-implicit_figures \
--pdf-engine=lualatex \
--pdf-engine-opt=-interaction=nonstopmode \
--template=pdf/templates/kant-book.tex \
-H pdf/styles/kant-colors.tex \
--metadata-file=pdf/metadata.yaml \
--lua-filter=pdf/filters/boxes.lua \
--lua-filter=pdf/filters/figures.lua \
--lua-filter=pdf/filters/partpages.lua \
--resource-path=.:bilder:assets:build \
-V lang=de-DE -V papersize=a4 -V colorlinks \
--toc -o dist/kant-sachbuch.pdf
-V toc-title=Inhaltsverzeichnis \
--toc --toc-depth=2 \
-o dist/kant-sachbuch.pdf
```
Weitere Rezepte: `just pdf-draft` (Entwurfs-PDF mit `draft`-Variable),
`just pdf-sample-styled` (gestylte Vorschau, erste 3 Kapitel) und
`just clean` (löscht `build/` und `dist/*.pdf`). Ohne `devbox` funktionieren
die Befehle auch direkt, sofern `pandoc`/`just` und LuaLaTeX im `PATH` sind.
`just pdf-sample-styled` (gestylte Vorschau, erste 3 Kapitel),
`just diagrams` (TikZ) und `just clean` (löscht Book/Logs/`dist/*.pdf`).
Ohne `devbox` funktionieren die Befehle auch direkt, sofern `pandoc`/`just`
und LuaLaTeX im `PATH` sind.
### Verzeichnisstruktur
- `assets/` — Bilder & Diagramme (`cover/`, `parts/`, `diagrams/`)
- `pdf/` — Template, Lua-Filter und Styles (`templates/`, `filters/`, `styles/`)
- `scripts/` — Assembler und QA (`assemble_book.py`, `check_pdf.py`)
- `build/` — Zwischen-Markdown (`book.md`, gitignored)
- `dist/` — finales PDF (`kant-sachbuch.pdf`, gitignored)
- `assets/` — **kanonische** Build-Bilder (`cover/`, `parts/`, `diagrams/`)
- `bilder/` — Katalog, Stil, Gemini-Prompts, `pics/` (Exports)
- `pdf/` — Template, Lua-Filter, Styles
- `scripts/` — Assembler und QA
- `build/` · `dist/` — generiert (gitignored)
- `_staging/` — rohe Imports (gitignored)
**Hinweis zu den Bildern:** Cover, Part-Trenner und TikZ-Diagramme liegen
unter `assets/cover/`, `assets/parts/` bzw. `assets/diagrams/` und wurden
selbst erzeugt. Sie lassen sich einfach durch eigene PNGs/JPGs (Cover/Parts)
bzw. PDFs (Diagramme) ersetzen — der Build bricht bei fehlenden Dateien nicht
(`\IfFileExists`-Absicherung).
**Bilder:** Build nur aus `assets/`. Prompts/Katalog unter `bilder/`. Fehlende
Dateien brechen den Build nicht (`\IfFileExists`).
### Formale Seiten (Selbstverlag)
-32
View File
@@ -1,32 +0,0 @@
# Kant-Sachbuch — Bild-Stil-Guide (PR5)
Einheitlicher Stil für alle Buch-Illustrationen (Cover + 6 Part-Trenner):
„Engraving / Line-Art / Vintage-Kupferstich“ im Geist von Kants Zeitalter.
## Farbpalette (Hex)
- Preußischblau (Akzent): `#1B3A4B`
- Gold (Akzent): `#C4A35A`
- Pergament / Creme (Hintergrund): `#F7F3EB`
## Gemeinsamer Stil-Suffix (an jeden Prompt anhängen)
```
Vintage engraving illustration, fine copperplate line art, monochrome ink with subtle Prussian blue (#1B3A4B) and gold (#C4A35A) accents on warm cream (#F7F3EB) background, classical 18th-century philosophy book plate, clean composition, no text, no photos, no modern 3D render
```
## Kompositions-Regeln
- Hochformat, nah an A4 (aspect_ratio `3:4`).
- Mitte / oberer Bereich nicht überladen — Platz für Titel-Text (Cover)
bzw. Teil-Nummer (Trenner).
- Keine eingebettete Schrift im Bild (Typografie kommt aus LaTeX).
- Cover braucht viel ruhigen Raum oben-mittig für den Buchtitel.
## Zielpfade
- `assets/cover/cover.jpg` — Cover-Seite (vollflächig; Quelle: `pics/kant-2.jpg`).
Die Präambel `pdf/templates/kant-preamble.tex` bindet es via
`\IfFileExists{assets/cover/cover.jpg}` relativ zum Repo-Root ein.
- `assets/parts/teil-01.png` … `teil-05.png` — Teile I–V
- `assets/parts/schluss.png` — Schluss-Kapitel
## Werkzeug
Bilder wurden mit der xAI Imagine `image_gen`-API erzeugt (JPG → via macOS `sips`
nach PNG konvertiert, Auflösung 864×1152 px).
+34
View File
@@ -0,0 +1,34 @@
# AGENTS.md — Manuskript (`buch/`)
Gilt bei Arbeit unter `buch/`. Root: [`../AGENTS.md`](../AGENTS.md).
## Quelle
- Editieren: Dateien hier. **Nicht** `build/book.md` oder `buch-gesamt.md` als Quelle behandeln.
- Kapitel-Reihenfolge: `scripts/assemble_book.py` → `CHAPTER_ORDER` (nicht raten).
## Stil (Pflicht)
Vollständig: [`../_hy3/style-sheet.md`](../_hy3/style-sheet.md). Kurz:
- Deutsch, „wir“-Anrede, lebendig/seriös; keine Emojis.
- Fachbegriff **fett** + kurze Erklärung beim **ersten** Vorkommen.
- Kapitel: Orientierung am Anfang, `## Zusammenfassung` am Ende.
- Zitate: *„…“* (Werk, Jahr) — **keine** erfundenen Kant-Zitate/AA-Seiten.
- Listen nur für echte Übersichten; Argumente in Prosa.
- Anti-KI-Glätte: Blacklist in style-sheet (W9).
## Marker
Figure-Marker **im Kapitel** an inhaltlich passender Stelle belassen/setzen:
```html
<!-- figure: assets/diagrams/<id> caption="Deutscher Titel" -->
```
IDs und Captions: [`../bilder/ABBILDUNGEN.md`](../bilder/ABBILDUNGEN.md).
Part-Trenner **nicht** manuell einfügen (Assembler).
## Fakten
Bei Zitaten/Daten: [`../_hy3/faktenblatt.md`](../_hy3/faktenblatt.md), [`../quellen.md`](../quellen.md).
-361
View File
@@ -1,361 +0,0 @@
# Hy3-Plan: Sachbuch „Immanuel Kant – Das gesamte Werk verständlich erklärt“
**Umsetzungsmodell:** Tencent Hy3 (`commandcode-hy3`)
**Orchestrator:** Grok (Eltern-Agent) – Koordination, Quality Gates, Merge
**Basisplan:** `plan.md` (inhaltlich unverändert gültig; dieser Plan regelt die *Ausführung mit Hy3*)
---
## 0. Kernentscheidung
Das Buch wird **nicht** primär vom Orchestrator Kapitel für Kapitel selbst geschrieben, sondern von **Hy3-Subagenten** (`spawn_subagent` mit `model: "commandcode-hy3"`).
| Rolle | Modell | Aufgabe |
|-------|--------|---------|
| Orchestrator | Grok (Session) | Scaffold, Prompts, Dispatch, Review, Merge, Längenkontrolle |
| Autoren-Subagenten | `commandcode-hy3` | Kapitel-/Teil-Manuskripte schreiben |
| Review-Subagenten | `commandcode-hy3` | Stil-, Fakten- und Kohärenzprüfung (read-only oder read-write Fixes) |
| Merge-Pass | Orchestrator (+ optional Hy3) | `buch-gesamt.md`, Wortzahl, Querverweise |
**Modell-Slug (verbindlich):** `commandcode-hy3`
Kein anderes Modell für Autoren-Tasks, es sei denn der User ändert das explizit.
---
## 1. Warum Hy3-Anpassung nötig ist
| Aspekt | Sequenzplan (Grok allein) | Hy3-Plan |
|--------|---------------------------|----------|
| Schreibkraft | Ein Agent, Kontextdruck | Viele parallele Hy3-Agenten |
| Stil | Natürlich einheitlich | **Muss per Prompt erzwungen** |
| Fakten | Ein Wissensstand | **Faktenblatt + Werkliste** an jeden Prompt |
| KrV-Tiefe | Ein langer Lauf | Kap. 6 in **Subkapitel-Batches** splitten |
| Risiko | Timeout/Kontext | Stilbruch, Wiederholung, Halluzination von Zitaten |
Hy3 eignet sich gut für umfangreiche, gut spezifizierte Schreibaufgaben. Deshalb: **sehr explizite Prompts**, **shared assets**, **enge Dateizuordnung**, **Review-Schleifen**.
---
## 2. Lieferformat (unverändert, mit Hy3-Assets)
```
/Volumes/SSD2TB/work/antigravity/kant/
├── README.md
├── hy3-plan.md # dieser Plan
├── _hy3/ # Steuerungsassets für Subagenten
│ ├── style-sheet.md
│ ├── faktenblatt.md # Daten, Werke, Jahreszahlen
│ ├── glossar-draft.md # Pflichtbegriffe + Kurzdefinitionen
│ ├── querverweise.md # Kapitelnummern, Verweisregeln
│ ├── prompt-template-autor.md
│ └── prompt-template-review.md
├── buch/
│ ├── 00-titelblatt-inhaltsverzeichnis.md
│ ├── teil-01-einfuehrung.md # Kap. 1–3 + Zwischenbilanz
│ ├── teil-02-vorkritisch.md # Kap. 4–5 + Zwischenbilanz
│ ├── kap-06-krv.md # extra Datei (Umfang)
│ ├── kap-07-kpv.md
│ ├── kap-08-ku.md
│ ├── teil-03-zwischenbilanz.md
│ ├── teil-04-weitere-schriften.md # Kap. 9–14 + Zwischenbilanz
│ ├── teil-05-system-wirkung.md # Kap. 15–18 (Glossar aus glossar.md)
│ ├── glossar.md # Kap. 16 final
│ └── schluss.md # Kap. 19–20
└── buch-gesamt.md
```
**Abweichung vom Basisplan:** Teil III wird in **einzelne Dateien** (Kap. 6–8) gesplittet, weil Hy3-Läufe bei 14k–18k Wörtern (KrV) sonst abbrechen oder ausdünnen.
---
## 3. Orchestration mit `spawn_subagent`
### 3.1 Standard-Parameter pro Autoren-Task
```text
subagent_type: "general-purpose"
model: "commandcode-hy3"
capability_mode: "read-write" # schreiben in zugewiesene Dateien
isolation: "none" # Default: gemeinsamer Workspace (klare File-Owner)
background: true
```
**Wann `isolation: "worktree"`?**
Nur wenn parallele Agents dieselben Dateien riskieren würden. Bei **disjunkten Zieldateien** reicht `none` und ist einfacher zu mergen.
### 3.2 File-Ownership (keine Konflikte)
| Agent-Welle | Agent-ID (logisch) | Schreibt nur |
|-------------|--------------------|--------------|
| W0 Scaffold | Orchestrator | `_hy3/*`, Gerüst `buch/*` |
| W1 | hy3-teil-01 | `buch/teil-01-einfuehrung.md` |
| W1 | hy3-teil-02 | `buch/teil-02-vorkritisch.md` |
| W1 | hy3-kap-06a | `buch/kap-06-krv.md` (Teil A: bis Analytik) |
| W2 | hy3-kap-06b | `buch/kap-06-krv.md` (Teil B anhängen: Dialektik–Schluss) **sequenziell nach 06a** |
| W2 | hy3-kap-07 | `buch/kap-07-kpv.md` |
| W2 | hy3-kap-08 | `buch/kap-08-ku.md` |
| W3 | hy3-teil-04 | `buch/teil-04-weitere-schriften.md` |
| W4 | hy3-teil-05 | `buch/teil-05-system-wirkung.md` + Draft Glossar |
| W4 | hy3-schluss | `buch/schluss.md` |
| W5 | hy3-glossar | `buch/glossar.md` final |
| W6 | hy3-review-* | Fixes nur in zugewiesener Datei |
| W7 | Orchestrator | Merge → `buch-gesamt.md` |
### 3.3 Wellenplan (kritischer Pfad)
```text
W0 Orchestrator: Scaffold + Style + Fakten + Glossar-Draft + Titelblatt/IV
│
├──────────────┬──────────────┐
W1 teil-01 teil-02 kap-06a (KrV 1. Hälfte)
│ │ │
│ │ W2 kap-06b (KrV 2. Hälfte, sequenziell)
│ │ ├──────── kap-07 ── kap-08 (parallel zu 06b ok)
│ │ │
W3 (warten auf W1+W2 Kern) → teil-04 (9–14)
│
W4 teil-05 + schluss (brauchen Überblick über fertige Teile)
│
W5 glossar final + Zwischenbilanzen nachziehen
│
W6 Review-Welle (Hy3): Stil, Fakten, Querverweise, Lücken
│
W7 Orchestrator: Merge, Wortzahl, README, finale Stichprobe
```
**Parallelität max. 3–4 Hy3-Agenten** gleichzeitig, um Reviewbarkeit und I/O-Konflikte zu begrenzen.
---
## 4. Shared Assets (muss vor W1 stehen)
### 4.1 `_hy3/style-sheet.md` (Auszug der Regeln)
- Deutsche Sprache, modern, lebendig, seriös
- Keine Emojis im Buchtext
- Jedes Kapitel: `## Worum geht es in diesem Kapitel?` → Hauptteil → `## Zusammenfassung`
- Fachbegriff beim **ersten** Vorkommen: **fett**, dann 1–2 Sätze Erklärung + Beispiel
- Zitate: kurz, danach erklären; Format: *„Zitat…“* (Werk, Jahr)
- Keine erfundenen Akademie-Seitenzahlen
- Anrede: „wir“; Kant respektvoll; Kritik fair
- Listen nur für Übersichten; Argumente in Prosa
- Zielwortzahl pro Auftrag **explizit** nennen und annähernd einhalten
### 4.2 `_hy3/faktenblatt.md` (Pflichtinhalte)
- Lebensdaten: 22.4.1724 – 12.2.1804, Königsberg
- Werksjahre: KrV 1781/1787, Prolegomena 1783, GMS 1785, KpV 1788, KU 1790, Religion 1793, Ewiger Frieden 1795, MS 1797, Anthropologie 1798
- A- vs. B-Auflage KrV
- Drei Fragen + „Was ist der Mensch?“
- Kategorischer Imperativ: kanonische Formulierungen (Vorlage, nicht frei erfinden)
- Vier Antinomien (These/Antithese stichwortartig)
- Kategorien: 4 Gruppen à 3 (Tafel-Stichworte)
### 4.3 `_hy3/glossar-draft.md`
40–60 Lemmata mit 1-Satz-Definition als **Terminologie-Anker** (Autoren dürfen ausformulieren, aber nicht umdefinieren).
### 4.4 Prompt-Template Autor (Pflichtblöcke)
Jeder Hy3-Autorenprompt enthält:
1. **Rolle:** „Du bist Fachautor eines seriösen deutschsprachigen Kant-Sachbuchs.“
2. **Modellkontext:** stilistisch einheitlich mit den anderen Teilen; lies zuerst `_hy3/style-sheet.md` und `_hy3/faktenblatt.md`.
3. **Zieldatei** (exakter Pfad) – nur diese Datei schreiben/überschreiben.
4. **Kapitelstruktur** (Überschriften 1:1 aus Plan).
5. **Zielwortzahl** (Min–Max).
6. **Inhaltliche Bullet-Punkte** (aus Basisplan Kap. X).
7. **Querverweise:** „siehe Kapitel N“ nur auf existierende Nummern.
8. **Verbote:** keine Meta-Kommentare („Als KI…“), keine englischen Passagen, keine erfundenen Zitate.
9. **Done-Kriterium:** Datei vollständig, Vorbemerkung + Zusammenfassung, Wortzahl im Korridor.
10. **Am Ende:** kurze Agent-Notiz an Orchestrator (Wortzahl, offene Unsicherheiten) – *nicht* in die Buchdatei, sondern in `_hy3/reports/<task>.md`.
### 4.5 Prompt-Template Review
- Lies Zieldatei + Style + Fakten
- Prüfe: Vollständigkeit der Unterabschnitte, Begriffserklärungen, erfundene Zitate, Längen, Tonalität
- Schreibe Fix **in die Datei** (wenn read-write) oder Report nach `_hy3/reports/`
- Checkliste abhaken
---
## 5. Spezielle Hy3-Strategie für Kapitel 6 (KrV)
Kap. 6 ist zu groß für einen einzigen zuverlässigen Hy3-Lauf.
| Batch | Inhalt | Zielwörter |
|-------|--------|------------|
| 06a | Zentralfrage, analytisch/synthetisch, a priori, synth. Urteile a priori, Raum/Zeit, Kategorien, Deduktion (gestuft), Idealismus | 8.000–10.000 |
| 06b | Dialektik, Paralogismen, Antinomien (Tabelle), Ideen regulativ, A/B-Auflage, Kritik & Fragen, **Kapitel-Zusammenfassung** | 6.000–8.000 |
**Regel:** 06b **hängt an** 06a an (nicht neu schreiben). Prompt für 06b enthält: „Lies `kap-06-krv.md` vollständig; setze ab Überschrift X fort; überschreibe 06a nicht.“
Kap. 7 und 8: je **ein** Hy3-Lauf (8–10k Wörter) mit detaillierter Gliederung im Prompt.
---
## 6. Inhaltlicher Leitfaden (kurz – Details wie Basisplan)
Unverändert aus `plan.md`:
- **Teil I:** Kap. 1–3
- **Teil II:** Kap. 4–5
- **Teil III:** Kap. 6–8
- **Teil IV:** Kap. 9–14
- **Teil V:** Kap. 15–18
- **Schluss:** Kap. 19–20
Jedes Kapitel: Vorbemerkung + Zusammenfassung.
Jeder Teil: Zwischenbilanz.
Stil, Zitate, Kritik: wie Basisplan Abschnitt 2 und 5.
---
## 7. Qualitäts-Gates (Hy3-spezifisch)
### Gate G0 – vor W1
- [ ] `_hy3/style-sheet.md` existiert
- [ ] `_hy3/faktenblatt.md` existiert
- [ ] `_hy3/glossar-draft.md` existiert
- [ ] Titelblatt + Inhaltsverzeichnis stehen
### Gate G1 – nach jedem Autoren-Deliverable
- [ ] Datei nicht leer / nicht abgebrochen mitten im Satz
- [ ] Wortzahl ≥ 80 % des Minimums
- [ ] Vorbemerkung + Zusammenfassung vorhanden
- [ ] Keine Meta-KI-Floskeln
- [ ] Stichprobe Fakten (1–2 Jahreszahlen) korrekt
### Gate G2 – nach Teil III
- [ ] Kap. 6 enthält Antinomien + synth. a priori + Raum/Zeit
- [ ] Kap. 7 enthält alle KI-Formulierungen
- [ ] Kap. 8 erklärt Brückenfunktion
### Gate G3 – vor Merge
- [ ] Alle 20 Kapitel abgedeckt
- [ ] Glossar final
- [ ] Zwischenbilanzen vorhanden
- [ ] Review-Reports ohne Blocker
### Gate G4 – final
- [ ] `buch-gesamt.md` gebaut
- [ ] Gesamtwortzahl im Korridor ~95k–125k (flexibel 80k–140k akzeptabel mit Notiz)
- [ ] README aktualisiert
**Bei Gate-Fail:** gezielter Hy3-Rewrite-Prompt nur für den defekten Abschnitt (nicht ganzes Buch neu).
---
## 8. Umgang mit Hy3-typischen Fehlerbildern
| Fehlerbild | Gegenmaßnahme |
|------------|----------------|
| Kapitel endet abrupt | Resume-Prompt: „Continue from last heading…“ / `resume_from` falls sinnvoll |
| Zu kurz / oberflächlich | Expand-Prompt mit Mindestwörtern pro Unterabschnitt |
| Erfundene Kant-Zitate | Verbot im Style; Review streicht oder ersetzt durch kanonische Kurzform / Paraphrase |
| Stilbruch („Du“-Anrede, Listenflut) | Style-Rewrite-Pass Hy3 mit style-sheet |
| Doppelte Begriffserklärungen | Kohärenz-Pass: erstes Vorkommen behalten |
| Englische Einsprengsel | DE-only Fix-Pass |
| Halluzinierte Sekundärliteratur | Kap. 20: nur kuratierte Liste aus Faktenblatt/Orchestrator-Vorlage |
---
## 9. Orchestrator-Workflow (konkrete Tool-Schritte)
1. **Scaffold** (Orchestrator): Ordner, Assets, leere Ziel-Dateien mit H1-Titel.
2. **Dispatch W1:** 3× `spawn_subagent` (`model: commandcode-hy3`, disjunkte Dateien).
3. **`get_command_or_subagent_output`** auf alle Task-IDs (warten).
4. **G1** pro Datei; bei Fail: Fix-Agent.
5. **Dispatch W2** (06b sequenziell nach 06a; 07/08 parallel).
6. **W3–W5** analog.
7. **W6 Review:** 1–2 Hy3-Reviewer (Teil I–II, Teil III, Teil IV–V).
8. **Merge:**
`cat`/`//` Reihenfolge: 00 → teil-01 → teil-02 → kap-06 → kap-07 → kap-08 → bilanz-03 → teil-04 → teil-05 → glossar → schluss
9. Wortzahl: `wc -w buch-gesamt.md`
10. README + kurze Abschlussnotiz an User.
**Timeouts:** große Kapitel-Agenten mit ausreichend Zeit; bei Hintergrund-Tasks auf Completion-Notify warten, nicht busy-loopen.
---
## 10. Prompt-Skizze (Beispiel W1 – Teil I)
```text
Modell: commandcode-hy3
Aufgabe: Schreibe vollständig buch/teil-01-einfuehrung.md
Lies zuerst:
- _hy3/style-sheet.md
- _hy3/faktenblatt.md
- _hy3/glossar-draft.md
Inhalt:
# Teil I – Einführung
## Kapitel 1 – Wer war Immanuel Kant?
[… Bullet-Punkte aus Basisplan …]
## Kapitel 2 – Warum ist Kant so wichtig?
[…]
## Kapitel 3 – Vorkritische und kritische Periode
[…]
## Zwischenbilanz Teil I
Zielwortzahl: 10.500–14.000 Wörter gesamt.
Jedes Kapitel: Abschnitt „Worum geht es in diesem Kapitel?“ und „Zusammenfassung“.
Nur diese eine Datei schreiben.
Report: _hy3/reports/teil-01.md mit Wortzahl und Unsicherheiten.
```
---
## 11. Erfolgskriterien (wie Basisplan + Hy3)
- [ ] Alle 20 Kapitel + Titelblatt + IV
- [ ] Umgesetzt **überwiegend durch** `commandcode-hy3`-Subagenten
- [ ] Orchestrator-Merge zu `buch-gesamt.md`
- [ ] Gates G0–G4 grün
- [ ] Einheitlicher Stil (Review bestanden)
- [ ] Keine erfundenen Zitate / keine groben Datumsfehler
- [ ] Umfang sachbuchtauglich (Ziel 250–350 MS-Seiten)
---
## 12. Risiken & Defaults
| Risiko | Default-Gegenmaßnahme |
|--------|----------------------|
| Hy3-Agent zu flach | Mindestwörter + Pflicht-Unterüberschriften im Prompt |
| Parallele Konflikte | Disjunkte File-Ownership |
| Kontextverlust | Shared `_hy3/*` statt langer Chat-History |
| Review endlos | Max. 2 Fix-Runden pro Datei, dann Orchestrator-Entscheidung |
| Worktree-Overhead | Default `isolation: none` |
### Offene Defaults (wie Basisplan)
- Zitation: Werk + Jahr/Abschnitt (keine AA-Pflicht)
- Sekundärliteratur: kurze kuratierte Liste
- Anthropologie/Rasse: ehrlich, knapp in Kap. 14 + 18
---
## 13. Sofortstart nach Freigabe dieses Plans
1. Orchestrator legt `_hy3/` + `buch/` an und schreibt Style, Fakten, Glossar-Draft, Titelblatt.
2. Start W1: drei Hy3-Agenten (Teil I, Teil II, Kap. 06a).
3. Fortsetzung nach Wellenplan bis `buch-gesamt.md`.
**Nicht** mit dem Schreiben der Kapitel beginnen, bevor G0 erfüllt ist.
---
## 14. Abgrenzung zum Basisplan
| Thema | `plan.md` | `hy3-plan.md` |
|-------|-----------|---------------|
| Was geschrieben wird | vollständige Buchstruktur | identisch |
| Wer schreibt | implizit ein Agent | **Hy3-Subagenten** |
| Wie parallelisiert | optional/zurückhaltend | **Wellen + Ownership** |
| Kap. 6 | ein Block | **06a/06b Split** |
| Qualität | Stil-Sheet intern | **Gates + Review-Agenten + Reports** |
| Modell | — | **`commandcode-hy3` verpflichtend** |
Bei Widerspruch in *Ausführungstechnik* gilt dieser Hy3-Plan; bei *Inhalt/Kapitelstruktur* gilt der Basisplan.
+97 -30
View File
@@ -1,100 +1,167 @@
# Justfile — Build orchestration for the Kant Sachbuch PDF
#
# PR 6 (Finalisierung): `pdf` / `pdf-styled` produce the FINAL product
# `dist/kant-sachbuch.pdf` via the full design-system pipeline
# (assemble build/book.md + KOMA/LuaLaTeX template + 3 Lua-filters).
# Portiert/gehärtet nach Konventionen des Schwesterprojekts ../ki-buch
# (resource-path, nonstopmode, pandoc.log, toc-title, Größen-Report),
# ohne Mermaid/Callout-Preprocess (kant hat TikZ-Diagramme + HTML-Figure-Marker).
#
# TeX/LaTeX is intentionally NOT provided by Devbox — the host's
# existing TeX Live (with KOMA-Script / scrbook.cls) is used as the
# fallback. Devbox supplies pandoc + just; the recipe simply passes
# the commands through.
# Requires: pandoc, lualatex (TeX Live + KOMA), python3
# Optional: just, devbox, pdfinfo
# Default recipe — build the final styled PDF.
default: pdf
# ---------------------------------------------------------------------------
# Assembler (PR3): builds build/book.md from the individual buch/*.md files
# in fixed order, injecting part pages + figure markers.
# Assembler: builds build/book.md from buch/*.md in fixed CHAPTER_ORDER
# ---------------------------------------------------------------------------
assemble:
@python3 scripts/assemble_book.py
# ---------------------------------------------------------------------------
# Final product (PR 6): full design-system build from the assembled
# build/book.md, rendered with the Kant KOMA/LuaLaTeX template + the
# boxes / figures / partpages Lua-filters. Output: dist/kant-sachbuch.pdf
# TikZ diagrams → assets/diagrams/*.pdf
# ---------------------------------------------------------------------------
diagrams:
#!/usr/bin/env bash
set -euo pipefail
if [[ -x assets/diagrams/build.sh ]]; then
bash assets/diagrams/build.sh
else
echo "WARN: assets/diagrams/build.sh missing or not executable"
exit 1
fi
# ---------------------------------------------------------------------------
# Final product: KOMA/LuaLaTeX template + Lua filters
# Output: dist/kant-sachbuch.pdf
# ---------------------------------------------------------------------------
pdf-styled: assemble
@mkdir -p dist
#!/usr/bin/env bash
set -euo pipefail
mkdir -p dist build
echo "==> Pandoc → PDF (LuaLaTeX)…"
pandoc build/book.md \
--from=markdown+smart+pipe_tables+table_captions+fenced_code_attributes+link_attributes+raw_attribute+header_attributes-implicit_figures \
--pdf-engine=lualatex \
--pdf-engine-opt=-interaction=nonstopmode \
--template=pdf/templates/kant-book.tex \
-H pdf/styles/kant-colors.tex \
--metadata-file=pdf/metadata.yaml \
--lua-filter=pdf/filters/boxes.lua \
--lua-filter=pdf/filters/figures.lua \
--lua-filter=pdf/filters/partpages.lua \
--resource-path=.:bilder:assets:build \
-V lang=de-DE -V papersize=a4 -V colorlinks \
--toc -o dist/kant-sachbuch.pdf
-V toc-title=Inhaltsverzeichnis \
--toc --toc-depth=2 \
-o dist/kant-sachbuch.pdf \
2> build/pandoc.log || {
echo "ERROR: pandoc failed. Last 80 lines of build/pandoc.log:"
tail -n 80 build/pandoc.log || true
exit 1
}
SIZE=$(wc -c < dist/kant-sachbuch.pdf | tr -d ' ')
PAGES=$(pdfinfo dist/kant-sachbuch.pdf 2>/dev/null | awk '/^Pages:/ {print $2}' || echo "?")
echo "==> Done: dist/kant-sachbuch.pdf ($SIZE bytes, ~$PAGES pages)"
# Alias for the final product (PR 6).
# Alias for the final product.
pdf: pdf-styled
# Draft PDF: keeps TOC, adds a `draft` variable for styling hooks.
# Draft PDF: same pipeline, draft variable for styling hooks.
pdf-draft: assemble
@mkdir -p dist
#!/usr/bin/env bash
set -euo pipefail
mkdir -p dist build
pandoc build/book.md \
--from=markdown+smart+pipe_tables+table_captions+fenced_code_attributes+link_attributes+raw_attribute+header_attributes-implicit_figures \
--pdf-engine=lualatex \
--pdf-engine-opt=-interaction=nonstopmode \
--template=pdf/templates/kant-book.tex \
-H pdf/styles/kant-colors.tex \
--metadata-file=pdf/metadata.yaml \
--lua-filter=pdf/filters/boxes.lua \
--lua-filter=pdf/filters/figures.lua \
--lua-filter=pdf/filters/partpages.lua \
--resource-path=.:bilder:assets:build \
-V lang=de-DE -V papersize=a4 -V colorlinks \
-V toc-title=Inhaltsverzeichnis \
-V draft=true \
--toc -o dist/kant-sachbuch-draft.pdf
--toc --toc-depth=2 \
-o dist/kant-sachbuch-draft.pdf \
2> build/pandoc.log || {
echo "ERROR: pandoc failed. Last 80 lines of build/pandoc.log:"
tail -n 80 build/pandoc.log || true
exit 1
}
echo "==> Draft: dist/kant-sachbuch-draft.pdf"
# Sample PDF: only the first 3 chapter files, for fast layout iteration.
# Sample PDF: first chapter files, fast layout iteration (no full assemble).
pdf-sample:
@mkdir -p dist
#!/usr/bin/env bash
set -euo pipefail
mkdir -p dist build
pandoc \
buch/00-titelblatt-inhaltsverzeichnis.md \
buch/teil-01-einfuehrung.md \
buch/teil-02-vorkritisch.md \
--from=markdown+smart+pipe_tables+table_captions+fenced_code_attributes+link_attributes+raw_attribute+header_attributes-implicit_figures \
--pdf-engine=lualatex \
--pdf-engine-opt=-interaction=nonstopmode \
-V documentclass=scrbook \
-V lang=de-DE \
-V papersize=a4 \
--toc \
-o dist/kant-sample.pdf
-V toc-title=Inhaltsverzeichnis \
--toc --toc-depth=2 \
--resource-path=.:bilder:assets \
-o dist/kant-sample.pdf \
2> build/pandoc-sample.log || {
echo "ERROR: sample build failed. Last 80 lines:"
tail -n 80 build/pandoc-sample.log || true
exit 1
}
echo "==> Sample: dist/kant-sample.pdf"
# Styled sample PDF (PR 2/3): first 3 chapter files + title, fast layout check.
# Styled sample (template + filters, first chapters).
pdf-sample-styled:
@mkdir -p dist
#!/usr/bin/env bash
set -euo pipefail
mkdir -p dist build
pandoc \
buch/00-titelblatt-inhaltsverzeichnis.md \
buch/teil-01-einfuehrung.md \
buch/teil-02-vorkritisch.md \
--from=markdown+smart+pipe_tables+table_captions+fenced_code_attributes+link_attributes+raw_attribute+header_attributes-implicit_figures \
--pdf-engine=lualatex \
--pdf-engine-opt=-interaction=nonstopmode \
--template=pdf/templates/kant-book.tex \
-H pdf/styles/kant-colors.tex \
--metadata-file=pdf/metadata.yaml \
--lua-filter=pdf/filters/boxes.lua \
--lua-filter=pdf/filters/figures.lua \
--lua-filter=pdf/filters/partpages.lua \
--resource-path=.:bilder:assets:build \
-V lang=de-DE \
-V papersize=a4 \
-V colorlinks \
--toc \
-o dist/kant-sample-styled.pdf
-V toc-title=Inhaltsverzeichnis \
--toc --toc-depth=2 \
-o dist/kant-sample-styled.pdf \
2> build/pandoc-sample.log || {
echo "ERROR: styled sample failed. Last 80 lines:"
tail -n 80 build/pandoc-sample.log || true
exit 1
}
echo "==> Sample styled: dist/kant-sample-styled.pdf"
# Quality assurance: run the post-build PDF checks (PR 6).
# Quality assurance: post-build PDF checks.
qa:
@python3 scripts/check_pdf.py
# Clean build artifacts (only the things we create).
# Clean generated book/PDF artifacts (keep assets).
clean:
@rm -rf build
@rm -f build/book.md build/pandoc.log build/pandoc-sample.log
@rm -f dist/*.pdf
@echo "cleaned build/ and dist/*.pdf"
@echo "cleaned build/book.md, logs, and dist/*.pdf"
# Full clean including temp review renders
clean-all: clean
@rm -rf tmp
@echo "also removed tmp/"