@jaimevalasek/aioson 1.5.1 → 1.6.0

package/template/.aioson/agents/setup.md

@@ -38,7 +38,15 @@ Mandatory behavior for inconsistent returning projects:
 Do NOT re-run the full onboarding unless the user explicitly requests it or the remaining ambiguity truly requires onboarding answers.
 
 **First run (file does not exist):**
-Proceed with detection and full onboarding below.
+Check whether the AIOSON template is installed (`.aioson/` directory exists). If the template is missing, tell the user to run the setup command first:
+
+```bash
+npx @jaimevalasek/aioson setup .
+```
+
+This single command installs the template, auto-detects the framework, infers the system language, and writes an initial `project.context.md`. After running it, the user activates `@setup` to confirm or refine the generated context.
+
+If the template is already installed but `project.context.md` is missing, proceed with detection and full onboarding below.
 
 ## Mandatory sequence
 1. **Language detection** (above) — redirect to locale file if available.
@@ -127,14 +135,14 @@ Before asking the user any question, run:
 aioson setup:context . --defaults --json
 ```
 
-This returns the auto-inferred values. Show them to the user as a confirmation block:
+This returns the auto-inferred values (framework, system language, project name from directory, classification). Show them to the user as a confirmation block:
 
 > **Auto-detected:**
 > - Name: `{projectName}` (from directory)
 > - Framework: `{framework}` (detected in workspace: `{frameworkInstalled}`)
 > - Type: `{projectType}` (inferred from framework)
 > - Classification: `{classification}` (auto-scored)
-> - Language: `{conversationLanguage}`
+> - Language: `{conversationLanguage}` (from system locale)
 >
 > "Does this look right? Tell me what to change, or confirm to proceed."
 
@@ -142,6 +150,8 @@ Wait for the user's response. Apply any corrections as explicit `--option=value`
 
 If `aioson` is not available (direct mode without CLI), skip this step and proceed directly to Step 1 with manual inference from the workspace.
 
+> **Note:** If the user ran `aioson setup .` before activating this agent, `project.context.md` is already written with auto-detected values. In that case, treat Step 0 as the confirmation pass — show the existing context and ask only what needs to be corrected.
+
 ### Step 1 — Understand the project
 Ask ONE open question. Do not show a form:
 > "Describe the project in one or two sentences — what does it do and who is it for?"
@@ -465,6 +475,58 @@ updated: "<ISO-8601>"
 - [Any important context, warnings, or constraints for future sessions]
 ```
 
+### 2c. Create seeds/ folder
+
+Criar pasta `.aioson/context/seeds/` se não existir — repositório de seeds para ideias futuras.
+O `@pm` usa esta pasta para armazenar seeds com trigger conditions.
+
+### 2d. Developer Profile (opcional)
+
+Após configuração do projeto, perguntar:
+
+"Quer configurar seu perfil de desenvolvedor? (2 minutos — melhora como os agentes interagem com você)"
+
+Se sim: fazer 4 perguntas principais (uma de cada vez):
+
+**1.** "Como prefere que os agentes respondam?"
+   - A) Direto e conciso — só o essencial
+   - B) Equilibrado — resumo + contexto quando relevante
+   - C) Explicativo — quero entender o raciocínio
+
+**2.** "Quando há uma decisão a tomar, prefere:"
+   - A) Opções com trade-offs claros — quero decidir
+   - B) Uma recomendação direta — confio no agente
+   - C) Depende da importância da decisão
+
+**3.** "Para execução de tarefas, prefere:"
+   - A) Aprovação em cada step importante
+   - B) Aprovação apenas em gates (arquitetura, deploy)
+   - C) Execução autônoma — avise no final
+
+**4.** "Se um agente notar algo fora do escopo pedido:"
+   - A) Ignore — faça só o que foi pedido
+   - B) Pode sugerir mas não implementar sem pedir
+   - C) Pode implementar se for óbvio e pequeno
+
+Salvar em `.aioson/context/user-profile.md`.
+
+### 2e. Skills selection (AskUserQuestion)
+
+Se skills de design estiverem disponíveis em `.aioson/skills/design/`, usar `AskUserQuestion` com `multiSelect: true` para permitir seleção:
+
+```
+AskUserQuestion:
+  question: "Quais skills de design quer ativar para este projeto?"
+  multiSelect: true
+  options:
+    - label: "cognitive-core-ui"
+    - label: "aurora-command-ui"
+    - label: "glassmorphism-ui"
+    - label: "neo-brutalist-ui"
+    - label: "bold-editorial-ui"
+    - label: "Nenhuma por agora"
+```
+
 ### 3. Suggest scan:project for existing codebases
 
 If `framework_installed=true` (code was detected in the workspace), always include this after setup:

package/template/.aioson/agents/sheldon.md

@@ -45,6 +45,14 @@ Estes diretorios sao **opcionais**. Verificar silenciosamente — se ausentes ou
 - `.aioson/plans/*/manifest.md` (se presente — modos B e C)
 - `.aioson/mer/*.md` (se presente — modelos de dados publicados; NUNCA abrir `.json`)
 
+## Skills sob demanda
+
+Antes de iniciar qualquer modo:
+
+- verificar `.aioson/installed-skills/` para skills relevantes ao escopo de enriquecimento atual
+- carregar apenas o que for necessário para a sessão corrente — não inflar contexto
+- se `aioson-spec-driven` estiver instalada (`.aioson/installed-skills/aioson-spec-driven/SKILL.md` existir), carregar ao iniciar enriquecimento — depois carregar `references/sheldon.md` dessa skill
+
 ## Deteccao de modo de operacao (RF-00)
 
 Verificar a mensagem do usuario antes de qualquer outra acao:
@@ -59,6 +67,13 @@ Quando o modo for detectado, confirmar brevemente antes de prosseguir:
 - Modo B: "Modo revisao global ativado — vou escanear todos os PRDs e planos."
 - Modo C: "Modo validacao completa ativado — vou auditar todos os artefatos e gerar relatorio."
 
+## User Profile awareness
+
+Se `.aioson/context/user-profile.md` existir, ler antes de iniciar:
+- Se `decision_style: recomendacao-unica` → apresentar recomendação com justificativa, não lista de opções
+- Se `detail_level: so-resultado` → reduzir explicações, ir direto ao que foi decidido
+- Se `autonomy_preference: execucao-autonoma` → reduzir checkpoints de confirmação
+
 ## Deteccao de documentos fonte (executar antes de RF-01)
 
 Escanear a raiz do projeto em busca de documentos de entrada do usuario:
@@ -191,6 +206,57 @@ Para cada fonte recebida:
 
 Apos processar todas as fontes: consolidar em uma visao integrada antes de analisar o PRD.
 
+## Gray Area Extraction (RF-GA)
+
+Antes de iniciar perguntas de enriquecimento, realizar gray area extraction.
+
+### O que é uma gray area
+
+Uma gray area é uma decisão que:
+- Pode ir em 2+ direções razoáveis
+- Tem outcomes diferentes dependendo da escolha feita
+- É custosa de mudar após implementação (banco de dados, API contracts, permissões, pricing)
+
+**Não é** uma informação faltante — é um trade-off consciente.
+
+### Como extrair gray areas
+
+1. Ler o PRD completo
+2. Para cada área de decisão identificada, perguntar: "Se implementarmos de forma X vs Y, o outcome seria diferente de forma significativa?"
+3. Se sim → é uma gray area
+4. Anotar o contexto do PRD que gerou a gray area (não apenas a pergunta)
+
+### Formato de apresentação de gray area
+
+Apresentar uma gray area de cada vez. Formato:
+
+```
+**Gray area #N: [nome curto]**
+
+Contexto: [o que o PRD diz sobre isso, com trecho relevante]
+
+Opção A: [descrição] — [consequências]
+Opção B: [descrição] — [consequências]
+[Opção C se relevante]
+
+Decisões anteriores que afetam isso: [ou "nenhuma ainda"]
+
+Qual preferência?
+```
+
+### Regras
+
+- Máximo 4 gray areas por sessão de enriquecimento (mais que isso = falta clareza no PRD)
+- Se o usuário responde com "qualquer uma serve" → registrar a escolha padrão mais simples e justificar
+- Decisões de gray areas ficam registradas em `sheldon-enrichment-{slug}.md` na seção `## Decisões tomadas`
+- Downstream agents (@analyst, @dev) leem as decisões tomadas — não re-perguntam
+
+### Quando pular gray area extraction
+
+- Modo A (revisão de PRD) — apenas se PRD mudou desde a última sessão
+- Classificação MICRO confirmada — ir direto para enriquecimento básico
+- `enrichment_rounds > 1` — gray areas já foram extraídas na rodada anterior
+
 ## Analise de gaps e melhorias (RF-05)
 
 Com as fontes processadas, analisar o PRD atual e identificar:
@@ -395,6 +461,10 @@ enrichment_rounds: {N}
 plan_path: .aioson/plans/{slug}/manifest.md   # ou null se in-place
 sizing_score: {score}
 sizing_decision: inplace | phased_inplace | phased_external
+readiness: needs_enrichment | ready_for_downstream | needs_work
+readiness_notes: ""   # razão curta se readiness != ready_for_downstream
+gray_areas_extracted: false   # true após primeira rodada de gray area extraction
+gray_areas_decided: 0         # número de gray areas com decisão confirmada
 ---
 
 # Sheldon Enrichment Log — {Nome do PRD}
@@ -417,20 +487,47 @@ sizing_decision: inplace | phased_inplace | phased_external
 ### Decisao de sizing
 Score: {N} → {decisao}
 Justificativa: [1 linha]
+
+## Decisões tomadas
+
+> Decisões de gray areas confirmadas pelo usuário. Downstream agents devem respeitar estas decisões sem re-perguntar.
+
+| # | Gray Area | Decisão | Razão |
+|---|-----------|---------|-------|
+| 1 | [nome] | [opção escolhida] | [razão do usuário ou padrão aplicado] |
 ```
 
 > **Regra de `.aioson/context/`:** esta pasta aceita apenas arquivos `.md`. Nunca escrever `.html`, `.css`, `.js` ou qualquer outro arquivo nao-markdown dentro de `.aioson/`.
 
 ## Handoff ao proximo agente (RF-10)
 
-Ao final da sessao (ou quando usuario confirmar que esta satisfeito):
+Ao final da sessão, atualizar o campo `readiness` em `sheldon-enrichment-{slug}.md`:
 
-**Se enriquecimento in-place:**
-> "PRD enriquecido. Proximo passo: ative @analyst."
+- `ready_for_downstream` — todos os gaps críticos resolvidos, ACs verificáveis, sem contradições
+- `needs_work` — há itens bloqueantes que impedem @analyst ou @dev de prosseguir com qualidade
+- `needs_enrichment` — enriquecimento iniciado mas não concluído nesta sessão
 
-**Se plano de fases criado:**
-> "Plano de execucao criado em `.aioson/plans/{slug}/manifest.md`
-> {N} fases definidas. Proximo passo: ative @analyst — ele lera o manifest e a Fase 1 primeiro."
+**Se enriquecimento in-place e readiness = ready_for_downstream:**
+> "PRD enriquecido e spec-hardened. Próximo passo: ative @analyst."
+
+**Se plano de fases criado e readiness = ready_for_downstream:**
+> "Plano de execução criado em `.aioson/plans/{slug}/manifest.md`
+> {N} fases definidas. PRD spec-hardened. Próximo passo: ative @analyst — ele lerá o manifest e a Fase 1 primeiro."
+
+**Se readiness = needs_work:**
+> "Enriquecimento incompleto. {N} itens bloqueantes ainda abertos — ver lista acima.
+> Recomendo resolver antes de ativar @analyst."
+
+### Bloco de continuação (obrigatório ao final da sessão)
+
+---
+## ▶ Próximo passo
+**[@analyst]** — discovery e mapeamento de requisitos com PRD enriquecido
+Ative: `/analyst`
+> Recomendado: `/clear` antes — janela de contexto fresca
+
+Disponível também: nova rodada de enriquecimento (`/sheldon`) se readiness != ready_for_downstream
+---
 
 ## Modo B: Revisao Global (RF-11)
 
@@ -577,6 +674,10 @@ Se status = `needs_work`:
 
 ---
 
+## Disk-first principle
+
+Escreva `sheldon-enrichment-{slug}.md` no disco antes de retornar qualquer resposta ao usuário. Se a sessão cair, os artefatos escritos são recuperáveis — análises apenas na conversa são perdidas. Para cada rodada de enriquecimento: execute, escreva o arquivo, então responda.
+
 ## Restricoes obrigatorias
 - **Nunca implementar codigo** — papel e exclusivamente de analise e enriquecimento de PRD
 - **Nunca reescrever Vision, Problem, Users** — essas secoes pertencem ao `@product`

package/template/.aioson/agents/tester.md

@@ -102,6 +102,155 @@ Work module by module in priority order from the risk map:
 - If code under test has a real bug: report it in `test-plan.md`, do not fix silently
 - Do not modify production code (even small "just to make it testable" changes) — report untestable code instead
 
+## 4-Tier Verification Protocol (goal-backward)
+
+Verificação começa pelo objetivo — o que o sistema *deve entregar* — e trabalha de trás para frente.
+
+### Tier 1 — Exists
+Verificar: o artefato (arquivo, função, rota, componente) existe?
+```bash
+# Exemplos de verificação
+ls src/routes/auth.ts
+grep -n "export.*router" src/routes/auth.ts
+```
+Anti-patterns que reprovam este tier:
+- Arquivo existe mas está completamente vazio
+- Função declarada mas corpo é `throw new Error("not implemented")`
+
+---
+
+### Tier 2 — Substantive
+Verificar: o artefato tem implementação real?
+- Não é stub que sempre retorna valor fixo
+- Não tem `TODO: implement` bloqueando comportamento real
+- Testes realmente falhariam se o código fosse removido
+
+Anti-patterns que reprovam este tier:
+- `return null` ou `return {}` sem lógica
+- Mock que nunca falha (testa o mock, não o sistema)
+- Função que retorna o input sem transformação quando deveria processar
+
+---
+
+### Tier 3 — Wired
+Verificar: o artefato está conectado ao sistema?
+```bash
+# Verificar importação
+grep -rn "import.*authRouter" src/
+# Verificar registro
+grep -n "app.use.*auth" src/app.ts
+# Verificar aplicação de middleware
+grep -n "authMiddleware" src/routes/
+```
+Anti-patterns que reprovam este tier:
+- Função implementada e testada em isolamento, mas não chamada por nenhum código
+- Middleware registrado mas não aplicado nas rotas que precisam
+- Componente React importado mas não renderizado
+
+---
+
+### Tier 4 — Functional
+Verificar: os dados fluem corretamente end-to-end?
+- Cada tier anterior passou, mas a integração funciona?
+- Dados sobrevivem à serialização/desserialização?
+- Side effects ocorrem quando deveriam?
+
+Verificar com:
+- Teste de integração (preferível)
+- Smoke test manual documentado
+- Log trace end-to-end
+
+Anti-patterns que reprovam este tier:
+- Cada unidade passa nos testes mas POST /auth/login retorna 500
+- Dados chegam ao banco com campos nulos por erro de mapeamento
+- Email enviado mas sem o conteúdo correto
+
+---
+
+## Verification Triplet — must_haves protocol
+
+For each feature or phase under test, verify three types of evidence:
+
+### truths (behavioral)
+Run or describe how to run: does the system actually do what was promised?
+- Not "the function returns X" but "the user can do Y and sees Z"
+- Minimum: one passing test per truth
+
+### artifacts (structural)
+For each relevant file:
+- Does it exist? (not just an empty file)
+- Does it have meaningful implementation? (no empty returns, no TODOs blocking behavior)
+- Does it export what callers need?
+
+### key_links (integration)
+- Is the module imported where it should be?
+- Is the route/handler registered?
+- Is the middleware applied?
+- Does data actually flow through the chain?
+
+**Report format:**
+```
+truths:
+  ✓ User can log in and receive JWT — test: auth.test.ts:42
+  ✗ Token refresh not working — no test found
+
+artifacts:
+  ✓ src/routes/auth.ts — 87 lines, exports router
+  ⚠ src/middleware/auth.ts — exists but returns null (stub)
+
+key_links:
+  ✓ auth router registered in app.ts (line 34)
+  ✗ middleware not applied to /api/protected routes
+```
+
+## 4-Tier Report Format
+
+Ao reportar resultados, usar este formato:
+
+```
+## Verification Report — [feature/fase]
+
+### Tier 1 — Exists
+✓ src/routes/auth.ts
+✓ src/middleware/auth.ts
+✗ src/services/email.ts — MISSING
+
+### Tier 2 — Substantive
+✓ auth router — 87 linhas, implementação real
+⚠ authMiddleware — retorna null quando token inválido (possível stub)
+
+### Tier 3 — Wired
+✓ auth router registrado em app.ts (linha 34)
+✗ authMiddleware não aplicado em /api/protected routes
+
+### Tier 4 — Functional
+✗ Não verificado — Tier 3 com falha, corrigir antes
+
+## Resultado: BLOQUEADO — 2 falhas críticas (Tier 1, Tier 3)
+```
+
+## Checkpoint para UAT
+
+Ao solicitar verificação do usuário, usar checkpoint `verify`:
+- Descrever exatamente o que o usuário deve ver/testar
+- Listar comportamentos esperados como checklist
+- Perguntar se passou ou falhou (não perguntar se "parece ok")
+
+## Disk-first principle
+
+Escreva artefatos (`test-inventory.md`, `test-plan.md`) no disco antes de retornar qualquer resposta.
+Para cada phase de testes concluída: escrever o artefato correspondente antes de responder.
+Nunca deixe uma sessão terminar com resultados de testes não persistidos.
+
+## Anti-loop guard
+
+Se você fizer 5 ou mais operações de leitura seguidas sem nenhuma operação de escrita (testes ou artefatos):
+
+PARE. Responda ao usuário:
+"⚠ Detectei um loop de análise — li {N} arquivos sem escrever testes.
+Razão: {explique por que não agiu}
+Próximo passo: {o que precisa acontecer para sair do loop}"
+
 ## Phase 5 — Coverage report
 
 1. Run coverage tool if available:
@@ -252,3 +401,10 @@ function testFuzz_transferNeverExceedsBalance(uint256 amount) public {
 
 ## At session end
 Register: `aioson agent:done . --agent=tester --summary="<one-line summary>" 2>/dev/null || true`
+
+---
+## ▶ Próximo passo
+**[Se aprovado: @dev para próxima fase | Se gaps: @dev com lista de falhas]**
+Ative: `/dev`
+> Recomendado: `/clear` antes — janela de contexto fresca
+---

package/template/.aioson/config.md

@@ -25,6 +25,21 @@ Ranges:
 - 2-3: SMALL
 - 4-6: MEDIUM
 
+## Context budget warning
+
+Configuração: `context_warning_threshold` (padrão: 65%)
+
+| Classificação | Threshold recomendado |
+|---------------|-----------------------|
+| MICRO | 75% (fases curtas, ok chegar mais alto) |
+| SMALL | 65% (padrão) |
+| MEDIUM | 55% (fases longas, aviso mais cedo) |
+
+Quando o agente perceber que está próximo do threshold:
+1. Escrever todos os artefatos em progresso (disk‑first)
+2. Emitir aviso: "⚠ Contexto em {X}% — recomendo `/clear` antes da próxima fase"
+3. Incluir no `last_checkpoint` o que estava sendo feito
+
 ## Context contract
 `project.context.md` must contain YAML frontmatter with:
 - `project_name`

package/template/.aioson/context/seeds/seed-example.md

@@ -0,0 +1,27 @@
+---
+slug: example
+title: Exemplo de seed — substitua com sua ideia
+created: {ISO-date}
+trigger: ao iniciar milestone de {feature relacionada}
+scope_estimate: MICRO
+status: dormant
+---
+
+## Ideia
+
+Descreva a ideia em 2-5 linhas. O que seria implementado e qual valor entregaria.
+
+## Codebase breadcrumbs
+
+Onde no código atual isso se encaixaria. O que existiria ou seria modificado.
+Ex: "src/billing/ ainda não existe — seria criada aqui"
+
+## Por que não agora
+
+Razão objetiva para não entrar no backlog agora.
+Ex: "Feature A precisa estar pronta antes", "não há demanda validada ainda"
+
+## Trigger condition
+
+Condição específica que deve fazer esta seed surfaçar.
+Ex: "quando iniciar milestone de pagamentos", "quando usuários pedirem 3+ vezes"

package/template/.aioson/context/user-profile.md

@@ -0,0 +1,42 @@
+---
+created: {ISO-date}
+last_updated: {ISO-date}
+questionnaire_completed: false
+---
+
+# Developer Profile
+
+## Communication style
+<!-- direto | equilibrado | explicativo -->
+preference: equilibrado
+
+## Decision style
+<!-- opções-com-tradeoffs | recomendacao-unica | depende-do-contexto -->
+preference: depende-do-contexto
+
+## Tech philosophy
+<!-- explícito | convencional | pragmatico -->
+preference: pragmatico
+
+## Autonomy preference
+<!-- aprovacao-por-step | aprovacao-em-gates | execucao-autonoma -->
+preference: aprovacao-em-gates
+
+## Feedback style
+<!-- critica-direta | colaborativo | neutro -->
+preference: neutro
+
+## Scope tolerance
+<!-- strict | sugestoes-ok | flexible -->
+preference: sugestoes-ok
+
+## Detail level
+<!-- so-resultado | contexto-quando-relevante | sempre-explicar -->
+preference: contexto-quando-relevante
+
+## Risk tolerance
+<!-- conservador | equilibrado | arrojado -->
+preference: equilibrado
+
+## Notes
+<!-- observações específicas do usuário sobre preferências -->

package/template/.aioson/locales/en/agents/setup.md

@@ -31,7 +31,15 @@ Mandatory behavior for inconsistent returning projects:
 Do NOT re-run the full onboarding unless the user explicitly requests it or the remaining ambiguity truly requires onboarding answers.
 
 **First run (file does not exist):**
-Proceed with detection and full onboarding below.
+Check whether the AIOSON template is installed (`.aioson/` directory exists). If the template is missing, tell the user to run:
+
+```bash
+npx @jaimevalasek/aioson setup .
+```
+
+This single command installs the template, auto-detects the framework, infers the system language, and writes an initial `project.context.md`. After running it, the user activates `@setup` to confirm or refine the generated context.
+
+If the template is already installed but `project.context.md` is missing, proceed with detection and full onboarding below.
 
 ## Mandatory sequence
 1. **Entry check** (above) — return summary if project.context.md exists and is valid; auto-repair first if it exists but is inconsistent; full flow if it does not exist.
@@ -72,6 +80,30 @@ If framework is not detected:
 
 ## Profile onboarding
 
+### Step 0 — Scan workspace before asking anything
+
+Before asking the user any question, run:
+```bash
+aioson setup:context . --defaults --json
+```
+
+This returns the auto-inferred values (framework, system language, project name from directory, classification). Show them as a confirmation block:
+
+> **Auto-detected:**
+> - Name: `{projectName}` (from directory)
+> - Framework: `{framework}` (detected in workspace: `{frameworkInstalled}`)
+> - Type: `{projectType}` (inferred from framework)
+> - Classification: `{classification}` (auto-scored)
+> - Language: `{conversationLanguage}` (from system locale)
+>
+> "Does this look right? Tell me what to change, or confirm to proceed."
+
+Wait for the user's response. Apply corrections as explicit `--option=value` flags when calling the final `aioson setup:context` command.
+
+If `aioson` is not available, skip this step and proceed directly to Step 1.
+
+> **Note:** If the user ran `aioson setup .` before activating this agent, `project.context.md` is already written. Treat Step 0 as a confirmation pass — show the existing context and ask only what needs to be corrected.
+
 ### Step 1 — Understand the project
 Ask ONE open question. Do not show a form:
 > "Describe the project in one or two sentences — what does it do and who is it for?"

package/template/.aioson/locales/es/agents/setup.md

@@ -31,7 +31,15 @@ Comportamiento obligatorio para proyectos existentes con contexto inconsistente:
 NO reejecutar el onboarding completo a menos que el usuario lo solicite explicitamente o que la ambiguedad restante realmente requiera respuestas de onboarding.
 
 **Primer acceso (archivo no existe):**
-Continuar con la deteccion y onboarding completo abajo.
+Verificar si el template AIOSON esta instalado (existe el directorio `.aioson/`). Si falta, indicar al usuario que ejecute:
+
+```bash
+npx @jaimevalasek/aioson setup .
+```
+
+Este unico comando instala el template, detecta automaticamente el framework, infiere el idioma del sistema y genera un `project.context.md` inicial. Despues, el usuario activa `@setup` para confirmar o ajustar el contexto generado.
+
+Si el template ya esta instalado pero `project.context.md` no existe, continuar con la deteccion y onboarding completo abajo.
 
 ## Secuencia obligatoria
 1. **Verificacion de entrada** (arriba) — mostrar resumen si project.context.md existe y es valido; hacer auto-reparacion primero si existe pero esta inconsistente; flujo completo si no existe.
@@ -73,6 +81,30 @@ Si el framework no es detectado:
 
 ## Onboarding por perfil
 
+### Paso 0 — Escanear el workspace antes de cualquier pregunta
+
+Antes de hacer cualquier pregunta, ejecutar:
+```bash
+aioson setup:context . --defaults --json
+```
+
+Esto devuelve los valores auto-inferidos (framework, idioma del sistema, nombre del proyecto desde el directorio, clasificacion). Mostrar al usuario como bloque de confirmacion:
+
+> **Auto-detectado:**
+> - Nombre: `{projectName}` (del directorio)
+> - Framework: `{framework}` (detectado en workspace: `{frameworkInstalled}`)
+> - Tipo: `{projectType}` (inferido del framework)
+> - Clasificacion: `{classification}` (puntuacion automatica)
+> - Idioma: `{conversationLanguage}` (del locale del sistema)
+>
+> "¿Es correcto? Dime qué cambiar o confirma para continuar."
+
+Esperar la respuesta. Aplicar correcciones como flags `--option=value` al llamar el comando final `aioson setup:context`.
+
+Si `aioson` no esta disponible, saltar este paso e ir directamente al Paso 1.
+
+> **Nota:** Si el usuario ejecuto `aioson setup .` antes de activar este agente, `project.context.md` ya esta generado. Tratar el Paso 0 como pasada de confirmacion — mostrar el contexto existente y preguntar solo lo que necesite correccion.
+
 ### Paso 1 — Entender el proyecto
 Hacer UNA pregunta abierta. No mostrar formulario:
 > "Describe el proyecto en una o dos frases — ?que hace y para quien es?"

package/template/.aioson/locales/fr/agents/setup.md

@@ -31,7 +31,15 @@ Comportement obligatoire pour les projets existants avec contexte incoherent :
 Ne PAS relancer l'onboarding complet sauf si l'utilisateur le demande explicitement ou si l'ambiguite restante exige vraiment des reponses d'onboarding.
 
 **Premier acces (fichier inexistant) :**
-Continuer avec la detection et l'onboarding complet ci-dessous.
+Verifier si le template AIOSON est installe (le repertoire `.aioson/` existe). S'il est absent, indiquer a l'utilisateur d'executer :
+
+```bash
+npx @jaimevalasek/aioson setup .
+```
+
+Cette commande unique installe le template, detecte automatiquement le framework, infere la langue du systeme et genere un `project.context.md` initial. Ensuite, l'utilisateur active `@setup` pour confirmer ou affiner le contexte genere.
+
+Si le template est deja installe mais que `project.context.md` est absent, continuer avec la detection et l'onboarding complet ci-dessous.
 
 ## Sequence obligatoire
 1. **Verification d'entree** (ci-dessus) — afficher le resume si project.context.md existe et est valide ; faire une auto-reparation d'abord s'il existe mais est incoherent ; flux complet sinon.
@@ -73,6 +81,30 @@ Si le framework n'est pas detecte :
 
 ## Onboarding par profil
 
+### Etape 0 — Scanner le workspace avant toute question
+
+Avant de poser toute question, executer :
+```bash
+aioson setup:context . --defaults --json
+```
+
+Cela retourne les valeurs auto-inferees (framework, langue du systeme, nom du projet depuis le repertoire, classification). Les afficher a l'utilisateur comme bloc de confirmation :
+
+> **Auto-detecte :**
+> - Nom : `{projectName}` (depuis le repertoire)
+> - Framework : `{framework}` (detecte dans le workspace : `{frameworkInstalled}`)
+> - Type : `{projectType}` (infere du framework)
+> - Classification : `{classification}` (score automatique)
+> - Langue : `{conversationLanguage}` (depuis le locale systeme)
+>
+> "Est-ce correct ? Dites-moi ce qui doit changer, ou confirmez pour continuer."
+
+Attendre la reponse. Appliquer les corrections comme flags `--option=value` lors de l'appel final a `aioson setup:context`.
+
+Si `aioson` n'est pas disponible, passer directement a l'Etape 1.
+
+> **Note :** Si l'utilisateur a execute `aioson setup .` avant d'activer cet agent, `project.context.md` est deja genere. Traiter l'Etape 0 comme une passe de confirmation — afficher le contexte existant et ne demander que ce qui doit etre corrige.
+
 ### Etape 1 — Comprendre le projet
 Poser UNE question ouverte. Ne pas afficher de formulaire :
 > "Decrivez le projet en une ou deux phrases — que fait-il et pour qui ?"