# {{PROJECT_NAME}} — Paperclip

> Gerado: {{GENERATION_DATE}} | Claude Craft v{{VERSION}}

## O Que (Stack & Estrutura)

**Stack**: Node.js 20+ LTS, TypeScript 5.x (strict), React 18+, Vitest, pnpm 9.15+, PostgreSQL 15+
**Paperclip**: 2026.403.0+ (MIT) — https://docs.paperclip.ing/

**Paperclip é um sistema de duas camadas**: um plano de controle (server + web + DB) que possui todo o estado de governança, e adaptadores que executam trabalho e reportam de volta. Adaptadores nunca decidem orçamentos ou aprovações.

### Estrutura do Projeto
```
paperclip/
├── server/            # API Node.js + TS (módulos: agents, approvals, costs, ...)
├── ui/                # UI React (dashboard, org chart, approvals)
├── shared/            # Tipos compartilhados entre server e web
├── adapters/          # Adaptadores (claude-local, codex-local, http, process, ...)
└── tests/             # Cross-cutting / e2e
```

## Por Que (Invariantes de Governança)

| Invariante | Motivo |
|---|---|
| Adaptadores nunca mantêm estado de governança | Auditabilidade + política consistente |
| Orçamentos são limites rígidos | Sem drenagem silenciosa |
| Aprovações bloqueiam execução | Human-in-the-loop é real |
| Toda mutação emite um evento de atividade | Trilha de auditoria append-only |
| `companyId` da sessão, nunca do cliente | Isolamento de tenant |

Veja `rules/02-architecture-paperclip.md` e `rules/12-adapter-protocol.md`.

## Como (Comandos & Workflows)

### Desenvolvimento

```bash
pnpm install
pnpm dev                # server + web em modo watch
pnpm test               # Vitest
pnpm test --coverage
pnpm lint
pnpm typecheck
pnpm build
```

### Banco de Dados

```bash
pnpm db:migrate
pnpm db:seed
pnpm db:reset           # apenas dev
```

### Paperclip CLI

```bash
npx paperclipai onboard --yes
paperclipai plugin list
paperclipai agent list
paperclipai company list
paperclipai approval list
```

### Workflow

1. **Analisar** — Identificar módulos afetados, impacto de governança (`rules/01-workflow-analysis.md`)
2. **TDD** — Red → Green → Refactor (`rules/07-testing-paperclip.md`)
3. **Mudanças de adaptador** → executar a suite de contrato compartilhada (`rules/12-adapter-protocol.md`)
4. **Verificação de governança** — Log de atividades, orçamento, aprovações conectadas
5. **Compliance** — Executar `/paperclip:check-compliance` antes do PR
6. **Commit** — Conventional Commits

## Referências

| Tópico | Arquivo de Regra |
|---|---|
| Análise | `rules/01-workflow-analysis.md` |
| Arquitetura | `rules/02-architecture-paperclip.md` |
| Padrões de Código | `rules/03-coding-standards.md` |
| Ferramentas | `rules/06-tooling.md` |
| Testes | `rules/07-testing-paperclip.md` |
| Ferramentas de Qualidade | `rules/08-quality-tools.md` |
| Segurança | `rules/11-security-paperclip.md` |
| Protocolo de Adaptador | `rules/12-adapter-protocol.md` |

<!-- PROJECT-SPECIFIC-START -->
## Especificidades do Projeto

{{TECH_STACK}}

<!-- Adicione configuração específica do projeto abaixo -->

<!-- PROJECT-SPECIFIC-END -->
