diff --git a/acidaos/README.md b/acidaos/README.md new file mode 100644 index 0000000..54a5ca9 --- /dev/null +++ b/acidaos/README.md @@ -0,0 +1,28 @@ +# Plugin: acidaos + +Skills especializadas para desenvolvimento do **AcidaOS** — o sistema operativo de negócio para PMEs da Descomplicar®. + +## Arquitectura + +O AcidaOS usa uma arquitectura Hub-and-Spoke: +- **Core (Hub):** Rust + Axum — motor de orquestração de agentes, API gRPC/REST interna +- **Spokes:** Next.js/TypeScript — dashboards, UI, aplicações de negócio + +## Skills disponíveis + +| Skill | Trigger | Descrição | +|-------|---------|-----------| +| `acidaos:rust-dev` | `/rust-dev`, desenvolvimento Core | Desenvolvimento do Core em Rust (Axum, Tokio) | +| `acidaos:spoke-dev` | `/spoke-dev`, desenvolvimento Spokes | Aplicações Next.js e componentes React | +| `acidaos:devops` | `/acidaos-pipeline`, CI/CD | Pipelines Gitea Actions para o AcidaOS | +| `acidaos:docs` | `/acidaos-docs`, documentação técnica | Gerar documentação a partir do código | + +## Referências + +- Arquitectura: `Hub/01-Planeamento/AcidaOS/Relatorio_Arquitetura_Core.md` +- SPECs: `Hub/01-Planeamento/AcidaOS/acidaos-core/SPECs.md` +- Visão estratégica: `Hub/01-Planeamento/AcidaOS/AcidaOS_Visao-Estrategica.md` +- Repositório: Gitea `acidaos-core`, `acidaos-dashboard` + +--- +**Versão**: 1.0.0 | **Autor**: Descomplicar® | **Data**: 2026-03-12 diff --git a/acidaos/skills/devops/SKILL.md b/acidaos/skills/devops/SKILL.md new file mode 100644 index 0000000..1a37803 --- /dev/null +++ b/acidaos/skills/devops/SKILL.md @@ -0,0 +1,316 @@ +--- +name: devops +description: CI/CD pipelines para o AcidaOS via Gitea Actions — build, test, deploy para acidaos-core (Rust) e acidaos-dashboard (Next.js). Usar quando "pipeline acidaos", "gitea actions acidaos", "ci cd acidaos", "deploy acidaos", "workflow acidaos". +allowed-tools: Read, Write, Edit, Bash, mcp__gitea__list_repo_action_workflows, mcp__gitea__get_repo_action_workflow, mcp__gitea__create_file, mcp__gitea__update_file, mcp__memory-supabase__search_memories +--- + +# AcidaOS DevOps — Gitea Actions + +Skill para criar e gerir pipelines CI/CD do AcidaOS via **Gitea Actions**. + +> **Atenção:** O AcidaOS usa **Gitea Actions**, não GitHub Actions. A sintaxe é compatível mas o runner é self-hosted em `mcp-hub.descomplicar.pt`. + +## Contexto + +``` +Repositórios Gitea: + acidaos-core → Rust Core + acidaos-dashboard → Next.js Dashboard + +Runners: + self-hosted @ mcp-hub.descomplicar.pt + Labels: [self-hosted, linux, rust, node] + +Deploy target: + EasyPanel (projectName: "descomplicar") + acidaos-core → serviceName: "acidaos-core" + acidaos-dashboard → serviceName: "acidaos-dashboard" +``` + +## Protocolo Inicial + +``` +mcp__memory-supabase__search_memories "acidaos devops pipeline" +mcp__gitea__list_repo_action_workflows # ver workflows existentes +``` + +--- + +## Pipelines Disponíveis + +### 1. Core Rust — CI Pipeline + +**Ficheiro:** `.gitea/workflows/ci.yml` + +```yaml +name: AcidaOS Core CI + +on: + push: + branches: [main, develop] + pull_request: + branches: [main] + +jobs: + check: + name: Verificar código + runs-on: [self-hosted, linux, rust] + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Cache Cargo + uses: actions/cache@v3 + with: + path: | + ~/.cargo/registry + ~/.cargo/git + target/ + key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }} + + - name: Cargo check + run: cargo check --all-features + + - name: Clippy + run: cargo clippy --all-features -- -D warnings + + - name: Formatação + run: cargo fmt --all -- --check + + test: + name: Testes + needs: check + runs-on: [self-hosted, linux, rust] + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Cache Cargo + uses: actions/cache@v3 + with: + path: | + ~/.cargo/registry + ~/.cargo/git + target/ + key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }} + + - name: Testes unitários + run: cargo test --all-features + + - name: Testes de integração + run: cargo test --test '*' --all-features + env: + ACIDAOS_ENV: test + DATABASE_URL: ${{ secrets.TEST_DATABASE_URL }} + + security: + name: Auditoria de segurança + runs-on: [self-hosted, linux, rust] + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: cargo-audit + run: | + cargo install cargo-audit --quiet + cargo audit +``` + +--- + +### 2. Core Rust — Deploy Pipeline + +**Ficheiro:** `.gitea/workflows/deploy.yml` + +```yaml +name: AcidaOS Core Deploy + +on: + push: + branches: [main] + tags: ['v*'] + +jobs: + deploy: + name: Deploy para EasyPanel + runs-on: [self-hosted, linux, rust] + environment: production + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Build release + run: cargo build --release + + - name: Build Docker image + run: | + docker build \ + -t acidaos-core:${{ gitea.sha }} \ + -t acidaos-core:latest \ + . + + - name: Push para registry + run: | + docker tag acidaos-core:latest \ + registry.descomplicar.pt/acidaos/core:latest + docker push registry.descomplicar.pt/acidaos/core:latest + env: + DOCKER_REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }} + + - name: Deploy via EasyPanel API + run: | + curl -X POST \ + "https://easypanel.descomplicar.pt/api/deploy" \ + -H "Authorization: Bearer ${{ secrets.EASYPANEL_TOKEN }}" \ + -H "Content-Type: application/json" \ + -d '{ + "projectName": "descomplicar", + "serviceName": "acidaos-core", + "image": "registry.descomplicar.pt/acidaos/core:latest" + }' + + - name: Verificar health + run: | + sleep 10 + curl -f http://acidaos-core.descomplicar.pt/health || exit 1 +``` + +--- + +### 3. Dashboard Next.js — CI Pipeline + +**Ficheiro:** `.gitea/workflows/ci.yml` (no repo acidaos-dashboard) + +```yaml +name: AcidaOS Dashboard CI + +on: + push: + branches: [main, develop] + pull_request: + branches: [main] + +jobs: + lint-typecheck: + name: Lint e TypeCheck + runs-on: [self-hosted, linux, node] + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'pnpm' + + - name: Instalar dependências + run: pnpm install --frozen-lockfile + + - name: TypeScript check + run: pnpm tsc --noEmit + + - name: ESLint + run: pnpm lint + + test: + name: Testes + needs: lint-typecheck + runs-on: [self-hosted, linux, node] + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'pnpm' + + - name: Instalar dependências + run: pnpm install --frozen-lockfile + + - name: Testes unitários + run: pnpm test + + - name: Build de verificação + run: pnpm build + env: + ACIDAOS_CORE_URL: http://localhost:3001 + + e2e: + name: Testes E2E + needs: test + runs-on: [self-hosted, linux, node] + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'pnpm' + + - name: Instalar dependências + run: pnpm install --frozen-lockfile + + - name: Instalar Playwright + run: pnpm exec playwright install --with-deps chromium + + - name: Testes E2E + run: pnpm test:e2e + env: + BASE_URL: http://localhost:3000 + ACIDAOS_CORE_URL: http://localhost:3001 + + - name: Upload relatório E2E + if: failure() + uses: actions/upload-artifact@v3 + with: + name: playwright-report + path: playwright-report/ +``` + +--- + +## Gestão via MCP Gitea + +```javascript +// Listar workflows de um repo +mcp__gitea__list_repo_action_workflows({ owner: "descomplicar", repo: "acidaos-core" }) + +// Ver runs recentes +mcp__gitea__list_repo_action_runs({ owner: "descomplicar", repo: "acidaos-core" }) + +// Desencadear workflow manualmente +mcp__gitea__dispatch_repo_action_workflow({ + owner: "descomplicar", + repo: "acidaos-core", + workflow_id: "deploy.yml", + ref: "main" +}) + +// Ver logs de uma job +mcp__gitea__get_repo_action_job_log_preview({ owner: "descomplicar", repo: "acidaos-core", job_id: }) +``` + +## Segredos necessários (Gitea Secrets) + +| Segredo | Usado em | Descrição | +|---------|----------|-----------| +| `TEST_DATABASE_URL` | Core CI | PostgreSQL de teste | +| `REGISTRY_TOKEN` | Core Deploy | Token registry Docker | +| `EASYPANEL_TOKEN` | Core/Dashboard Deploy | Token API EasyPanel | + +## Checklist Pipeline Nova + +- [ ] Workflow criado em `.gitea/workflows/` +- [ ] Runner labels correctas (`self-hosted, linux, rust` ou `node`) +- [ ] Cache Cargo/pnpm configurado +- [ ] Segredos referenciados (não hardcoded) +- [ ] Health check no deploy +- [ ] Tested com `mcp__gitea__dispatch_repo_action_workflow` + +--- +**Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos diff --git a/acidaos/skills/docs/SKILL.md b/acidaos/skills/docs/SKILL.md new file mode 100644 index 0000000..8cbea79 --- /dev/null +++ b/acidaos/skills/docs/SKILL.md @@ -0,0 +1,191 @@ +--- +name: docs +description: Gerar documentação técnica do AcidaOS a partir do código — Rust (rustdoc), TypeScript (TypeDoc), e publicar no Outline. Usar quando "documentação acidaos", "gerar docs", "rustdoc", "typedoc", "acidaos-docs", documentar código do projecto. +allowed-tools: Read, Write, Bash, mcp__gitea__get_file_content, mcp__gitea__get_dir_content, mcp__outline-api__create_document, mcp__outline-api__update_document, mcp__outline-api__search_documents, mcp__memory-supabase__search_memories +--- + +# AcidaOS Docs + +Skill para gerar e publicar documentação técnica do AcidaOS. + +## Estratégia de Documentação + +| Camada | Ferramenta | Destino | +|--------|-----------|---------| +| API interna Rust | `rustdoc` + comentários `///` | `/docs` no repo | +| Componentes React | TypeDoc + Storybook | Storybook deployed | +| Arquitectura | Mermaid.js diagramas | Outline (Wiki) | +| Endpoints API | OpenAPI/Swagger | Outline (Wiki) | +| Decisões técnicas | ADRs em Markdown | Outline (Wiki) | + +## Protocolo + +``` +mcp__memory-supabase__search_memories "acidaos documentação" +mcp__outline-api__search_documents "acidaos" # ver docs existentes +``` + +--- + +## Operações + +### 1. Gerar documentação Rust (`rustdoc`) + +**Verificar comentários existentes:** +``` +mcp__gitea__get_dir_content acidaos-core/src/ +``` + +**Gerar localmente (no container dev):** +```bash +cd /root/Dev/acidaos-core +cargo doc --all-features --no-deps --open +``` + +**Verificar cobertura de documentação:** +```bash +cargo doc --all-features 2>&1 | grep "warning: missing documentation" +``` + +**Template comentários Rust:** +```rust +/// # ComponenteX +/// +/// Breve descrição em uma linha. +/// +/// ## Descrição detalhada +/// +/// Explicação mais longa do comportamento e propósito. +/// +/// ## Exemplos +/// +/// ```rust +/// use acidaos_core::ComponenteX; +/// +/// let c = ComponenteX::new("id"); +/// assert!(c.is_valid()); +/// ``` +/// +/// ## Erros +/// +/// Retorna [`Error::Init`] se a inicialização falhar. +pub struct ComponenteX { ... } +``` + +--- + +### 2. Gerar documentação TypeScript (TypeDoc) + +**Verificar configuração:** +``` +mcp__gitea__get_file_content acidaos-dashboard/typedoc.json +``` + +**Gerar (no container dev):** +```bash +cd /root/Dev/acidaos-dashboard +pnpm typedoc --out docs/api src/ +``` + +**Template JSDoc para componentes:** +```typescript +/** + * AgentStatusCard — Mostra o estado de um agente AcidaOS + * + * @example + * ```tsx + * refetch()} + * /> + * ``` + */ +export interface AgentStatusCardProps { + /** ID único do agente no Core */ + agentId: string; + /** Callback chamado ao clicar em refrescar */ + onRefresh?: () => void; +} +``` + +--- + +### 3. Publicar arquitectura no Outline + +**Criar/actualizar diagrama de arquitectura:** + +```javascript +mcp__outline-api__create_document({ + title: "AcidaOS — Arquitectura Core", + text: ` +# Arquitectura AcidaOS Core + +## Hub-and-Spoke + +\`\`\`mermaid +graph TD + A[acidaos-dashboard] -->|API REST| B[AcidaOS Core] + B --> C[Agent Kernel] + B --> D[Security & Sandboxing] + B --> E[Memory Engine] + B --> F[Observability] +\`\`\` + +## Componentes + +| Componente | Linguagem | Responsabilidade | +|-----------|-----------|-----------------| +| Core | Rust | Orquestração de agentes | +| Dashboard | Next.js | Interface de utilizador | + `, + collectionId: "" +}) +``` + +--- + +### 4. Criar ADR (Architecture Decision Record) + +**Template ADR:** +```markdown +# ADR-: + +**Data:** YYYY-MM-DD +**Estado:** [Proposto | Aceite | Depreciado | Substituído por ADR-NNN] + +## Contexto + +[Situação que levou à necessidade de tomar esta decisão] + +## Opções Consideradas + +1. **Opção A** — descrição breve +2. **Opção B** — descrição breve + +## Decisão + +[Opção escolhida e porquê] + +## Consequências + +**Positivas:** +- [Consequência positiva] + +**Negativas / Trade-offs:** +- [Limitação ou custo] +``` + +--- + +## Quality Gate de Documentação + +Antes de marcar tarefa como concluída: + +- [ ] Rust: zero `missing documentation` warnings em `cargo doc` +- [ ] TypeScript: TypeDoc gera sem erros +- [ ] Novos módulos têm exemplos de uso nos comentários +- [ ] Diagramas Mermaid actualizado se arquitectura mudou +- [ ] ADR criado para decisões técnicas significativas + +--- +**Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos diff --git a/acidaos/skills/rust-dev/SKILL.md b/acidaos/skills/rust-dev/SKILL.md new file mode 100644 index 0000000..df83d43 --- /dev/null +++ b/acidaos/skills/rust-dev/SKILL.md @@ -0,0 +1,232 @@ +--- +name: rust-dev +description: Desenvolvimento do AcidaOS Core em Rust — criar crates, definir endpoints Axum, debugar erros do compilador. Usar quando "rust", "axum", "cargo", "crate", "core", "acidaos core", "rust error", "borrow checker", desenvolvimento do motor central do AcidaOS. +allowed-tools: Read, Write, Edit, Bash, mcp__memory-supabase__search_memories, mcp__gitea__get_file_content, mcp__gitea__create_file, mcp__gitea__update_file +--- + +# AcidaOS Rust Dev + +Skill para desenvolvimento do **Core do AcidaOS** em Rust. + +## Contexto do Projecto + +``` +acidaos-core (Rust) +├── src/ +│ ├── api/ ← endpoints Axum (REST/gRPC) +│ ├── kernel/ ← Agent Kernel & Scheduler +│ ├── security/ ← Sandboxing, isolamento WASM +│ ├── memory/ ← Context & Memory Engine +│ ├── registry/ ← Parsers de skills/plugins +│ ├── observability/← Logging, tracing +│ └── ethics/ ← Constitution Engine +├── crates/ ← bibliotecas internas +└── Cargo.toml +``` + +**Stack:** Rust stable | Axum | Tokio | Serde | Tracing | SQLx | wasmtime + +## Protocolo Inicial + +``` +mcp__memory-supabase__search_memories "acidaos core [componente]" +mcp__gitea__get_file_content acidaos-core/Cargo.toml # verificar dependências actuais +``` + +--- + +## Operações + +### 1. Criar novo crate (`/rust-create-crate`) + +**Input:** Nome do crate e propósito + +**Passos:** +1. Criar directório `crates//` +2. Gerar `Cargo.toml` com dependências mínimas +3. Criar `src/lib.rs` com estrutura base +4. Adicionar ao workspace `Cargo.toml` +5. Criar `src/error.rs` com tipo de erro custom usando `thiserror` + +**Template `Cargo.toml`:** +```toml +[package] +name = "acidaos-" +version = "0.1.0" +edition = "2021" +description = "" + +[dependencies] +tracing = "0.1" +serde = { version = "1", features = ["derive"] } +thiserror = "1" +tokio = { version = "1", features = ["full"] } +``` + +**Template `src/lib.rs`:** +```rust +//! # acidaos- +//! +//! +//! +//! ## Exemplo +//! ```rust +//! use acidaos_::; +//! ``` + +mod error; +pub use error::Error; + +pub type Result = std::result::Result; +``` + +**Template `src/error.rs`:** +```rust +use thiserror::Error; + +#[derive(Debug, Error)] +pub enum Error { + #[error("Erro de inicialização: {0}")] + Init(String), + + #[error("Operação não suportada: {0}")] + Unsupported(String), +} +``` + +--- + +### 2. Definir endpoint Axum (`/rust-define-api-endpoint`) + +**Input:** Definição do endpoint (método, path, request/response types) de uma SPEC.md + +**Template de endpoint:** +```rust +use axum::{ + extract::{Path, State}, + http::StatusCode, + response::Json, + routing::{get, post}, + Router, +}; +use serde::{Deserialize, Serialize}; +use tracing::instrument; + +// --- Tipos --- + +#[derive(Debug, Deserialize)] +pub struct { + // campos do request +} + +#[derive(Debug, Serialize)] +pub struct { + // campos do response +} + +// --- Handler --- + +#[instrument(skip(state))] +pub async fn ( + State(state): State, + Json(req): Json<>, +) -> Result>, StatusCode> { + tracing::info!("Processando "); + + // lógica do handler + + Ok(Json( { + // preencher response + })) +} + +// --- Router --- + +pub fn _router() -> Router { + Router::new() + .route("/", post()) +} +``` + +**Princípios obrigatórios:** +- `#[instrument]` em todos os handlers (observabilidade) +- Erros retornam `StatusCode` ou tipo de erro custom (nunca `.unwrap()`) +- Estado partilhado via `State` (não globals) +- Validação de input antes de processamento + +--- + +### 3. Debugar erro do compilador (`/rust-debug-compiler-error`) + +**Input:** Output completo de `cargo build` ou `cargo check` + +**Protocolo de análise:** + +1. **Identificar categoria do erro:** + | Código | Categoria | Solução típica | + |--------|-----------|----------------| + | E0382 | Move após uso | Usar `clone()` ou referências `&` | + | E0502 | Borrow conflict | Reordenar operações, usar `Arc>` | + | E0308 | Type mismatch | Verificar tipos, usar `.into()` ou cast explícito | + | E0277 | Trait not impl | Implementar trait ou usar tipo diferente | + | E0499 | Multiple mut borrows | Usar `RefCell` ou reestruturar lógica | + +2. **Analisar mensagem de erro completa** (incluindo `help:` e `note:`) + +3. **Gerar código corrigido** com explicação da causa raiz + +4. **Verificar:** `cargo check` passa antes de `cargo build` + +**Padrões comuns no AcidaOS Core:** + +```rust +// ❌ Move não intencional +let data = fetch_data(); +process(data); +log(data); // ERRO: data foi moved + +// ✅ Correcto +let data = fetch_data(); +process(&data); // ou process(data.clone()) +log(&data); + +// ❌ Async + lifetime +async fn handler(req: &Request) -> Response { ... } // lifetime issue + +// ✅ Correcto — owned ou Arc +async fn handler(req: Arc) -> Response { ... } +``` + +--- + +## Quality Gate + +Antes de fazer commit: + +```bash +cargo check # zero erros +cargo clippy # zero warnings +cargo test # todos os testes passam +cargo fmt --check # formatação correcta +``` + +**Standards:** +- Zero `unwrap()` em código de produção — usar `?` ou `expect("mensagem descritiva")` +- Funções async < 50 linhas +- `tracing::instrument` em todas as funções públicas async +- Documentação `///` em todos os tipos e funções públicas + +--- + +## Checklist Entrega + +- [ ] `cargo check` sem erros +- [ ] `cargo clippy -- -D warnings` limpo +- [ ] `cargo test` 100% pass +- [ ] Documentação `///` completa +- [ ] Observabilidade: `#[instrument]` nos handlers +- [ ] Sem `.unwrap()` em paths críticos +- [ ] CHANGELOG.md actualizado + +--- +**Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos diff --git a/acidaos/skills/spoke-dev/SKILL.md b/acidaos/skills/spoke-dev/SKILL.md new file mode 100644 index 0000000..8f087e7 --- /dev/null +++ b/acidaos/skills/spoke-dev/SKILL.md @@ -0,0 +1,239 @@ +--- +name: spoke-dev +description: Desenvolvimento de Spokes do AcidaOS em Next.js/TypeScript — criar aplicações Spoke, componentes React com testes e Storybook. Usar quando "spoke", "dashboard acidaos", "next.js acidaos", "componente react acidaos", "ts-create-spoke", "acidaos ui", "acidaos frontend". +allowed-tools: Read, Write, Edit, Bash, mcp__memory-supabase__search_memories, mcp__gitea__get_file_content, mcp__gitea__create_file, mcp__gitea__update_file +--- + +# AcidaOS Spoke Dev + +Skill para desenvolvimento dos **Spokes do AcidaOS** em Next.js/TypeScript. + +## Contexto do Projecto + +Os Spokes são as aplicações de interface que comunicam com o Core via API interna: + +``` +acidaos-dashboard (Next.js 15 + App Router) +├── src/ +│ ├── app/ ← App Router pages +│ ├── components/ ← Componentes React +│ │ ├── ui/ ← Componentes base (shadcn/ui) +│ │ └── features/ ← Componentes de funcionalidade +│ ├── lib/ +│ │ ├── api/ ← Client para AcidaOS Core API +│ │ └── hooks/ ← React hooks custom +│ └── types/ ← TypeScript types partilhados +├── __tests__/ ← Jest + Testing Library +└── .storybook/ ← Storybook +``` + +**Stack:** Next.js 15 | TypeScript 5 | React 19 | Tailwind CSS | shadcn/ui | Vercel AI SDK | Vitest | Playwright + +## Protocolo Inicial + +``` +mcp__memory-supabase__search_memories "acidaos spoke dashboard [componente]" +mcp__gitea__get_file_content acidaos-dashboard/package.json +``` + +--- + +## Operações + +### 1. Criar nova aplicação Spoke (`/ts-create-spoke-app`) + +**Input:** Nome do Spoke e propósito + +**Estrutura a criar:** +```bash +# No container dev (Regra #48) +cd /root/Dev +npx create-next-app@latest acidaos- \ + --typescript \ + --tailwind \ + --app \ + --src-dir \ + --import-alias "@/*" \ + --no-git +``` + +**Ficheiros obrigatórios após scaffold:** + +`src/lib/api/core-client.ts` — cliente para o Core: +```typescript +/** + * AcidaOS Core API Client + * + * @author Descomplicar® Crescimento Digital + * @link https://descomplicar.pt + */ + +const CORE_API_URL = process.env.ACIDAOS_CORE_URL ?? 'http://localhost:3001'; + +export async function coreRequest( + endpoint: string, + options?: RequestInit +): Promise { + const res = await fetch(`${CORE_API_URL}${endpoint}`, { + ...options, + headers: { + 'Content-Type': 'application/json', + 'X-AcidaOS-Version': '1', + ...options?.headers, + }, + }); + + if (!res.ok) { + throw new Error(`Core API error: ${res.status} ${res.statusText}`); + } + + return res.json() as Promise; +} +``` + +`src/types/index.ts` — tipos base: +```typescript +export interface AgentTask { + id: string; + status: 'pending' | 'running' | 'completed' | 'failed'; + createdAt: string; + completedAt?: string; +} + +export interface CoreHealth { + status: 'healthy' | 'degraded' | 'down'; + version: string; + uptime: number; +} +``` + +--- + +### 2. Criar componente React (`/ts-create-react-component`) + +**Input:** Descrição do componente (nome, props, comportamento) + +**Template base — componente:** + +`src/components/features//.tsx`: +```typescript +/** + * — + * + * @author Descomplicar® Crescimento Digital + */ + +import { type FC } from 'react'; +import { cn } from '@/lib/utils'; + +interface Props { + // props do componente + className?: string; +} + +export const : FC<Props> = ({ className }) => { + return ( +
+ {/* conteúdo */} +
+ ); +}; + +.displayName = ''; +``` + +**Template — teste (Vitest + Testing Library):** + +`src/components/features//.test.tsx`: +```typescript +import { render, screen } from '@testing-library/react'; +import { describe, it, expect } from 'vitest'; +import { } from './'; + +describe('', () => { + it('renderiza sem erros', () => { + render(< />); + // asserção específica ao componente + }); + + it('aceita className personalizada', () => { + const { container } = render(< className="test-class" />); + expect(container.firstChild).toHaveClass('test-class'); + }); +}); +``` + +**Template — Storybook:** + +`src/components/features//.stories.tsx`: +```typescript +import type { Meta, StoryObj } from '@storybook/react'; +import { } from './'; + +const meta: Meta> = { + title: 'Features/', + component: , + parameters: { + layout: 'centered', + }, +}; + +export default meta; +type Story = StoryObj>; + +export const Default: Story = { + args: {}, +}; +``` + +**Criar index de exportação:** + +`src/components/features//index.ts`: +```typescript +export { } from './'; +export type { Props } from './'; +``` + +--- + +## Padrões Obrigatórios + +### TypeScript +- `strict: true` em `tsconfig.json` — sem `any` implícito +- Props sempre tipadas com interface exportada +- Hooks custom em `src/lib/hooks/use.ts` +- Server Components por defeito; `'use client'` apenas quando necessário + +### Performance +- `next/image` para todas as imagens +- `loading="lazy"` em componentes pesados +- `Suspense` boundaries em torno de data-fetching +- Cache de API calls com `unstable_cache` ou React cache + +### Segurança +- Nunca expor `ACIDAOS_CORE_URL` no cliente (apenas server-side) +- Sanitizar input do utilizador antes de enviar ao Core +- Usar Next.js Server Actions para mutações + +--- + +## Quality Gate + +```bash +pnpm build # zero erros TypeScript +pnpm test # todos os testes passam +pnpm lint # zero erros ESLint +``` + +## Checklist Entrega + +- [ ] Tipos TypeScript sem `any` +- [ ] Testes criados (>80% cobertura) +- [ ] Story Storybook criada +- [ ] `displayName` definido no componente +- [ ] `pnpm build` sem erros +- [ ] Client/Server components correctamente marcados +- [ ] CHANGELOG.md actualizado + +--- +**Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: acidaos diff --git a/dev-tools/skills/prompt-refine/SKILL.md b/dev-tools/skills/prompt-refine/SKILL.md new file mode 100644 index 0000000..0a50943 --- /dev/null +++ b/dev-tools/skills/prompt-refine/SKILL.md @@ -0,0 +1,132 @@ +--- +name: prompt-refine +description: Transforma um pedido vago em prompt de excelência — especificação detalhada, inequívoca e estruturada para agentes de IA. Usar quando "refinar prompt", "melhorar prompt", "engenharia de prompts", "prompt para agente", "estruturar instrução IA", "prompt engineering". +allowed-tools: Read, Write, mcp__memory-supabase__search_memories +--- + +# /prompt-refine — Engenharia de Prompts + +Transforma um pedido em linguagem natural num **prompt de excelência** pronto para ser executado por outro agente de IA. + +## Quando Usar + +- Pedido do utilizador é vago ou incompleto +- Preparar instrução para um agente especializado +- Criar template reutilizável para uma tarefa recorrente +- Garantir qualidade máxima de input antes de executar + +## Protocolo + +### 1. Pesquisar contexto relevante + +``` +mcp__memory-supabase__search_memories "" +``` + +Verificar se há padrões ou decisões anteriores relacionadas. + +### 2. Analisar o pedido original + +Identificar: +- **O quê** — resultado final esperado +- **Para quê** — objectivo ou problema a resolver +- **Quem** — agente ou utilizador que vai executar +- **Restrições** — limitações técnicas, de formato ou de negócio +- **Lacunas** — o que está implícito mas não dito + +Se faltar informação crítica → perguntar antes de estruturar. + +### 3. Estruturar o prompt de excelência + +Usar este template como base: + +```markdown +## Função +[Quem é / que papel assume o agente executante] + +## Objectivo +[O que deve ser produzido — resultado concreto e mensurável] + +## Contexto +[Informação de fundo necessária para compreender o pedido] + +## Requisitos +- [Requisito 1 — obrigatório] +- [Requisito 2 — obrigatório] +- [Restrição ou critério de qualidade] + +## Input +[Descrição do que o agente recebe como entrada] + +## Output esperado +[Formato, estrutura e conteúdo exacto do resultado] + +## Exemplos +### Exemplo positivo (fazer) +[Exemplo concreto do resultado desejado] + +### Exemplo negativo (não fazer) +[Exemplo do que deve ser evitado] + +## Critérios de sucesso +- [ ] Critério 1 +- [ ] Critério 2 +``` + +### 4. Rever antes de entregar + +Verificar checklist: +- [ ] Sem ambiguidades — cada instrução tem um único significado possível +- [ ] Completo — nenhuma informação crítica em falta +- [ ] Accionável — o agente pode executar sem fazer suposições +- [ ] Testável — é possível verificar se o output é correcto +- [ ] Conciso — sem redundâncias ou instruções contraditórias + +### 5. Entregar com explicação + +Apresentar: +1. **Prompt refinado** (em bloco de código copiável) +2. **Decisões tomadas** — o que foi inferido vs. o que estava explícito +3. **Questões em aberto** — se houver ambiguidades que o utilizador deve resolver + +## Exemplos de Transformação + +### Input vago +> "Cria um agente que analisa clientes" + +### Output refinado +```markdown +## Função +Analista de CRM especializado em classificação de clientes + +## Objectivo +Gerar um relatório de segmentação de clientes com base em histórico de compras +e interacções, identificando os segmentos de alto, médio e baixo valor. + +## Contexto +Base de dados Desk CRM com clientes activos nos últimos 12 meses. +Acesso via mcp__desk-crm-v3__get_customers e mcp__desk-crm-v3__get_payments. + +## Requisitos +- Segmentar em 3 níveis: Alto Valor (>5000EUR/ano), Médio (1000-5000EUR), Baixo (<1000EUR) +- Incluir número de projectos activos por cliente +- Formato: tabela Markdown ordenada por valor decrescente + +## Input +Lista de IDs de clientes ou "todos" para analisar base completa + +## Output esperado +Tabela com: ID, Nome, Segmento, Volume Anual (EUR), Projectos Activos, Última Interacção +``` + +## Padrões de Qualidade + +| Característica | Mau prompt | Bom prompt | +|---|---|---| +| Especificidade | "Analisa dados" | "Calcula receita mensal por cliente em EUR para Q1 2026" | +| Formato output | "Devolve resultados" | "Tabela Markdown com colunas: ID, Nome, Valor, Delta%" | +| Critério sucesso | "Deve ser bom" | "Score de satisfação >85% em teste com 3 utilizadores reais" | +| Contexto | Nenhum | "Sistema usa Desk CRM v3, moeda EUR, fuso Europe/Lisbon" | + +--- +**Versão**: 1.0.0 | **Autor**: Descomplicar® | **Plugin**: dev-tools