Padrões da BlackAgents

Padrões da Aplicação BlackAgents

Quando Aplicar

Leia isto ao implementar uma funcionalidade ou correção que toque em app/**, app/api/** ou lib/**. As restrições rígidas estão nas regras typescript-strict e api-response-format; este arquivo explica as camadas e as receitas.

Arquitetura (respeite as camadas)

UI (components/features/, client) ──fetch──▶ Rotas da API (app/api/**/route.ts)
                                                    │  { success, data | error }
                                              Domínio (lib/artifacts/, lib/standards/)
                                                    │  fazer parsing / serializar / grafo
                                              Sistema de Arquivos (lib/fs-service.ts)
                                                    │  resolveInWorkspace (sem escape)
                                              Pasta do Workspace (.cursor / .claude ...)

Regras de conduta:

• Lógica pura e independente de plataforma vive em lib/artifacts/**. Nunca importa React ou next/server.
• Preocupações HTTP vivem apenas em app/api/**/route.ts.
• Todo acesso a disco passa por lib/fs-service.ts; nunca chame node:fs diretamente de uma rota.

Convenções do App Router

• Páginas são componentes de servidor por padrão; adicione "use client" apenas para interatividade/estado/efeitos.
• Grupos de rotas: /agents, /commands, /rules, /skills cada um tem uma página de listagem, uma página de edição [name] e uma página new; /new é o assistente guiado. Outras rotas: /graph, /standards, /export, /sync, /chat, /providers, /settings.
• Componentes de funcionalidade no cliente buscam dados através de apiFetch (lib/api.ts) e leem o estado do workspace ativo de WorkspaceProvider — sem fetch bruto e sem leitura direta de configuração no cliente.

Receita de Rota da API

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)
    // ...trabalho de domínio via lib/artifacts + lib/fs-service...
    return ok({ /* dados */ })
  })
}

• Sempre retorne via ok / fail; envolva em handle para que exceções se tornem um envelope 500.
• Leia a raiz do workspace da configuração (lib/config.ts), depois use resolveInWorkspace(root, relPath).
• Leia segredos com lib/secrets.ts apenas no lado do servidor; credenciais ausentes → fail("...", 412).

O Modelo de Domínio

lib/artifacts/:

• types.ts — Artifact, ArtifactType, Platform, ArtifactFrontmatter (independente de ferramenta).
• layout.ts — PLATFORM_LAYOUTS + artifactRelPath() / artifactDeletePath(); o único lugar que conhece as pastas/extensões de uma plataforma. ACTIVE_PLATFORMS = ["cursor", "claude"], padrão cursor.
• parser.ts — scanWorkspace(root) e parseArtifact (via gray-matter); skills são um diretório <name>/SKILL.md percorrido recursivamente.
• serializer.ts — serializeArtifact(input) escreve frontmatter + corpo; regras omitem name (identificado pelo nome do arquivo).
• schemas.ts — nameSchema (kebab-case), artifactInputSchema, normalizeExtra (frontmatter por tipo).
• graph.ts — extrai referências cruzadas das convenções de autoria.

Convenções de Referência Cruzada (o que o grafo lê)

De → Para	Convenção no corpo
Comando → Agente	nome-do-agente (negrito)
Agente → Regra	`nome-da-regra` regra
Agente → Skill	`nome-da-skill` skill
Regra → Regra	Regras relacionadas: a, b.
Regra → Skill	Veja também: skill x.

Escreva os corpos com essas convenções exatas para que o grafo de relacionamentos e a detecção de links do assistante os identifiquem.

Segurança do Sistema de Arquivos

export function resolveInWorkspace(root: string, relativePath: string): string {
  // resolve relativePath dentro de root e lança WorkspaceError se escapar
}

Cada leitura/escrita deve ser construída a partir de um caminho relativo ao workspace através desta função. Nunca concatene caminhos absolutos ou aceite um caminho absoluto fornecido pelo cliente.

Persistência Fora do Workspace

• ~/.black-agents/config.json — workspaces salvos + currentPath ativo (lib/config.ts).
• ~/.black-agents/secrets.json — chaves de LLM, modo 0600, apenas no servidor (lib/secrets.ts).
• <workspace>/.black-agents/standards.md — substituição das diretrizes de autoria por workspace.
• Substitua o diretório de configuração com BLACK_AGENTS_CONFIG_DIR (útil em testes).

Como Usar

Apenas referência. A persona e o fluxo de trabalho vivem no agente feature-developer; as proteções vivem nas regras typescript-strict e api-response-format. Use este arquivo para colocar a lógica na camada correta e copiar a receita da rota; depois, entregue a UI ao agente uiux-designer e a cobertura de testes ao agente tester.