create-genia-os 2.4.0 → 3.0.0

package/template/.claude/rules/ids-principles.md

@@ -1,52 +1,119 @@
-# Princípios IDS — GEN.IA OS
-## Incremental Decision System
-
-## Hierarquia de Decisão
-
-```
-REUSAR > ADAPTAR > CRIAR
-```
-
-Antes de criar qualquer artefato (componente, task, template, módulo, contexto):
-
-**1. REUSAR** — Buscar no projeto algo que já resolve o problema
-**2. ADAPTAR** — Se 70%+ compatível, adaptar o existente
-**3. CRIAR** — Apenas se reutilização não é viável
-
-## Onde Buscar Antes de Criar
-
-| Tipo | Buscar em |
-|------|-----------|
-| Task | `.genia/development/tasks/` |
-| Template de doc | `.claude/templates/` (se existir) |
-| Contexto de API | `.genia/contexts/` |
-| Skill | `.genia/skills/` |
-| Guideline | `.genia/guidelines/` |
-| Checklist | `.genia/development/checklists/` |
-
-## Justificativa Obrigatória para CRIAR
-
-Ao criar novo artefato que poderia ser reusado, documentar inline:
-
-```
-// NOVO: não foi possível reusar porque [razão]
-// Adaptação de: [nada existente] | [X arquivo, mas incompatível por Y]
-```
-
-## Prevenção de Duplicação em Stories
-
-Antes de criar `STORY-NNN`, verificar:
-1. Existe story similar em `docs/stories/`?
-2. Está dentro de um épico já existente?
-3. Já foi implementado e mergeado?
-
-## Circuit Breaker
-
-Se a busca por artefato reutilizável demorar mais de 30 segundos, prosseguir com criação e documentar a tentativa de busca.
-
-## Benefícios
-
-- Reduz explosão de arquivos no projeto
-- Mantém consistência entre implementações similares
-- Facilita manutenção no longo prazo
-- Evita reinventar soluções já validadas
+---
+paths:
+  - ".aiox-core/**"
+  - "packages/**"
+  - "bin/**"
+---
+
+# IDS Principles — Detailed Rules
+
+> Status: Planned (IDS epic is Draft — principles apply as aspirational guidance)
+
+## Decision Hierarchy: REUSE > ADAPT > CREATE
+
+### REUSE (Relevance >= 90%)
+- Use existing artifact directly without modification
+- Import/reference existing entity
+- No justification needed beyond confirming match
+
+### ADAPT (Relevance 60-89%)
+- Adaptability score >= 0.6
+- Changes MUST NOT exceed 30% of original artifact
+- Changes MUST NOT break existing consumers (check usedBy list)
+- Document changes in artifact's change log
+- Update registry relationships
+- Impact analysis required
+
+### CREATE (No suitable match)
+Required justification:
+- `evaluated_patterns`: Existing entities you considered
+- `rejection_reasons`: Why each was rejected (technical reasons)
+- `new_capability`: What unique capability this provides
+- Register in Entity Registry within 24 hours
+- Establish relationships with existing entities
+- Define adaptability constraints for future reuse
+
+## Verification Gates G1-G6
+
+### G1: Epic Creation (@pm)
+- **Type:** Human-in-loop, Advisory
+- **Trigger:** `*create-epic` workflow
+- **Action:** Query registry for related entities, display potentially reusable artifacts
+- **Latency:** < 24h (async)
+- **Blocking:** No
+
+### G2: Story Creation (@sm)
+- **Type:** Human-in-loop, Advisory
+- **Trigger:** `*draft` workflow
+- **Action:** Check existing tasks/templates matching story work
+- **Latency:** < 24h (async)
+- **Blocking:** No
+
+### G3: Story Validation (@po)
+- **Type:** Human-in-loop, Soft Block
+- **Trigger:** `*validate-story-draft` workflow
+- **Action:** Verify referenced artifacts exist, detect potential duplication
+- **Latency:** < 4h (async)
+- **Blocking:** Soft (can override with reason)
+
+### G4: Dev Context (@dev)
+- **Type:** Automated, Informational
+- **Trigger:** Story assignment / `*develop` start
+- **Action:** Display matching patterns as reminder
+- **Latency:** < 2s
+- **Blocking:** NO (logged only for metrics)
+
+### G5: QA Review (@qa)
+- **Type:** Automated, Blocks Merge
+- **Trigger:** PR/merge request
+- **Action:** Check if new artifacts could have reused existing
+- **Latency:** < 30s
+- **Blocking:** YES if new entity without registry entry or justification
+
+### G6: CI/CD (@devops)
+- **Type:** Automated, Blocks Merge
+- **Trigger:** CI pipeline
+- **Action:** Registry integrity check + sync
+- **Latency:** < 60s
+- **Blocking:** YES on CRITICAL, WARN on MEDIUM/LOW
+
+## Override Policy
+
+**Command:** `--override-ids --override-reason "explanation"`
+
+**Permitted when:**
+- Time-critical fix requires immediate creation
+- Adaptation would introduce unacceptable risk
+- Existing artifact is deprecated/frozen
+
+**Requirements:**
+- Logged for audit trail
+- Reviewed within 7 days
+- Include override reason in gate verification log
+
+## Graceful Degradation
+
+All gates implement circuit breaker:
+- **Timeout:** 2s default
+- **On timeout:** warn-and-proceed
+- **On error:** log-and-proceed
+- **Key principle:** Development NEVER blocked by IDS failures
+
+```yaml
+circuit_breaker:
+  failure_threshold: 5
+  success_threshold: 3
+  reset_timeout_ms: 60000
+```
+
+## Article IV-A: Incremental Development (Constitution Amendment)
+
+**Severity:** MUST
+
+**Four Core Rules:**
+1. **Registry Consultation Required** — Query before creating
+2. **Decision Hierarchy** — REUSE > ADAPT > CREATE strictly
+3. **Adaptation Limits** — Changes < 30%, don't break consumers
+4. **Creation Requirements** — Full justification, register within 24h
+
+**Reference:** `docs/stories/epics/epic-ids-incremental-development/`

package/template/.claude/rules/mcp-usage.md

@@ -1,49 +1,176 @@
-# Uso de Ferramentas e MCP — GEN.IA OS
-
-## Prioridade de Ferramentas
-
-```
-1. Ferramentas nativas Claude Code  (sempre preferir)
-2. Ferramentas MCP configuradas     (quando necessário)
-3. Bash com CLI tools               (último recurso)
-```
-
-## Ferramentas Nativas — Sempre Preferir
-
-| Operação | Ferramenta Correta | NÃO usar |
-|----------|--------------------|----------|
-| Ler arquivo | Read | Bash cat/head/tail |
-| Criar arquivo | Write | Bash echo/cat heredoc |
-| Editar arquivo | Edit | Bash sed/awk |
-| Buscar arquivo | Glob | Bash find/ls |
-| Buscar conteúdo | Grep | Bash grep/rg |
-| Perguntar usuário | AskUserQuestion | — |
-| Tarefa complexa | Task | — |
-
-## Gerenciamento MCP
-
-**@devops é o ÚNICO autorizado a:**
-- Adicionar servidores MCP
-- Remover servidores MCP
-- Configurar MCP (editar settings.json de MCP)
-- Fazer upgrade de versão de servidor MCP
-
-Outros agentes são **consumidores apenas**.
-
-## Regra de Ouro
-
-> "Se uma ferramenta nativa do Claude Code resolve, não use MCP."
-
-## Servidores MCP Disponíveis
-
-Ver configuração em `.claude/settings.json` (gerenciado por @devops).
-
-## Quando Usar Bash
-
-Use Bash apenas para:
-- Comandos git (quando necessário)
-- Executar scripts (npm, python, etc.)
-- Operações de sistema que não têm ferramenta nativa
-- Comandos CLI específicos (supabase, gh, etc.)
-
-Nunca para: leitura/escrita/busca de arquivos.
+---
+paths: **/*
+---
+
+# MCP Server Usage Rules - AIOX Architecture
+
+## MCP Governance
+
+**IMPORTANT:** All MCP infrastructure management is handled EXCLUSIVELY by the **DevOps Agent (@devops / Gage)**.
+
+| Operation | Agent | Command |
+|-----------|-------|---------|
+| Search MCP catalog | DevOps | `*search-mcp` |
+| Add MCP server | DevOps | `*add-mcp` |
+| List enabled MCPs | DevOps | `*list-mcps` |
+| Remove MCP server | DevOps | `*remove-mcp` |
+| Setup Docker MCP | DevOps | `*setup-mcp-docker` |
+
+Other agents (Dev, Architect, etc.) are MCP **consumers**, not administrators. If MCP management is needed, delegate to @devops.
+
+---
+
+## MCP Configuration Architecture
+
+AIOX uses Docker MCP Toolkit as the primary MCP infrastructure:
+
+### Direct in Claude Code (global ~/.claude.json)
+| MCP | Purpose |
+|-----|---------|
+| **playwright** | Browser automation, screenshots, web testing |
+| **desktop-commander** | Docker container operations via docker-gateway |
+
+### Inside Docker Desktop (via docker-gateway)
+
+| MCP | Purpose |
+|-----|---------|
+| **EXA** | Web search, research, company/competitor analysis |
+| **Context7** | Library documentation lookup |
+| **Apify** | Web scraping, Actors, social media data extraction |
+
+## CRITICAL: Tool Selection Priority
+
+ALWAYS prefer native Claude Code tools over MCP servers:
+
+| Task | USE THIS | NOT THIS |
+|------|----------|----------|
+| Read files | `Read` tool | docker-gateway |
+| Write files | `Write` / `Edit` tools | docker-gateway |
+| Run commands | `Bash` tool | docker-gateway |
+| Search files | `Glob` tool | docker-gateway |
+| Search content | `Grep` tool | docker-gateway |
+| List directories | `Bash(ls)` or `Glob` | docker-gateway |
+
+## desktop-commander (docker-gateway) Usage
+
+### ONLY use docker-gateway when:
+1. User explicitly says "use docker" or "use container"
+2. User explicitly mentions "Desktop Commander"
+3. Task specifically requires Docker container operations
+4. Accessing MCPs running inside Docker (EXA, Context7)
+5. User asks to run something inside a Docker container
+
+### NEVER use docker-gateway for:
+- Reading local files (use `Read` tool)
+- Writing local files (use `Write` or `Edit` tools)
+- Running shell commands on host (use `Bash` tool)
+- Searching files (use `Glob` or `Grep` tools)
+- Listing directories (use `Bash(ls)` or `Glob`)
+- Running Node.js or Python scripts on host (use `Bash` tool)
+
+## playwright MCP Usage
+
+### ONLY use playwright when:
+1. User explicitly asks for browser automation
+2. User wants to take screenshots of web pages
+3. User needs to interact with a website
+4. Task requires web scraping or testing
+5. Filling forms or clicking elements on web pages
+
+### NEVER use playwright for:
+- General file operations
+- Running commands
+- Anything not related to web browsers
+
+## EXA MCP Usage (via Docker)
+
+### Use EXA (mcp__docker-gateway__web_search_exa) for:
+1. Web searches for current information
+2. Research and documentation lookup
+3. Company and competitor research
+4. Finding code examples online
+
+### Access pattern:
+```
+mcp__docker-gateway__web_search_exa
+```
+
+## Context7 MCP Usage (via Docker)
+
+### Use Context7 for:
+1. Library documentation lookup
+2. API reference for packages/frameworks
+3. Getting up-to-date docs for dependencies
+
+### Access pattern:
+```
+mcp__docker-gateway__resolve-library-id
+mcp__docker-gateway__get-library-docs
+```
+
+## Apify MCP Usage (via Docker)
+
+### Use Apify for:
+1. Searching Actors in Apify Store (web scrapers, automation tools)
+2. Running web scrapers for social media (Instagram, TikTok, LinkedIn, etc.)
+3. Extracting data from e-commerce sites
+4. Automated data collection from any website
+5. RAG-enabled web browsing for AI context
+
+### Access pattern (7 tools available):
+
+```text
+mcp__docker-gateway__apify-slash-rag-web-browser  # RAG-enabled web browsing
+mcp__docker-gateway__search-actors                 # Search for Actors
+mcp__docker-gateway__call-actor                    # Run an Actor
+mcp__docker-gateway__fetch-actor-details           # Get Actor info/schema
+mcp__docker-gateway__get-actor-output              # Get results from Actor run
+mcp__docker-gateway__search-apify-docs             # Search Apify documentation
+mcp__docker-gateway__fetch-apify-docs              # Fetch documentation page
+```
+
+### When to use Apify vs other tools:
+| Task | Tool |
+|------|------|
+| General web search | EXA (`web_search_exa`) |
+| Scrape specific website | Apify (`call-actor`) |
+| Social media data extraction | Apify (use specialized Actors) |
+| Library documentation | Context7 |
+
+---
+
+## Rationale
+
+- **Native tools** execute on the LOCAL system (Windows/Mac/Linux)
+- **docker-gateway** executes inside Docker containers (Linux)
+- Using docker-gateway for local operations causes path mismatches and failures
+- Native tools are faster and more reliable for local file operations
+- EXA, Context7, and Apify run inside Docker for isolation and consistent environment
+- playwright runs directly for better browser integration with host system
+
+---
+
+## Known Issues
+
+### Docker MCP Secrets Bug (Dec 2025)
+
+**Issue:** Docker MCP Toolkit's secrets store and template interpolation do not work properly. Credentials set via `docker mcp secret set` are NOT passed to containers.
+
+**Symptoms:**
+- `docker mcp tools ls` shows "(N prompts)" instead of "(N tools)"
+- MCP server starts but fails authentication
+- Verbose output shows `-e ENV_VAR` without values
+
+**Workaround:** Edit `~/.docker/mcp/catalogs/docker-mcp.yaml` directly with hardcoded env values:
+```yaml
+{mcp-name}:
+  env:
+    - name: API_TOKEN
+      value: 'actual-token-value'
+```
+
+**Affected MCPs:** Any MCP requiring authentication (Apify, Notion, Slack, etc.)
+
+**Working MCPs:** EXA works because its key is in `~/.docker/mcp/config.yaml` under `apiKeys`
+
+For detailed instructions, see `*add-mcp` task or ask @devops for assistance.

package/template/.claude/rules/story-lifecycle.md

@@ -1,87 +1,145 @@
-# Ciclo de Vida de Stories — GEN.IA OS
-
-## Estados
-
-```
-Draft → Ready → InProgress → InReview → Done
-                                      ↘ Blocked
-```
-
-## Responsabilidades por Estado
-
-| Estado | Responsável | O que acontece |
-|--------|-------------|----------------|
-| **Draft** | @sm | Cria story com template padrão |
-| **Ready** | @po | Valida com checklist 10 pontos |
-| **InProgress** | @dev | Implementa o código |
-| **InReview** | @qa + @reviewer | Testa e revisa código |
-| **Done** | @devops | Faz push/PR; @pm atualiza backlog |
-| **Blocked** | agente atual | Documenta blocker e escalona |
-
-## Checklist de Validação — @po (10 pontos obrigatórios)
-
-- [ ] Título claro e acionável (verbo + objeto)
-- [ ] Formato: "Como [persona] quero [ação] para [benefício]"
-- [ ] Acceptance criteria definidos (mínimo 3 critérios)
-- [ ] Tasks técnicas listadas (mínimo 2 tasks)
-- [ ] Dependências de outras stories mapeadas
-- [ ] Estimativa de esforço definida (P/M/G/XG)
-- [ ] Nome da branch definido: `tipo/STORY-NNN-slug`
-- [ ] Arquivos a criar/modificar listados
-- [ ] Testes necessários identificados
-- [ ] Riscos e pontos de atenção documentados
-
-**Story com menos de 8 pontos = REJEITADA pelo @po**
-
-## Localização das Stories
-
-```
-docs/stories/STORY-[NNN]-[slug].md
-```
-
-Exemplo: `docs/stories/STORY-001-autenticacao-usuario.md`
-
-## Atualização de Status na Story
-
-Sempre atualizar o cabeçalho quando mudar de estado:
-
-```markdown
-**Status:** InProgress
-**Agente:** @dev
-**Atualizado:** 2026-02-24
-```
-
-## Template de Story
-
-```markdown
-# STORY-NNN — Título da Story
-
-**Status:** Draft
-**Agente:** @sm
-**Criado:** YYYY-MM-DD
-**Estimativa:** M
-
-## Descrição
-Como [persona] quero [ação] para [benefício].
-
-## Acceptance Criteria
-- [ ] AC1: ...
-- [ ] AC2: ...
-- [ ] AC3: ...
-
-## Tasks Técnicas
-- [ ] Task 1: ...
-- [ ] Task 2: ...
-
-## Branch
-`feat/STORY-NNN-slug`
-
-## Arquivos Envolvidos
-- `src/...`
-
-## Dependências
-- STORY-XXX (se houver)
-
-## Riscos
-- ...
-```
+---
+paths:
+  - "docs/stories/**"
+  - ".aiox-core/development/**"
+---
+
+# Story Lifecycle — Detailed Rules
+
+## Status Progression
+
+```
+Draft → Ready → InProgress → InReview → Done
+```
+
+| Status | Trigger | Agent | Action |
+|--------|---------|-------|--------|
+| Draft | @sm creates story | @sm | Story file created |
+| Ready | @po validates (GO) | @po | **MUST update status field in story file from Draft → Ready** |
+| InProgress | @dev starts implementation | @dev | Update status field |
+| InReview | @dev completes, @qa reviews | @qa | Update status field |
+| Done | @qa PASS, @devops pushes | @devops | Update status field |
+
+**CRITICAL:** The `Draft → Ready` transition is the responsibility of @po during `*validate-story-draft`. When verdict is GO (including conditional GO after fixes are applied), @po MUST update the story's Status field to `Ready` and log the transition in the Change Log. A story left in `Draft` after a GO verdict is a process violation.
+
+## Phase 1: Create (@sm)
+
+**Task:** `create-next-story.md`
+**Inputs:** PRD sharded, epic context
+**Output:** `{epicNum}.{storyNum}.story.md`
+
+## Phase 2: Validate (@po)
+
+**Task:** `validate-next-story.md`
+
+### 10-Point Validation Checklist
+
+1. Clear and objective title
+2. Complete description (problem/need explained)
+3. Testable acceptance criteria (Given/When/Then preferred)
+4. Well-defined scope (IN and OUT clearly listed)
+5. Dependencies mapped (prerequisite stories/resources)
+6. Complexity estimate (points or T-shirt sizing)
+7. Business value (benefit to user/business clear)
+8. Risks documented (potential problems identified)
+9. Criteria of Done (clear definition of complete)
+10. Alignment with PRD/Epic (consistency with source docs)
+
+**Decision:** GO (≥7/10) or NO-GO (<7/10 with required fixes)
+
+## Phase 3: Implement (@dev)
+
+**Task:** `dev-develop-story.md`
+
+### Execution Modes
+
+**YOLO (autonomous):**
+- 0-1 prompts
+- Decisions logged in `decision-log-{story-id}.md`
+- Best for: simple, deterministic tasks
+
+**Interactive (default):**
+- 5-10 prompts with educational checkpoints
+- Confirmations at key decision points
+- Best for: learning, complex decisions
+
+**Pre-Flight (plan-first):**
+- All questions upfront (10-15 prompts)
+- Generates execution plan
+- Then zero-ambiguity execution
+- Best for: ambiguous requirements, critical work
+
+### CodeRabbit Self-Healing in Dev Phase
+
+```
+iteration = 0
+while CRITICAL issues found AND iteration < 2:
+  auto-fix CRITICAL/HIGH
+  iteration++
+if CRITICAL persist after 2 iterations:
+  HALT — manual intervention required
+```
+
+## Phase 4: QA Gate (@qa)
+
+**Task:** `qa-gate.md`
+
+### 7 Quality Checks
+
+1. **Code review** — patterns, readability, maintainability
+2. **Unit tests** — adequate coverage, all passing
+3. **Acceptance criteria** — all met per story AC
+4. **No regressions** — existing functionality preserved
+5. **Performance** — within acceptable limits
+6. **Security** — OWASP basics verified
+7. **Documentation** — updated if necessary
+
+### Gate Decisions
+
+| Decision | Score | Action |
+|----------|-------|--------|
+| PASS | All checks OK | Approve, proceed to @devops push |
+| CONCERNS | Minor issues | Approve with observations documented |
+| FAIL | HIGH/CRITICAL issues | Return to @dev with feedback |
+| WAIVED | Issues accepted | Approve with waiver documented (rare) |
+
+### Gate File Structure
+
+```yaml
+storyId: STORY-42
+verdict: PASS | CONCERNS | FAIL | WAIVED
+issues:
+  - severity: low | medium | high
+    category: code | tests | requirements | performance | security | docs
+    description: "..."
+    recommendation: "..."
+```
+
+## QA Loop (Iterative Review-Fix)
+
+```
+@qa review → verdict → @dev fixes → re-review (max 5 iterations)
+```
+
+**Commands:**
+- `*qa-loop {storyId}` — Start full loop
+- `*stop-qa-loop` — Pause and save state
+- `*resume-qa-loop` — Resume from saved state
+- `*escalate-qa-loop` — Force manual escalation
+
+**Escalation triggers:**
+- max_iterations_reached (default: 5)
+- verdict_blocked
+- fix_failure (after retries)
+- manual_escalate (user command)
+
+**Status:** Tracked in `qa/loop-status.json`
+
+## Story File Update Rules
+
+| Section | Who Can Edit |
+|---------|-------------|
+| Title, Description, AC, Scope | @po only |
+| File List, Dev Notes, checkboxes | @dev |
+| QA Results | @qa only |
+| Change Log | Any agent (append only) |