@jaimevalasek/aioson 1.3.0 → 1.4.0

package/template/.aioson/tasks/squad-execution-plan.md

@@ -0,0 +1,279 @@
+# Task: Squad Execution Plan
+
+> Gera o plano de execução do squad após criação e validação.
+> Define como os executors vão atacar o objetivo em sequência.
+> Garante consistência entre executors, workflows, e checklists.
+
+## Quando usar
+- Automaticamente após `@squad create` + `@squad validate` + warm-up (para squads qualificados)
+- `@squad plan <slug>` — invocação direta
+- Antes da primeira session produtiva do squad
+- Quando o squad muda (novos executors, nova investigation, workflow redesign)
+
+## Entrada
+- Squad manifest (`squad.manifest.json`)
+- Blueprint (`.designs/{slug}.blueprint.json`)
+- Investigation report (se existir em `squad-searches/`)
+- Workflow definition (se existir em `workflows/`)
+- Quality checklists (se existirem em `checklists/`)
+- Loaded rules de `.aioson/rules/squad/`
+- Loaded skills de `.aioson/skills/squad/`
+- Learnings anteriores (se `learnings/index.md` existir)
+
+## Processo
+
+### Passo 1 — Re-análise cruzada
+
+Ler o manifest completo e verificar consistência:
+
+**Coverage analysis — cada executor:**
+- O role cobre algo ÚNICO que nenhum outro executor cobre?
+- Existe gap no coverage? (aspecto do goal que ninguém cobre)
+- Existe overlap? (dois executors fazem a mesma coisa)
+- As skills declaradas existem e são relevantes para o role?
+
+**Workflow analysis — se workflow existe:**
+- Cada phase tem executor atribuído que existe no manifest?
+- O output de cada phase é o input esperado da próxima?
+- Existem handoffs sem transformação clara?
+- Human gates estão posicionados em pontos de risco real?
+- Review loops (se configurados) apontam para phases que existem?
+
+**Checklist analysis:**
+- Os critérios do checklist cobrem os aspectos críticos do domínio?
+- Existem critérios genéricos demais? (substituir por específicos)
+- Existe critério que nenhum executor pode avaliar? (gap de competência)
+
+**Investigation analysis — se investigation report existe:**
+- Os anti-patterns descobertos estão refletidos como hard constraints nos executors?
+- O vocabulário de domínio foi injetado nos executors relevantes?
+- Os frameworks descobertos estão sendo usados na estrutura do squad?
+- Os benchmarks de qualidade estão no checklist?
+
+Para cada issue, classificar:
+- **ADJUST** — corrigir antes de executar (ex: executor sem coverage)
+- **WARN** — sinalizar mas pode prosseguir (ex: overlap parcial intencional)
+- **INFO** — anotar para consciência do orquestrador (ex: dimension não coberta pela investigation)
+
+### Passo 2 — Sequência de ativação
+
+Definir a ordem ideal de rounds para atingir o goal do squad.
+
+**Se o squad tem workflow definido:**
+- Usar as phases do workflow como base
+- Mapear cada phase para um round no execution plan
+- Adicionar rounds de review/synthesis entre phases críticas
+- Respeitar o execution mode (sequential/parallel/mixed)
+
+**Se o squad NÃO tem workflow:**
+- Derivar a sequência do manifest + domain knowledge
+- Heurística padrão:
+
+```
+1. Research / Analysis (executors com focus em pesquisa)
+2. Creation / Production (executors com focus em criação)
+3. Review / Quality (executors com focus em revisão)
+4. Synthesis / Delivery (@orquestrador)
+```
+
+**Para cada round, definir:**
+
+```markdown
+### Round {N} — {título descritivo}
+- **Executor:** @{slug} ({type})
+- **Objective:** {o que este executor vai produzir neste round}
+- **Input:** {o que precisa receber — de quem, qual artefato}
+- **Output esperado:** {artefato concreto que será produzido}
+- **Quality gate:** {critério de aceitação deste round}
+- **Anti-patterns a evitar:** {do investigation report, se disponível}
+- **Handoff:** output → Round {N+1} input
+- **Parallel:** {true | false — se pode rodar junto com outro round}
+```
+
+**Rounds especiais:**
+- `Round 0 — Context Loading` (implícito, não um round real): o orquestrador carrega learnings e context
+- `Round N — Synthesis` (sempre o último): @orquestrador sintetiza todos os outputs em deliverable final
+- `Review Round` (após rounds críticos): se review loop está configurado, inserir round de review
+
+### Passo 3 — Context per executor
+
+Para cada executor no plan, definir o "briefing package":
+
+```markdown
+## Briefing: @{executor-slug}
+
+### Deve ler antes de começar
+- Seu agent file (`.aioson/squads/{slug}/agents/{executor}.md`)
+- Output do round anterior (se houver)
+- {artefato específico relevante para este executor}
+
+### Contexto injetado pelo orquestrador
+- Goal do squad: {1 frase}
+- Seu objetivo neste round: {1 frase}
+- Anti-patterns a evitar: {lista curta}
+- Vocabulário de domínio: {termos-chave, se da investigation}
+
+### O que NÃO precisa ler
+- {artefatos de outros executors que não são input deste round}
+- {investigation completa — só os excerpts relevantes}
+```
+
+### Passo 4 — Success criteria
+
+Definir como saber que o squad cumpriu o objective:
+
+```markdown
+## Success Criteria
+
+### Output final esperado
+- {descrição concreta do deliverable — não "conteúdo de qualidade" mas "3 scripts de vídeo com hook, body, e CTA"}
+
+### Quality gates que devem passar
+- {checklist item 1 — do quality.md}
+- {checklist item 2}
+- {item do investigation report, se aplicável}
+
+### Definition of done
+- [ ] Todos os rounds completados
+- [ ] Output final salvo em `output/{squad-slug}/`
+- [ ] Session HTML gerado em `output/{squad-slug}/{session-id}.html`
+- [ ] Nenhum review loop pendente (se configurados)
+- [ ] Checklists validados
+```
+
+### Passo 5 — Orchestration notes
+
+Instruções específicas para o @orquestrador:
+
+```markdown
+## Orchestration Notes
+
+### Session management
+- {como o orquestrador deve abrir a session}
+- {quando escalar para o usuário vs. decidir autonomamente}
+- {como lidar com review loops se configurados}
+
+### Round transitions
+- Após cada round, verificar o quality gate ANTES de passar ao próximo
+- Se quality gate falha: {retry strategy — do review loop config ou default}
+- Se executor pede ajuda de outro: {routing rules}
+
+### Escalation policy
+- Se um executor não consegue produzir output: escalar ao usuário
+- Se dois executors conflitam: sintetizar a tensão e perguntar ao usuário
+- Se o quality gate falha após max retries: {strategy}
+
+### Learning capture
+- Ao final da session, detectar learnings (ver squad-learning)
+- Registrar em `learnings/` antes de fechar a session
+```
+
+### Passo 6 — Gerar execution-plan.md
+
+Salvar em `.aioson/squads/{slug}/docs/execution-plan.md`:
+
+```markdown
+---
+squad: "{squad-slug}"
+created: "{ISO-8601}"
+status: "draft"
+based_on_blueprint: "{blueprint path}"
+based_on_investigation: "{investigation path ou null}"
+rounds_total: {N}
+source_artifacts:
+  - squad.manifest.json
+  - {blueprint path}
+  - {investigation path}
+---
+
+# Execution Plan: {squad-name}
+
+> Plano de como o squad vai atacar o objetivo.
+> Gerado após criação, aprovado antes da primeira session.
+> Status: draft → approved → in_progress → completed
+
+## Pre-flight check
+
+### Artefatos consolidados
+{inventory do Passo 1}
+
+### Consistency check
+{issues encontrados, classificados como ADJUST/WARN/INFO}
+
+### Squad readiness verdict
+{READY | NEEDS_ADJUSTMENT | NOT_READY}
+
+## Execution Strategy
+
+### Sequência de rounds
+{Rounds do Passo 2}
+
+## Executor Briefings
+{Briefings do Passo 3}
+
+## Success Criteria
+{Critérios do Passo 4}
+
+## Orchestration Notes
+{Notas do Passo 5}
+
+## Context Package (para session ou novo chat)
+
+### O que o @orquestrador deve ler no início de cada session
+1. Este execution-plan.md
+2. squad.manifest.json
+3. Último session HTML (se não é a primeira session)
+4. learnings/index.md (se existe)
+
+### O que cada executor recebe
+- Seu agent file + briefing deste plan
+- Output do round anterior (se houver)
+```
+
+### Passo 7 — Apresentar ao usuário
+
+```
+Execution Plan gerado para squad {name}.
+
+Rounds: {N} ({M paralelos se houver)
+Consistency: {N adjusts, M warns, P infos}
+Readiness: {READY | NEEDS_ADJUSTMENT | NOT_READY}
+
+Sequência:
+1. {round 1 — executor — 1 linha}
+2. {round 2 — executor — 1 linha}
+[...]
+
+Success criteria: {1 linha do deliverable final esperado}
+```
+
+Perguntar:
+> "Plano de execução pronto. Quer ajustar algo antes de iniciar a primeira session?"
+
+Se NEEDS_ADJUSTMENT:
+> "Encontrei {N} ajustes necessários. Quer que eu corrija antes de aprovar o plan?"
+
+## Quando gerar automaticamente (decision tree para squad.md)
+
+```
+Squad criado e validado
+  ├── 4+ executors? → GERAR automaticamente
+  ├── Workflow definido? → GERAR automaticamente
+  ├── Investigation @orache foi feita? → GERAR automaticamente
+  ├── Mode = software ou mixed? → GERAR automaticamente
+  ├── 3 executors + goal simples? → OFERECER (não obrigar)
+  ├── Ephemeral squad? → PULAR
+  └── 2 executors + flow óbvio? → PULAR
+```
+
+## Regras
+
+- NÃO execute nenhum round aqui — SÓ planeje
+- NÃO ignore issues ADJUST — sinalize e ofereça correção
+- NÃO gere rounds vagos como "produzir conteúdo" — detalhe O QUE, COMO, e COM QUAIS inputs
+- O execution plan é PERSISTENTE — salvar em arquivo, não só no chat
+- Se investigation existe, DEVE ser usada para enriquecer o plan
+- Se learnings existem, DEVEM informar a sequência de rounds
+- Rounds review são OPCIONAIS se não há review loop configurado, mas RECOMENDADOS para squads com 4+ executors
+- Após aprovação do usuário, mudar status de `draft` para `approved`
+- Se o squad é editado depois do plan ser aprovado, marcar plan como `stale`

package/template/.aioson/tasks/squad-export.md

@@ -11,7 +11,7 @@
 2. Se inválido: abortar com sugestão de correção
 3. Coletar todos os arquivos do pacote:
    - .aioson/squads/<slug>/ (tudo)
-   - NÃO incluir: output/, aios-logs/, media/ (são dados de sessão)
+   - NÃO incluir: output/, aioson-logs/, media/ (são dados de sessão)
 4. Gerar archive: `.aioson/squads/exports/<slug>.aios-squad.tar.gz`
 5. Incluir um `import-instructions.md` no archive
 

package/template/.aioson/tasks/squad-investigate.md

@@ -0,0 +1,44 @@
+# Task: Squad Investigate
+
+> Fase de investigação do lifecycle. Enriquece o design com conhecimento real do domínio.
+
+## Quando usar
+- `@squad investigate <domain>` — investigação standalone
+- `@squad` flow quando o usuário aceita investigação
+- `@squad design --investigate` — dispara investigação antes do design
+
+## Entrada
+- Domínio ou tópico
+- Goal do squad
+- Output type esperado
+- Opcional: dimensions específicas para focar
+
+## Processo
+
+### Passo 1 — Ativar @orache
+Leia `.aioson/agents/orache.md` e execute como @orache.
+Passe o contexto do domínio coletado pelo @squad.
+
+### Passo 2 — Aguardar investigação
+@orache executa o processo de investigação (Steps 1-6 do agent).
+
+### Passo 3 — Receber relatório
+@orache salva o relatório em `squad-searches/`.
+
+### Passo 4 — Validar completude
+Verifique que o relatório cobre pelo menos 4 das 7 dimensões.
+Se não cobrir, pergunte ao usuário se quer aprofundar.
+
+### Passo 5 — Integrar com design
+Se esta task foi invocada do flow do @squad:
+- Retorne o path do relatório para o @squad
+- O @squad usa o relatório para enriquecer o blueprint
+
+## Saída
+- Relatório de investigação salvo em `squad-searches/`
+- Path do relatório disponível para o @squad design
+
+## Regras
+- NÃO gere o squad aqui — isso é responsabilidade da task create
+- NÃO fabrique descobertas — se não encontrou, diga
+- SEMPRE salve o relatório em arquivo — nunca apenas no chat

package/template/.aioson/tasks/squad-learning-review.md

@@ -0,0 +1,44 @@
+# Task: Squad Learning Review
+
+> Periodic review of accumulated squad learnings.
+
+## When to use
+- `@squad learning review <slug>` — manual review
+- Automatically when learnings > 15 (consolidation needed)
+- Periodically suggested by @orquestrador after 10+ sessions
+
+## Process
+
+### Step 1 — Inventory
+List all active learnings in `learnings/index.md`.
+
+### Step 2 — Consolidation
+Identify redundant learnings and consolidate:
+- Two learnings saying the same thing → merge into one with combined evidence
+- Keep reference to originals in the consolidated learning
+
+### Step 3 — Promotion
+Identify candidates for promotion (rules or skills):
+- Quality learnings with frequency >= 3 → candidate for rule
+- Domain learnings totaling >= 7 for same domain → candidate for domain skill
+- Process learnings confirmed across 3+ sessions → candidate for rule
+
+### Step 4 — Archive
+Move stale learnings to `learnings/archive/`:
+- Learnings not reinforced in 90+ days
+- Learnings contradicted by newer learnings
+- Learnings that were promoted (keep original as historical record)
+
+### Step 5 — Report
+Present summary:
+- Learnings active: N
+- Consolidated: M
+- Promoted: P
+- Archived: A
+
+## CLI support
+- `aioson squad:learning list <slug>` — list active learnings
+- `aioson squad:learning stats <slug>` — statistics by type and status
+- `aioson squad:learning archive <slug>` — archive stale learnings
+- `aioson squad:learning promote <slug> <id>` — promote learning to rule
+- `aioson squad:learning export <slug>` — export learnings as JSON

package/template/.aioson/tasks/squad-output-config.md

@@ -0,0 +1,177 @@
+# Task: Squad Output Configuration
+
+> Loaded on-demand by `@squad` when configuring output strategy.
+> Trigger: `@squad --config=output --squad={slug}` or auto-detected during creation.
+
+## Purpose
+
+Guide the user through configuring how the squad stores, routes, and delivers its outputs.
+Write the result into `outputStrategy` in `squad.manifest.json`.
+
+## Domain heuristics — auto-suggest the right mode
+
+Before asking questions, infer the best strategy from the squad domain:
+
+| Domain pattern | Suggested mode | Reasoning |
+|---------------|---------------|-----------|
+| Landing page, site, HTML standalone, presentation | `files` | Output IS the file |
+| Copy for ads, social media, product descriptions | `sqlite` | Recurring data, dashboard + webhook |
+| YouTube creator, editorial (scripts + thumbnails) | `hybrid` | Mix of structured data + media |
+| Report/PDF generator | `files` + worker | Worker generates file |
+| Blog, newsletter, editorial content | `hybrid` | Data in DB + HTML preview |
+| Research, analysis, strategy | `files` | Document-oriented, not recurring |
+| Data pipeline, ETL, structured extraction | `sqlite` | Structured data, API/webhook consumption |
+| Image/video/media generation | `hybrid` | Media files + DB references |
+
+## Configuration wizard
+
+Present the inferred suggestion and ask for confirmation:
+
+> "Based on the domain **{domain}**, I suggest:
+>
+> **Output mode: {mode}**
+> - {brief explanation of what this means}
+>
+> Does this fit your workflow, or do you want to adjust?"
+
+If the user wants to adjust, walk through these questions:
+
+### Q1 — Output destination
+> "Where should the squad outputs go?"
+> - **Files only** — physical files in `output/{slug}/` (HTML, MD, etc.)
+> - **Database only** — structured records in SQLite, viewable in dashboard
+> - **Both** — files for preview + database for management and delivery
+
+### Q2 — Delivery (only if `sqlite` or `hybrid`)
+> "Should finished content be delivered somewhere automatically?"
+> - **No** — just store in database, publish manually from dashboard
+> - **Cloud** — publish to aioson.com when I click publish
+> - **Webhook** — POST to an external URL (website, CMS, API)
+> - **Both** — cloud + webhook
+
+### Q3 — Webhook config (only if webhook selected)
+> "Configure the webhook:"
+> - **URL**: the endpoint to POST to (or use `{{ENV:WEBHOOK_URL}}` for env variable)
+> - **Auth**: Bearer token? (or use `{{ENV:WEBHOOK_TOKEN}}`)
+> - **Trigger**: on-publish (manual) or on-create (automatic)?
+
+### Q4 — Auto-publish (only if webhook or cloud selected)
+> "Should content be published automatically after creation?"
+> - **No** — I'll review and publish manually from dashboard
+> - **Yes** — publish automatically when the agent finishes
+
+## Output — write to manifest
+
+After collecting answers, write `outputStrategy` to `squad.manifest.json`:
+
+```json
+{
+  "outputStrategy": {
+    "mode": "{files|sqlite|hybrid}",
+    "fileOutput": {
+      "enabled": true,
+      "dir": "output/{squad-slug}/",
+      "formats": ["html", "md"]
+    },
+    "dataOutput": {
+      "enabled": true,
+      "storage": "sqlite",
+      "table": "content_items",
+      "contentItems": true
+    },
+    "delivery": {
+      "webhooks": [
+        {
+          "slug": "{webhook-slug}",
+          "url": "{{ENV:WEBHOOK_URL}}",
+          "trigger": "on-publish",
+          "format": "json",
+          "headers": {
+            "Authorization": "Bearer {{ENV:WEBHOOK_TOKEN}}"
+          },
+          "worker": ".aioson/squads/{squad-slug}/workers/webhook-post.py"
+        }
+      ],
+      "cloudPublish": false,
+      "autoPublish": false
+    }
+  }
+}
+```
+
+## Delivery worker generation
+
+If webhook is configured, generate a delivery worker at `.aioson/squads/{squad-slug}/workers/webhook-post.py`:
+
+```python
+#!/usr/bin/env python3
+"""Delivery worker: POST content items to configured webhook."""
+import json, sys, os, urllib.request, urllib.error
+
+def main():
+    if len(sys.argv) > 1:
+        with open(sys.argv[1], 'r') as f:
+            payload = json.load(f)
+    else:
+        payload = json.load(sys.stdin)
+
+    url = os.environ.get('WEBHOOK_URL')
+    token = os.environ.get('WEBHOOK_TOKEN', '')
+
+    if not url:
+        print('ERROR: WEBHOOK_URL not set', file=sys.stderr)
+        sys.exit(1)
+
+    headers = {'Content-Type': 'application/json'}
+    if token:
+        headers['Authorization'] = f'Bearer {token}'
+
+    data = json.dumps(payload).encode('utf-8')
+    req = urllib.request.Request(url, data=data, headers=headers, method='POST')
+
+    try:
+        with urllib.request.urlopen(req) as resp:
+            print(f'OK: {resp.status} {resp.reason}')
+    except urllib.error.HTTPError as e:
+        print(f'ERROR: {e.code} {e.reason}', file=sys.stderr)
+        sys.exit(1)
+
+if __name__ == '__main__':
+    main()
+```
+
+Register the worker in the manifest:
+```json
+{
+  "slug": "webhook-post",
+  "title": "Webhook Delivery",
+  "type": "worker",
+  "role": "POST content to configured webhook endpoint",
+  "entrypoint": ".aioson/squads/{squad-slug}/workers/webhook-post.py",
+  "runtime": "python",
+  "deterministic": true,
+  "usesLLM": false
+}
+```
+
+## Compatibility with storagePolicy
+
+If the squad already has `storagePolicy` but no `outputStrategy`:
+- `primary: "sqlite"` → infer `mode: "hybrid"` (preserve existing behavior)
+- `exports.html: true` → `fileOutput.formats` includes `"html"`
+- Do NOT remove `storagePolicy` — keep both for backward compatibility
+
+## After configuration
+
+Show summary:
+```
+Output strategy configured for **{squad-name}**:
+- Mode: {mode}
+- Files: {enabled/disabled} → {dir}
+- Database: {enabled/disabled} → {table}
+- Delivery: {none | cloud | webhook | cloud+webhook}
+- Auto-publish: {yes/no}
+
+{if webhook: Delivery worker created at `.aioson/squads/{slug}/workers/webhook-post.py`}
+{Reminder: Set WEBHOOK_URL and WEBHOOK_TOKEN in your environment if using {{ENV:}} placeholders.}
+```

package/template/.aioson/tasks/squad-validate.md

@@ -24,7 +24,7 @@ Verifique que existem:
 - `.aioson/squads/<slug>/agents/agents.md` (obrigatório)
 - `.aioson/squads/<slug>/agents/orquestrador.md` (obrigatório)
 - Para cada executor em manifest.executors: o arquivo referenciado existe
-- Diretórios: `output/<slug>/`, `aios-logs/<slug>/`
+- Diretórios: `output/<slug>/`, `aioson-logs/<slug>/`
 
 ### Camada 3 — Validação semântica (básica nesta fase, aprofundada na Fase 2)
 - Slug do manifesto bate com o nome do diretório

package/template/.claude/commands/aioson/agent/deyvin.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Pair programming partner (alias: pair)"
+---
+
+Read `.aioson/agents/deyvin.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/discovery-design-doc.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Discovery and design doc generation"
+---
+
+Read `.aioson/agents/discovery-design-doc.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/genome.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Domain genome creation and application"
+---
+
+Read `.aioson/agents/genome.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/product.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Product vision, PRD and feature scoping"
+---
+
+Read `.aioson/agents/product.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/profiler-enricher.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Clone profiler: enrichment phase"
+---
+
+Read `.aioson/agents/profiler-enricher.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/profiler-forge.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Clone profiler: forge and validate"
+---
+
+Read `.aioson/agents/profiler-forge.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/profiler-researcher.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Clone profiler: research phase"
+---
+
+Read `.aioson/agents/profiler-researcher.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/squad.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Squad assembly and management"
+---
+
+Read `.aioson/agents/squad.md` and follow all instructions. $ARGUMENTS

package/template/.gemini/GEMINI.md

@@ -8,3 +8,5 @@
 ## Commands
 Use command files in `.gemini/commands/` that point to the same agents in `.aioson/agents/`.
 - Include `aios-ux-ui` for frontend design specification when UI quality is critical.
+- Include `aios-deyvin` when you want to continue recent work, inspect what changed, or implement a small slice together.
+- `aios-pair` remains as a compatibility alias.

package/template/.gemini/commands/aios-deyvin.toml

@@ -0,0 +1,6 @@
+name = "aios-deyvin"
+description = "Continuity pair programming"
+instruction_file = ".aioson/agents/deyvin.md"
+requires_context = [
+  ".aioson/context/project.context.md"
+]

package/template/.gemini/commands/aios-pair.toml

@@ -0,0 +1,6 @@
+name = "aios-pair"
+description = "Compatibility alias for aios-deyvin"
+instruction_file = ".aioson/agents/deyvin.md"
+requires_context = [
+  ".aioson/context/project.context.md"
+]