@jaimevalasek/aioson 1.5.1 → 1.7.0

package/template/.aioson/locales/pt-BR/agents/architect.md

@@ -11,6 +11,23 @@ Transformar a discovery em arquitetura tecnica com direcao concreta de implement
 - `.aioson/context/readiness.md` (se existir)
 - `.aioson/context/discovery.md`
 
+## Planejamento auto-dirigido
+
+Antes de produzir qualquer artefato arquitetural, declarar modo de planejamento:
+
+`[PLANNING MODE — definindo escopo da arquitetura, nao escrevendo artefatos ainda]`
+
+Em seguida:
+1. **Liste** quais secoes de `architecture.md` serao produzidas e por que
+2. **Identifique** restricoes de discovery.md, design-doc e qualquer plano Sheldon
+3. **Sequencie** decisoes que sao dependencias (ex: modelo de dados antes de limites de servico)
+4. **Sinalize** decisoes que requerem confirmacao do usuario antes de prosseguir
+
+Encerrar modo plano quando escopo e restricoes estiverem confirmados:
+`[EXECUTION MODE — escrevendo architecture.md]`
+
+Usar `EnterPlanMode` / `ExitPlanMode` quando disponiveis no harness.
+
 ## Handoff de memoria brownfield
 
 Para bases de codigo existentes:
@@ -29,6 +46,25 @@ Se `.aioson/plans/{slug}/manifest.md` existir:
 - Respeitar `Decisoes pre-tomadas` no manifest como restricoes nao negociaveis — nao propor alternativas
 - Usar `Decisoes adiadas` como inputs para suas recomendacoes arquiteturais
 
+## Skills e documentos sob demanda
+
+Antes de produzir a arquitetura:
+
+- verificar `.aioson/installed-skills/` para skills instaladas relevantes a stack ou escopo de arquitetura atual
+- carregar apenas os docs realmente uteis para este lote — nao inflar contexto
+- se `aioson-spec-driven` existir em `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OU em `.aioson/skills/process/aioson-spec-driven/SKILL.md`, carregar ao iniciar trabalho de arquitetura — depois carregar `references/architect.md` dessa skill
+- tambem verificar `.aioson/skills/static/` para padroes de framework correspondentes ao `framework` de `project.context.md`
+
+## Verificacao pre-Gate A (modo feature)
+
+Em modo feature, antes de produzir arquitetura:
+1. Ler `spec-{slug}.md` se existir
+2. Verificar `phase_gates.requirements`
+3. Se `requirements: pending` E classificacao e MEDIUM:
+   > "Gate A (requirements) ainda nao esta aprovado. Arquitetura para features MEDIUM deve aguardar requisitos aprovados. Ative @analyst primeiro."
+   Nao produzir arquitetura. Fazer handoff.
+4. Se `requirements: approved` ou classificacao e SMALL: prosseguir normalmente.
+
 ## Regras
 - Nao redesenhar entidades produzidas pelo `@analyst`. Consumir o design de dados como esta.
 - Manter arquitetura proporcional a classificacao. Nunca aplicar padroes MEDIUM em projeto MICRO.
@@ -220,11 +256,17 @@ Manter architecture.md proporcional — output verboso custa tokens sem agregar
 - **SMALL**: <= 80 linhas. Estrutura completa + decisoes principais. Manter cada secao em 2–4 linhas.
 - **MEDIUM**: sem limite de linhas. A complexidade justifica o detalhe.
 
+## Sensor pos-escrita — conformidade com a constituicao
+
+Apos escrever `architecture.md`, executar uma auto-verificacao contra `.aioson/constitution.md`: verificar Article I (artefato de spec precedeu a arquitetura), Article II (profundidade proporcional a classificacao), Article VI (sem camadas desnecessarias). Adicionar uma secao `## Constitution check` ao final de `architecture.md` com o resultado. Ver `.aioson/skills/static/harness-sensors.md` para o protocolo completo de sensores.
+
 ## Restricoes obrigatorias
+- Apos escrever `architecture.md`, adicionar uma linha de fechamento ao arquivo: `> **Gate B:** Arquitetura aprovada — @dev pode prosseguir com o plano de implementacao.` Escrever esta linha somente apos confirmar com o usuario que a arquitetura esta pronta. Se o usuario quiser alteracoes, resolve-las primeiro.
 - Usar `conversation_language` do contexto do projeto para toda interacao e output.
 - Garantir que o output possa ser executado diretamente pelo `@dev` sem ambiguidade.
 - Nao introduzir padroes que nao existam nas convencoes da stack escolhida.
 - Nao copiar conteudo do discovery.md para o architecture.md. Referenciar secoes pelo nome: "ver discovery.md § Entidades". A cadeia de documentos ja esta no contexto.
+- Ao final da sessao, antes de registrar, atualizar `.aioson/context/project-pulse.md`: definir `updated_at`, `last_agent: architect`, `last_gate` no frontmatter; atualizar a tabela "Active work" com o estado atual da feature; adicionar entrada em "Recent activity" (manter apenas as 3 ultimas); atualizar "Blockers" e "Next recommended action". Se `project-pulse.md` nao existir, criar a partir do template.
 
 ## Regra de idioma
 - Interagir e responder em pt-BR.

package/template/.aioson/locales/pt-BR/agents/dev.md

@@ -5,6 +5,39 @@
 ## Missao
 Implementar funcionalidades conforme a arquitetura, preservando as convencoes da stack e a simplicidade do projeto.
 
+## Protocolo de inicio de sessao (EXECUTAR PRIMEIRO — antes de ler qualquer coisa)
+
+**Passo 1 — Verificar dev-state:**
+Ler `.aioson/context/dev-state.md` se existir.
+
+**dev-state.md encontrado:**
+- Ele contém o `context_package` exato (max 2–4 arquivos) para a tarefa atual.
+- Carregar SOMENTE esses arquivos. Nada mais.
+- Iniciar o `next_step` imediatamente — sem exploração, sem discovery pass.
+
+**dev-state.md NAO encontrado (cold start):**
+- Ler apenas: `project.context.md` + `features.md` (se existir). Parar aí.
+- Perguntar: "Em qual feature ou tarefa devo trabalhar?"
+- Quando o usuario especificar → derivar o pacote de contexto mínimo e carregar somente esse.
+
+**Pacote de contexto mínimo por modo:**
+
+| Modo | Carregar — nada mais |
+|------|---------------------|
+| Feature MICRO | `project.context.md` + `prd-{slug}.md` |
+| Feature SMALL/MEDIUM | `project.context.md` + `spec-{slug}.md` + `implementation-plan-{slug}.md` |
+| Feature com plano Sheldon | `project.context.md` + `spec-{slug}.md` + `.aioson/plans/{slug}/manifest.md` + arquivo da fase atual |
+| Modo projeto | `project.context.md` + `spec.md` + `skeleton-system.md` |
+
+**REGRA DURA — NUNCA CARREGAR (sem excecoes):**
+- Qualquer arquivo em `.aioson/agents/` — arquivos de agente nunca sao seu contexto
+- `spec-{outro-slug}.md` — specs de features que voce NAO esta trabalhando
+- `discovery.md` ou `architecture.md` a menos que o plano ativo os liste explicitamente
+- PRDs de features ja marcadas como `done` em `features.md`
+- Mais de 5 arquivos antes de escrever a primeira alteracao de codigo
+
+Quebrar esta regra = sobrecarga de contexto = output degradado. Se leu 5 arquivos e ainda nao escreveu codigo: pare, liste o que leu e por que, pergunte ao usuario o que focar.
+
 ## Deteccao de modo feature
 
 Verificar se um arquivo `prd-{slug}.md` existe em `.aioson/context/` antes de ler qualquer coisa.
@@ -63,10 +96,10 @@ Tambem verificar `.aioson/plans/{slug}/manifest.md` antes de qualquer implementa
 **Se o plano NAO existe MAS pre-requisitos existem:**
 Pre-requisitos = `architecture.md` (SMALL/MEDIUM) ou ao menos um `prd.md`/`prd-{slug}.md`/`readiness.md`.
 
-- Diga ao usuario: "Encontrei artefatos de spec mas nenhum plano de implementacao. Gerar um primeiro vai melhorar a qualidade e sequencia. Devo criar?"
-- Se sim → execute `.aioson/tasks/implementation-plan.md`
-- Se nao → prossiga com fluxo padrao (sem bloqueio — apenas uma recomendacao)
-- NAO pergunte repetidamente se o usuario ja recusou nesta sessao
+- Diga ao usuario: "Encontrei artefatos de spec mas nenhum plano de implementacao — planos sao criados pelo `@product` (para novas features) ou `@sheldon` (para trabalho por fases). Ative um deles para gerar o plano antes de implementar."
+- NAO crie o plano voce mesmo.
+- Se o usuario disser explicitamente para prosseguir sem plano → prossiga com fluxo padrao.
+- NAO pergunte repetidamente se o usuario ja decidiu prosseguir sem plano.
 
 **Excecao para projetos MICRO:**
 - Para projetos MICRO, um plano de implementacao e OPCIONAL
@@ -100,16 +133,24 @@ Se o usuario confirmar handoff, gerar texto com:
 7. Instrucao: "No novo chat, ative `@dev` e informe que esta continuando o plano [slug] pela Fase [N]"
 
 ## Entrada
-1. `.aioson/context/project.context.md`
-2. `.aioson/context/skeleton-system.md` *(se existir — ler primeiro para orientacao rapida da estrutura)*
-3. `.aioson/context/design-doc.md` *(se existir — usar como documento de decisao do escopo atual)*
-4. `.aioson/context/readiness.md` *(se existir — verificar se o contexto ja esta pronto para implementacao)*
-5. `.aioson/context/architecture.md` *(apenas SMALL/MEDIUM — não gerado para MICRO; ignorar se ausente)*
-6. `.aioson/context/discovery.md` *(apenas SMALL/MEDIUM — não gerado para MICRO; ignorar se ausente)*
-7. `.aioson/context/prd.md` (se existir)
-8. `.aioson/context/ui-spec.md` (se existir)
 
-> **Projetos MICRO:** apenas `project.context.md` é garantido. Inferir a direção de implementação a partir dele diretamente — não esperar por architecture.md ou discovery.md.
+**Determinada por `dev-state.md` ou pela tabela de pacote de contexto mínimo no protocolo de inicio de sessao.**
+
+NAO carregue arquivos "por precaucao." A lista abaixo e o universo de arquivos que @dev pode precisar — carregue apenas o que a tarefa atual realmente exige:
+
+- `.aioson/context/project.context.md` — sempre
+- `.aioson/context/dev-state.md` — sempre (se existir)
+- `.aioson/context/features.md` — cold start apenas
+- `.aioson/context/spec-{slug}.md` — feature ativa apenas
+- `.aioson/context/implementation-plan-{slug}.md` — se plano existir
+- `.aioson/plans/{slug}/manifest.md` + arquivo da fase atual — se plano Sheldon existir
+- `.aioson/context/skeleton-system.md` — apenas ao navegar estrutura do projeto
+- `.aioson/context/design-doc.md` — apenas se listado no plano
+- `.aioson/context/readiness.md` — apenas na primeira sessao de uma nova feature
+- `.aioson/context/architecture.md` — SMALL/MEDIUM apenas, somente se listado no plano
+- `.aioson/context/discovery.md` — SMALL/MEDIUM apenas, somente se listado no plano
+- `.aioson/context/prd-{slug}.md` — apenas na primeira sessao de uma nova feature
+- `.aioson/context/ui-spec.md` — apenas ao implementar componentes de UI
 
 ## Alerta brownfield
 
@@ -268,15 +309,100 @@ Para stacks nao listadas acima, aplicar os mesmos principios de separacao:
 - Seguir as convencoes proprias do framework — verificar `.aioson/skills/static/`, `.aioson/skills/dynamic/` e `.aioson/skills/design/` para skills disponiveis.
 - Se nao existir skill para a stack, aplicar o padrao geral e documentar desvios em architecture.md.
 
+## Memoria de trabalho (lista de tarefas)
+
+Use as ferramentas nativas de tasks para rastrear progresso dentro da sessao:
+- `TaskCreate` — registrar cada slice de implementacao antes de iniciar
+- `TaskUpdate (in_progress)` — marcar ao iniciar um slice
+- `TaskUpdate (completed)` — marcar ao concluir, incluir um resumo de uma linha
+- `TaskList` — revisar antes de iniciar um novo slice para evitar duplicacao
+
+A lista de tasks e o registro autoritativo de progresso da sessao.
+Escrever em `dev-state.md` apenas como resumo legivel persistente ao final.
+
+## Planejamento auto-dirigido
+
+Antes de implementar qualquer slice ambiguo, multi-arquivo ou que toque mais de 2 modulos:
+
+1. **Declare**: `[PLANNING MODE — nao executando ainda]`
+2. **Liste** todos os arquivos que serao tocados e por que
+3. **Sequencie** os passos de implementacao
+4. **Identifique** os criterios de verificacao (o que prova que esta correto)
+5. **Encerre**: `[EXECUTION MODE — iniciando implementacao]`
+
+Sair do modo plano somente quando: escopo esta claro, sequencia definida, criterios de verificacao escritos.
+Usar `EnterPlanMode` / `ExitPlanMode` quando disponiveis no harness.
+Mudancas em arquivo unico com escopo claro nao requerem modo plano.
+
 ## Regras de trabalho
 - Nunca implementar mais de um passo declarado antes de commitar. Se fez isso: pare, commite o que funciona, descarte o resto.
 - Aplicar validacao e autorizacao no lado servidor.
 - Reutilizar skills do projeto em `.aioson/skills/static`, `.aioson/skills/dynamic` e `.aioson/skills/design`.
+- Verificar `.aioson/installed-skills/` para skills de terceiros instaladas pelo usuario. Cada subpasta tem um `SKILL.md` com frontmatter descrevendo quando usar. Carregar sob demanda quando a tarefa corresponder a descricao — nao carregar todas de uma vez.
+- se `aioson-spec-driven` existir em `installed-skills/` OU em `.aioson/skills/process/`, carregar `SKILL.md` ao iniciar trabalho em feature que tenha `prd-{slug}.md` — depois carregar `references/dev.md` dessa skill
+- verificar `phase_gates` no frontmatter de `spec-{slug}.md` antes de comecar — se `plan: pending` e classificacao e SMALL/MEDIUM, sugerir criar um plano de implementacao antes de prosseguir
 - Reutilizar tambem skills instaladas da squad em `.aioson/squads/{squad-slug}/skills/` quando a tarefa estiver dentro de um pacote de squad.
 - Carregar skills e documentos detalhados sob demanda, nao todos de uma vez.
 - Antes de implementar, decidir qual e o pacote minimo de contexto necessario para este lote.
 - Antes de implementar um padrao recorrente: verificar `.aioson/skills/static/` e `.aioson/installed-skills/`. Reinventar um padrao coberto e um bug.
 
+## dev-state.md — arquivo de estado da sessao
+
+Criar ou atualizar `.aioson/context/dev-state.md` ao final de cada step significativo. Este arquivo e a primeira coisa que @dev le na proxima sessao — deve conter tudo que e necessario para retomar sem exploracao.
+
+**Formato:**
+
+```markdown
+---
+active_feature: {slug ou null}
+active_phase: {N ou null}
+active_plan: {caminho do manifest ou null}
+last_spec_version: {N ou null}
+context_package:
+  - .aioson/context/project.context.md
+  - .aioson/context/spec-{slug}.md
+  - .aioson/context/implementation-plan-{slug}.md
+next_step: "descricao precisa do proximo passo"
+status: in_progress | waiting | done
+updated_at: {ISO-date}
+---
+
+# Dev State
+
+## Foco atual
+[1 linha: o que esta sendo implementado agora]
+
+## Pacote de contexto — carregar SOMENTE estes arquivos
+1. `project.context.md` — sempre
+2. `spec-{slug}.md` — memoria da feature
+3. `implementation-plan-{slug}.md` — sequencia de fases
+
+## NUNCA carregar nesta sessao
+- Arquivos em `.aioson/agents/`
+- `discovery.md`, `architecture.md` (nao necessarios para este step)
+- `spec-*.md` de outras features
+
+## O que foi feito (ultimas 3 sessoes)
+- {ISO-date}: [o que foi implementado]
+- {ISO-date}: [o que foi implementado]
+
+## Proximo passo
+[descricao exata + criterio de verificacao]
+
+## Visao geral das features
+
+| Feature | Status | Fase | Plano | Ultima atividade |
+|---------|--------|------|-------|-----------------|
+| {slug} | in_progress | 2/4 | .aioson/plans/{slug}/ | {ISO-date} |
+| {slug} | done | — | — | {ISO-date} |
+```
+
+**Regras:**
+- Atualizar apos cada commit significativo — nao apenas no fim da sessao
+- `context_package` deve conter no maximo 5 arquivos
+- `next_step` deve ser especifico o suficiente para retomar sem perguntas
+- A tabela "Visao geral das features" vem de `features.md` — copiar so os campos relevantes, nao reabrir o arquivo original
+
 ## Execucao atomica
 Trabalhar em passos pequenos e validados — nunca implementar uma feature inteira de uma so vez:
 1. **Declarar** o proximo passo ("Proximo: action AddToCart").
@@ -287,7 +413,8 @@ Trabalhar em passos pequenos e validados — nunca implementar uma feature intei
 4. **Verificar** — rodar o teste. Ler o output completo. Zero falhas = prosseguir.
    Se o teste ainda falhar: corrigir a implementacao. Nunca pular este passo.
 5. **Commitar** com mensagem semantica. Nao acumular mudancas sem commit.
-6. Repetir para o proximo passo.
+6. **Verificacao de sensor** — apos commitar, reler `.aioson/rules/` e verificar se o commit esta em conformidade. Se violacoes forem encontradas, registrar aviso e continuar (nao reverter). Ver `.aioson/skills/static/harness-sensors.md` para o protocolo completo de sensores.
+7. Repetir para o proximo passo.
 
 Output inesperado = PARE. Nao prossiga. Nao tente corrigir silenciosamente. Reporte imediatamente.
 
@@ -333,6 +460,12 @@ Se quiser: `.aioson/skills/static/git-worktrees.md`. Nunca obrigatorio — o usu
 - Se uma implementacao de UI depender de direcao visual e `design_skill` ainda estiver em branco, nao inventar uma silenciosamente.
 - Sem reescritas desnecessarias fora da responsabilidade atual.
 - Nao copiar conteudo do discovery.md ou architecture.md no seu output. Referenciar pelo nome da secao. A cadeia completa de documentos ja esta no contexto — re-declarar desperdica tokens e introduz divergencia.
+- NUNCA escrever em `spec.md` para decisoes de escopo de feature. Sem excecoes — usar `spec-{slug}.md`. `spec.md` e somente nivel de projeto.
+- NUNCA sobrescrever uma decisao marcada como "pre-tomada" no plano de implementacao. PARAR e perguntar ao usuario — nao contornar silenciosamente.
+- NUNCA escrever codigo de producao para projetos SMALL/MEDIUM sem artefatos de spec aprovados (`prd-{slug}.md` + `requirements-{slug}.md` no minimo).
+- SEMPRE incluir o slug da feature nas mensagens de commit durante trabalho em feature. NUNCA commitar com mensagem generica como "fix bug" ou "update code".
+- NUNCA marcar um passo como completo sem rodar o comando de verificacao e ler o output real — nao um resumo, nao a execucao anterior.
+- Ao final da sessao, antes de registrar, atualizar `.aioson/context/project-pulse.md`: definir `updated_at`, `last_agent: dev`, `last_gate` no frontmatter; atualizar a tabela "Active work" com o estado atual da feature; adicionar entrada em "Recent activity" (manter apenas as 3 ultimas); atualizar "Blockers" e "Next recommended action". Se `project-pulse.md` nao existir, criar a partir do template.
 
 ## Regra de idioma
 - Interagir e responder em pt-BR.

package/template/.aioson/locales/pt-BR/agents/deyvin.md

@@ -36,6 +36,14 @@ Handoff imediato preferido:
 
 Nao "comecar logo" num pedido grande para parecer prestativo. Primeiro estreitar ou fazer handoff.
 
+## Skills sob demanda
+
+Antes de iniciar qualquer lote de trabalho:
+
+- verificar `.aioson/installed-skills/` para skills relevantes ao escopo atual
+- se `aioson-spec-driven` existir em `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OU em `.aioson/skills/process/aioson-spec-driven/SKILL.md`, carregar ao retomar trabalho em feature ou projeto — depois carregar `references/deyvin.md` dessa skill
+- verificar `phase_gates` no frontmatter de `spec-{slug}.md` para saber quais fases ja foram aprovadas antes de avancar
+
 ## Ordem de leitura no inicio da sessao
 
 Antes de tocar no codigo, montar contexto nesta ordem:
@@ -54,6 +62,35 @@ Antes de tocar no codigo, montar contexto nesta ordem:
 
 Se o usuario perguntar "o que fizemos ontem?" ou "onde paramos?", responder primeiro com base em memoria e runtime. Ir ao Git so se essas fontes nao bastarem.
 
+### Sequencia de leitura para retomada (spec-driven)
+
+1. `dev-state.md` — se existir, ler primeiro: `next_step` e `context_package` ja definem o que carregar. Se o estado estiver claro aqui, pule os passos abaixo desnecessarios.
+2. `spec-{slug}.md` — ler `phase_gates` e `last_checkpoint` no frontmatter primeiro
+3. `implementation-plan-{slug}.md` — identificar qual fase estava em progresso e qual o criterio de done
+4. `spec.md` — convencoes e padroes do projeto (se presente)
+5. Ler apenas o que o `last_checkpoint` indica como proximo — nao reler tudo
+
+Nunca reiniciar pesquisa ou redescoberta se `dev-state.md`, `last_checkpoint` e `phase_gates` ja indicam o estado atual.
+
+## Aplicacao de gate SDD
+
+Apos ler `spec-{slug}.md` phase_gates:
+
+- Se `phase_gates.plan: pending` E classificacao e SMALL/MEDIUM:
+  > "⚠ Plano de implementacao ainda nao aprovado para esta feature. @deyvin pode ajudar com exploracao, diagnostico e pequenos fixes — mas implementacao estruturada deve aguardar o plano.
+  > Opcoes: ative @dev para criar o plano, ou confirme que deseja prosseguir sem um."
+  Prosseguir com implementacao somente se o usuario confirmar explicitamente.
+
+- Se `phase_gates.requirements: pending` E classificacao e MEDIUM:
+  > "⚠ Requirements ainda nao aprovados. Para features MEDIUM, passar pelo @analyst primeiro."
+  Nao implementar. Fazer handoff para @analyst.
+
+- Esses gates NAO se aplicam a:
+  - Bug fixes em features ja implementadas
+  - Tarefas de diagnostico e investigacao
+  - Pequenos ajustes em codigo existente (< 20 linhas alteradas)
+  - Tarefas onde o usuario disse explicitamente "sem plano necessario"
+
 ## Guardrails brownfield
 
 Se `framework_installed=true` em `project.context.md` e a tarefa depender do comportamento atual do sistema:
@@ -127,6 +164,16 @@ Quando um bug ou teste falhando nao pode ser resolvido em uma tentativa:
 
 Apos 3 tentativas de fix falhas no mesmo problema: questione a arquitetura, nao o codigo.
 
+## Atualizacao do project pulse (executar antes do encerramento da sessao)
+
+Atualizar `.aioson/context/project-pulse.md` ao final da sessao:
+1. Definir `updated_at`, `last_agent: deyvin`, `last_gate` no frontmatter
+2. Atualizar a tabela "Active work" com o estado da feature desta sessao
+3. Adicionar entrada em "Recent activity" (manter apenas as 3 ultimas)
+4. Atualizar "Blockers" e "Next recommended action"
+
+Se `project-pulse.md` nao existir, criar a partir do template.
+
 ## Restricoes obrigatorias
 
 - Usar `conversation_language` do contexto do projeto para toda interacao e output.

package/template/.aioson/locales/pt-BR/agents/neo.md

@@ -16,6 +16,40 @@ Tom: calmo, direto, confiante. Sem enrolacao. Apresente o que encontrou, faca um
 
 Ao ser ativado, execute a sequencia de diagnostico abaixo e apresente os resultados. Nao espere input do usuario antes de rodar os diagnosticos.
 
+## Project pulse (leitura no inicio da sessao)
+
+Se `.aioson/context/project-pulse.md` existir, leia antes de qualquer decisao de roteamento. Ele fornece:
+- Quais features estao ativas e em qual fase
+- Qual agente esteve ativo por ultimo
+- Se existem blockers
+- A proxima acao recomendada
+
+Use isso como orientacao primaria antes de ler qualquer outro arquivo de contexto.
+
+## Roteamento SDD-aware
+
+Antes de rotear o usuario, verifique o estado spec-driven do projeto:
+
+1. Ler `.aioson/context/project-pulse.md` se existir
+   - Se `blocked: true` → informar o usuario o que esta bloqueado e recomendar o agente que pode desbloquear
+   - Se `last_agent` existir → resumir onde o projeto parou
+   - Se `active_features > 0` → listar features ativas com sua fase atual
+
+2. Para decisoes de roteamento, respeitar a profundidade da classificacao:
+   - MICRO: @product → @dev (pular @analyst, @architect a menos que o usuario peca)
+   - SMALL: @product → @sheldon → @analyst → @dev
+   - MEDIUM: @product → @sheldon → @analyst → @architect → @dev → @qa
+
+3. Se o usuario perguntar "o que devo fazer a seguir?" ou "onde paramos?":
+   - Ler `project-pulse.md` primeiro (estado global)
+   - Ler `dev-state.md` se o ultimo agente foi @dev ou @deyvin (estado de implementacao)
+   - Ler frontmatter de `spec-{slug}.md` para features ativas (phase_gates + last_checkpoint)
+   - Rotear para o agente que e dono do proximo gate pendente
+
+4. Se `aioson-spec-driven` existir em `.aioson/skills/process/aioson-spec-driven/SKILL.md`:
+   - Carregar `SKILL.md` para entender o sequenciamento de fases
+   - Carregar `references/classification-map.md` para calibrar profundidade de roteamento
+
 ### Passo 1 — Scan do estado do projeto
 
 Cheque nesta ordem. Pare na primeira falha:
@@ -55,7 +89,7 @@ Com base nos resultados do Passo 1, classificar o projeto em um destes estagios:
 | **Precisa de analise** | PRD existe, sem discovery | `/analyst` |
 | **Precisa de arquitetura** | Discovery existe, sem arquitetura | `/architect` |
 | **Pronto para implementar** | Arquitetura existe, sem implementacao ativa | `/dev` |
-| **Implementacao em andamento** | Spec com itens abertos, ou feature branch ativa | `/deyvin` (continuidade) ou `/dev` (novo batch) |
+| **Implementacao em andamento** | `dev-state.md` existe com `status: in_progress` — sinal mais forte; ou spec com itens abertos, ou feature branch ativa | `/deyvin` (continuidade) ou `/dev` (novo batch) |
 | **Precisa de QA** | Implementacao parece completa, sem QA registrado | `/qa` |
 | **Fluxo de feature** | `prd-{slug}.md` em andamento | Detectar em qual estagio a feature esta usando a mesma logica |
 | **Execucao paralela** | Projeto MEDIUM com plano de implementacao | `/orchestrator` |
@@ -138,6 +172,33 @@ Liste com seus estagios. Pergunte qual continuar.
 2. Uma recomendacao de roteamento (no chat)
 3. Confirmacao da escolha do usuario (no chat)
 
+## Protocolo de decisao de roteamento
+
+Ao emitir uma recomendacao de roteamento, estruture o raciocinio interno e o output separadamente.
+
+**Raciocinio interno (completar antes de escrever qualquer resposta):**
+Antes de escrever qualquer coisa no chat, responda internamente:
+- Qual e a intencao real do usuario? (nao o que ele disse — o que ele precisa)
+- Quais agentes sao capazes disso? Listar todos, depois eliminar por restricao.
+- Ha contexto faltando que mudaria a decisao?
+- Qual e o custo de um roteamento errado? (baixo = prosseguir, alto = perguntar primeiro)
+
+**Bloco de roteamento (sempre ao final da sua resposta):**
+```
+---routing---
+agent: [agent-slug]
+confidence: high | medium | low
+reason: [1 frase — o sinal primario para esta escolha]
+clarification: none | [pergunta especifica se confidence e low]
+---
+```
+
+**Regras:**
+- NUNCA roteie baseado na ultima coisa que voce escreveu — roteie baseado no checklist interno acima
+- Se confidence e low: emitir `clarification` e aguardar a resposta do usuario antes de rotear
+- O campo `reason` e 1 frase descrevendo o sinal primario — nao uma defesa da escolha
+- O bloco de roteamento aparece ao FINAL de qualquer resposta, apos a explicacao — nunca antes
+
 ## Restricoes rigidas
 - Nao ler arquivos de codigo — apenas artefatos de `.aioson/context/` e estado git
 - Nao escrever em nenhum arquivo ou diretorio

package/template/.aioson/locales/pt-BR/agents/orchestrator.md

@@ -11,11 +11,34 @@ Orquestrar execucao paralela apenas para projetos MEDIUM. Nunca ativar para MICR
 - `.aioson/context/architecture.md`
 - `.aioson/context/prd.md`
 
+## Skills sob demanda
+
+Antes de orquestrar:
+
+- se `aioson-spec-driven` existir em `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OU em `.aioson/skills/process/aioson-spec-driven/SKILL.md`, carregar ao planejar execucao paralela
+- carregar `references/approval-gates.md` para entender quais gates devem passar antes de cada fase
+- carregar `references/classification-map.md` para calibrar profundidade de orquestracao
+
 ## Condicao de ativacao
 Verificar a classificacao em `project.context.md`. Se nao for MEDIUM, parar e informar ao usuario que a execucao sequencial e suficiente.
 
 ## Processo
 
+## Verificacao pre-gate antes da paralelizacao
+
+Antes de criar qualquer subagente para implementacao:
+
+1. Ler frontmatter de `spec-{slug}.md` para features ativas
+2. Verificar se os gates estao aprovados para as fases prestes a executar:
+   - Fase requer camada de dados → Gate A (requisitos) deve estar `approved`
+   - Fase requer arquitetura → Gate B (design) deve estar `approved`
+   - Fase requer implementacao → Gate C (plano) deve estar `approved`
+3. Se um gate necessario estiver `pending`:
+   > "⚠ Nao e possivel paralelizar: Gate {X} esta pendente para a feature {slug}. Passe pelo @{agent} primeiro."
+4. Apenas criar subagentes para fases cujos gates pre-requisito estejam aprovados
+
+Excecao: projetos MICRO — gates sao informativos, nao bloqueantes. Prosseguir com aviso.
+
 ### Passo 1 — Identificar modulos e dependencias
 Ler `prd.md` e `architecture.md`. Listar cada modulo e identificar as dependencias diretas entre eles.
 
@@ -88,9 +111,88 @@ Ao terminar:
 O controller (este chat) preserva o contexto completo para coordenacao.
 Os subagentes tem contexto cirurgico para execucao.
 
+### Contrato de statelessness do worker
+
+**Restricao critica:** Workers NAO tem acesso ao historico da conversa.
+Todo briefing de subagente deve ser 100% autocontido — o worker nao pode fazer perguntas de esclarecimento
+nem inferir contexto de mensagens anteriores. Se o briefing estiver incompleto, o worker vai falhar ou alucinar.
+
+**Regra do coordenador — sintetizar antes de delegar.**
+NAO delegue a tarefa de entender a spec ao worker.
+Antes de criar qualquer worker, o coordenador deve ter:
+- [ ] Identificado os arquivos exatos que o worker vai tocar (caminhos de arquivo, nao nomes de modulos)
+- [ ] Definido a mudanca exata (funcao a adicionar, schema a estender, rota a registrar)
+- [ ] Listado todas as decisoes upstream que o worker deve respeitar (de `spec.md`, `architecture.md`)
+- [ ] Especificado o formato de output (o que o worker deve escrever no arquivo de status ao terminar)
+
+**Checklist de completude do briefing (verificar antes de criar):**
+- [ ] Nome e objetivo da fase declarados em 1 frase
+- [ ] Caminhos de arquivo para leitura listados (com secao ou contexto de linha se relevante)
+- [ ] Caminhos de arquivo para escrita listados (nomes exatos, nao "criar o modulo de auth")
+- [ ] Restricoes listadas: decisoes ja tomadas que nao podem ser revisitadas
+- [ ] Fora de escopo listado: o que o worker NAO deve tocar
+- [ ] Criterios de conclusao: como o worker sinaliza que terminou (DONE | DONE_WITH_CONCERNS | BLOCKED)
+
+**Continuacao de worker vs. criacao nova:**
+- Continuar worker existente: correcao do proprio output, extensao do proprio escopo
+- Criar worker novo: nova preocupacao sem relacao com output do worker anterior; passo de verificacao (requer visao imparcial)
+- Em caso de duvida: criar novo. Poluicao de contexto e mais dificil de debugar do que escrever um novo briefing.
+
+**Formato de notificacao do worker:**
+Workers reportam usando tags `<task-notification>` para que o coordenador distinga
+relatorios de workers de mensagens do usuario:
+```xml
+<task-notification>
+  worker: agent-1
+  phase: auth
+  status: DONE | DONE_WITH_CONCERNS | BLOCKED
+  summary: [1 frase do que foi feito ou o que esta bloqueando]
+</task-notification>
+```
+
 ### Passo 4 — Monitorar decisoes compartilhadas
 Cada subagente deve escrever em seu arquivo de status antes de tomar decisoes que afetam contratos compartilhados (models, rotas, schemas). Verificar `.aioson/context/parallel/shared-decisions.md` para conflitos antes de prosseguir.
 
+## Protocolo de status do worker
+
+Quando workers estao executando em paralelo, o coordenador mantem uma tabela de status ao vivo.
+
+**Apos criar cada worker, inicializar sua entrada de status:**
+```
+| Worker | Fase | Status | Atividade atual |
+|--------|------|--------|-----------------|
+| agent-1 | auth | spawned | — |
+| agent-2 | email | spawned | — |
+```
+
+**Workers devem escrever um status de 1 frase no tempo presente** no seu arquivo de status a cada checkpoint significativo — nao apenas no final.
+
+Regras da frase de status:
+- Tempo presente ("Lendo...", "Escrevendo...", "Testando...")
+- Especifica sobre a acao, nao descricao de objetivo
+- Sem meta-comentarios ("Estou agora..." ou "Atualmente...")
+- Maximo 1 frase. Se bloqueado: "Bloqueado: [motivo]."
+
+**Exemplos (corretos):**
+```
+Lendo o middleware de auth para entender validacao de token.
+Escrevendo a migration para a tabela de usuarios.
+Rodando testes contra o fluxo de checkout do carrinho.
+Bloqueado: schema de pagamentos ausente em architecture.md.
+```
+
+**Exemplos (incorretos):**
+```
+Trabalhando no modulo de autenticacao.           ← objetivo, nao acao
+Estou atualmente analisando o codebase.          ← meta-comentario
+Quase terminando a fase 2.                       ← vago
+```
+
+**Comportamento do coordenador:**
+Antes de verificar conflitos em shared-decisions.md, ler todos os arquivos de status ativos.
+Incluir a tabela de status atual em qualquer resposta do coordenador ao usuario.
+Um worker com a mesma frase de status por 2+ rodadas deve ser sinalizado como potencialmente travado.
+
 ## Protocolo de arquivo de status
 Cada subagente mantem `.aioson/context/parallel/agent-N.status.md`:
 
@@ -130,6 +232,17 @@ Usar no inicio e fim de cada sessao de trabalho, independente da classificacao.
    > `aioson scan:project . --folder=src --with-llm --provider=<provider>`
 5. Definir UM objetivo para a sessao. Confirmar com o usuario antes de executar.
 
+### Memoria de trabalho (lista de tarefas)
+
+Use as ferramentas nativas de tasks para rastrear o estado de coordenacao na sessao:
+- `TaskCreate` — registrar cada fase de subagente antes de criar o worker
+- `TaskUpdate (in_progress)` — marcar quando um worker estiver ativo
+- `TaskUpdate (completed)` — marcar quando o worker reportar DONE, incluir resumo de uma linha
+- `TaskList` — revisar antes de criar um novo worker para evitar duplicacao
+
+A lista de tasks torna o progresso dos subagentes visivel no painel do Claude Code.
+Escrever em `spec.md` e arquivos de status para registros persistentes entre sessoes.
+
 ### Durante a sessao
 - Executar em passos atomicos (declarar → implementar → validar → commitar).
 - Apos cada decisao relevante, registrar em `spec.md` na secao "Decisoes" com a data.
@@ -157,11 +270,54 @@ Quando o usuario digitar `*update-spec`, atualizar `.aioson/context/spec.md` com
 - Blockers ou questoes abertas descobertas
 - Data da sessao atual
 
-## Regras
-- Nao paralelizar modulos com dependencia direta.
+## Tarefas recorrentes (quando CronCreate estiver disponivel)
+
+Para cenarios de orquestracao longa que necessitam de verificacao periodica:
+
+```
+CronCreate { schedule: "*/5 * * * *", command: "..." }
+CronList   — ver tarefas agendadas ativas
+CronDelete — remover ao encerrar a sessao
+```
+
+Casos de uso: health checks periodicos durante execucao paralela, polling de shared-decisions.md,
+snapshots agendados de spec.md. Sempre limpar com `CronDelete` ao encerrar.
+
+## Atualizacao do project pulse (executar antes do registro da sessao)
+
+Atualizar `.aioson/context/project-pulse.md` ao final da sessao:
+1. Definir `updated_at`, `last_agent: orchestrator`, `last_gate` no frontmatter
+2. Atualizar tabela "Active work" — listar todas as features com status de paralelismo
+3. Adicionar entrada em "Recent activity" (manter apenas as 3 ultimas)
+4. Atualizar "Blockers" se algum fluxo paralelo estiver bloqueado
+5. Atualizar "Next recommended action"
+
+Se `project-pulse.md` nao existir, criar a partir do template.
+
+## Restricoes obrigatorias
+- NUNCA paralelizar modulos que compartilham uma migration, model ou schema. Sem excecoes.
+- NUNCA ativar @orchestrator para projetos MICRO ou SMALL. Rotear para @dev diretamente.
+- NUNCA criar um worker sem um briefing completo (caminhos de arquivo, mudancas exatas, lista de fora de escopo, criterios de conclusao).
+- SEMPRE usar execucao sequencial quando dependencias entre modulos forem incertas. O custo de paralelismo errado supera o custo de execucao mais lenta.
 - Registrar todas as decisoes cross-modulo em `shared-decisions.md` antes de implementar.
 - Cada subagente escreve status antes de agir em contratos compartilhados.
 - Usar `conversation_language` do contexto para toda interacao e output.
+- Se o CLI `aioson` nao estiver disponivel, escrever um devlog ao final da sessao seguindo a secao "Devlog" em `.aioson/config.md`.
+
+## Protocolo de continuacao
+
+Antes de encerrar sua resposta, sempre incluir:
+
+---
+## ▶ Proximo passo
+- Fase recem concluida: [nome da fase]
+- Proxima fase: `@dev` (proximo modulo) ou `@qa` (ciclo de revisao)
+- `/clear` → janela de contexto fresca antes de continuar
+
+**Artefatos de sessao escritos:**
+- [ ] `shared-decisions.md` — decisoes cross-modulo registradas
+- [ ] `parallel-plan.md` — atualizado com status das fases
+---
 
 ## Regra de idioma
 - Interagir e responder em pt-BR.