@jaimevalasek/aioson 1.4.0 → 1.5.1

package/template/.aioson/skills/squad/references/workflow-templates.md

@@ -0,0 +1,169 @@
+---
+name: workflow-templates
+description: Reusable workflow templates for common squad types
+version: 1.0.0
+---
+
+# Workflow Templates
+
+Starter workflow templates for common squad configurations. Adapt to the
+specific domain — these are starting points, not rigid prescriptions.
+
+## Linear content workflow
+
+Best for: single-output content squads (blog post, newsletter, video script).
+
+```json
+{
+  "slug": "linear-content",
+  "phases": [
+    { "id": "research", "executor": "researcher" },
+    { "id": "draft", "executor": "writer" },
+    {
+      "id": "review",
+      "executor": "editor",
+      "review": {
+        "reviewer": "editor",
+        "criteria": ["clarity", "accuracy", "voice"],
+        "onReject": "draft",
+        "maxRetries": 2
+      }
+    },
+    { "id": "polish", "executor": "writer" },
+    { "id": "publish", "executor": "publisher" }
+  ]
+}
+```
+
+## Parallel content workflow
+
+Best for: multi-format or multi-platform squads producing several pieces simultaneously.
+
+```json
+{
+  "slug": "parallel-content",
+  "phases": [
+    { "id": "brief", "executor": "strategist" },
+    {
+      "id": "create",
+      "parallel": true,
+      "executors": ["scriptwriter", "copywriter", "designer"]
+    },
+    {
+      "id": "review",
+      "executor": "editor",
+      "review": {
+        "reviewer": "editor",
+        "criteria": ["brand-consistency", "platform-fit"],
+        "onReject": "create",
+        "maxRetries": 1
+      }
+    },
+    { "id": "finalize", "executor": "publisher" }
+  ]
+}
+```
+
+## Research-heavy workflow
+
+Best for: squads where investigation and analysis precede creation.
+
+```json
+{
+  "slug": "research-heavy",
+  "phases": [
+    { "id": "scope", "executor": "analyst" },
+    { "id": "investigate", "executor": "researcher" },
+    { "id": "synthesize", "executor": "analyst" },
+    {
+      "id": "create",
+      "executor": "writer",
+      "humanGate": true
+    },
+    { "id": "review", "executor": "fact-checker" },
+    { "id": "publish", "executor": "publisher" }
+  ]
+}
+```
+
+## Software development workflow
+
+Best for: software squads with design-implement-test cycle.
+
+```json
+{
+  "slug": "software-dev",
+  "phases": [
+    { "id": "design", "executor": "architect" },
+    {
+      "id": "implement",
+      "executor": "developer",
+      "humanGate": true
+    },
+    { "id": "test", "executor": "qa-engineer" },
+    {
+      "id": "review",
+      "executor": "architect",
+      "review": {
+        "reviewer": "architect",
+        "criteria": ["code-quality", "architecture-fit", "test-coverage"],
+        "onReject": "implement",
+        "maxRetries": 2
+      }
+    },
+    { "id": "deploy", "executor": "devops" }
+  ]
+}
+```
+
+## Persona-driven workflow
+
+Best for: squads producing content in a specific person's voice.
+
+```json
+{
+  "slug": "persona-driven",
+  "phases": [
+    { "id": "research", "executor": "researcher" },
+    { "id": "draft", "executor": "ghostwriter", "genome": "{person-slug}" },
+    {
+      "id": "voice-check",
+      "executor": "brand-guardian",
+      "genome": "{person-slug}",
+      "review": {
+        "reviewer": "brand-guardian",
+        "criteria": ["voice-fidelity", "methodology-alignment", "authenticity"],
+        "onReject": "draft",
+        "maxRetries": 2,
+        "vetoConditions": ["voice-inconsistency"]
+      }
+    },
+    { "id": "polish", "executor": "ghostwriter", "genome": "{person-slug}" },
+    { "id": "approve", "humanGate": true }
+  ]
+}
+```
+
+## Choosing a workflow template
+
+```
+What is the squad's primary mode?
+├── content
+│   ├── Single output → Linear content
+│   ├── Multi-platform/format → Parallel content
+│   └── Persona-based → Persona-driven
+├── research
+│   └── → Research-heavy
+├── software
+│   └── → Software development
+└── mixed
+    └── Start with Linear content, add parallel phases as needed
+```
+
+## Customization guidelines
+
+- **Add phases** for additional quality gates or specialized steps
+- **Remove phases** if the squad is lightweight (micro squad)
+- **Add review blocks** to any phase that produces user-facing output
+- **Add humanGate** to phases with irreversible or high-stakes decisions
+- **Add vetoConditions** to review phases in regulated domains

package/template/.aioson/skills/static/debugging-protocol.md

@@ -0,0 +1,42 @@
+# Debugging Protocol
+
+> Load this when a bug cannot be resolved in one direct attempt.
+
+## Iron law
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.
+A fix without root cause understanding is a guess. Guesses fail.
+
+## Phase 1 — Root Cause Investigation (before any fix)
+1. Read the full error message — completely, not a summary
+2. Reproduce consistently: if you cannot reproduce, you cannot fix
+3. Review recent changes: what changed before this broke?
+4. Add instrumentation at every system boundary to locate where it fails
+5. Document: what exactly breaks, where, and under what conditions
+
+## Phase 2 — Pattern Analysis
+1. Find similar code that works correctly
+2. Compare implementations completely — not just the broken line
+3. Identify every difference (types, order, configuration)
+4. Understand dependencies the broken code relies on
+
+## Phase 3 — Hypothesis and Testing
+1. Form one hypothesis: "The bug is X because Y"
+2. Test only that hypothesis — one variable at a time
+3. No stacked changes: never change A and B simultaneously hoping one works
+4. If hypothesis fails: form a new one. Never abandon hypothesis testing for random attempts.
+
+## Phase 4 — Fix
+1. Write a failing test that reproduces the bug (this is the RED)
+2. Apply one focused fix
+3. Verify with full test run (not just the new test)
+4. If still failing after 3 focused attempts: escalate to architecture review
+
+## Defense-in-Depth (after fixing)
+When a bug is found, do not just fix the symptom. Add protection at every layer:
+- **Entry point**: reject invalid input at the API/form boundary
+- **Business logic**: validate that the operation makes sense for the domain
+- **Data layer**: DB constraints match application rules
+- **Instrumentation**: add logging that would catch this class of bug in future
+
+Single validation: "We fixed the bug."
+Multiple layers: "We made the bug impossible."

package/template/.aioson/skills/static/git-worktrees.md

@@ -0,0 +1,36 @@
+# Git Worktrees — Isolated Development
+
+> Optional but recommended for SMALL/MEDIUM feature work.
+> Keeps main branch clean while you develop.
+
+## When to use
+- Starting implementation of a new feature branch
+- When you want to be able to discard work safely
+- When you need to switch context between features
+
+## Quick setup
+```bash
+# Create worktree for feature
+git worktree add ../project-feature-name -b feature/name
+
+# Work in the worktree
+cd ../project-feature-name
+# ... install deps, run setup ...
+
+# When done: merge or discard
+git worktree remove ../project-feature-name
+```
+
+## Safety rule
+The worktrees directory must be in `.gitignore`.
+Add before creating:
+```bash
+echo ".worktrees/" >> .gitignore
+git add .gitignore && git commit -m "chore: add worktrees to gitignore"
+```
+
+## Finish options
+1. Merge back to main locally
+2. Push and create PR
+3. Keep branch as-is (continue later)
+4. Discard (requires typing "discard" to confirm)

package/template/.aioson/tasks/implementation-plan.md

@@ -255,6 +255,25 @@ Perguntar:
 Se o chat atual já consumiu muitos tokens com discovery/design:
 > "Recomendo iniciar um novo chat para a implementação — o context package está definido no plano."
 
+### Modo de execução
+
+Após aprovação do plano, oferecer dois modos:
+
+**Modo padrão** (recomendado para MICRO/SMALL):
+> "Implementar fase por fase neste chat com `/dev`."
+
+**Modo precisão** (recomendado para MEDIUM ou planos com 5+ fases):
+> "Para cada fase, abrir um novo chat com contexto isolado.
+> Isso evita contaminação de contexto entre fases e mantém cada subagent focado.
+>
+> Para cada fase:
+> 1. Abrir novo chat
+> 2. Colar o context package desta fase (definido no plano)
+> 3. Executar com `/dev`
+> 4. Ao terminar: atualizar `spec.md` e retornar ao plano"
+
+Se MEDIUM e `@orchestrator` disponível: o modo precisão é feito automaticamente via Task tool.
+
 ## Adaptação por classificação
 
 ### MICRO

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

@@ -75,6 +75,34 @@ O JSON deve seguir o schema `squad-blueprint.schema.json`.
 
 Gere um UUID para o campo `id`. Use `new Date().toISOString()` para `createdAt`.
 
+### Passo 6.5 — Squad Spec Self-Review
+
+Antes de apresentar ao usuário, revisar o blueprint como se fosse outro agente lendo pela primeira vez:
+
+**Verificar completude:**
+- [ ] Cada executor tem role único e não sobrepõe outro executor
+- [ ] Cada executor tem focus com 3-5 bullets concretos (não vagos)
+- [ ] Sem "TBD", "a definir", "conforme necessário" em nenhum campo
+- [ ] Mission do squad é uma frase que explica o que faz E para quem
+
+**Verificar consistência:**
+- [ ] Sem contradições: tom/audiência do squad vs tone de cada executor
+- [ ] Se mode=content: content blueprints cobrem os outputs esperados
+- [ ] Se mode=software: executores cobrem as fases de desenvolvimento necessárias
+- [ ] Squad não tem mais responsabilidades do que os executores conseguem cobrir
+
+**Verificar scope:**
+- [ ] O squad resolve o problema declarado pelo usuário — nem mais, nem menos
+- [ ] Nenhum executor foi adicionado por "seria útil" sem relação com o objetivo
+- [ ] Se user pediu N executores: verificar que não foram adicionados extras silenciosamente
+
+**Calibração:** Só bloqueie se o problema causaria output fundamentalmente errado.
+Preferências de estilo não bloqueiam. Lacunas de detalhe não bloqueiam.
+Contradições de escopo e roles sem responsabilidade real = bloqueiam.
+
+Se encontrar problemas: corrigir no blueprint antes de apresentar ao usuário.
+Se tudo OK: prosseguir para Passo 7.
+
 ### Passo 7 — Apresentar resumo
 Mostre ao usuário:
 - Executores propostos com roles

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

@@ -0,0 +1,48 @@
+# Task: Squad Profiler Integration
+
+> Orquestra profiling dentro do flow de criação do squad.
+
+## Quando usar
+- Automaticamente pelo @squad quando detecta persona-based squad
+- `@squad design --profile` — dispara profiling antes do design
+
+## Detecção de persona
+
+Heurísticas para oferecer profiling:
+- Usuário menciona uma pessoa específica por nome
+- O goal inclui "no estilo de", "como {pessoa}", "baseado na abordagem de {pessoa}"
+- O domínio é personal branding, criação de conteúdo para um criador específico
+
+## Processo
+
+### Passo 1 — Verificar perfil existente
+Checar se `.aioson/profiler-reports/{person-slug}/` já existe.
+Se existir: ler o perfil enriquecido e pular para aplicação do genome.
+
+### Passo 2 — Executar pipeline de profiling
+Se não existir perfil:
+1. @profiler-researcher → coleta de evidências
+2. @profiler-enricher → análise de padrões cognitivos
+3. @profiler-forge → geração do genome
+
+### Passo 3 — Aplicar genome aos executores
+O genome resultante é aplicado apenas aos executores relevantes:
+- Executores criativos (copywriter, scriptwriter) → SIM
+- Executores de pesquisa e orquestração → NÃO (não precisam da voz da persona)
+
+### Passo 4 — Registrar no blueprint
+```json
+"profiling": {
+  "person": "{name}",
+  "genomePath": "{path}",
+  "genomeSlug": "{slug}",
+  "evidenceMode": "verified | inferred | mixed",
+  "profiledAt": "{ISO-8601}"
+}
+```
+
+## Regras
+- NÃO execute profiling sem o consentimento do usuário
+- NÃO aplique genome a todos os executores — apenas os que precisam da voz
+- O profiling é uma SUGESTÃO, não uma obrigação
+- Registre a associação profiling → squad no blueprint

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

@@ -0,0 +1,61 @@
+# Task: Squad Review Loop
+
+> Protocolo de review loop dentro de uma workflow phase.
+
+## Quando usar
+- Automaticamente pelo @orquestrador quando uma phase tem `review` declarado
+- O orquestrador NÃO precisa ser instruído — ele lê o manifest e segue
+
+## Processo
+
+### Passo 1 — Fase produz output
+O executor da phase gera seu output normalmente.
+
+### Passo 2 — Checar veto conditions
+Antes do review, verificar se alguma veto condition é violada:
+- Se `action: block` → parar pipeline, notificar usuário
+- Se `action: reject` → auto-rejeitar sem review (economiza uma rodada)
+- Se `action: warn` → continuar mas marcar warning
+
+### Passo 3 — Invocar reviewer
+O executor definido em `review.reviewer` avalia o output com base nos `criteria`.
+
+O reviewer deve produzir:
+```
+## Review: {phase-title}
+
+**Verdict:** accepted | rejected
+**Score:** {0-10}
+
+### Criteria evaluation
+- ✓ {criteria 1}: {assessment}
+- ✗ {criteria 2}: {assessment with specific feedback}
+- ✓ {criteria 3}: {assessment}
+
+### Feedback (if rejected)
+{Specific, actionable feedback for the creator. Not vague — exact issues and suggestions.}
+
+### Veto check
+- {veto condition 1}: passed | triggered
+```
+
+### Passo 4 — Se aceito
+Marcar phase como completed. Seguir para a próxima.
+
+### Passo 5 — Se rejeitado
+1. Incrementar retry counter
+2. Se retry counter > maxRetries → escalate:
+   - `human`: pausar e pedir decisão humana
+   - `skip`: pular a fase com warning
+   - `fail`: falhar o pipeline
+3. Se ainda tem retries:
+   - `feedback` strategy: enviar feedback do reviewer ao executor original
+   - `fresh` strategy: re-executar sem contexto do attempt anterior
+   - `alternative` strategy: pedir a um executor diferente (se disponível)
+4. Voltar ao onReject phase ID
+
+## Regras
+- NUNCA permitir mais de maxRetries iterações (hard limit)
+- SEMPRE incluir o feedback do reviewer no retry
+- O reviewer NUNCA deve ser o mesmo executor que criou o output
+- Registrar cada retry no log: attempt number, reason, feedback

package/template/.aioson/tasks/squad-task-decompose.md

@@ -0,0 +1,66 @@
+# Task: Squad Task Decomposition
+
+> Guia de decomposição de executores em tasks granulares.
+
+## Quando usar
+- Durante `@squad create`, ao avaliar cada executor
+- `@squad extend` quando o usuário pede task decomposition retroativa
+
+## Formato de um task file
+
+Salvar em `.aioson/squads/{squad-slug}/agents/{executor-slug}/tasks/{task-slug}.md`:
+
+```markdown
+# Task: {task-name}
+
+> Order: {1, 2, 3...}
+> Executor: @{executor-slug}
+> Input: {what this task receives}
+> Output: {what this task produces}
+
+## Process
+1. {Step 1 — concrete action}
+2. {Step 2 — concrete action}
+3. {Step 3 — concrete action}
+
+## Output Format
+{Schema or description of expected output}
+
+## Output Example
+{15+ lines of realistic output example}
+
+## Quality Criteria
+1. {Measurable criterion}
+2. {Measurable criterion}
+3. {Measurable criterion}
+
+## Veto Conditions
+1. {Hard block — output CANNOT have this}
+2. {Hard block — output CANNOT have this}
+```
+
+## Árvore de decisão
+
+```
+EXECUTOR
+  ├── Faz UMA coisa bem? (reviewer, validator, formatter)
+  │   └── SEM tasks — o agent file é suficiente
+  │
+  ├── Tem processo multi-step repetível?
+  │   ├── 2 steps → provavelmente sem tasks (mantenha simples)
+  │   ├── 3+ steps com outputs distintos → SIM, decompor em tasks
+  │   └── 3+ steps internos → SEM tasks (steps no agent file)
+  │
+  ├── As tasks serão reutilizadas?
+  │   └── SIM → decompor (reusabilidade)
+  │
+  └── Qualidade é crítica e cada step precisa de seus critérios?
+      └── SIM → decompor (controle granular de qualidade)
+```
+
+## Regras
+- Manter o agent file focado na identidade (missão, foco, restrições)
+- Mover detalhes de processo para task files
+- Cada task deve ser independentemente avaliável
+- Tasks executam sequencialmente — output da task N é input da task N+1
+- Adicionar quality criteria por task, não só por executor

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

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — System router: see the full picture, get guided to the right agent"
+---
+
+Read `.aioson/agents/neo.md` and follow all instructions. $ARGUMENTS

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

@@ -0,0 +1,5 @@
+---
+description: "AIOSON — Systematic test engineering for implemented apps (all sizes)"
+---
+
+Read `.aioson/agents/tester.md` and follow all instructions. $ARGUMENTS

package/template/.gemini/GEMINI.md

@@ -8,5 +8,6 @@
 ## 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-neo` when you want an overview of the project state and guidance on which agent to use next.
 - 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-neo.toml

@@ -0,0 +1,4 @@
+name = "aios-neo"
+description = "System router — see the full picture, get guided to the right agent"
+instruction_file = ".aioson/agents/neo.md"
+requires_context = []

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

@@ -0,0 +1,6 @@
+name = "aios-tester"
+description = "Systematic test engineering for implemented apps"
+instruction_file = ".aioson/agents/tester.md"
+requires_context = [
+  ".aioson/context/project.context.md"
+]

package/template/AGENTS.md

@@ -33,6 +33,7 @@ Describe your intent. The agent system will match and execute.
 | @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" |
+| @neo | "where do I start?", "what should I do next?", "show project status", "guide me", "use the neo agent" |
 | @orchestrator | "coordinate this session", "use the orchestrator agent" |
 | @squad | "assemble a squad", "use the squad agent", "montar squad" |
 | @genome | "generate a genome", "use the genome agent", "gerar genome" |
@@ -81,6 +82,8 @@ When running Codex directly (without `aioson workflow:next`), these rules apply:
 - @pm → `.aioson/agents/pm.md`
 - @dev → `.aioson/agents/dev.md`
 - @qa → `.aioson/agents/qa.md`
+- @tester → `.aioson/agents/tester.md`
+- @neo → `.aioson/agents/neo.md`
 - @orchestrator → `.aioson/agents/orchestrator.md`
 - @squad → `.aioson/agents/squad.md`
 - @genome → `.aioson/agents/genome.md`

package/template/CLAUDE.md

@@ -16,11 +16,14 @@ You operate as AIOSON.
 - /architect -> `.aioson/agents/architect.md`
 - /ux-ui (UI/UX) -> `.aioson/agents/ux-ui.md`
 - /product -> `.aioson/agents/product.md`
+- /sheldon -> `.aioson/agents/sheldon.md`
 - /deyvin -> `.aioson/agents/deyvin.md`
 - /pair -> `.aioson/agents/deyvin.md` (compatibility alias)
 - /pm -> `.aioson/agents/pm.md`
 - /dev -> `.aioson/agents/dev.md`
 - /qa -> `.aioson/agents/qa.md`
+- /tester -> `.aioson/agents/tester.md`
+- /neo -> `.aioson/agents/neo.md`
 - /orchestrator -> `.aioson/agents/orchestrator.md`
 - /squad -> `.aioson/agents/squad.md`
 - /orache -> `.aioson/agents/orache.md`
@@ -51,8 +54,8 @@ When running Claude Code directly (without `aioson workflow:next`), these rules
 - Use `aioson runtime:emit . --agent=<agent> --type=plan_checkpoint --plan-step=<step>` when the session is attached to an explicit plan and a step has just been completed.
 - Use `aioson live:handoff . --agent=<agent> --to=<next-agent> --reason="..."` when the active agent must transfer the same live session to another AIOSON agent.
 - Monitor active live sessions with `aioson live:status . --agent=<agent> --watch=2` and close them with `aioson live:close . --agent=<agent> --summary="..."`.
-- Plain slash-command activation can execute agent instructions, but does not guarantee runtime records in the dashboard by itself.
-- Do not try to synthesize dashboard telemetry by emitting `aioson runtime-log` shell snippets from inside the session.
+- Plain slash-command activation registers in the dashboard automatically via `aioson agent:done` at the end of each agent session — each agent file has the call in its "Observability" section.
+- Do not call `aioson runtime-log` directly from inside the session — use `aioson agent:done` instead, which is safe in both direct and live-session contexts.
 
 ## Golden rule
 Small project, small solution.

package/template/OPENCODE.md

@@ -17,6 +17,8 @@
 - pm -> `.aioson/agents/pm.md`
 - dev -> `.aioson/agents/dev.md`
 - qa -> `.aioson/agents/qa.md`
+- tester -> `.aioson/agents/tester.md`
+- neo -> `.aioson/agents/neo.md`
 - orchestrator -> `.aioson/agents/orchestrator.md`
 - squad -> `.aioson/agents/squad.md`
 - genome -> `.aioson/agents/genome.md`