stealthos-cli 0.1.0-alpha.3 → 0.1.0-alpha.4

package/ai/blueprints/README.md

@@ -0,0 +1,67 @@
+---
+version: 1.0.0
+updated: 2026-05-16
+tier: on-demand
+tokens: ~500
+load: blueprint, compose, scaffold, estrutura inicial
+triggers: blueprint, scaffolding, novo projeto, estrutura inicial, compose
+---
+
+# Structural Blueprints — Catálogo + Composition Guide
+
+> Fragmentos declarativos de estrutura por tipo de projeto. Projetos modernos são **híbridos** — combine múltiplos blueprints via `aios_compose_structure`.
+
+## Catálogo (8 blueprints)
+
+| Blueprint | Quando | Foca em |
+|---|---|---|
+| [`web.json`](./web.json) | Aplicação web típica | apps/web + services/api + packages/ui |
+| [`saas.json`](./saas.json) | Produto SaaS multi-tenant | + billing, tenancy, permissions, audit |
+| [`crm.json`](./crm.json) | CRM ou plataforma de relacionamento | + customers, leads, pipelines, communications |
+| [`mobile.json`](./mobile.json) | App mobile (nativo ou cross-platform) | + offline, sync, device, push |
+| [`game.json`](./game.json) | Jogo / engine | + engine, scenes, entities, physics, ai |
+| [`ai-platform.json`](./ai-platform.json) | Plataforma com runtime IA | + ai-runtime, prompts, agents, embeddings |
+| [`telemetry.json`](./telemetry.json) | Telemetry / logistics / IoT | + tracking, geofencing, devices, providers |
+| [`realtime.json`](./realtime.json) | Sistema realtime / eventos | + websockets, queues, event-streams |
+
+## Como compor (via MCP)
+
+```
+aios_list_blueprints()
+  → { count: 8, blueprints: [...] }
+
+aios_get_blueprint({ name: "saas" })
+  → { id: "saas", description: ..., folders: [...], modules: [...], ... }
+
+aios_compose_structure({ types: ["saas", "telemetry", "realtime"] })
+  → {
+      types_resolved: ["web", "saas", "telemetry", "realtime"],  // 'extends' expandido
+      folders: [...],            // union dedupe
+      modules: [...],            // union dedupe
+      packages_recommended: [...],
+      integrations_recommended: [...],
+      constraints: { ... },      // merged
+      notes: [...]
+    }
+```
+
+## Princípios
+
+1. **Compose, don't fork**: nunca duplique blueprint para customizar — referencie via `extends`.
+2. **Evolutionary**: comece com 1-2 blueprints; adicione conforme necessidade.
+3. **Constraints heredity**: composição mescla constraints; mais restritivo vence.
+4. **Modules são apenas sugestões**: não force criar todos os módulos listados; surgem quando há requisito real.
+5. **Domain-first sempre**: módulos novos seguem `.ai/rules/structure-canon.md`.
+
+## Adicionar blueprint novo
+
+1. Criar `.ai/blueprints/<id>.json` seguindo `_schema.json`.
+2. Listar `extends` se reaproveita outro (ex.: SaaS extends Web).
+3. Adicionar linha ao catálogo acima.
+4. Atualizar `.ai/manifest.json` (`required_files`) com bypass `.claude/.unlock` + ADR amendment se for change major.
+
+## Referências
+
+- ADR-0010 (decisão)
+- `.ai/rules/structure-canon.md` (princípios qualitativos)
+- `.ai/rules/structural-constraints.md` (limites quantitativos)

package/ai/blueprints/_schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AI OS Structural Blueprint",
+  "type": "object",
+  "required": ["id", "description", "folders", "modules"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{1,32}$" },
+    "description": { "type": "string" },
+    "extends": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "IDs de outros blueprints cujo conteúdo é incluído transitivamente."
+    },
+    "folders": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Pastas a adicionar ao root (com '/' final)."
+    },
+    "modules": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Módulos de domínio recomendados (geralmente sob services/api/src/modules/)."
+    },
+    "packages_recommended": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Packages sob packages/ que tendem a ser úteis."
+    },
+    "integrations_recommended": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Integrações externas comuns para este tipo."
+    },
+    "constraints_overrides": {
+      "type": "object",
+      "description": "Overrides de structural-constraints.md (ex.: max_modules_before_split aumentado)."
+    },
+    "notes": { "type": "string" }
+  }
+}

package/ai/blueprints/ai-platform.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "./_schema.json",
+  "id": "ai-platform",
+  "description": "Plataforma com runtime de IA (LLM-driven): prompts, agents, embeddings, RAG.",
+  "extends": ["web"],
+  "folders": [
+    "services/ai-runtime/",
+    "packages/llm-adapters/",
+    "packages/prompts/",
+    "data/embeddings/",
+    "workflows/evaluations/"
+  ],
+  "modules": [
+    "agents",
+    "prompts",
+    "embeddings",
+    "rag",
+    "evaluations",
+    "guardrails",
+    "telemetry-llm"
+  ],
+  "packages_recommended": ["llm-adapters", "prompt-library", "vector-store-sdk"],
+  "integrations_recommended": ["anthropic", "openai", "pinecone", "langfuse"],
+  "constraints_overrides": {
+    "max_modules_before_split": 15
+  },
+  "notes": "Prompts versionados. Evaluations rodam em CI. Guardrails entre prompt e LLM (PII redact, injection detect)."
+}

package/ai/blueprints/crm.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "./_schema.json",
+  "id": "crm",
+  "description": "CRM ou plataforma de relacionamento com pipelines, comunicações e analytics de leads.",
+  "extends": ["web"],
+  "folders": [
+    "workflows/automation/",
+    "data/exports/"
+  ],
+  "modules": [
+    "customers",
+    "leads",
+    "pipelines",
+    "deals",
+    "communications",
+    "tasks",
+    "contacts"
+  ],
+  "packages_recommended": ["email-templates", "sms-adapter", "analytics-core"],
+  "integrations_recommended": ["sendgrid", "twilio", "google-calendar", "hubspot"],
+  "notes": "Modelo dominante: pipeline com estados configuráveis. Eventos cross-module via communications/."
+}

package/ai/blueprints/game.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "./_schema.json",
+  "id": "game",
+  "description": "Jogo (single-player ou multiplayer) com engine, scenes, entities e física.",
+  "folders": [
+    "apps/client/",
+    "services/game-server/",
+    "packages/engine/",
+    "packages/assets/",
+    "data/scenes/"
+  ],
+  "modules": [
+    "engine",
+    "scenes",
+    "entities",
+    "physics",
+    "network",
+    "ai-npcs",
+    "input",
+    "audio"
+  ],
+  "packages_recommended": ["engine", "ecs-core", "asset-pipeline"],
+  "integrations_recommended": ["steam", "playfab", "discord-rpc"],
+  "notes": "ECS (Entity-Component-System) recomendado para entidades. Asset pipeline separado do code path."
+}

package/ai/blueprints/mobile.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "./_schema.json",
+  "id": "mobile",
+  "description": "App mobile nativo ou cross-platform com offline-first e sync.",
+  "folders": [
+    "apps/mobile/",
+    "packages/mobile-sdk/",
+    "packages/sync-engine/"
+  ],
+  "modules": [
+    "offline",
+    "sync",
+    "device",
+    "storage",
+    "push",
+    "deep-linking"
+  ],
+  "packages_recommended": ["mobile-sdk", "sync-engine", "device-info"],
+  "integrations_recommended": ["firebase", "onesignal", "sentry-mobile"],
+  "constraints_overrides": {
+    "max_file_lines": 400
+  },
+  "notes": "Offline-first: state sempre persistente local. Sync conflict resolution explícito (last-write-wins ou CRDT)."
+}

package/ai/blueprints/realtime.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "./_schema.json",
+  "id": "realtime",
+  "description": "Sistema realtime / event-driven: websockets, queues, event streams, CQRS.",
+  "folders": [
+    "services/realtime/",
+    "services/event-bus/",
+    "packages/event-types/",
+    "workflows/event-handlers/"
+  ],
+  "modules": [
+    "websockets",
+    "event-streams",
+    "queues",
+    "subscriptions",
+    "presence",
+    "broadcasts"
+  ],
+  "packages_recommended": ["event-types", "ws-adapters", "queue-sdk"],
+  "integrations_recommended": ["redis-streams", "kafka", "nats", "ably"],
+  "notes": "Idempotência obrigatória em handlers (eventos podem reprocessar). Schema registry para event-types. Backpressure + dead-letter queue."
+}

package/ai/blueprints/saas.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "./_schema.json",
+  "id": "saas",
+  "description": "Produto SaaS multi-tenant com billing, permissões granulares e auditoria.",
+  "extends": ["web"],
+  "folders": [
+    "apps/admin/",
+    "services/billing/",
+    "data/migrations/billing/"
+  ],
+  "modules": [
+    "billing",
+    "subscriptions",
+    "tenancy",
+    "permissions",
+    "audit",
+    "feature-flags"
+  ],
+  "packages_recommended": ["stripe-adapter", "auth-sdk", "feature-flag-sdk"],
+  "integrations_recommended": ["stripe", "auth0", "posthog", "intercom"],
+  "constraints_overrides": {
+    "max_modules_before_split": 25
+  },
+  "notes": "Tenancy isolation é crítico: nunca consultar dados cross-tenant sem filtro explícito. Audit log obrigatório em mudanças sensíveis."
+}

package/ai/blueprints/telemetry.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "./_schema.json",
+  "id": "telemetry",
+  "description": "Telemetry / logistics / IoT: tracking, geofencing, ingestão de devices.",
+  "extends": ["web"],
+  "folders": [
+    "services/telemetry/",
+    "services/ingestion/",
+    "data/timeseries/",
+    "workflows/ingestion/",
+    "workflows/alerts/"
+  ],
+  "modules": [
+    "tracking",
+    "telemetry",
+    "geofencing",
+    "fleet",
+    "devices",
+    "providers",
+    "trips",
+    "events",
+    "alerts"
+  ],
+  "packages_recommended": ["telemetry-core", "geo-utils", "provider-adapters"],
+  "integrations_recommended": ["google-maps", "mapbox", "mqtt", "kafka", "timescaledb"],
+  "constraints_overrides": {
+    "max_modules_before_split": 30
+  },
+  "notes": "Time-series volumoso. Providers adapter pattern crítico (cada device fabricante = adapter). Backpressure obrigatório em ingestão."
+}

package/ai/blueprints/web.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "./_schema.json",
+  "id": "web",
+  "description": "Base para aplicação web típica: SPA/SSR + API REST/GraphQL + UI library compartilhada.",
+  "folders": [
+    "apps/web/",
+    "services/api/",
+    "packages/ui/",
+    "packages/contracts/",
+    "packages/types/",
+    "infrastructure/docker/",
+    "infrastructure/ci/",
+    "tests/e2e/"
+  ],
+  "modules": [
+    "auth",
+    "users",
+    "notifications"
+  ],
+  "packages_recommended": ["ui", "contracts", "types", "sdk"],
+  "integrations_recommended": ["sendgrid", "sentry"],
+  "notes": "Base mínima. Adicionar blueprints (saas/crm/etc.) para capacidades extras."
+}

package/ai/bootstrap/discovery-questions.md

@@ -0,0 +1,117 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: on_demand
+tokens: ~600
+load: bootstrap_discovery
+---
+
+# Discovery Questions
+
+> Banco de perguntas estruturadas. Use uma de cada vez. Pare quando tiver o essencial.
+
+---
+
+## TL;DR
+
+- **Não fazer 10 perguntas de uma vez.** Uma por turno.
+- **Inferir antes de perguntar.** Só pergunte o que NÃO dá para descobrir lendo.
+- **Marcar `?` em `project-context.md`** para itens não confirmados — preencher quando souber.
+
+---
+
+## Categorias
+
+### 1. Negócio / Visão
+- Em uma frase, qual o objetivo deste projeto?
+- Quem é o usuário final? (interno, B2B, B2C, número aproximado)
+- Qual a métrica de sucesso? (uso, receita, retenção, qualidade...)
+- Existe deadline ou marco importante? Qual data?
+- O projeto é estratégico, experimental ou manutenção?
+
+### 2. Stack & Técnica
+- Stack atual / preferida?
+- Há requisitos de linguagem ou framework não-negociáveis?
+- Cloud / on-prem / híbrido?
+- Existe sistema legado com o qual integrar?
+
+### 3. Time
+- Quantas pessoas tocam o código?
+- Papéis (front, back, DevOps, QA, design)?
+- Quem decide arquitetura?
+- Qual o nível médio (júnior, pleno, sênior, misto)?
+
+### 4. Ambiente Operacional
+- Quais ambientes existem (dev, staging, prod, outros)?
+- Janelas de deploy? Janelas de blackout?
+- Quem é on-call?
+- Qual SLA do produto?
+
+### 5. Compliance & Risco
+- LGPD / GDPR / PCI-DSS / HIPAA / SOC2 / outros aplicam?
+- Há auditoria externa periódica?
+- Dados sensíveis manipulados? (PII, financeiro, saúde)
+- Riscos conhecidos (segurança, performance, dependência única)?
+
+### 6. Histórico (só para projeto existente)
+- O projeto tem quantos meses/anos?
+- Houve incidente significativo recente? (vazamento, downtime, regressão grave)
+- Quais áreas do código são "intocáveis"?
+- Qual a maior dor técnica hoje?
+
+### 7. Direção
+- Próximos 30 dias: o que precisa estar pronto?
+- Próximos 90 dias: principal entrega?
+- 6-12 meses: visão de produto?
+
+### 8. Limites do Agente
+- O agente pode commitar direto ou só via PR?
+- Pode rodar comandos de DB? (read? write?)
+- Pode acessar internet/MCPs? (busca, browser, ...)
+- Há diretórios proibidos?
+
+---
+
+## Tabela de Mínimo Vital
+
+Antes de **qualquer execução não-trivial**, o agente deve ter pelo menos:
+
+| Campo | Origem |
+|---|---|
+| Objetivo | Q1.1 |
+| Stack | Inspeção + Q2.1 |
+| Ambientes | Q4.1 |
+| Compliance (se há) | Q5.1 |
+| Limites do agente | Q8.* |
+
+Sem isso → conduzir o diálogo. Não improvisar.
+
+---
+
+## Ritmo do Diálogo
+
+1. **Bloco temático por turno.** Ex: faz 1-2 perguntas de "Stack", aguarda.
+2. **Resumir** a cada 3-4 respostas e pedir confirmação.
+3. **Salvar progressivamente** em `project-context.md` — não esperar o final.
+4. **Encerrar quando "mínimo vital" estiver coberto** + perguntar se há mais algo crítico.
+
+---
+
+## Sugestões Pró-ativas Durante Descoberta
+
+Conforme o usuário responde, o agente pode propor:
+- "Você mencionou X — sugiro também considerar Y. Quer que eu detalhe?"
+- "A combinação de A + B é incomum por causa de C. Confirma essa direção?"
+- "Pelo descrito, alguns trade-offs aparecem cedo. Quer que eu liste?"
+
+Sugestão NÃO é decisão. Decisão fica em ADR.
+
+---
+
+## Quando Pular Discovery
+
+- Tarefa é trivial (ler arquivo, responder pergunta factual).
+- `project-context.md` já está preenchido e relevante.
+- Usuário declarou "só faça X, sem perguntas".
+
+Mas mesmo nestes casos: **mínimo vital** deve estar em `project-context.md` antes de qualquer mudança estrutural.

package/ai/bootstrap/dispatcher.md

@@ -0,0 +1,85 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~500
+load: bootstrap_triggers
+---
+
+# Bootstrap Dispatcher
+
+> Ponto de entrada para qualquer projeto novo ou já em andamento.
+> Carregado pelo ROUTER quando o usuário fala em "começar", "novo projeto", "projeto existente", "setup", "init".
+
+---
+
+## TL;DR
+
+1. **Pergunta 1**: novo ou existente?
+2. Se **novo** → carregar `bootstrap/new-project.md`.
+3. Se **existente** → carregar `bootstrap/existing-project.md`.
+4. Em ambos, em seguida → `bootstrap/discovery-questions.md`.
+
+Não pular para implementação enquanto não houver respostas mínimas de descoberta.
+
+---
+
+## Fluxo
+
+### Passo 0 — Identificar contexto
+Antes de fazer pergunta, o agente verifica:
+- O diretório atual tem `package.json`/`pyproject.toml`/`Cargo.toml`/`go.mod`/etc? → provável existente.
+- O diretório está vazio (ou só com `.ai/`)? → provável novo.
+- O usuário já indicou? → respeitar.
+
+Apresentar a hipótese e confirmar, não assumir cegamente.
+
+### Passo 1 — Pergunta de classificação
+
+Formato (adaptar idioma ao usuário):
+
+```
+Antes de eu seguir, preciso entender o ponto de partida.
+
+[ ] Projeto NOVO (vamos criar do zero)
+[ ] Projeto EXISTENTE em andamento
+    → Onde está o projeto? (caminho, repositório, ou descrição)
+
+Pode escolher e, se existente, me indicar o local.
+```
+
+### Passo 2 — Rota
+
+| Resposta | Próximo arquivo |
+|---|---|
+| Novo | `.ai/bootstrap/new-project.md` |
+| Existente | `.ai/bootstrap/existing-project.md` |
+| Ambíguo | repetir pergunta com exemplos |
+
+### Passo 3 — Descoberta
+Após rota, carregar `.ai/bootstrap/discovery-questions.md`. Conduzir o diálogo até ter os campos mínimos para preencher `memory/project-context.md`.
+
+### Passo 4 — Maturação
+- Preencher `memory/project-context.md` com o que foi descoberto.
+- Sugerir 1-3 melhorias se o agente identificar lacunas (ex: "sua stack não tem testes — sugiro adicionar configuração mínima").
+- Confirmar plano antes de codar.
+
+---
+
+## Anti-padrões
+
+- Começar a implementar sem descoberta básica.
+- Fazer 10 perguntas de uma vez (sobrecarrega o usuário).
+- Aceitar "tanto faz" e improvisar sem registrar a escolha em `decisions.md`.
+- Pular preenchimento de `project-context.md` "para ganhar tempo".
+
+---
+
+## Maturidade
+
+Um projeto é considerado "amadurecido" (não precisa mais de bootstrap) quando:
+- `memory/project-context.md` tem stack, ambientes, restrições.
+- ≥3 ADRs em `memory/decisions.md`.
+- `operating-system/architecture.md` está específico ao projeto.
+
+Antes disso → diálogo guiado. Depois disso → o agente já pode operar com autonomia razoável.