@onion-ai/cli 1.0.0-beta.1

package/framework/rules/nestjs-modules.md

@@ -0,0 +1,141 @@
+---
+paths:
+  - 'apps/api/src/modules/**/*.module.ts'
+  - 'apps/api/src/modules/**/index.ts'
+---
+
+# NestJS Module Standards
+
+Reference implementation: `apps/api/src/modules/initiatives/initiatives.module.ts`
+
+## Module Types
+
+### Feature modules (initiatives, creators, brands)
+
+Portal-split structure when both portals need separate endpoints:
+
+```
+modules/[feature]/
+├── admin/
+│   ├── [name].controller.ts
+│   └── dto/
+│       ├── [action].dto.ts
+│       ├── responses/[resource].response.ts
+│       └── index.ts
+├── creator/
+│   ├── [name].controller.ts
+│   └── dto/
+│       └── index.ts
+├── shared/
+│   ├── [name].service.ts
+│   └── dto/                  # Only if both portals share the same DTO
+├── [feature].module.ts
+└── index.ts
+```
+
+Simpler features (like brands settings) can use admin-only structure without creator/:
+
+```
+modules/[feature]/
+├── admin/
+│   ├── [name]-admin.controller.ts
+│   └── dto/
+├── [feature].controller.ts   # Public controller (if needed)
+├── [feature].service.ts
+├── [feature].module.ts
+└── index.ts
+```
+
+### Infrastructure modules (auth, remote-files, queue)
+
+Flat structure, no portal split:
+
+```
+modules/[feature]/
+├── [feature].controller.ts
+├── [feature].service.ts
+├── dto/
+├── guards/
+├── decorators/
+├── [feature].module.ts
+└── index.ts
+```
+
+## Module Registration
+
+```typescript
+@Module({
+  imports: [DatabaseModule, AuthModule], // Dependencies
+  controllers: [AdminController, CreatorController],
+  providers: [
+    ResourceService,
+    ResourceScheduler,
+    BrandAccessGuard, // Scoped guard as provider
+  ],
+  exports: [ResourceService], // Only export what other modules need
+})
+export class FeatureModule {}
+```
+
+Add a JSDoc block documenting the module's responsibilities:
+
+```typescript
+/**
+ * Feature Module
+ *
+ * Manages [resource] lifecycle including CRUD, [specific concern], and [other concern].
+ *
+ * Controllers:
+ * - AdminController: Brand admin CRUD operations
+ * - CreatorController: Creator-facing endpoints
+ *
+ * Services:
+ * - ResourceService: Core business logic (shared)
+ */
+```
+
+## Index Exports
+
+### Module index (`modules/[feature]/index.ts`)
+
+Export only what downstream modules need:
+
+```typescript
+export { FeatureModule } from './feature.module';
+export { FeatureService } from './shared/feature.service'; // If consumed by other modules
+```
+
+### Shared index (`shared/index.ts`)
+
+```typescript
+export { ResourceService } from './resource.service';
+export { ResourceScheduler } from './resource.scheduler';
+```
+
+## Service Placement Rules
+
+- Service used by ONE portal → place next to that portal's controller
+- Service used by BOTH portals → place in `shared/`
+- Service used by OTHER modules → place in `shared/` and add to module `exports`
+
+## DTO Placement Rules
+
+- Admin-only DTOs → `admin/dto/`
+- Creator-only DTOs → `creator/dto/`
+- Shared DTOs (same shape used by both) → `shared/dto/`
+- Response sub-types → `dto/responses/` subdirectory
+
+## Hard Rules
+
+- `admin/` and `creator/` must never import from each other
+- Every `dto/` directory must have a barrel `index.ts`
+- Guards used only within the module → register as providers in the module
+- Guards used across modules → register in `common/guards/`
+
+## Common Mistakes
+
+- Exporting services that no other module needs (leaks internal implementation)
+- Missing barrel exports causing relative import chains (`../../../shared/`)
+- Placing admin-only services in `shared/` prematurely
+- Circular imports between feature modules (use forwardRef or restructure)
+- Forgetting to register `BrandAccessGuard` as a provider when using it

package/framework/rules/nestjs-services.md

@@ -0,0 +1,230 @@
+---
+paths:
+  - 'apps/api/src/modules/**/*.service.ts'
+  - 'apps/api/src/modules/**/*.scheduler.ts'
+---
+
+# NestJS Service Standards
+
+Reference implementation: `apps/api/src/modules/initiatives/shared/initiatives.service.ts`
+
+## Class Setup
+
+```typescript
+@Injectable()
+export class ResourceService {
+  private readonly logger = new Logger(ResourceService.name);
+
+  constructor(private readonly prisma: PrismaService) {}
+}
+```
+
+- Every service must have a `Logger` with the class name
+- Add `@consumers` JSDoc tag listing which controller(s) use it:
+
+```typescript
+/**
+ * @consumers ResourceController, ResourceCreatorController
+ */
+```
+
+## Prisma Include/Select Constants
+
+Define reusable include clauses at module scope:
+
+```typescript
+const RESOURCE_INCLUDE = {
+  relation: true,
+  nested: { include: { deepRelation: true } },
+} satisfies Prisma.ResourceInclude; // satisfies (not as const) for type safety
+
+type ResourceWithRelations = Prisma.ResourceGetPayload<{
+  include: typeof RESOURCE_INCLUDE;
+}>;
+```
+
+For simple selects:
+
+```typescript
+const RESOURCE_SELECT = {
+  id: true,
+  name: true,
+  slug: true,
+} satisfies Prisma.ResourceSelect;
+```
+
+## Query Building
+
+Optional filters with spread:
+
+```typescript
+const where: Prisma.ResourceWhereInput = {
+  brandId,
+  ...(status && { status }),
+  ...(type && { type }),
+  ...(search && {
+    OR: [{ name: { contains: search, mode: 'insensitive' as const } }],
+  }),
+};
+```
+
+## List Methods (Pagination)
+
+Always use `Promise.all` for parallel data + count:
+
+```typescript
+const [items, total] = await Promise.all([
+  this.prisma.resource.findMany({
+    where,
+    include: RESOURCE_INCLUDE,
+    orderBy: { [sortBy]: sortOrder },
+    skip: (page - 1) * limit,
+    take: limit,
+  }),
+  this.prisma.resource.count({ where }),
+]);
+
+return {
+  data: items.map((i) => this.toResponse(i as ResourceWithRelations)),
+  total,
+  page,
+  limit,
+  totalPages: Math.ceil(total / limit),
+};
+```
+
+## Transactions
+
+Use for any operation touching multiple tables:
+
+```typescript
+const result = await this.prisma.$transaction(async (tx) => {
+  const created = await tx.resource.create({ data: { ... } });
+
+  if (relatedItems?.length) {
+    await tx.relatedItem.createMany({
+      data: relatedItems.map((item) => ({ ...item, resourceId: created.id })),
+    });
+  }
+
+  // Return full object with relations
+  return tx.resource.findUniqueOrThrow({
+    where: { id: created.id },
+    include: RESOURCE_INCLUDE,
+  });
+});
+```
+
+For array relation updates, delete + recreate inside transaction:
+
+```typescript
+await tx.resourceItem.deleteMany({ where: { resourceId: id } });
+await tx.resourceItem.createMany({ data: newItems.map(...) });
+```
+
+## Validation
+
+Sync validation first, then async:
+
+```typescript
+// 1. Sync business rules
+this.validateBusinessRules(dto);
+
+// 2. Async checks (file ownership, uniqueness)
+if (dto.fileId) {
+  await this.validateFileOwnership(dto.fileId, userId);
+}
+```
+
+Use `Pick<>` for reusable validators:
+
+```typescript
+private validateOptions(
+  dto: Pick<CreateResourceDto, 'fieldA' | 'fieldB'>,
+): void {
+  if (dto.fieldA && dto.fieldB) {
+    throw new BadRequestException('Only one of fieldA or fieldB allowed');
+  }
+}
+```
+
+For partial updates, only validate fields being updated:
+
+```typescript
+if (dto.fieldA !== undefined || dto.fieldB !== undefined) {
+  this.validateOptions(dto);
+}
+```
+
+## Response Transformation
+
+Private `toResponse` method converts Prisma entities to response DTOs:
+
+```typescript
+private toResponse(entity: ResourceWithRelations): ResourceResponse {
+  return {
+    id: entity.id,
+    date: entity.date.toISOString().split('T')[0],          // Date-only: YYYY-MM-DD
+    createdAt: entity.createdAt.toISOString(),               // Datetime: full ISO
+    optionalField: entity.optionalField ?? undefined,        // null → undefined
+    amount: entity.amount ? Number(entity.amount) : undefined, // Decimal → number
+    items: entity.items.map((i) => ({ id: i.id, name: i.name })),
+  };
+}
+```
+
+- Use `?? undefined` (not `|| undefined`) to clean nulls
+- Date-only fields: `.toISOString().split('T')[0]`
+- Prisma Decimal fields: `Number(entity.field)`
+
+## Error Handling
+
+| Exception             | HTTP | When                                        |
+| --------------------- | ---- | ------------------------------------------- |
+| `NotFoundException`   | 404  | Resource not found                          |
+| `BadRequestException` | 400  | Validation failure, business rule violation |
+| `ConflictException`   | 409  | Duplicate action, state conflict            |
+| `ForbiddenException`  | 403  | Authorization beyond guard scope            |
+
+## Logging
+
+Log every write operation with resource IDs:
+
+```typescript
+this.logger.log(`Created resource ${resource.id} for brand ${brandId}`);
+this.logger.log(`Updated resource ${id}`);
+this.logger.error('Failed to process resource', error);
+```
+
+Use conditional logging for batch results:
+
+```typescript
+if (count > 0) {
+  this.logger.log(`Processed ${count} items`);
+}
+```
+
+## Scheduler Pattern
+
+```typescript
+@Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT)
+async handleExpiredItems(): Promise<void> {
+  this.logger.log('Running expired items check...');
+  try {
+    const count = await this.service.completeExpired();
+    this.logger.log(count > 0 ? `Completed ${count} item(s)` : 'No items found');
+  } catch (error) {
+    this.logger.error('Failed to process expired items', error);
+  }
+}
+```
+
+## Common Mistakes
+
+- Missing `Logger` on service class
+- Using `as const` instead of `satisfies Prisma.XInclude` (loses Prisma type checking)
+- Sequential queries instead of `Promise.all` for independent data fetches
+- Using `|| undefined` instead of `?? undefined` (breaks on `0` and `''`)
+- Logging without resource IDs (impossible to trace)
+- Missing transaction for multi-table writes (data inconsistency risk)
+- Validating all fields on partial update instead of only provided ones

package/framework/rules/nx-rules.mdc

@@ -0,0 +1,41 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+
+// This file is automatically generated by Nx Console
+
+You are in an nx workspace using Nx 19.5.3 and pnpm as the package manager.
+
+You have access to the Nx MCP server and the tools it provides. Use them. Follow these guidelines in order to best help the user:
+
+# General Guidelines
+- When answering questions, use the nx_workspace tool first to gain an understanding of the workspace architecture
+- For questions around nx configuration, best practices or if you're unsure, use the nx_docs tool to get relevant, up-to-date docs!! Always use this instead of assuming things about nx configuration
+- If the user needs help with an Nx configuration or project graph error, use the 'nx_workspace' tool to get any errors
+- To help answer questions about the workspace structure or simply help with demonstrating how tasks depend on each other, use the 'nx_visualize_graph' tool
+
+# Generation Guidelines
+If the user wants to generate something, use the following flow:
+
+- learn about the nx workspace and any specifics the user needs by using the 'nx_workspace' tool and the 'nx_project_details' tool if applicable
+- get the available generators using the 'nx_generators' tool
+- decide which generator to use. If no generators seem relevant, check the 'nx_available_plugins' tool to see if the user could install a plugin to help them
+- get generator details using the 'nx_generator_schema' tool
+- you may use the 'nx_docs' tool to learn more about a specific generator or technology if you're unsure
+- decide which options to provide in order to best complete the user's request. Don't make any assumptions and keep the options minimalistic
+- open the generator UI using the 'nx_open_generate_ui' tool
+- wait for the user to finish the generator
+- read the generator log file using the 'nx_read_generator_log' tool
+- use the information provided in the log file to answer the user's question or continue with what they were doing
+
+
+# CI Error Guidelines
+If the user wants help with fixing an error in their CI pipeline, use the following flow:
+- Retrieve the list of current CI Pipeline Executions (CIPEs) using the 'nx_cloud_cipe_details' tool
+- If there are any errors, use the 'nx_cloud_fix_cipe_failure' tool to retrieve the logs for a specific task
+- Use the task logs to see what's wrong and help the user fix their problem. Use the appropriate tools if necessary
+- Make sure that the problem is fixed by running the task that you passed into the 'nx_cloud_fix_cipe_failure' tool
+
+

package/framework/rules/onion-patterns.mdc

@@ -0,0 +1,197 @@
+---
+description: Padrões de nomenclatura, estrutura e convenções do Sistema Onion
+globs: .claude/**
+alwaysApply: false
+---
+# 🧅 Padrões do Sistema Onion
+
+## 🎯 Objetivo
+
+Definir padrões consistentes para nomenclatura, estrutura e convenções do Sistema Onion v3.0.
+
+## 📁 Estrutura de Diretórios
+
+### Comandos (.claude/commands/)
+```
+.claude/commands/
+├── engineer/         # Fluxos de desenvolvimento
+├── product/          # Gestão de produto
+├── git/              # Operações Git
+│   ├── feature/      # Git flow - features
+│   ├── hotfix/       # Git flow - hotfixes
+│   └── release/      # Git flow - releases
+├── docs/             # Documentação
+├── meta/             # Meta-comandos (criadores)
+├── validate/         # Validações
+├── quick/            # Ações rápidas
+└── common/           # Recursos compartilhados
+    ├── templates/    # Templates base
+    └── prompts/      # Prompts modulares
+```
+
+### Agentes (.claude/agents/)
+```
+.claude/agents/
+├── development/      # Dev: python, react, postgres
+├── product/          # Produto: product-agent, task-specialist
+├── compliance/       # Compliance: regulatory, security
+├── meta/             # Meta: onion, metaspec-gate-keeper
+├── review/           # Review: code-reviewer
+├── testing/          # Testes: test-engineer, test-planner
+├── research/         # Pesquisa: research-agent
+├── git/              # Git: branch-*, code-review
+└── common/           # Templates compartilhados
+```
+
+### Sessions (.claude/sessions/)
+```
+.claude/sessions/<feature-slug>/
+├── context.md        # Contexto e IDs ClickUp
+├── architecture.md   # Decisões arquiteturais
+├── plan.md           # Plano de fases
+└── notes.md          # Notas de desenvolvimento
+```
+
+## 📝 Nomenclatura
+
+### Feature Slugs
+```bash
+# Padrão: kebab-case descritivo
+✅ user-authentication
+✅ payment-integration
+✅ onion-v3-refactoring
+
+❌ UserAuth
+❌ payment_integration
+❌ feature123
+```
+
+### Task IDs (ClickUp)
+```bash
+# Formato: alfanumérico ClickUp
+✅ 86adf8jj6
+✅ 86adf8kr3
+
+# Referência em documentos:
+**Task ID**: 86adf8jj6
+**Subtask ID**: `86adf8kr3`
+```
+
+### Comandos
+```bash
+# Nome: kebab-case
+✅ create-agent
+✅ code-review
+✅ warm-up
+
+# Caminho: /categoria/nome
+✅ /engineer/start
+✅ /product/task
+✅ /git/feature/start
+```
+
+### Agentes
+```bash
+# Nome: kebab-case + sufixo descritivo
+✅ python-developer.md
+✅ task-specialist.md
+✅ code-reviewer.md
+
+# Referência: @nome (sem extensão)
+✅ @python-developer
+✅ @onion
+```
+
+## 📋 Estrutura de Arquivos
+
+### Comando (YAML Header Obrigatório)
+```yaml
+---
+name: nome-comando
+description: Descrição curta (1-2 linhas)
+model: sonnet
+category: engineer|product|git|docs|meta|validate|quick
+tags: [tag1, tag2]
+version: "3.0.0"
+updated: "YYYY-MM-DD"
+---
+```
+
+### Agente (YAML Header Obrigatório)
+```yaml
+---
+name: nome-agente
+description: Descrição da especialização
+model: sonnet
+category: development|product|meta|compliance|review|testing|research|git
+tags: [tag1, tag2]
+expertise: [area1, area2, area3]
+version: "3.0.0"
+updated: "YYYY-MM-DD"
+---
+```
+
+## 🔗 Integração ClickUp MCP
+
+### Identificação de Workspace
+```typescript
+// Sempre usar workspace_id explícito
+workspace_id: "90131664218"  // Workspace padrão
+```
+
+### Padrões de Comentários
+- **Subtask**: Comentário DETALHADO (métricas, arquivos, decisões)
+- **Task Principal**: Comentário RESUMIDO (fase, status, próximo)
+
+### Formatação de Comentários
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ FASE N CONCLUÍDA - Nome da Fase
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📅 YYYY-MM-DD | Status: DONE
+
+📊 **Resultados:**
+∟ Item 1: valor
+∟ Item 2: valor
+
+🚀 Próxima: Fase N+1 - Nome
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## ⚡ Limites e Métricas
+
+| Métrica | Limite | Razão |
+|---------|--------|-------|
+| Linhas por comando | < 400 | Otimização de tokens |
+| Linhas por agente | < 300 | Foco e clareza |
+| Expertise por agente | 3-5 | Especialização |
+| Tags por arquivo | 3-7 | Organização |
+
+## 🔄 Fluxos Principais
+
+### Feature Development
+```bash
+/product/task "descrição"     # Criar task ClickUp
+/engineer/start <slug>        # Iniciar sessão
+/engineer/work               # Continuar trabalho
+/engineer/pre-pr             # Preparar PR
+/engineer/pr                 # Criar PR
+```
+
+### Criação de Componentes
+```bash
+/meta/create-agent <nome>    # Criar agente
+/meta/create-command <nome>  # Criar comando
+/docs/build-tech-docs        # Documentar
+```
+
+## 📚 Referências
+
+- Knowledge Bases: `docs/knowbase/`
+- Templates: `.claude/commands/common/templates/`
+- Prompts: `.claude/commands/common/prompts/`
+
+---
+
+**Última atualização:** 2025-11-24
+**Versão:** 3.0.0

package/framework/skills/codebase-visualizer/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: codebase-visualizer
+description: Generate an interactive collapsible tree visualization of your codebase. Use when exploring a new repo, understanding project structure, or identifying large files.
+allowed-tools: Bash(python *)
+---
+
+# Codebase Visualizer
+
+Generate an interactive HTML tree view that shows your project's file structure with collapsible directories.
+
+## Usage
+
+Run the visualization script from your project root:
+
+```bash
+python3 .claude/skills/codebase-visualizer/scripts/visualize.py .
+```
+
+This creates `codebase-map.html` in the current directory and opens it in your default browser.
+
+## What the visualization shows
+
+- **Collapsible directories**: Click folders to expand/collapse
+- **File sizes**: Displayed next to each file
+- **Colors**: Different colors for different file types
+- **Directory totals**: Shows aggregate size of each folder