BlackAgents

BlackAgents App Patterns

Anwendungsbereich

Lesen, wenn eine Funktion oder Korrektur implementiert wird, die app/**, app/api/** oder lib/** betrifft. Die harten Beschränkungen sind in den Regeln typescript-strict und api-response-format festgelegt; diese Datei erklärt die Schichten und die Rezepte.

Architektur (die Schichten respektieren)

UI (components/features/, client) ──fetch──▶ API routes (app/api/**/route.ts)
                                                    │  { success, data | error }
                                              Domain (lib/artifacts/, lib/standards/)
                                                    │  parse / serialize / graph
                                              Filesystem (lib/fs-service.ts)
                                                    │  resolveInWorkspace (no escape)
                                              Workspace folder (.cursor / .claude ...)

Verhaltensregeln:

• Reine, plattformunabhängige Logik lebt in lib/artifacts/**. Sie importiert niemals React oder next/server.
• HTTP-Belange leben ausschließlich in app/api/**/route.ts.
• Jeder Plattenzugriff erfolgt über lib/fs-service.ts; node:fs niemals direkt aus einer Route aufrufen.

App Router Konventionen

• Seiten sind standardmäßig Serverkomponenten; füge "use client" nur für Interaktivität/State/Effekte hinzu.
• Routengruppen: /agents, /commands, /rules, /skills haben jeweils eine Listenseite, eine [name]-Bearbeitungsseite und eine new-Seite; /new ist der geführte Assistent. Weitere Routen: /graph, /standards, /export, /sync, /chat, /providers, /settings.
• Client-Feature-Komponenten rufen apiFetch (lib/api.ts) auf und lesen den aktiven Workspace-State aus WorkspaceProvider – kein rohes fetch und keine direkten Konfigurationszugriffe im Client.

API-Route Rezept

import { ok, fail, handle } from "@/lib/api-response"
import { artifactInputSchema } from "@/lib/artifacts/schemas"

export async function POST(req: Request) {
  return handle(async () => {
    const parsed = artifactInputSchema.safeParse(await req.json())
    if (!parsed.success) return fail(parsed.error.issues[0].message, 400)
    // ...Domänenarbeit via lib/artifacts + lib/fs-service...
    return ok({ /* data */ })
  })
}

• Immer über ok / fail zurückgeben; in handle einwickeln, damit Würfe zu einem 500-Envelope werden.
• Workspace-Wurzel aus der Konfiguration lesen (lib/config.ts), dann resolveInWorkspace(root, relPath) verwenden.
• Geheimnisse mit lib/secrets.ts nur serverseitig lesen; fehlende Zugangsdaten → fail("...", 412).

Das Domänenmodell

lib/artifacts/:

• types.ts — Artifact, ArtifactType, Platform, ArtifactFrontmatter (werkzeugunabhängig).
• layout.ts — PLATFORM_LAYOUTS + artifactRelPath() / artifactDeletePath(); der einzige Ort, der die Ordner/Erweiterungen einer Plattform kennt. ACTIVE_PLATFORMS = ["cursor", "claude"], Standard cursor.
• parser.ts — scanWorkspace(root) und parseArtifact (via gray-matter); Skills werden als ein <name>/SKILL.md-Verzeichnis rekursiv durchlaufen.
• serializer.ts — serializeArtifact(input) schreibt Frontmatter + Body; Regeln lassen name weg (werden per Dateinamen identifiziert).
• schemas.ts — nameSchema (kebab-case), artifactInputSchema, normalizeExtra (pro Typ Frontmatter).
• graph.ts — extrahiert Querverweise aus den Autorenkonventionen.

Querverweis-Konventionen (was der Graph liest)

Von → Nach	Konvention im Body
Befehl → Agent	agent-name (fett)
Agent → Regel	`rule-name` Regel
Agent → Skill	`skill-name` Skill
Regel → Regel	Verwandte Regeln: a, b.
Regel → Skill	Siehe auch: x Skill.

Schreibe Bodies mit diesen genauen Konventionen, damit der Beziehungsgraph und die Linkerkennung des Assistenten sie aufgreifen.

Dateisystemsicherheit

export function resolveInWorkspace(root: string, relativePath: string): string {
  // löst relativePath unterhhalb von root auf und wirft WorkspaceError, wenn es escaped
}

Jeder Lese-/Schreibzugriff muss über diese Funktion aus einem workspace-relativen Pfad aufgebaut werden. Niemals absolute Pfade konkatenieren oder einen client-gelieferten absoluten Pfad akzeptieren.

Persistenz außerhalb des Workspace

• ~/.black-agents/config.json — gespeicherte Workspaces + aktiver currentPath (lib/config.ts).
• ~/.black-agents/secrets.json — LLM-Schlüssel, Modus 0600, nur server (lib/secrets.ts).
• <workspace>/.black-agents/standards.md — workspace-spezifische Überschreibung der Autorenstandards.
• Konfigurationsverzeichnis mit BLACK_AGENTS_CONFIG_DIR überschreiben (nützlich in Tests).

Verwendung

Nur Referenz. Die Persona und der Arbeitsablauf leben im Feature-Entwickler-Agenten; die Leitplanken in den Regeln typescript-strict und api-response-format. Diese Datei verwenden, um Logik in die richtige Schicht zu platzieren und das Routenrezept zu kopieren, dann die UI an den UiUx-Designer-Agenten und die Testabdeckung an den Tester-Agenten übergeben.