create-genia-os 2.4.0 → 3.0.0

package/template/.claude/hooks/write-path-validation.py

@@ -1,59 +1,194 @@
 #!/usr/bin/env python3
 """
-GEN.IA OS — Hook: write-path-validation
-Trigger: PreToolUse (Write)
-Ação: Avisa quando documentos são criados fora do path padrão.
+Hook: Write Path Validation
+
+REGRA: Documentos devem ir para os paths corretos conforme convenções.
+
+Este hook intercepta Write/Edit e AVISA (não bloqueia) quando o path
+parece violar as convenções de organização de documentos.
+
+Exit Codes:
+- 0: Sempre (apenas avisa, nunca bloqueia)
 """
+
 import json
 import sys
-import re
 import os
+import re
+from datetime import datetime
+
+# =============================================================================
+# CONFIGURAÇÃO: Regras de organização de documentos
+# =============================================================================
+
+PATH_RULES = [
+    # (pattern no nome/conteúdo, path esperado, descrição)
+    {
+        "name_patterns": [r"session", r"handoff", r"^2\d{3}-\d{2}-\d{2}"],
+        "expected_path": "docs/sessions/",
+        "description": "Session logs e handoffs → docs/sessions/YYYY-MM/",
+    },
+    {
+        "name_patterns": [r"architecture", r"system-design", r"infra"],
+        "expected_path": "docs/architecture/",
+        "description": "Docs de arquitetura → docs/architecture/",
+        "exclude_patterns": [r"ARCHITECTURE_RULES"],  # Exceção para MMOS
+    },
+    {
+        "name_patterns": [r"guide", r"tutorial", r"how-to"],
+        "expected_path": "docs/guides/",
+        "description": "Guias e tutoriais → docs/guides/",
+    },
+    {
+        "name_patterns": [r"prd\.md$", r"epic.*\.md$", r"story.*\.md$"],
+        "expected_path": "docs/projects/",
+        "description": "PRDs, Epics, Stories → docs/projects/{project}/",
+    },
+    {
+        "name_patterns": [r"mind.*specific", r"mind.*validation"],
+        "expected_path": "outputs/minds/",
+        "description": "Docs específicos de mind → outputs/minds/{slug}/docs/",
+    },
+]
+
+# Paths que são sempre válidos (não avisar)
+ALWAYS_VALID_PATHS = [
+    ".claude/",
+    ".aiox-core/",
+    ".aiox-upstream/",
+    "squads/",
+    "node_modules/",
+    ".git/",
+    "app/",
+    "supabase/",
+    "outputs/",
+]
+
+# =============================================================================
+# LÓGICA DO HOOK
+# =============================================================================
+
+def get_project_root():
+    """Obtém o root do projeto."""
+    return os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+
+def normalize_path(file_path: str, project_root: str) -> str:
+    """Normaliza path para relativo."""
+    if file_path.startswith(project_root):
+        return file_path[len(project_root):].lstrip("/")
+    return file_path
+
+def is_always_valid(relative_path: str) -> bool:
+    """Verifica se o path está em área sempre válida."""
+    for valid in ALWAYS_VALID_PATHS:
+        if relative_path.startswith(valid):
+            return True
+    return False
 
+def is_documentation_file(relative_path: str) -> bool:
+    """Verifica se é um arquivo de documentação."""
+    doc_extensions = [".md", ".mdx", ".txt", ".rst"]
+    return any(relative_path.endswith(ext) for ext in doc_extensions)
 
-# Padrões de arquivo → path recomendado
-DOC_RULES = {
-    r"^PRD\.md$": "docs/[projeto]/PRD.md",
-    r"^SPEC-TECNICO\.md$": "docs/[projeto]/SPEC-TECNICO.md",
-    r"^COMERCIAL\.md$": "docs/[projeto]/COMERCIAL.md",
-    r"^BRIEFING\.md$": "docs/[projeto]/BRIEFING.md",
-    r"^STORY-\d+.*\.md$": "docs/stories/STORY-NNN-slug.md",
-    r"^ADR-\d+.*\.md$": "docs/[projeto]/adrs/ADR-NNN-titulo.md",
-}
+def check_path_rules(relative_path: str) -> list[dict]:
+    """
+    Verifica se o path viola alguma regra.
 
+    Returns:
+        Lista de violações com sugestões
+    """
+    violations = []
+    filename = os.path.basename(relative_path)
+
+    for rule in PATH_RULES:
+        # Verificar se o nome do arquivo corresponde ao pattern
+        matches_name = False
+        for pattern in rule["name_patterns"]:
+            if re.search(pattern, filename, re.IGNORECASE):
+                matches_name = True
+                break
+
+        if not matches_name:
+            continue
+
+        # Verificar exceções
+        if "exclude_patterns" in rule:
+            is_excluded = False
+            for exc_pattern in rule["exclude_patterns"]:
+                if re.search(exc_pattern, filename, re.IGNORECASE):
+                    is_excluded = True
+                    break
+            if is_excluded:
+                continue
+
+        # Verificar se está no path esperado
+        expected = rule["expected_path"]
+        if not relative_path.startswith(expected):
+            violations.append({
+                "current_path": relative_path,
+                "expected_path": expected,
+                "description": rule["description"],
+            })
+
+    return violations
 
 def main():
+    # Ler input do stdin
     try:
-        raw = sys.stdin.read()
-        data = json.loads(raw)
-    except Exception:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
         sys.exit(0)
 
-    tool = data.get("tool_name", "")
-    if tool != "Write":
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+
+    # Só processar Write e Edit
+    if tool_name not in ["Write", "Edit"]:
         sys.exit(0)
 
-    file_path = data.get("tool_input", {}).get("file_path", "")
+    file_path = tool_input.get("file_path", "")
     if not file_path:
         sys.exit(0)
 
-    # Normalizar separadores
-    normalized = file_path.replace("\\", "/")
-    filename = os.path.basename(normalized)
+    # Normalizar path
+    project_root = get_project_root()
+    relative_path = normalize_path(file_path, project_root)
 
-    for pattern, correct_path in DOC_RULES.items():
-        if re.match(pattern, filename, re.IGNORECASE):
-            # Verificar se está no path correto
-            if "docs/" not in normalized:
-                print(
-                    f"[GEN.IA OS] ⚠️  Documento '{filename}' fora do path padrão.\n"
-                    f"[GEN.IA OS] Path recomendado: {correct_path}\n"
-                    f"[GEN.IA OS] Criando assim mesmo — ajuste se necessário.",
-                    file=sys.stderr,
-                )
-            break
+    # Verificar se é área sempre válida
+    if is_always_valid(relative_path):
+        sys.exit(0)
 
-    sys.exit(0)  # Apenas avisa, não bloqueia
+    # Só verificar arquivos de documentação
+    if not is_documentation_file(relative_path):
+        sys.exit(0)
+
+    # Verificar regras
+    violations = check_path_rules(relative_path)
+
+    if not violations:
+        sys.exit(0)
+
+    # AVISAR (não bloquear)
+    violation = violations[0]  # Mostrar primeira violação
 
+    warning_message = f"""
+┌──────────────────────────────────────────────────────────────────────────────┐
+│  ⚠️  PATH WARNING: Documento pode estar no local errado                       │
+├──────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│  Arquivo: {relative_path[:60]:<60} │
+│                                                                              │
+│  Convenção: {violation['description'][:56]:<56} │
+│  Esperado:  {violation['expected_path']:<57} │
+│                                                                              │
+│  NOTA: Este é apenas um AVISO, a operação será executada.                    │
+│        Verifique se o path está correto antes de continuar.                  │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+"""
+    # Imprimir warning mas NÃO bloquear (exit 0)
+    print(warning_message, file=sys.stderr)
+    sys.exit(0)
 
 if __name__ == "__main__":
     main()

package/template/.claude/rules/agent-authority.md

@@ -1,39 +1,105 @@
-# Autoridade dos Agentes — GEN.IA OS
-
-## Matriz de Delegação
-
-| Agente | Nome | Autoridade Exclusiva | Git Permitido | Git Bloqueado |
-|--------|------|---------------------|---------------|---------------|
-| @analyst | Ana | Briefing, requisitos, pesquisa | status, log, diff | push, commit, merge |
-| @pm | Marina | PRD, escopo, priorização, épicos | status, log, diff | push, commit, merge |
-| @architect | Arqui | Arquitetura, stack, VETO técnico | status, log, diff | push, commit, merge |
-| @dev | Dev | Implementação de código | checkout, add, commit | **PUSH (BLOQUEADO)** |
-| @devops | Gate | **git push, PR, release, MCP** | TUDO | nada |
-| @qa | Quinn | Veredictos de qualidade, testes | status, log, diff, stash | push, commit |
-| @reviewer | Rev | Code review, aprovação | status, log, diff | push, commit |
-| @po | Pax | Validação de stories, backlog | status, log, diff | push, commit, merge |
-| @sm | Sami | **Criação de stories**, sprint | status, log, diff | push, commit, merge |
-
-## Regras Invioláveis (Artigo II da Constituição)
-
-1. **@dev NUNCA faz push** — sempre delegar para @devops após commit
-2. **@sm é o ÚNICO que cria stories** — nenhum outro agente cria STORY-*.md
-3. **@architect tem veto técnico irrevogável** — qualquer decisão arquitetural
-4. **@po é o ÚNICO que aprova stories** para ir para desenvolvimento
-5. **@devops gerencia MCP** — nenhum outro agente adiciona/remove servidores MCP
-
-## Protocolo de Escalação
-
-Quando uma tarefa está fora do seu escopo:
-1. **PARAR** imediatamente
-2. **Anunciar** o agente correto: "Esta tarefa pertence a @[agente]"
-3. **Fazer handoff** usando o protocolo de `.claude/rules/agent-handoff.md`
-4. **NÃO executar** tarefas fora da sua autoridade
-
-## Exemplos de Escalação Obrigatória
-
-- @dev termina implementação → delega push para **@devops**
-- @dev tem dúvida arquitetural → consulta **@architect**
-- @pm precisa de requisitos → solicita para **@analyst**
-- @dev precisa de story → solicita para **@sm**
-- @sm criou story → entrega para **@po** validar
+# Agent Authority — Detailed Rules
+
+## Delegation Matrix
+
+### @devops (Gage) — EXCLUSIVE Authority
+
+| Operation | Exclusive? | Other Agents |
+|-----------|-----------|--------------|
+| `git push` / `git push --force` | YES | BLOCKED |
+| `gh pr create` / `gh pr merge` | YES | BLOCKED |
+| MCP add/remove/configure | YES | BLOCKED |
+| CI/CD pipeline management | YES | BLOCKED |
+| Release management | YES | BLOCKED |
+
+### @pm (Morgan) — Epic Orchestration
+
+| Operation | Exclusive? | Delegated From |
+|-----------|-----------|---------------|
+| `*execute-epic` | YES | — |
+| `*create-epic` | YES | — |
+| EPIC-{ID}-EXECUTION.yaml management | YES | — |
+| Requirements gathering | YES | — |
+| Spec writing (spec pipeline) | YES | — |
+
+### @po (Pax) — Story Validation
+
+| Operation | Exclusive? | Details |
+|-----------|-----------|---------|
+| `*validate-story-draft` | YES | 10-point checklist |
+| Story context tracking in epics | YES | — |
+| Epic context management | YES | — |
+| Backlog prioritization | YES | — |
+
+### @sm (River) — Story Creation
+
+| Operation | Exclusive? | Details |
+|-----------|-----------|---------|
+| `*draft` / `*create-story` | YES | From epic/PRD |
+| Story template selection | YES | — |
+
+### @dev (Dex) — Implementation
+
+| Allowed | Blocked |
+|---------|---------|
+| `git add`, `git commit`, `git status` | `git push` (delegate to @devops) |
+| `git branch`, `git checkout`, `git merge` (local) | `gh pr create/merge` (delegate to @devops) |
+| `git stash`, `git diff`, `git log` | MCP management |
+| Story file updates (File List, checkboxes) | Story file updates (AC, scope, title) |
+
+### @architect (Aria) — Design Authority
+
+| Owns | Delegates To |
+|------|-------------|
+| System architecture decisions | — |
+| Technology selection | — |
+| High-level data architecture | @data-engineer (detailed DDL) |
+| Integration patterns | @data-engineer (query optimization) |
+| Complexity assessment | — |
+
+### @data-engineer (Dara) — Database
+
+| Owns (delegated from @architect) | Does NOT Own |
+|----------------------------------|-------------|
+| Schema design (detailed DDL) | System architecture |
+| Query optimization | Application code |
+| RLS policies implementation | Git operations |
+| Index strategy execution | Frontend/UI |
+| Migration planning & execution | — |
+
+### @aiox-master — Framework Governance
+
+| Capability | Details |
+|-----------|---------|
+| Execute ANY task directly | No restrictions |
+| Framework governance | Constitutional enforcement |
+| Override agent boundaries | When necessary for framework health |
+
+## Cross-Agent Delegation Patterns
+
+### Git Push Flow
+```
+ANY agent → @devops *push
+```
+
+### Schema Design Flow
+```
+@architect (decides technology) → @data-engineer (implements DDL)
+```
+
+### Story Flow
+```
+@sm *draft → @po *validate → @dev *develop → @qa *qa-gate → @devops *push
+```
+
+### Epic Flow
+```
+@pm *create-epic → @pm *execute-epic → @sm *draft (per story)
+```
+
+## Escalation Rules
+
+1. Agent cannot complete task → Escalate to @aiox-master
+2. Quality gate fails → Return to @dev with specific feedback
+3. Constitutional violation detected → BLOCK, require fix before proceed
+4. Agent boundary conflict → @aiox-master mediates

package/template/.claude/rules/agent-handoff.md

@@ -1,71 +1,97 @@
-# Protocolo de Handoff — GEN.IA OS
-
-## Quando Fazer Handoff
-
-Handoff é obrigatório quando:
-- Tarefa requer autoridade de outro agente (Artigo II)
-- Fase do workflow mudou
-- Blocker identificado fora do escopo atual
-- Trabalho está completo e próxima etapa é de outro agente
-
-## Formato de Handoff (≤ 400 tokens)
-
-```
-[@agente-atual → @próximo-agente]
-
-📋 Contexto: [O que foi feito em 2-3 frases]
-
-📌 Decisões tomadas:
-- [decisão 1]
-- [decisão 2]
-
-📁 Arquivos criados/modificados:
-- [path/arquivo.md]
-
-⚠️  Pendências:
-- [o que precisa ser feito]
-
-🔗 Story atual: STORY-NNN (se aplicável)
-```
-
-## Regra de Token Budget
-
-- Handoff DEVE ser ≤ 400 tokens
-- Após 2+ trocas de agente, comprimir histórico ao essencial
-- Não repassar contexto completo — apenas decisões e pendências
-
-## Compressão de Contexto
-
-Quando o contexto estiver saturado (muitas trocas de agente):
-
-1. Criar `.genia/session/context-summary.md` com:
-   - Decisões arquiteturais tomadas
-   - Stories em andamento e seus estados
-   - Blockers conhecidos
-   - Stack tecnológica confirmada
-
-2. Referenciar o arquivo no próximo handoff:
-   ```
-   [Contexto comprimido em .genia/session/context-summary.md]
-   ```
-
-## Exemplos de Handoff
-
-**@dev → @devops (após implementação):**
-```
-[@dev → @devops]
-📋 Implementei STORY-003 (autenticação JWT). Commits feitos localmente.
-📌 Decisões: Usei jose library, tokens expiram em 1h, refresh em 7d.
-📁 Modificados: src/auth/jwt.ts, src/middleware/auth.ts, tests/auth.test.ts
-⚠️  Pendências: Push da branch feat/STORY-003-jwt-auth e criar PR para main.
-🔗 Story atual: STORY-003 (status: InReview)
-```
-
-**@analyst → @pm (após briefing):**
-```
-[@analyst → @pm]
-📋 Coletei requisitos completos do sistema de orçamentos BrasilUp.
-📌 Decisões: App web (não mobile), integração com Kommo CRM, 3 usuários simultâneos.
-📁 Criados: docs/brasilup/BRIEFING.md
-⚠️  Pendências: Criar PRD com base no briefing. Atenção ao requisito de relatórios PDF.
-```
+# Agent Handoff Protocol — Context Compaction
+
+## Purpose
+
+Prevent context window accumulation when switching between AIOX agents (`@agent` commands). Each agent switch compacts the previous agent's full persona into a structured handoff artifact (~379 tokens) instead of retaining the full definition (~3-5K tokens).
+
+## When This Applies
+
+This protocol activates whenever:
+1. A user invokes a new agent via `@agent-name` or `/AIOX:agents:agent-name`
+2. The current session already has a different agent active
+
+## Handoff Protocol
+
+### On Agent Switch (outgoing agent)
+
+Before loading the new agent, mentally generate a handoff artifact with:
+
+```yaml
+handoff:
+  from_agent: "{current_agent_id}"
+  to_agent: "{new_agent_id}"
+  story_context:
+    story_id: "{active story ID}"
+    story_path: "{active story path}"
+    story_status: "{current status}"
+    current_task: "{last task being worked on}"
+    branch: "{current git branch}"
+  decisions:
+    - "{key decision 1}"
+    - "{key decision 2}"
+  files_modified:
+    - "{file 1}"
+    - "{file 2}"
+  blockers:
+    - "{any active blockers}"
+  next_action: "{what the incoming agent should do}"
+```
+
+### On Agent Switch (incoming agent)
+
+The incoming agent receives:
+1. Its own **full agent profile** (persona, commands, dependencies)
+2. The **handoff artifact** from the previous agent (compact summary)
+3. **NOT** the previous agent's full persona/instructions/tool definitions
+
+### Compaction Limits
+
+| Limit | Value |
+|-------|-------|
+| Max handoff artifact size | 500 tokens |
+| Max retained agent summaries | 3 (oldest discarded on 4th switch) |
+| Max decisions in artifact | 5 |
+| Max files_modified entries | 10 |
+| Max blockers | 3 |
+
+### What to Preserve (ALWAYS include)
+
+- Active story ID and path
+- Current task being worked on
+- Git branch name
+- Key architectural decisions made
+- Files created or modified
+- Active blockers
+
+### What to Discard (NEVER carry forward)
+
+- Previous agent's full persona definition
+- Previous agent's command list
+- Previous agent's dependency list
+- Previous agent's tool configurations
+- Previous agent's CodeRabbit integration details
+- Previous agent's greeting templates
+
+## Storage
+
+Handoff artifacts are stored at `.aiox/handoffs/` (runtime, gitignored). Format: `handoff-{from}-to-{to}-{timestamp}.yaml`.
+
+## Template Reference
+
+Full template: `.aiox-core/development/templates/agent-handoff-tmpl.yaml`
+
+## Example
+
+Session flow: `@sm` creates story → `@dev` implements → `@qa` reviews
+
+After `@sm` → `@dev` switch:
+- `@sm` full persona (~3K tokens) is **discarded**
+- Handoff artifact (~379 tokens) is **retained**: story ID, decisions, files, next action
+- `@dev` full persona (~5K tokens) is **loaded**
+- **Total context: ~5.4K** instead of ~8K (33% reduction per switch)
+
+After `@dev` → `@qa` switch:
+- `@dev` full persona is **discarded**
+- `@dev` handoff artifact is **retained** alongside `@sm` handoff
+- `@qa` full persona is **loaded**
+- **Total context: ~5.2K** instead of ~12K (57% reduction after 2 switches)

package/template/.claude/rules/agent-memory-imports.md

@@ -0,0 +1,15 @@
+---
+paths: .aiox-core/development/agents/**
+---
+
+# Agent Memory Imports
+
+Each AIOX agent has a canonical MEMORY.md containing persistent knowledge.
+These are the canonical locations — agents should read their memory on activation.
+
+@import .aiox-core/development/agents/dev/MEMORY.md
+@import .aiox-core/development/agents/qa/MEMORY.md
+@import .aiox-core/development/agents/architect/MEMORY.md
+@import .aiox-core/development/agents/devops/MEMORY.md
+@import .aiox-core/development/agents/pm/MEMORY.md
+@import .aiox-core/development/agents/po/MEMORY.md

package/template/.claude/rules/coderabbit-integration.md

@@ -0,0 +1,101 @@
+---
+paths:
+  - ".aiox-core/**"
+  - "tests/**"
+  - "packages/**"
+  - "bin/**"
+---
+
+# CodeRabbit Integration — Detailed Rules
+
+## Self-Healing Configuration
+
+### Dev Phase (@dev — Story Development Cycle Phase 3)
+
+```yaml
+mode: light
+max_iterations: 2
+timeout_minutes: 30
+severity_filter: [CRITICAL, HIGH]
+behavior:
+  CRITICAL: auto_fix
+  HIGH: auto_fix (iteration < 2) else document_as_debt
+  MEDIUM: document_as_debt
+  LOW: ignore
+```
+
+**Flow:**
+```
+RUN CodeRabbit → CRITICAL found?
+  YES → auto-fix (iteration < 2) → Re-run
+  NO → Document HIGH as debt, proceed
+After 2 iterations with CRITICAL → HALT, manual intervention
+```
+
+### QA Phase (@qa — QA Loop Pre-Review)
+
+```yaml
+mode: full
+max_iterations: 3
+timeout_minutes: 30
+severity_filter: [CRITICAL, HIGH]
+behavior:
+  CRITICAL: auto_fix
+  HIGH: auto_fix
+  MEDIUM: document_as_debt
+  LOW: ignore
+```
+
+**Flow:**
+1. Pre-commit review scan
+2. Self-healing loop (max 3 iterations)
+3. Manual QA analysis (architectural, traceability, NFR)
+4. Gate decision (verdict)
+
+## Severity Handling Summary
+
+| Severity | Dev Phase | QA Phase |
+|----------|-----------|----------|
+| CRITICAL | auto_fix, block if persists | auto_fix, block if persists |
+| HIGH | auto_fix, document if fails | auto_fix, document if fails |
+| MEDIUM | document_as_tech_debt | document_as_tech_debt |
+| LOW | ignore | ignore |
+
+## WSL Execution (Windows)
+
+```bash
+# Self-healing mode (automatic in dev tasks)
+wsl bash -c 'cd /mnt/c/.../aiox-core && ~/.local/bin/coderabbit --severity CRITICAL,HIGH --auto-fix'
+
+# Manual review
+wsl bash -c 'cd /mnt/c/.../aiox-core && ~/.local/bin/coderabbit -t uncommitted'
+
+# Prompt-only mode
+wsl bash -c 'cd /mnt/c/.../aiox-core && ~/.local/bin/coderabbit --prompt-only -t uncommitted'
+```
+
+## Integration Points
+
+| Workflow | Phase | Trigger | Agent |
+|----------|-------|---------|-------|
+| Story Development Cycle | 3 (Implement) | After task completion | @dev |
+| QA Loop | 1 (Review) | At review start | @qa |
+| Standalone | Any | `*coderabbit-review` command | Any |
+
+## Focus Areas by Story Type
+
+| Story Type | Primary Focus |
+|-----------|--------------|
+| Feature | Code patterns, test coverage, API design |
+| Bug Fix | Regression risk, root cause coverage |
+| Refactor | Breaking changes, interface stability |
+| Documentation | Markdown quality, reference validity |
+| Database | SQL injection, RLS coverage, migration safety |
+
+## Report Location
+
+CodeRabbit reports saved to: `docs/qa/coderabbit-reports/`
+
+## Configuration Reference
+
+Full config in `.aiox-core/core-config.yaml` under `coderabbit_integration` section.