diff --git a/docs/superpowers/specs/2026-06-12-projekt-anlegen-erweiterung-design.md b/docs/superpowers/specs/2026-06-12-projekt-anlegen-erweiterung-design.md new file mode 100644 index 0000000..52b40f7 --- /dev/null +++ b/docs/superpowers/specs/2026-06-12-projekt-anlegen-erweiterung-design.md @@ -0,0 +1,132 @@ +# Design: Erweiterung des Skills `projekt-anlegen` + +**Datum:** 2026-06-12 +**Status:** Freigegeben (Brainstorming abgeschlossen) +**Sprache:** Deutsch +**Basis:** Die unveränderte Ausgangsfassung ist als inaktiver Skill `cowork-projekt-match` archiviert. Aktiv erweitert wird `.claude/skills/projekt-anlegen/SKILL.md`. + +## 1. Zweck + +Den aus Claude Cowork übernommenen und an diese Umgebung angepassten Skill `projekt-anlegen` zum gewünschten Zielzustand erweitern: + +1. Rahmenbedingungen (Verfügbarkeit, Auslastung, Laufzeit, Einsatzort) **automatisch** aus einer festen Vorgaben-Datei bewerten — damit Thomas sie nicht in jedem Review manuell setzen muss. +2. Aus der Ausschreibung zusätzlich **Käufer-Typ**, **Ansprechperson** und **Firmenname** extrahieren. +3. Beim CRM-Eintrag zuerst **Firma**, dann **Kontakt**, dann **Verkaufschance** anlegen (mit Dedup-Prüfung) und korrekt verknüpfen. + +### Erfolgskriterien +- Misc-Anforderungen werden ohne Rückfrage mit ✅/❌/❔ bewertet, sofern die Regeln greifen. +- Firma und Kontakt werden vor der Verkaufschance angelegt oder wiederverwendet; keine ungewollten Dubletten. +- Agenturen erhalten `type = Reseller` und landen im Feld „Über Agentur" (`cAccount1`); der Endkunde landet bei Direktaufträgen im Feld `account`. + +## 2. Verifizierte CRM-Fakten (EspoCRM) + +- **`Account.type`** ist ein Enum mit den API-Werten `Customer`, `Investor`, `Partner`, `Reseller`. „Wiederverkäufer" (Oberfläche) = API-Wert **`Reseller`**. +- **`Contact`** verknüpft die Firma über `accountId`/`accountName`; Personenname über `firstName`/`lastName` (+ optional `salutationName`, `emailAddress`). +- **`Opportunity`**-Verknüpfungen: `account` (Hauptfirma, link), `cAccount1` (= „Über Agentur", link), `contacts` (linkMultiple). Setzen beim Anlegen über `accountId`, `cAccount1Id`, `contactsIds: []`. +- Zugriff direkt per `curl` (Key/Base aus `.secrets/espocrm-api.md`), wie in der aktuellen Skill-Fassung etabliert. + +## 3. Neue Vorgaben-Datei `vorgaben/rahmenbedingungen.md` + +Genau dieser Inhalt wird angelegt: + +```markdown +# Rahmenbedingungen (Misc-Bewertung) + +Feste Kriterien für die automatische Bewertung von Rahmenbedingungen (Kategorie Misc) +durch den Skill `projekt-anlegen`. Ändern sich selten. + +## Kriterien + +| Dimension | Vorgabe | Bewertung | +|---|---|---| +| Verfügbar ab | sofort | Projektstart ≤ 8 Wochen ab heute → ✅; > 8 Wochen → ❌; nicht genannt → ❔ | +| Auslastung | 100 % (Vollzeit) | 75–100 % → ✅; < 75 % → ❔; nicht genannt → ❔ | +| Laufzeit | keine Einschränkung | jede Laufzeit → ✅ | +| Einsatzort / Remote | 100 % Remote oder Onsite ≤ 50 km um Sauerlach | siehe Einsatzort-Regel | + +## Einsatzort-Regel +- 100 % Remote → ✅ (Ort egal). +- Onsite/Hybrid, Ort ≲ 50 km Luftlinie um Sauerlach → ✅. +- Onsite/Hybrid, Ort grenzwertig ≈ 50–60 km → ❔. +- Onsite/Hybrid, Ort ≳ 60 km → ❌. +- Einsatzort/Remote-Anteil unklar oder nicht genannt → ❌. + +### Referenz-Distanzen ab Sauerlach (Luftlinie, gerundet) +- München-Zentrum ≈ 25 km ✅ · Holzkirchen ≈ 10 km ✅ · Wolfratshausen ≈ 15 km ✅ · Rosenheim ≈ 40 km ✅ +- Augsburg ≈ 75 km ❌ · Landshut ≈ 80 km ❌ · Ingolstadt ≈ 95 km ❌ · Nürnberg ≈ 150 km ❌ · Stuttgart ≈ 200 km ❌ + +Hinweis: „heute" = aktuelles Datum der Session. „8 Wochen" = 56 Tage. +``` + +## 4. Extraktion erweitern (Skill-Schritt 1) + +Zusätzlich zu Projektname/URL/Anforderungen aus der Ausschreibung ziehen: + +- **Käufer-Typ:** Agentur (Wiederverkäufer) **oder** Endkunde (Direktauftrag). + - Signale für Agentur: bekannte Personaldienstleister/Vermittler (z. B. Hays, GULP/Randstad, SThree/Computer Futures, Aristo), Formulierungen wie „im Auftrag unseres Kunden", „für unseren Kunden", Vermittler-Kontext des Portals. + - Ist der Typ nicht eindeutig bestimmbar, im Review nachfragen. +- **Ansprechperson:** vollständiger Name (für Aufteilung in Vor-/Nachname siehe §6). +- **Firmenname:** Name der Agentur bzw. des Endkunden. + +## 5. Rahmenbedingungen automatisch bewerten (Skill-Schritt 3/4) + +Misc-Anforderungen zu Verfügbarkeit/Auslastung/Laufzeit/Einsatzort werden gegen `vorgaben/rahmenbedingungen.md` bewertet und erhalten direkt ✅/❌/❔ gemäß den Regeln in §3 — **statt** des bisherigen pauschalen ❔. Greift eine Regel nicht eindeutig (Auslastung/Start nicht genannt, Ort grenzwertig), bleibt es ❔. + +- Distanzbeurteilung: Luftlinie vom genannten Onsite-Ort nach Sauerlach schätzen; Referenz-Distanzen aus §3 als Anker. Klar innerhalb → ✅, klar außerhalb → ❌, grenzwertig/unbekannter Ort → ❔ bzw. ❌ gemäß Regel. +- Startdatum: „heute + 8 Wochen" (56 Tage) gegen den genannten Projektstart prüfen. +- Misc-Zeilen gehen weiterhin **nicht** in die Match-Prozente ein; die automatische Bewertung ist informativ und spart das manuelle Setzen. + +## 6. CRM-Schreibablauf (Skill-Schritt 7) — Reihenfolge Firma → Kontakt → Verkaufschance + +Alle Schreibvorgänge erst **nach** der Review-Freigabe (§7). + +### 6.1 Firma (`Account`) +1. Dedup-Suche per Name (Kern-Token), inkl. naher Varianten (z. B. „Aristo Recruitment" vs. „Aristo Recruitment GmbH"). +2. Exakter/eindeutiger Treffer → bestehenden Datensatz wiederverwenden (im Review als „bestehend" ausweisen). +3. Ähnlich-aber-nicht-identisch → Kandidaten im Review auflisten; Thomas entscheidet „wiederverwenden" oder „neu anlegen". Nie still anlegen oder zusammenführen. +4. Kein Treffer → neu anlegen: `POST /Account` mit `{name, type}`. + - Agentur → `type = "Reseller"`. + - Endkunde (Direktauftrag) → `type = "Customer"`. + +### 6.2 Kontakt (`Contact`) +1. Dedup-Suche per Name analog zu 6.1. +2. Kein/zu bestätigender Treffer → nach Freigabe neu anlegen: `POST /Contact` mit `{firstName, lastName, accountId}` (verknüpft mit der Firma aus 6.1). + - Namensaufteilung: letztes Token = `lastName`, der Rest = `firstName`. Ungewöhnliche Fälle im Review klären. + +### 6.3 Verkaufschance (`Opportunity`) +`POST /Opportunity` wie bisher (`name`, `description` = Match-Tabelle, `cProjektlink`) **plus** Verknüpfungen: +- `contactsIds: []` +- **Agentur:** `cAccount1Id = ` („Über Agentur"); `account` bleibt **leer**. +- **Direktauftrag:** `accountId = `; `cAccount1` bleibt leer. + +Duplikat-Regel für den Opportunity-Namen (Suffix „ (2)", „ (3)", …) bleibt wie in der aktuellen Fassung. + +## 7. Review erweitern (Skill-Schritt 6) + +Vor jedem Schreibvorgang zeigt das Review zusätzlich zur bestehenden Match-Tabelle und den ❌/❔-Begründungen: +- **Käufer-Typ** (Agentur/Direktauftrag) mit Kurzbegründung. +- **Firma:** Name und `type`; „neu anlegen" oder „bestehende nutzen: "; bei Mehrdeutigkeit die Kandidatenliste. +- **Kontakt:** Name; „neu" oder „bestehend". +- **Verknüpfungs-Zuordnung** der Verkaufschance (account vs. cAccount1, Kontakt). + +Erst nach Freigabe werden Firma, Kontakt und Verkaufschance in dieser Reihenfolge geschrieben (§6). + +## 8. Geänderte/neue Dateien +- Neu: `vorgaben/rahmenbedingungen.md` (§3). +- Geändert: `.claude/skills/projekt-anlegen/SKILL.md` (Schritte 1, 3/4, 6, 7; Voraussetzungen um `rahmenbedingungen.md` ergänzt). +- Ggf. ergänzt: `CLAUDE.md` (Hinweis auf `vorgaben/rahmenbedingungen.md`). +- Unberührt: `cowork-projekt-match` (Archiv). + +## 9. Bewusst NICHT enthalten (YAGNI) +- Keine automatische Geokodierung/Distanz-API — Distanz wird anhand der Referenz-Anker geschätzt; Grenzfälle → ❔. +- Keine automatische Zusammenführung bestehender CRM-Dubletten. +- Keine Änderung der Must/Nice-Bewertungslogik oder der Match-Berechnung. + +## 10. Offene Annahme (im Spec-Review zu bestätigen) +- **Projektstart „nicht genannt" → ❔** (Review entscheidet). Alle anderen „nicht genannt"-Fälle sind oben explizit geregelt. + +## Selbstreview +- Alle vier Rahmen-Dimensionen haben eindeutige ✅/❌/❔-Regeln inkl. „nicht genannt"-Fall (Start = ❔, Auslastung = ❔, Einsatzort = ❌, Laufzeit n/a). ✓ +- CRM-Feldnamen gegen die API verifiziert (`type=Reseller/Customer`, `account`/`cAccount1`/`contacts`). ✓ +- Schreibreihenfolge und Verknüpfungen für beide Käufer-Typen konsistent. ✓ +- Keine Platzhalter; Dedup-Verhalten entspricht der getroffenen Entscheidung (Kandidaten im Review). ✓