aiox-core 5.0.2 → 5.0.3

package/pro/squads/squad-creator-pro/tasks/create-documentation.md

@@ -0,0 +1,258 @@
+---
+task: Create Documentation
+task_id: PV_DOC_001
+responsavel: "@pedro-valerio"
+responsavel_type: agent
+atomic_layer: task
+phase: operationalization
+
+trigger:
+  automatic:
+    - after: create-agent
+    - after: create-workflow
+    - after: create-squad
+  manual: "*create-doc {artefato}"
+
+templates:
+  - agent-flow-doc-tmpl      # SC-DP-001
+  - workflow-doc-tmpl        # SC-DP-002
+  - squad-readme-tmpl        # SC-DP-003
+
+patterns:
+  - SC-DP-001: Agent Flow Documentation
+  - SC-DP-002: Workflow Documentation
+  - SC-DP-003: Squad README
+
+rationale: |
+  Documentação é OPERACIONALIZAÇÃO, não extração.
+  Transforma conhecimento do artefato em processo documentado.
+  "Se não está documentado, não existe." — @pedro-valerio
+---
+
+# Create Documentation
+
+**Squad:** squad-creator
+**Phase:** Operationalization (Fase 3 do pipeline)
+**Agent:** @pedro-valerio
+**Pattern:** SC-DP-* (Documentation Patterns)
+
+## Purpose
+
+Criar documentação completa e padronizada para cada artefato do squad-creator.
+
+**REGRA ABSOLUTA:** Nenhum agent, workflow ou squad é considerado completo sem documentação no padrão especificado.
+
+---
+
+## Veto Conditions
+
+| Trigger | Ação |
+|---------|------|
+| Agent criado sem agent-flow doc | **VETO** - criar documentação antes de marcar done |
+| Workflow criado sem workflow doc | **VETO** - criar documentação antes de marcar done |
+| Squad criado sem README completo | **VETO** - criar README antes de marcar done |
+| Doc sem diagrama Mermaid | **VETO** - adicionar diagrama |
+| Doc sem troubleshooting | **VETO** - adicionar seção |
+
+---
+
+## Invocação
+
+### Automática
+
+Triggered automaticamente após:
+- `*create-agent` → Cria agent-flow doc
+- `*create-workflow` → Cria workflow doc
+- `*create-squad` → Cria/atualiza README
+
+### Manual
+
+```
+@pedro-valerio
+*create-doc {nome-do-artefato}
+```
+
+**Exemplos:**
+- `*create-doc hormozi-offers` → Cria agent-flow doc
+- `*create-doc wf-create-squad` → Cria workflow doc
+- `*create-doc hormozi` → Atualiza README do squad
+
+---
+
+## Roteamento por Tipo de Artefato
+
+| Artefato Criado | Tipo de Doc | Template | Destino |
+|-----------------|-------------|----------|---------|
+| Agent | Agent Flow Doc | `agent-flow-doc-tmpl.md` | `docs/guides/aios-agent-flows/{agent}-system.md` |
+| Workflow | Workflow Doc | `workflow-doc-tmpl.md` | `docs/guides/aios-workflows/{workflow}-workflow.md` |
+| Squad | README | `squad-readme-tmpl.md` | `squads/{squad}/README.md` |
+
+---
+
+## Conteúdo Obrigatório por Tipo
+
+### SC-DP-001: Agent Flow Doc
+
+| Seção | Obrigatório |
+|-------|-------------|
+| Visão geral com propósito | ✅ |
+| Lista completa de arquivos | ✅ |
+| Flowchart Mermaid do sistema | ✅ |
+| Mapeamento comando → task | ✅ |
+| Diagrama de colaboração | ✅ |
+| Best practices | ✅ |
+| Troubleshooting (3+ problemas) | ✅ |
+| Referências | ✅ |
+| Changelog | ✅ |
+
+### SC-DP-002: Workflow Doc
+
+| Seção | Obrigatório |
+|-------|-------------|
+| Visão geral com objetivo | ✅ |
+| **3 diagramas Mermaid** (flowchart, state, sequence) | ✅ |
+| Steps detalhados com inputs/outputs | ✅ |
+| Veto conditions por step | ✅ |
+| Agentes participantes com comandos | ✅ |
+| Mapa de tasks por fase | ✅ |
+| Pré-requisitos | ✅ |
+| Entradas e saídas do workflow | ✅ |
+| Pontos de decisão com diagrama | ✅ |
+| Condições de bloqueio (HALT) | ✅ |
+| Troubleshooting (3+ problemas) | ✅ |
+| Changelog | ✅ |
+
+### SC-DP-003: Squad README
+
+| Seção | Obrigatório |
+|-------|-------------|
+| Descrição clara do propósito | ✅ |
+| Tabela de agents com papéis | ✅ |
+| Estrutura de diretórios | ✅ |
+| Quick start funcional | ✅ |
+| Lista de workflows | ✅ |
+| Comandos por agent | ✅ |
+| Veto conditions | ✅ |
+| Links para docs completas | ✅ |
+
+---
+
+## Execution Flow
+
+```mermaid
+flowchart TD
+    TRIGGER["Trigger:<br/>Agent/Workflow/Squad criado"] --> DETECT{"Tipo de<br/>artefato?"}
+
+    DETECT -->|Agent| LOAD_A["Carregar template<br/>agent-flow-doc-tmpl.md"]
+    DETECT -->|Workflow| LOAD_W["Carregar template<br/>workflow-doc-tmpl.md"]
+    DETECT -->|Squad| LOAD_S["Carregar template<br/>squad-readme-tmpl.md"]
+
+    LOAD_A --> FILL_A["Preencher com dados<br/>do agent"]
+    LOAD_W --> FILL_W["Preencher com dados<br/>do workflow"]
+    LOAD_S --> FILL_S["Preencher com dados<br/>do squad"]
+
+    FILL_A --> VALIDATE{"Checklist<br/>completo?"}
+    FILL_W --> VALIDATE
+    FILL_S --> VALIDATE
+
+    VALIDATE -->|Não| FIX["Completar seções<br/>faltantes"]
+    FIX --> VALIDATE
+
+    VALIDATE -->|Sim| WRITE["Escrever doc<br/>no destino"]
+    WRITE --> UPDATE["Atualizar README<br/>do diretório"]
+    UPDATE --> DONE["✅ Documentação completa"]
+```
+
+---
+
+## Integração no Pipeline
+
+```
+AN extrai conhecimento → PV operacionaliza → PV documenta → Chief monta
+                                              ↑
+                                    Esta task (create-documentation)
+```
+
+### Posição no Fluxo
+
+| Fase | Responsável | Ação | Task |
+|------|-------------|------|------|
+| 1 | @oalanicolas | Extrai conhecimento | `extract-*.md` |
+| 2 | @pedro-valerio | Operacionaliza (SOPs, checklists) | `extract-sop.md`, etc |
+| **3** | **@pedro-valerio** | **Documenta** | **`create-documentation.md`** |
+| 4 | @squad-chief | Monta squad final | `create-squad.md` |
+
+---
+
+## Integração com Outros Tasks
+
+### Chamado Automaticamente Por
+
+| Task | Quando |
+|------|--------|
+| `create-agent.md` | Após agent criado com sucesso |
+| `create-workflow.md` | Após workflow criado com sucesso |
+| `create-squad.md` | Após squad criado com sucesso |
+| `upgrade-squad.md` | Se doc não existe ou está desatualizada |
+
+### Pode Chamar
+
+| Task | Quando |
+|------|--------|
+| `validate-squad.md` | Após criar README do squad |
+
+---
+
+## Output Schema
+
+```yaml
+documentation_output:
+  artefato:
+    name: string
+    type: agent|workflow|squad
+    version: string
+  documento:
+    pattern: SC-DP-001|SC-DP-002|SC-DP-003
+    template_used: string
+    path: string
+    sections_completed: number
+    total_sections: number
+  diagramas:
+    - type: flowchart|state|sequence
+      presente: boolean
+  validacao:
+    checklist_score: percentage
+    troubleshooting_count: number
+    mermaid_present: boolean
+  metadata:
+    generated_date: string
+    generator: "@pedro-valerio"
+    task: create-documentation
+```
+
+---
+
+## Completion Criteria
+
+| Critério | Obrigatório |
+|----------|-------------|
+| Doc criada no path correto | ✅ |
+| Template seguido 100% | ✅ |
+| Diagramas Mermaid presentes | ✅ |
+| Troubleshooting com 3+ itens | ✅ |
+| README do diretório atualizado | ✅ |
+| Checklist de qualidade 100% | ✅ |
+
+---
+
+## Templates
+
+| Pattern ID | Nome | Arquivo |
+|------------|------|---------|
+| SC-DP-001 | Agent Flow Documentation | `templates/agent-flow-doc-tmpl.md` |
+| SC-DP-002 | Workflow Documentation | `templates/workflow-doc-tmpl.md` |
+| SC-DP-003 | Squad README | `templates/squad-readme-tmpl.md` |
+
+---
+
+*Task criada por @pedro-valerio — "Se não está documentado, não existe"*

package/pro/squads/squad-creator-pro/tasks/create-pipeline.md

@@ -0,0 +1,296 @@
+# Task: Create Pipeline Scaffolding
+
+**Task ID:** create-pipeline
+**Version:** 1.0
+**Purpose:** Generate pipeline code scaffolding for a squad that needs multi-phase data processing
+**Orchestrator:** @squad-chief
+**Mode:** Guided (human checkpoints at Phase 1 and Phase 3)
+
+**References:**
+- `data/pipeline-patterns.md` → Pattern reference (consulted in Phase 1)
+- `templates/pipeline-state-tmpl.py` → State manager scaffold
+- `templates/pipeline-progress-tmpl.py` → Progress tracker scaffold
+- `templates/pipeline-runner-tmpl.py` → Phase runner scaffold
+
+---
+
+## Overview
+
+This task generates a customized pipeline code layer (`lib/`) for squads that need multi-phase data processing. **Not every squad needs this** — use the checklist in Phase 0 to determine.
+
+```
+INPUT (squad_name + phase_definitions + requirements)
+    ↓
+[PHASE 0: QUALIFICATION]
+    → Run "Does My Squad Need a Pipeline?" checklist
+    → VETO if score < 3
+    ↓
+[PHASE 1: DESIGN]
+    → Gather phase definitions (names, handlers, criticality)
+    → Determine which components needed (state/progress/runner)
+    → CHECKPOINT: Present design for approval
+    ↓
+[PHASE 2: GENERATE]
+    → Copy and customize templates
+    → Wire up phase definitions
+    → Generate __init__.py with imports
+    ↓
+[PHASE 3: VALIDATE]
+    → Run self-test (python -m lib.phase_runner)
+    → Verify state persistence works
+    → CHECKPOINT: Present generated files for review
+    ↓
+OUTPUT: squads/{squad}/lib/ with pipeline code
+```
+
+---
+
+## Phase 0: Qualification
+
+**Run this checklist before proceeding:**
+
+| # | Question | Y/N |
+|---|----------|-----|
+| 1 | Does the squad process items through 3+ sequential phases? | |
+| 2 | Does each item take > 1 minute to process? | |
+| 3 | Would it be painful to restart from scratch if interrupted? | |
+| 4 | Do you process items in batches (> 1 item)? | |
+| 5 | Do you need to track cost per item/phase? | |
+
+**Score:**
+- **3+ yes** → Proceed to Phase 1
+- **1-2 yes** → Pipeline is optional, ask user
+- **0 yes** → **VETO** — squad doesn't need pipeline, just use functions
+
+**Examples:**
+- Books squad: 5/5 → Pipeline (11 phases, hours per book, batch processing)
+- MMOS squad: 4/5 → Pipeline (8+ phases, long-running, resume needed)
+- Creator-OS: 3/5 → Pipeline (curriculum → lessons → validation)
+- Copy squad: 1/5 → No pipeline (single-shot copywriting)
+- Legal squad: 0/5 → No pipeline (request/response analysis)
+
+---
+
+## Phase 1: Design
+
+### Step 1.1: Gather Phase Definitions
+
+Ask the user or infer from existing squad code:
+
+```
+For each phase, I need:
+1. Phase number (0-indexed)
+2. Phase name (kebab-case: "url-discovery", "source-curation")
+3. Is it critical? (failure stops pipeline vs non-blocking)
+4. Timeout in seconds (default: 600)
+5. Can it be cached? (check for existing output)
+6. Brief description of what it does
+```
+
+**Format output as table:**
+
+| # | Name | Critical | Timeout | Cacheable | Description |
+|---|------|----------|---------|-----------|-------------|
+| 0 | research | Yes | 600s | Yes | Fetch external sources |
+| 1 | extract | Yes | 300s | No | Extract key content |
+| ... | | | | | |
+
+### Step 1.2: Determine Components
+
+| Component | When to Include | Default |
+|-----------|----------------|---------|
+| `pipeline_state.py` | Always if resume needed (Q3 = yes) | Include |
+| `progress.py` | Always if batch processing (Q4 = yes) | Include |
+| `phase_runner.py` | Always | Include |
+| `__init__.py` | Always | Include |
+
+### Step 1.3: CHECKPOINT
+
+Present the design:
+
+```
+Pipeline Design for: {squad_name}
+═══════════════════════════════════
+Phases: {count}
+Components: {list}
+Critical phases: {list}
+Non-critical: {list}
+Cacheable: {list}
+
+Estimated execution per item: ~{estimate}
+```
+
+**Wait for user approval before proceeding.**
+
+---
+
+## Phase 2: Generate
+
+### Step 2.1: Copy Templates
+
+For each included component:
+
+1. Read the template from `squads/squad-creator-pro/templates/`
+2. Replace customization points:
+   - `PHASE_DEFINITIONS` → User's phases
+   - `item_noun` → Squad's item type (books, minds, courses, etc.)
+   - `PANEL_TITLE` → Squad name
+   - Example handlers → Stub handlers with correct signatures
+3. Write to `squads/{squad}/lib/`
+
+### Step 2.2: Generate Phase Handlers
+
+For each phase, generate a stub handler:
+
+```python
+async def phase_{name}_handler(
+    item_id: str,
+    metadata: Dict[str, Any],
+    previous_outputs: Dict[int, str],
+    **kwargs,
+) -> PhaseResult:
+    """
+    Phase {num}: {description}
+
+    TODO: Implement this handler.
+
+    Args:
+        item_id: Unique identifier for the item being processed
+        metadata: Domain-specific metadata (e.g., title, author)
+        previous_outputs: Outputs from completed phases {num: output_str}
+
+    Returns:
+        PhaseResult with success status and output
+    """
+    raise NotImplementedError("TODO: Implement phase_{name}_handler")
+```
+
+### Step 2.3: Generate __init__.py
+
+```python
+"""
+{Squad Name} Pipeline Library
+Auto-generated by squad-creator/tasks/create-pipeline.md
+"""
+
+from .pipeline_state import PipelineStateManager, load_or_create_state
+from .progress import create_progress_tracker
+from .phase_runner import PhaseRunner, PhaseDefinition, PhaseResult, get_phase_definitions
+
+__all__ = [
+    "PipelineStateManager",
+    "load_or_create_state",
+    "create_progress_tracker",
+    "PhaseRunner",
+    "PhaseDefinition",
+    "PhaseResult",
+    "get_phase_definitions",
+]
+```
+
+### Step 2.4: File Layout
+
+After generation, the squad should have:
+
+```
+squads/{squad}/
+├── lib/
+│   ├── __init__.py              ← Exports
+│   ├── pipeline_state.py        ← From pipeline-state-tmpl.py
+│   ├── progress.py              ← From pipeline-progress-tmpl.py
+│   ├── phase_runner.py          ← From pipeline-runner-tmpl.py
+│   └── handlers/                ← Phase handler stubs (optional)
+│       ├── __init__.py
+│       └── phase_{name}.py      ← One file per phase (for complex squads)
+├── agents/
+├── tasks/
+└── ...
+```
+
+**Decision: Flat vs Handlers directory**
+- **< 5 phases**: Keep handlers inline in `phase_runner.py`
+- **5+ phases**: Create `handlers/` directory with one file per phase
+
+---
+
+## Phase 3: Validate
+
+### Step 3.1: Self-Test
+
+Run the built-in test:
+
+```bash
+cd squads/{squad}
+python -m lib.phase_runner
+```
+
+**Expected:** Test passes, shows phase execution with timing.
+
+### Step 3.2: State Persistence Test
+
+```bash
+cd squads/{squad}
+python -m lib.pipeline_state
+```
+
+**Expected:** Creates state, completes a phase, shows summary.
+
+### Step 3.3: CHECKPOINT
+
+Present generated files:
+
+```
+Generated Pipeline for: {squad_name}
+═══════════════════════════════════
+Files created:
+  ✅ lib/__init__.py
+  ✅ lib/pipeline_state.py ({n} phases configured)
+  ✅ lib/progress.py (item_noun: "{noun}")
+  ✅ lib/phase_runner.py ({n} phase stubs)
+
+Self-test: {PASS/FAIL}
+State test: {PASS/FAIL}
+
+Next steps for the developer:
+1. Implement phase handlers (marked with TODO)
+2. Wire up with your squad's CLI/entry point
+3. Test with real data
+```
+
+---
+
+## Veto Conditions
+
+| Condition | Action |
+|-----------|--------|
+| Squad scored 0 on qualification | **VETO** — don't create pipeline |
+| Phase has no clear input/output contract | **VETO** — define contracts first |
+| Squad already has lib/ with different pattern | **VETO** — audit existing code first |
+| Phases are not sequential (parallel needed) | **VETO** — this pattern is sequential only |
+
+---
+
+## Anti-Patterns to Prevent
+
+| Anti-Pattern | Why | Prevention |
+|-------------|-----|------------|
+| Copy template without customizing | Dead code, confusion | Phase 2 replaces ALL customization points |
+| Create pipeline for simple squad | Over-engineering | Phase 0 qualification with score threshold |
+| Hardcode domain terms in state manager | Can't reuse | State manager stays agnostic, domain in metadata |
+| Skip self-test | Broken code ships | Phase 3 is mandatory |
+
+---
+
+## Handoffs
+
+| When | To | What |
+|------|-----|------|
+| Need custom CLI entry point | `@dev` | `bin/run-pipeline.py` script |
+| Need database persistence (not JSON) | `@data-engineer` | DB adapter for state |
+| Need parallel phase execution | `@architect` | Different pattern needed |
+
+---
+
+_Task: create-pipeline v1.0_
+_Created: 2026-02-08_
+_Source: Pipeline patterns extracted from squads/books/lib/_