@jaimevalasek/aioson 1.3.0

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

@@ -0,0 +1,68 @@
+# Task: Squad Extend
+
+> Adiciona componentes a um squad existente sem reescrever o pacote.
+
+## Quando usar
+- `@squad extend <slug>` — modo interativo
+- `@squad extend <slug> --add executor --name <name>` — modo direto
+- Após `@squad analyze` recomendar adições
+
+## Entrada
+- slug do squad existente
+- tipo do componente: executor | skill | template | blueprint | genome | mcp
+- detalhes do componente (nome, role, etc.)
+
+## Processo
+
+### Passo 1 — Ler estado atual
+Leia squad.manifest.json e inventarie o que já existe.
+
+### Passo 2 — Se modo interativo, perguntar o que adicionar
+```
+O que deseja adicionar ao squad "<slug>"?
+1. Executor — Novo agente especialista
+2. Skill — Nova capacidade reutilizável
+3. Content Blueprint — Novo tipo de deliverable
+4. Genome — Aplicar genome existente
+5. MCP — Nova integração externa
+```
+
+### Passo 3 — Coletar detalhes do componente
+Dependendo do tipo:
+- **Executor:** slug, title, role, focus areas, skills. Gerar o arquivo .md.
+- **Skill:** slug, title, description. Criar em squads/<slug>/skills/
+- **Content Blueprint:** slug, contentType, layoutType, sections.
+- **Genome:** slug do genome, scope (squad ou executor específico).
+- **MCP:** slug, required, purpose.
+
+### Passo 4 — Mostrar diff antes de persistir
+Antes de salvar, mostre exatamente o que será alterado:
+```
+Changes to apply:
+
+  NEW FILE: .aioson/squads/<slug>/agents/<executor>.md
+  UPDATED: .aioson/squads/<slug>/squad.manifest.json
+    + executors[]: { slug: "<executor>", role: "...", file: "..." }
+  UPDATED: .aioson/squads/<slug>/agents/agents.md
+    + @<executor> — <role>
+  UPDATED: CLAUDE.md
+    + /<executor> -> .aioson/squads/<slug>/agents/<executor>.md
+  UPDATED: AGENTS.md
+    + @<executor> -> .aioson/squads/<slug>/agents/<executor>.md
+
+Proceed? [Y/n]
+```
+
+### Passo 5 — Persistir alterações
+- Criar arquivo(s) novo(s)
+- Atualizar squad.manifest.json
+- Atualizar agents.md
+- Atualizar CLAUDE.md e AGENTS.md (se executor)
+
+### Passo 6 — Validar
+Rodar mentalmente a task squad-validate para confirmar que o pacote está consistente.
+
+## Regras
+- SEMPRE mostrar diff antes de persistir
+- NUNCA deletar componentes existentes — extend é somente aditivo
+- Para remoção, oriente o usuário a editar manualmente ou usar repair (Fase 4)

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

@@ -0,0 +1,122 @@
+# Task: Squad Pipeline
+
+> Gerenciamento de pipelines inter-squad. Conecta squads em fluxos de produção autônomos via DAG.
+
+## Quando usar
+- `@squad pipeline create <nome>` — cria um novo pipeline
+- `@squad pipeline connect <pipeline> <source-squad>:<port> → <target-squad>:<port>` — conecta squads
+- `@squad pipeline show <pipeline>` — exibe o DAG com nós, arestas e status
+- `@squad pipeline run <pipeline>` — executa o pipeline (aciona handoffs)
+
+## Conceito
+
+Um **pipeline** é um grafo dirigido acíclico (DAG) de squads conectados por ports.
+Cada squad declara `ports.inputs` e `ports.outputs` no `squad.manifest.json`.
+Uma aresta conecta um output de um squad ao input de outro.
+
+Quando um squad produz um output, cria um **handoff** (tabela `squad_handoffs`) com o payload.
+O squad downstream lê os handoffs `pending` com `to_squad = seu slug` e os consome.
+
+## Pré-requisitos
+
+Antes de criar um pipeline, verifique:
+1. Os squads participantes existem em `.aioson/squads/`
+2. Cada squad tem `squad.manifest.json` com a seção `ports` declarada
+3. Os ports de input/output são compatíveis em `dataType`
+
+Se um squad não tem ports declarados, oriente o usuário a:
+- Editar `squad.manifest.json` adicionando a seção `ports`
+- Ou use `@squad extend <slug>` para adicionar ports interativamente
+
+## Passo 1 — Criar o pipeline
+
+```json
+{
+  "slug": "<pipeline-slug>",
+  "name": "<nome legível>",
+  "description": "<descrição opcional>",
+  "status": "draft",
+  "triggerMode": "manual"
+}
+```
+
+Registre via `aioson runtime` ou diretamente no SQLite (`squad_pipelines`).
+
+## Passo 2 — Adicionar nós ao pipeline
+
+Para cada squad participante, registre em `pipeline_nodes`:
+- `pipelineSlug` — slug do pipeline
+- `squadSlug` — slug do squad
+- `positionX`, `positionY` — posição no canvas visual (opcional, padrão 0,0)
+
+## Passo 3 — Conectar squads (criar arestas)
+
+Para cada conexão `source:port → target:port`, registre em `pipeline_edges`:
+- `pipelineSlug` — slug do pipeline
+- `sourceSquad`, `sourcePort` — squad origem e port de output
+- `targetSquad`, `targetPort` — squad destino e port de input
+- `transform` — transformação de dados opcional (JSON)
+
+Valide:
+- Nenhum ciclo no DAG (use ordenação topológica de Kahn)
+- Ports existem nos manifests
+- DataTypes compatíveis (ou `any`)
+
+## Passo 4 — Exibir o pipeline
+
+Ao mostrar `@squad pipeline show <pipeline>`, exiba:
+
+```
+Pipeline: <nome>
+Status: draft | active | paused
+Trigger: manual | on_output | scheduled
+
+Fluxo:
+  [squad-a] --output-key--> [squad-b] --outro-key--> [squad-c]
+
+Ordem topológica: squad-a → squad-b → squad-c
+
+Handoffs pendentes: 0
+```
+
+Se detectar ciclo: "⚠️ Ciclo detectado — pipeline inválido. Verifique as conexões."
+
+## Passo 5 — Executar o pipeline (handoff)
+
+Ao executar `@squad pipeline run <pipeline>`:
+1. Calcule a ordem topológica
+2. Para cada squad na ordem:
+   - Leia handoffs `pending` com `to_squad = squad_slug`
+   - Crie o contexto de execução com o payload dos handoffs
+   - Notifique o usuário: "Ativando @<squad> com input de @<source>"
+3. Após cada squad processar seu output:
+   - Crie handoffs `pending` para os squads downstream conectados
+   - Marque handoffs consumidos como `consumed`
+
+## Formato de handoff
+
+```json
+{
+  "id": "<uuid>",
+  "pipelineSlug": "<pipeline>",
+  "fromSquad": "<source>",
+  "fromPort": "<output-key>",
+  "toSquad": "<target>",
+  "toPort": "<input-key>",
+  "payload": { "contentKey": "...", "filePath": "..." },
+  "status": "pending"
+}
+```
+
+## Output contract
+
+- Pipeline registrado em SQLite (`squad_pipelines`, `pipeline_nodes`, `pipeline_edges`)
+- Handoffs em `squad_handoffs`
+- Relatório visual disponível em `/pipelines/<slug>` no dashboard
+
+## Hard constraints
+
+- Nunca criar um pipeline com ciclo — rejeite e explique o problema
+- Validar compatibilidade de dataType antes de conectar
+- Handoffs são imutáveis após criados — crie novos em vez de editar
+- Pipeline em status `active` não pode ter nós removidos sem voltar para `draft`

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

@@ -0,0 +1,85 @@
+# Task: Squad Repair
+
+> Reconcilia o manifesto com a estrutura real do filesystem. Corrige inconsistências.
+
+## Quando usar
+- `@squad repair <slug>` — invocação direta
+- Quando validate reporta erros de estrutura
+- Quando o usuário editou arquivos manualmente e quebrou a consistência
+
+## Processo
+
+### Passo 0 — Detecção de squad legado
+
+Se o slug existe como diretório em `.aioson/squads/<slug>/` mas NÃO tem `squad.manifest.json`:
+
+1. Ler `squad.md` (metadata textual) se existir
+2. Ler `agents/agents.md` se existir
+3. Listar arquivos em `agents/` para descobrir executores
+4. Inferir mode, mission, goal do texto encontrado
+5. Gerar `squad.manifest.json` a partir do que foi descoberto (schemaVersion: "1.0.0")
+6. Apresentar o manifesto gerado para aprovação:
+   ```
+   Squad legado detectado: "<slug>"
+   Manifesto inferido:
+     mode: content (inferido)
+     mission: "..." (inferido de squad.md)
+     executors: writer, editor (encontrados em agents/)
+     confidence: LOW — revisar antes de confirmar
+
+   Criar squad.manifest.json com estes dados? [Y/n]
+   ```
+7. Se aprovado, salvar e rodar validate
+8. Marcar readiness contextReady e blueprintReady como "partial"
+
+### Passo 1 — Detectar inconsistências
+
+Compare manifest vs filesystem:
+
+**Cenário A — Arquivo no manifesto mas não no filesystem:**
+- Executor referenciado mas arquivo não existe
+- Skill declarada mas diretório/arquivo faltando
+- Ação: oferecer REGENERAR o arquivo ou REMOVER do manifesto
+
+**Cenário B — Arquivo no filesystem mas não no manifesto:**
+- Novo executor .md em agents/ não declarado no manifesto
+- Skill instalada em skills/ não declarada
+- Ação: oferecer REGISTRAR no manifesto ou INFORMAR que é órfão
+
+**Cenário C — Dados inconsistentes:**
+- Slug do manifesto != nome do diretório
+- Executor com file path errado
+- CLAUDE.md/AGENTS.md desatualizado
+- Ação: oferecer CORRIGIR
+
+### Passo 2 — Mostrar diff completo
+
+Antes de qualquer correção, mostre exatamente o que será feito:
+```
+Repair plan for "<slug>":
+
+  FIX: Executor "analyst" — file missing → regenerate agents/analyst.md
+  FIX: Executor "ghost" — in manifest but no file → remove from manifest
+  ADD: File "agents/reviewer.md" found → register in manifest
+  FIX: CLAUDE.md — squad section outdated → update
+  SKIP: readiness.md — missing but not critical
+
+Apply repairs? [Y/n/select specific]
+```
+
+### Passo 3 — Aplicar correções selecionadas
+
+- Regenerar arquivos de executor usando o role/skills do manifesto como input (seguir Step 2 de squad-create.md)
+- Atualizar manifesto com novos arquivos encontrados
+- Corrigir paths e slugs
+- Atualizar CLAUDE.md e AGENTS.md
+
+### Passo 4 — Revalidar
+
+Ler e executar mentalmente `.aioson/tasks/squad-validate.md` após todas as correções para confirmar que o pacote está consistente.
+
+## Regras
+- NUNCA aplicar correções sem aprovação do usuário
+- SEMPRE mostrar diff antes
+- Para executores regenerados: gerar com as instruções de squad-create.md (Step 2 — Passo 5)
+- Se o squad não tem manifest formal (squad antigo): executar Passo 0 primeiro

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

@@ -0,0 +1,58 @@
+# Task: Squad Validate
+
+> Fase de validação do lifecycle. Verifica consistência do pacote.
+
+## Quando usar
+- `@squad validate <slug>` — invocação direta
+- Automaticamente após `@squad create`
+- Quando o CLI `aioson squad:validate <slug>` é executado
+
+## Entrada
+- slug do squad (deve existir em `.aioson/squads/<slug>/`)
+
+## Processo
+
+### Camada 1 — Validação de schema
+1. Leia `.aioson/squads/<slug>/squad.manifest.json`
+2. Valide contra `.aioson/schemas/squad-manifest.schema.json`
+3. Campos obrigatórios: schemaVersion, slug, name, mode, mission, goal
+4. Se falhar: ERRO com campo faltante e sugestão
+
+### Camada 2 — Validação estrutural
+Verifique que existem:
+- `.aioson/squads/<slug>/squad.manifest.json` (obrigatório)
+- `.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>/`
+
+### Camada 3 — Validação semântica (básica nesta fase, aprofundada na Fase 2)
+- Slug do manifesto bate com o nome do diretório
+- Executores no manifesto têm arquivo correspondente
+- Não há executores duplicados
+
+### Relatório
+Classifique cada check como:
+- ✅ PASS
+- ⚠️ WARNING (não bloqueia, mas recomenda correção)
+- ❌ ERROR (bloqueia — squad inválido)
+
+Formato de output:
+```
+═══ Squad Validation: <slug> ═══
+
+Schema:     ✅ PASS
+Structure:  ✅ PASS (7/7 files found)
+Semantics:  ⚠️ 1 warning
+  - executor "analyst" has no skills declared
+
+Result: VALID (1 warning)
+```
+
+## Saída
+- Relatório de validação (console)
+- Status: VALID | VALID_WITH_WARNINGS | INVALID
+
+## Regras
+- NÃO corrija problemas automaticamente — apenas reporte
+- SUGIRA o comando de correção quando possível (ex: "run @squad extend to add skills")

package/template/.aioson/templates/squads/content-basic/template.json

@@ -0,0 +1,21 @@
+{
+  "slug": "content-basic",
+  "name": "Content Basic",
+  "description": "Squad genérico de conteúdo: artigos, scripts, copy, estratégia",
+  "mode": "content",
+  "suggestedExecutors": [
+    { "slug": "writer", "role": "Creates written content, articles, scripts" },
+    { "slug": "strategist", "role": "Defines content strategy, angles, positioning" },
+    { "slug": "editor", "role": "Reviews, improves clarity, fact-checks" }
+  ],
+  "defaultContentBlueprint": {
+    "slug": "content-piece",
+    "contentType": "article",
+    "layoutType": "document",
+    "sections": [
+      { "key": "main-content", "label": "Content", "blockTypes": ["rich-text"] },
+      { "key": "summary", "label": "Summary", "blockTypes": ["rich-text"] },
+      { "key": "tags", "label": "Tags", "blockTypes": ["tags"] }
+    ]
+  }
+}

package/template/.aioson/templates/squads/media-channel/template.json

@@ -0,0 +1,24 @@
+{
+  "slug": "media-channel",
+  "name": "Media Channel",
+  "description": "Squad para canal de mídia: YouTube, podcast, newsletter, social",
+  "mode": "content",
+  "suggestedExecutors": [
+    { "slug": "scriptwriter", "role": "Writes scripts, outlines, narratives" },
+    { "slug": "title-generator", "role": "Creates titles, hooks, angles" },
+    { "slug": "copywriter", "role": "Writes descriptions, CTAs, social copy" },
+    { "slug": "trend-analyst", "role": "Researches trends, competitors, opportunities" }
+  ],
+  "defaultContentBlueprint": {
+    "slug": "media-package",
+    "contentType": "media-package",
+    "layoutType": "tabs",
+    "sections": [
+      { "key": "script", "label": "Script/Outline", "blockTypes": ["rich-text"] },
+      { "key": "titles", "label": "Title Options", "blockTypes": ["bullet-list"] },
+      { "key": "description", "label": "Description", "blockTypes": ["rich-text"] },
+      { "key": "tags", "label": "Tags & Keywords", "blockTypes": ["tags"] },
+      { "key": "thumbnail", "label": "Thumbnail Brief", "blockTypes": ["rich-text"] }
+    ]
+  }
+}

package/template/.aioson/templates/squads/research-analysis/template.json

@@ -0,0 +1,22 @@
+{
+  "slug": "research-analysis",
+  "name": "Research & Analysis",
+  "description": "Squad de pesquisa, benchmarks, relatórios e comparações",
+  "mode": "research",
+  "suggestedExecutors": [
+    { "slug": "researcher", "role": "Gathers data, finds sources, maps landscape" },
+    { "slug": "analyst", "role": "Interprets data, finds patterns, draws conclusions" },
+    { "slug": "reviewer", "role": "Validates methodology, challenges assumptions" }
+  ],
+  "defaultContentBlueprint": {
+    "slug": "research-report",
+    "contentType": "report",
+    "layoutType": "accordion",
+    "sections": [
+      { "key": "findings", "label": "Key Findings", "blockTypes": ["rich-text", "bullet-list"] },
+      { "key": "methodology", "label": "Methodology", "blockTypes": ["rich-text"] },
+      { "key": "data", "label": "Data & Sources", "blockTypes": ["bullet-list", "tags"] },
+      { "key": "recommendations", "label": "Recommendations", "blockTypes": ["numbered-list"] }
+    ]
+  }
+}

package/template/.aioson/templates/squads/software-delivery/template.json

@@ -0,0 +1,21 @@
+{
+  "slug": "software-delivery",
+  "name": "Software Delivery",
+  "description": "Squad de desenvolvimento: features, arquitetura, QA",
+  "mode": "software",
+  "suggestedExecutors": [
+    { "slug": "developer", "role": "Implements features, writes code" },
+    { "slug": "architect", "role": "Designs system structure, makes technical decisions" },
+    { "slug": "qa-engineer", "role": "Tests, validates, finds edge cases" }
+  ],
+  "defaultContentBlueprint": {
+    "slug": "feature-delivery",
+    "contentType": "feature",
+    "layoutType": "tabs",
+    "sections": [
+      { "key": "spec", "label": "Specification", "blockTypes": ["rich-text"] },
+      { "key": "implementation", "label": "Implementation", "blockTypes": ["rich-text", "copy-block"] },
+      { "key": "tests", "label": "Test Plan", "blockTypes": ["bullet-list"] }
+    ]
+  }
+}

package/template/.claude/commands/aioson/analyst.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Domain discovery and entity mapping (SMALL/MEDIUM)"
+---
+
+Read `.aioson/agents/analyst.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/architect.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Project structure and technical decisions (SMALL/MEDIUM)"
+---
+
+Read `.aioson/agents/architect.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/dev.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Feature implementation (any stack)"
+---
+
+Read `.aioson/agents/dev.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/orchestrator.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Session protocol and parallel execution (MEDIUM)"
+---
+
+Read `.aioson/agents/orchestrator.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/pm.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Backlog and user stories (MEDIUM only)"
+---
+
+Read `.aioson/agents/pm.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/qa.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Risk-first review and test generation (SMALL/MEDIUM)"
+---
+
+Read `.aioson/agents/qa.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/setup.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Project onboarding and context setup"
+---
+
+Read `.aioson/agents/setup.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/ux-ui.md

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — UI/UX design system and component spec (SMALL/MEDIUM)"
+---
+
+Read `.aioson/agents/ux-ui.md` and follow all instructions. $ARGUMENTS

package/template/.gemini/GEMINI.md

@@ -0,0 +1,10 @@
+# AIOSON - Gemini CLI
+
+## Initialization
+- Read `.aioson/config.md`
+- Check `.aioson/context/project.context.md`
+- If missing, run `aios-setup`
+
+## 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.

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

@@ -0,0 +1,4 @@
+name = "aios-analyst"
+description = "Requirements analysis"
+instruction_file = ".aioson/agents/analyst.md"
+requires_context = [".aioson/context/project.context.md"]

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

@@ -0,0 +1,7 @@
+name = "aios-architect"
+description = "Project architecture"
+instruction_file = ".aioson/agents/architect.md"
+requires_context = [
+  ".aioson/context/project.context.md",
+  ".aioson/context/discovery.md"
+]

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

@@ -0,0 +1,8 @@
+name = "aios-dev"
+description = "Development"
+instruction_file = ".aioson/agents/dev.md"
+requires_context = [
+  ".aioson/context/project.context.md",
+  ".aioson/context/discovery.md",
+  ".aioson/context/architecture.md"
+]

package/template/.gemini/commands/aios-discovery-design-doc.toml

@@ -0,0 +1,4 @@
+name = "aios-discovery-design-doc"
+description = "Discovery and living design doc"
+instruction_file = ".aioson/agents/discovery-design-doc.md"
+requires_context = [".aioson/context/project.context.md"]

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

@@ -0,0 +1,8 @@
+name = "aios-orchestrator"
+description = "Multi-agent orchestration"
+instruction_file = ".aioson/agents/orchestrator.md"
+requires_context = [
+  ".aioson/context/discovery.md",
+  ".aioson/context/architecture.md",
+  ".aioson/context/prd.md"
+]

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

@@ -0,0 +1,8 @@
+name = "aios-pm"
+description = "Lightweight PRD"
+instruction_file = ".aioson/agents/pm.md"
+requires_context = [
+  ".aioson/context/project.context.md",
+  ".aioson/context/discovery.md",
+  ".aioson/context/architecture.md"
+]

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

@@ -0,0 +1,4 @@
+name = "aios-product"
+description = "Conversational product wizard — prd.md"
+instruction_file = ".aioson/agents/product.md"
+requires_context = []

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

@@ -0,0 +1,6 @@
+name = "aios-qa"
+description = "Quality review"
+instruction_file = ".aioson/agents/qa.md"
+requires_context = [
+  ".aioson/context/discovery.md"
+]

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

@@ -0,0 +1,3 @@
+name = "aios-setup"
+description = "Project onboarding"
+instruction_file = ".aioson/agents/setup.md"

package/template/.gemini/commands/aios-ux-ui.toml

@@ -0,0 +1,8 @@
+name = "aios-ux-ui"
+description = "Frontend design and UX specification"
+instruction_file = ".aioson/agents/ux-ui.md"
+requires_context = [
+  ".aioson/context/project.context.md",
+  ".aioson/context/discovery.md",
+  ".aioson/context/architecture.md"
+]

package/template/AGENTS.md

@@ -0,0 +1,67 @@
+# AIOSON
+
+You operate as AIOSON — an AI development squad with specialized agents.
+
+## Mandatory first action
+1. Read `.aioson/config.md`
+2. Check whether `.aioson/context/project.context.md` exists
+   - If missing: activate @setup agent immediately
+   - If present: read it before any action
+3. Check `.aioson/rules/` — if any `.md` files exist, inform the user:
+   > "Project rules active: {n} rule(s) found in `.aioson/rules/`. Each agent will load applicable rules automatically."
+
+## How to invoke agents
+
+**Option 1 — @ file include (Codex v0.110+):**
+Type `@agent-name` in the prompt. Codex will find the agent file and include its content.
+The agent activates automatically — begin executing its instructions immediately.
+Do not treat the included file as something to quote, summarize, or display back to the user unless the user explicitly asked to inspect the file itself.
+
+Examples: `@setup`, `@dev`, `@squad`, `@genoma`, `@profiler-researcher`
+
+**Option 2 — Natural language:**
+Describe your intent. The agent system will match and execute.
+
+| Agent | Natural language examples |
+|-------|--------------------------|
+| @setup | "start the project setup", "use the setup agent", "iniciar o setup" |
+| @discovery-design-doc | "prepare the discovery and design doc", "use the discovery design doc agent" |
+| @analyst | "analyze the requirements", "use the analyst agent" |
+| @architect | "design the architecture", "use the architect agent" |
+| @ux-ui | "design the UI", "use the ux-ui agent" |
+| @product | "define the product vision", "use the product agent", "start the product wizard" |
+| @pm | "create the user stories", "use the pm agent" |
+| @dev | "implement the feature", "use the dev agent" |
+| @qa | "write the tests", "use the qa agent" |
+| @orchestrator | "coordinate this session", "use the orchestrator agent" |
+| @squad | "assemble a squad", "use the squad agent", "montar squad" |
+| @genoma | "generate a genome", "use the genoma agent", "gerar genoma" |
+| @profiler-researcher | "start the profiler research", "profile this person", "pesquisar DNA mental" |
+| @profiler-enricher | "enrich this profile", "analyze this person's cognition", "consolidar perfil cognitivo" |
+| @profiler-forge | "generate the advisor", "forge the genome 3.0", "gerar advisor da persona" |
+
+When an agent file is included via @ or described via natural language, read the corresponding file and execute its instructions immediately from the first step.
+Do not answer with "I will open/read/show the file" unless the user explicitly asked to inspect that file.
+
+## Agent files
+- @setup → `.aioson/agents/setup.md`
+- @discovery-design-doc → `.aioson/agents/discovery-design-doc.md`
+- @analyst → `.aioson/agents/analyst.md`
+- @architect → `.aioson/agents/architect.md`
+- @ux-ui → `.aioson/agents/ux-ui.md`
+- @product → `.aioson/agents/product.md`
+- @pm → `.aioson/agents/pm.md`
+- @dev → `.aioson/agents/dev.md`
+- @qa → `.aioson/agents/qa.md`
+- @orchestrator → `.aioson/agents/orchestrator.md`
+- @squad → `.aioson/agents/squad.md`
+- @genoma → `.aioson/agents/genoma.md`
+- @profiler-researcher → `.aioson/agents/profiler-researcher.md`
+- @profiler-enricher → `.aioson/agents/profiler-enricher.md`
+- @profiler-forge → `.aioson/agents/profiler-forge.md`
+
+## Session protocol
+If `.aioson/context/spec.md` exists, read it at session start and update it at session end.
+
+## Golden rule
+Small project, small solution.