aiox-core 5.0.2 → 5.0.3

package/pro/squads/squad-creator-pro/docs/QUICK-START.md

@@ -0,0 +1,205 @@
+# Quick Start: Resumo Rápido
+
+> **Este é um RESUMO.** Para tutorial completo com exemplos, veja [TUTORIAL-COMPLETO.md](./TUTORIAL-COMPLETO.md).
+>
+> **Primeira vez?** Comece por [POR-ONDE-COMECAR.md](./POR-ONDE-COMECAR.md).
+
+---
+
+## Pré-requisitos
+
+- Claude Code ativo
+- Projeto AIOS configurado
+
+---
+
+## Passo 1: Ativar o Squad Architect (30 seg)
+
+```
+@squad-creator
+```
+
+Você verá o greeting do Squad Architect. Ele está pronto para receber comandos.
+
+---
+
+## Passo 2: Solicitar Criação do Squad (1 min)
+
+Simplesmente diga o que você quer:
+
+```
+Quero um squad de copywriting
+```
+
+**O que acontece:**
+1. Squad Architect inicia automaticamente a pesquisa
+2. NÃO pergunta "quer pesquisar?" - já vai direto
+3. Executa 3-5 iterações de pesquisa com devil's advocate
+
+---
+
+## Passo 3: Pre-Flight (1 min)
+
+O sistema pergunta sobre o modo de execução:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ PRE-FLIGHT: CRIAÇÃO DE SQUAD                                    │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ Como você quer executar?                                        │
+│                                                                 │
+│ 🚀 YOLO    - Não tenho materiais (60-75% fidelity)             │
+│ 💎 QUALITY - Tenho livros/PDFs (85-95% fidelity)               │
+│ 🔀 HYBRID  - Tenho materiais de alguns experts                  │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Escolha:**
+- **YOLO** se quer rapidez e não tem materiais
+- **QUALITY** se tem livros/PDFs dos experts
+- **HYBRID** se tem materiais de alguns, não de todos
+
+---
+
+## Passo 4: Aprovar Elite Minds (1 min)
+
+Após a pesquisa, você vê os resultados:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ ELITE MINDS ENCONTRADOS                                         │
+├──────────────────┬──────────┬───────────────────────────────────┤
+│ Mind             │ Tier     │ Framework Principal               │
+├──────────────────┼──────────┼───────────────────────────────────┤
+│ {expert-1}       │ Tier 0   │ {framework-1}                     │
+│ {expert-2}       │ Tier 1   │ {framework-2}                     │
+│ {expert-3}       │ Tier 1   │ {framework-3}                     │
+│ ...              │ ...      │ ...                               │
+└──────────────────┴──────────┴───────────────────────────────────┘
+
+Criar agentes baseados nestes minds?
+```
+
+Responda **sim** para prosseguir.
+
+---
+
+## Passo 5: Aguardar Criação (2-3 min)
+
+O sistema executa automaticamente:
+
+```
+✓ Coletando fontes para {expert-name}...
+✓ Extraindo Voice DNA...
+✓ Extraindo Thinking DNA...
+✓ Rodando Smoke Tests (3/3)...
+✓ Criando agent.md...
+
+[Repetir para cada mind]
+
+✓ Criando orchestrator...
+✓ Gerando workflows...
+✓ Validando squad...
+✓ Gerando Quality Dashboard...
+```
+
+---
+
+## Passo 6: Receber o Squad Pronto
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ ✅ SQUAD CRIADO: {squad-name}                                   │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│ Agents: N (experts + 1 orchestrator)                            │
+│ Quality Score: X.X/10                                           │
+│ Fidelity Estimate: XX%                                          │
+│                                                                 │
+│ Ativação: @{squad-name}                                         │
+│ Dashboard: squads/{squad-name}/docs/quality-dashboard.md        │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Usar o Squad
+
+```
+@{squad-name}
+```
+
+Agora você tem acesso a todos os agents do squad:
+
+```
+@{squad-name}:{expert-1}  → Especialidade do expert 1
+@{squad-name}:{expert-2}  → Especialidade do expert 2
+@{squad-name}:{expert-3}  → Especialidade do expert 3
+```
+
+---
+
+## Resumo do Fluxo
+
+```
+@squad-creator
+      ↓
+"Quero um squad de {domínio}"
+      ↓
+Escolher modo (YOLO/QUALITY/HYBRID)
+      ↓
+Aprovar elite minds
+      ↓
+Aguardar criação automática
+      ↓
+@{squad} para usar
+```
+
+---
+
+## Comandos Úteis
+
+| Comando | O que faz |
+|---------|-----------|
+| `*create-squad` | Criar novo squad (com workflow guiado) |
+| `*clone-mind {name}` | Clonar um expert específico |
+| `*validate-squad {name}` | Validar squad existente |
+| `*quality-dashboard {name}` | Gerar dashboard de qualidade |
+| `*help` | Ver todos os comandos |
+
+---
+
+## Próximos Passos
+
+1. **Entender os conceitos:** Leia [CONCEPTS.md](./CONCEPTS.md)
+2. **Ver diagramas:** Leia [ARCHITECTURE-DIAGRAMS.md](./ARCHITECTURE-DIAGRAMS.md)
+3. **Problemas?** Leia [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)
+
+---
+
+## Exemplo Real: 30 Segundos
+
+```
+User: @squad-creator
+Bot:  🎨 Squad Architect ready...
+
+User: Quero um squad de {domínio}
+Bot:  I'll research the best minds in {domínio}. Starting...
+      [pesquisa 3-5 iterações]
+
+Bot:  Found N elite minds. Create agents?
+User: sim
+
+Bot:  [cria automaticamente]
+      ✅ Squad {squad-name} criado! Ative com @{squad-name}
+```
+
+**É isso.** Sem configuração, sem setup, sem complicação.
+
+---
+
+**Squad Architect | Quick Start v1.0**
+*"De zero a squad em 5 minutos."*

package/pro/squads/squad-creator-pro/docs/RFC-001-deterministic-refactoring.md

@@ -0,0 +1,463 @@
+# RFC-001: Deterministic Operations Refactoring
+
+**Status:** DRAFT
+**Created:** 2026-02-01
+**Author:** Squad Architect
+**Priority:** High
+
+---
+
+## Summary
+
+Analysis of squad-creator system revealed **107 deterministic operations** that can be handled by Python scripts, and **38 LLM-required operations** that need semantic understanding.
+
+This RFC proposes separating these concerns for:
+- Faster validation (no LLM latency)
+- Lower cost (no token usage for file checks)
+- More reliable results (deterministic = reproducible)
+- Better error messages (precise line numbers, exact issues)
+
+---
+
+## Current State
+
+```
+User: *validate-squad copy
+       ↓
+[LLM does EVERYTHING]
+- Counts files (could be script)
+- Checks YAML syntax (could be script)
+- Verifies references exist (could be script)
+- Judges content quality (needs LLM)
+- Calculates scores (could be script)
+       ↓
+Result: Mixed deterministic + semantic in one pass
+```
+
+**Problems:**
+1. Slow: LLM processes everything sequentially
+2. Expensive: Tokens spent on file counting
+3. Inconsistent: LLM might miss structural issues
+4. No caching: Same checks repeated every time
+
+---
+
+## Proposed Architecture
+
+```
+User: *validate-squad copy
+       ↓
+[PHASE 1: DETERMINISTIC SCRIPTS]
+├── script_inventory.py          → Counts files, lists components
+├── script_yaml_validator.py     → Checks YAML syntax, required keys
+├── script_dependency_check.py   → Verifies all references exist
+├── script_naming_validator.py   → Checks kebab-case, camelCase
+└── script_quality_gate.py       → Checks counts, line numbers
+       ↓
+[GATE: Any BLOCKING issues?]
+├── YES → Stop, report issues, no LLM needed
+└── NO  → Continue to Phase 2
+       ↓
+[PHASE 2: LLM SEMANTIC ANALYSIS]
+├── Content quality judgment
+├── Voice consistency check
+├── Example realism assessment
+├── Domain specificity analysis
+└── Architecture coherence
+       ↓
+[PHASE 3: SCORING]
+├── script_scoring.py            → Calculate weighted scores
+└── Compare to thresholds
+       ↓
+Result: Structured report with deterministic + semantic
+```
+
+---
+
+## Proposed Scripts
+
+### 1. script_inventory.py
+
+**Operations Handled:** 30+
+
+```python
+# Input
+squad_path: str  # "squads/{squad-name}/"
+
+# Output
+{
+  "exists": true,
+  "components": {
+    "agents": {"count": 22, "files": ["{agent-name}.md", ...]},
+    "tasks": {"count": 58, "files": [...]},
+    "workflows": {"count": 3, "files": [...]},
+    "templates": {"count": 10, "files": [...]},
+    "checklists": {"count": 5, "files": [...]},
+    "data": {"count": 2, "files": [...]}
+  },
+  "required_files": {
+    "config.yaml": true,
+    "README.md": true,
+    "CHANGELOG.md": false
+  }
+}
+```
+
+**What it does:**
+- `os.path.exists()` for directory checks
+- `glob.glob()` for file counting
+- `pathlib` for path operations
+
+### 2. script_yaml_validator.py
+
+**Operations Handled:** 25+
+
+```python
+# Input
+file_path: str  # "squads/{squad-name}/agents/{agent-name}.md"
+expected_keys: list  # ["agent", "persona", "commands", "voice_dna"]
+
+# Output
+{
+  "valid_syntax": true,
+  "parse_errors": [],
+  "missing_keys": ["voice_dna.emotional_states"],
+  "present_keys": ["agent", "persona", "commands", "voice_dna.vocabulary"],
+  "nested_counts": {
+    "voice_dna.vocabulary.always_use": 8,
+    "voice_dna.vocabulary.never_use": 6,
+    "output_examples": 3,
+    "objection_algorithms": 4,
+    "anti_patterns.never_do": 13
+  }
+}
+```
+
+**What it does:**
+- `yaml.safe_load()` for parsing
+- Recursive key checking
+- Array length counting
+
+### 3. script_dependency_check.py
+
+**Operations Handled:** 20+
+
+```python
+# Input
+agent_file: str  # "squads/{squad-name}/agents/{agent-name}.md"
+
+# Output
+{
+  "references": {
+    "tasks": ["create-sales-page.md", "write-headlines.md"],
+    "templates": ["sales-page-tmpl.yaml"],
+    "checklists": ["copy-quality.md"],
+    "data": ["copywriting-kb.md"]
+  },
+  "resolved": {
+    "tasks/create-sales-page.md": true,
+    "tasks/write-headlines.md": true,
+    "templates/sales-page-tmpl.yaml": false,  # MISSING
+    "checklists/copy-quality.md": true,
+    "data/copywriting-kb.md": true
+  },
+  "broken_references": ["templates/sales-page-tmpl.yaml"],
+  "orphan_files": ["tasks/unused-task.md"]
+}
+```
+
+**What it does:**
+- Parse YAML `dependencies` block
+- Check each referenced file exists
+- Scan for files not referenced by any agent
+
+### 4. script_naming_validator.py
+
+**Operations Handled:** 8+
+
+```python
+# Input
+squad_path: str
+
+# Output
+{
+  "config_name_matches_folder": true,
+  "slash_prefix_valid": true,  # camelCase
+  "file_naming": {
+    "agents": {"valid": ["{agent-name}.md"], "invalid": []},
+    "tasks": {"valid": [...], "invalid": ["Create_Sales_Page.md"]}  # Wrong case
+  },
+  "violations": [
+    {"file": "tasks/Create_Sales_Page.md", "issue": "Must be kebab-case"}
+  ]
+}
+```
+
+**What it does:**
+- Regex patterns: `^[a-z0-9]+(-[a-z0-9]+)*\.md$` for kebab-case
+- Regex patterns: `^[a-z][a-zA-Z0-9]*$` for camelCase
+- String comparison for config name vs folder
+
+### 5. script_quality_gate.py
+
+**Operations Handled:** 15+
+
+```python
+# Input
+agent_file: str
+thresholds: dict  # {"min_lines": 300, "min_examples": 3, ...}
+
+# Output
+{
+  "file": "agents/{agent-name}.md",
+  "metrics": {
+    "lines": 450,
+    "vocabulary_always_use": 8,
+    "vocabulary_never_use": 6,
+    "output_examples": 3,
+    "objection_algorithms": 4,
+    "anti_patterns_never_do": 13,
+    "anti_patterns_always_do": 9
+  },
+  "gates": {
+    "lines_check": {"threshold": 300, "value": 450, "pass": true},
+    "examples_check": {"threshold": 3, "value": 3, "pass": true},
+    "vocabulary_check": {"threshold": 5, "value": 8, "pass": true}
+  },
+  "blocking_issues": [],
+  "warnings": []
+}
+```
+
+**What it does:**
+- Count lines: `len(file.readlines())`
+- Count YAML array items
+- Compare against thresholds
+
+### 6. script_scoring.py
+
+**Operations Handled:** 10+
+
+```python
+# Input
+dimension_scores: dict  # From LLM
+{
+  "template_conformance": 9,
+  "principle_adherence": 8,
+  "internal_consistency": 9,
+  "integration_quality": 10,
+  "practical_utility": 9
+}
+weights: dict
+{
+  "template_conformance": 0.25,
+  "principle_adherence": 0.25,
+  "internal_consistency": 0.20,
+  "integration_quality": 0.15,
+  "practical_utility": 0.15
+}
+
+# Output
+{
+  "dimension_scores": {...},
+  "weighted_scores": {
+    "template_conformance": 2.25,  # 9 * 0.25
+    "principle_adherence": 2.00,
+    ...
+  },
+  "total_score": 8.95,
+  "interpretation": "Good - Ready for production",
+  "pass": true,
+  "threshold": 7.0
+}
+```
+
+**What it does:**
+- Multiply scores by weights
+- Sum weighted scores
+- Compare to thresholds
+- Return interpretation
+
+### 7. script_registry_manager.py
+
+**Operations Handled:** 5+
+
+```python
+# Input
+query: str  # "copywriting"
+registry_path: str  # "data/squad-registry.yaml"
+
+# Output
+{
+  "query": "copywriting",
+  "matches": [
+    {
+      "squad": "copy",
+      "domain": "copywriting",
+      "match_type": "domain_index",
+      "confidence": "exact"
+    }
+  ],
+  "related": [
+    {"squad": "creator-os", "reason": "content creation"}
+  ]
+}
+```
+
+**What it does:**
+- Parse squad-registry.yaml
+- Search domain_index
+- Search keywords arrays
+- Return matches with confidence
+
+---
+
+## Operation Classification Summary
+
+### DETERMINISTIC (107 operations)
+
+| Category | Count | Script |
+|----------|-------|--------|
+| File/directory existence | 30 | script_inventory.py |
+| YAML structure validation | 25 | script_yaml_validator.py |
+| Reference/dependency checks | 20 | script_dependency_check.py |
+| Naming convention validation | 8 | script_naming_validator.py |
+| Threshold comparisons | 15 | script_quality_gate.py |
+| Score calculation | 10 | script_scoring.py |
+
+### LLM-REQUIRED (38 operations)
+
+| Category | Count | Why LLM Needed |
+|----------|-------|----------------|
+| Content quality judgment | 12 | Semantic understanding |
+| Voice/persona consistency | 6 | Style analysis |
+| Example realism assessment | 5 | Domain knowledge |
+| Architecture design | 5 | Creative judgment |
+| Domain viability | 4 | Business judgment |
+| Gap analysis | 3 | Problem identification |
+| Tier classification | 3 | Expert judgment |
+
+---
+
+## Implementation Plan
+
+### Phase 1: Core Scripts (Week 1)
+
+1. **script_inventory.py** - Already created as `refresh-registry.py`
+2. **script_yaml_validator.py** - New
+3. **script_quality_gate.py** - New
+
+### Phase 2: Dependency & Naming (Week 2)
+
+4. **script_dependency_check.py** - New
+5. **script_naming_validator.py** - New
+
+### Phase 3: Scoring & Registry (Week 3)
+
+6. **script_scoring.py** - New
+7. **script_registry_manager.py** - Extend refresh-registry.py
+
+### Phase 4: Integration (Week 4)
+
+8. **script_orchestrator.py** - Chains all scripts
+9. Update tasks to use scripts
+10. Update agent to call scripts first
+
+---
+
+## Interface Between Scripts and LLM
+
+### Script Output → LLM Input
+
+```yaml
+# Scripts produce structured data
+deterministic_results:
+  inventory:
+    agents: 22
+    tasks: 58
+  structure_validation:
+    valid: true
+    missing_keys: []
+  dependency_check:
+    broken_references: []
+  quality_gates:
+    all_pass: true
+
+# LLM receives this context
+llm_prompt: |
+  The following structural checks have PASSED:
+  - 22 agents, 58 tasks found
+  - All YAML syntax valid
+  - All dependencies resolved
+  - All naming conventions followed
+
+  Now evaluate SEMANTIC quality:
+  1. Are the examples realistic?
+  2. Is the voice consistent?
+  3. Are anti-patterns domain-specific?
+```
+
+### LLM Output → Script Input
+
+```yaml
+# LLM produces dimension scores
+llm_output:
+  dimension_scores:
+    template_conformance: 9
+    principle_adherence: 8
+    internal_consistency: 9
+    integration_quality: 10
+    practical_utility: 9
+
+# Script calculates final score
+script_scoring.py:
+  input: llm_output.dimension_scores
+  output:
+    total_score: 8.95
+    interpretation: "Good"
+    pass: true
+```
+
+---
+
+## Benefits
+
+| Metric | Before | After |
+|--------|--------|-------|
+| Validation time | ~30s (all LLM) | ~5s (scripts) + ~10s (LLM) |
+| Token cost | High (counting files) | Low (only semantic) |
+| Reliability | Variable | Deterministic base |
+| Error messages | Generic | Precise (line numbers) |
+| Caching | None | Script results cached |
+
+---
+
+## Risks & Mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| Script bugs give wrong results | Comprehensive unit tests |
+| Scripts and LLM disagree | LLM can override with justification |
+| Maintenance burden | Single source of truth (scripts), clear interfaces |
+| Over-engineering | Start with 3 core scripts, expand as needed |
+
+---
+
+## Next Steps
+
+1. **Review this RFC** - Get feedback on approach
+2. **Prototype 3 core scripts** - inventory, yaml_validator, quality_gate
+3. **Test on squad-creator itself** - Validate approach works
+4. **Integrate with tasks** - Update validate-squad.md to use scripts
+5. **Document interfaces** - Clear contracts between scripts and LLM
+
+---
+
+## Appendix: Full Operation List
+
+See analysis output for complete list of 145 operations with classifications.
+
+---
+
+_RFC-001 Version: 1.0_
+_Status: Awaiting Review_