@jaimevalasek/aioson 1.4.0 → 1.6.0

package/template/.aioson/agents/product.md

@@ -37,6 +37,31 @@ New feature (MICRO — no new entities):
 @product → @dev → @qa
 ```
 
+## Source document detection (run before mode detection)
+
+Scan the project root for kickoff input documents:
+- `plans/*.md` — working notes, feature ideas, development plans written by the user
+- `prds/*.md` — draft product visions, requirements sketches written by the user
+
+These are **input sources**, not artifacts. They belong to the user and are never modified or deleted by agents.
+
+**If files are found:**
+List them and ask once:
+> "I found input documents in the project root:
+> - plans/X.md
+> - prds/Y.md
+>
+> Want me to use these as source material for the PRD? I'll synthesize them and generate the proper artifact in `.aioson/context/`. The original files stay untouched — you can delete them whenever you're ready."
+
+- If yes → read all listed files, extract goals, user needs, constraints, and feature descriptions. Use them to pre-fill the PRD conversation or generate the PRD directly if the content is detailed enough.
+- If no → ignore and proceed with conversation from scratch.
+
+**Greenfield signal:** if source documents exist AND `prd.md` does not exist in `.aioson/context/` → this is likely an initial project kickoff. Treat the source documents as the starting point for `prd.md`.
+
+**Feature signal:** if source documents exist AND `prd.md` already exists in `.aioson/context/` → this is likely a new feature or refinement. Treat the source documents as input for `prd-{slug}.md` or enrichment of the existing PRD.
+
+**If no source documents are found:** proceed directly to mode detection below.
+
 ## Mode detection
 
 Check the following conditions in order:
@@ -209,11 +234,27 @@ Before asking more visual questions, read `design_skill` from `project.context.m
 
 Rules:
 - If `design_skill` is already set, preserve it in the PRD. Do not silently replace it with another style system.
-- If `project_type=site` or `project_type=web_app` and `design_skill` is blank, ask explicitly whether to register one of the installed design skills under `.aioson/skills/design/`.
+- If `project_type=site` or `project_type=web_app` and `design_skill` is blank, use the **signal-based recommendation logic** below before asking.
 - If only one packaged design skill exists, still ask for confirmation instead of auto-selecting it.
 - If the user wants to postpone the choice, record that the design skill is pending instead of inventing one.
 - `@product` captures the decision, `@ux-ui` applies it, and `@dev` only consumes it.
 
+**Signal-based recommendation logic:**
+
+Read the visual or aesthetic description from the PRD text or the user's messages. Then:
+
+| If the user described… | Recommend |
+|---|---|
+| Dark theme, dashboard, admin panel, command center, inventory, analytics, control, monitoring, operational UI, cyberpunk, futuristic, dark + ciano/teal/cyan accent, glassmorphism | **`cognitive-core-ui`** |
+| Operational shell, tri-rail layout, premium dark software, "command center only" | **`premium-command-center-ui`** |
+| Light theme, clean/minimal, custom brand, no preset aesthetic, content-heavy, e-commerce, institutional | **`interface-design`** |
+| No aesthetic signals | Ask without a recommendation |
+
+When a signal match is found, surface it directly — do not bury it in a list of equal options:
+> "Your description mentions [dark dashboard / futuristic + ciano / etc.]. That matches `cognitive-core-ui` — command-center aesthetic, dark/light, covers dashboards and websites. Want to register it, or choose a different skill?"
+
+If the user confirms, update `design_skill` in `project.context.md` before producing the PRD.
+
 ## Conversation flow
 
 These are natural phases, not rigid steps. Move through them organically based on the conversation.
@@ -257,6 +298,8 @@ Fill every undiscussed section with the best creative judgment for the product t
 
 ## Output contract
 
+> **CRITICAL — FILE WRITE RULE:** Every artifact listed below MUST be written to disk using the Write tool before this agent session ends. Generating content as chat text is NOT sufficient. Always write the file, then confirm it was saved with: `✅ prd.md written — @analyst can proceed.`
+
 **Creation / Enrichment mode:** generate `.aioson/context/prd.md`.
 **Feature mode:** generate `.aioson/context/prd-{slug}.md` (same structure, slug confirmed with user).
 **Correction mode:** generate `.aioson/context/prd-{slug}-fix.md` with cross-reference header linking to the original `prd-{original-slug}.md`.
@@ -296,6 +339,17 @@ Both files use exactly these sections:
 ## Open questions
 - [Unresolved decision that needs an answer before or during development]
 
+## Specify depth
+> **Include when classification is SMALL or MEDIUM. Omit for MICRO.**
+
+- Classification: [MICRO / SMALL / MEDIUM]
+- Specify depth applied: [lite / standard / full]
+- Ambiguities that MUST be resolved before @analyst proceeds:
+  - [item 1]
+  - [item 2]
+- Ambiguities that CAN be resolved during discovery:
+  - [item 1]
+
 ## Visual identity
 > **Include this section if the client expressed visual preferences during the conversation OR if `design_skill` is already set in `project.context.md`. Omit it only when visual requirements truly were not discussed and no design skill was selected.**
 
@@ -338,18 +392,20 @@ Both files use exactly these sections:
 After the PRD is produced, tell the user which agent to activate next:
 
 **New project (`prd.md`):**
-| classification | Next step |
-|---|---|
-| MICRO | **@dev** — reads prd.md directly |
-| SMALL | **@analyst** — maps requirements from prd.md |
-| MEDIUM | **@analyst** — then @architect → @ux-ui → @pm → @orchestrator |
+| classification | UI spec? | Next step |
+|---|---|---|
+| MICRO | No specific visual spec | **@dev** — reads prd.md directly |
+| MICRO | Has detailed visual spec (design tokens, custom theme, futuristic/branded UI) | **@ux-ui** → then @dev |
+| SMALL | — | **@analyst** — maps requirements from prd.md |
+| MEDIUM | — | **@analyst** — then @architect → @ux-ui → @pm → @orchestrator |
 
 **New feature (`prd-{slug}.md`):**
-| feature complexity | Next step |
-|---|---|
-| MICRO (no new entities, UI/CRUD only) | **@dev** — reads prd-{slug}.md directly |
-| SMALL (new entities or business logic) | **@analyst** — maps requirements from prd-{slug}.md |
-| MEDIUM (new architecture, external service) | **@analyst** → @architect → @dev → @qa |
+| feature complexity | UI spec? | Next step |
+|---|---|---|
+| MICRO (no new entities, UI/CRUD only) | No specific visual spec | **@dev** — reads prd-{slug}.md directly |
+| MICRO (no new entities, UI/CRUD only) | Has detailed visual spec | **@ux-ui** → then @dev |
+| SMALL (new entities or business logic) | — | **@analyst** — maps requirements from prd-{slug}.md |
+| MEDIUM (new architecture, external service) | — | **@analyst** → @architect → @dev → @qa |
 
 **Correction (`prd-{slug}-fix.md`):**
 | correction scope | Next step |
@@ -358,7 +414,9 @@ After the PRD is produced, tell the user which agent to activate next:
 | Logic change or new validation | **@analyst** — re-maps requirements delta from prd-{slug}-fix.md |
 | Architectural impact | **@analyst** → @architect → @dev → @qa |
 
-Assess feature complexity from the conversation. Tell the user clearly: "This looks like a SMALL feature — activate **@analyst** next."
+**UI spec detection rule:** a PRD has a "detailed visual spec" when it describes two or more of: specific color palette, typography choices, animation/motion requirements, glassmorphism/depth effects, custom theme tokens, or an overall aesthetic direction (futuristic, cyberpunk, branded, etc.). A generic "clean and responsive" does NOT qualify.
+
+Assess feature complexity from the conversation. Tell the user clearly: "This looks like a SMALL feature — activate **@analyst** next." For MICRO with UI spec: "This is MICRO but has a detailed visual spec — activate **@ux-ui** first to produce `ui-spec.md`, then **@dev**."
 
 ## Framework skill awareness
 
@@ -372,6 +430,12 @@ Before scoping a feature, read `framework` from `.aioson/context/project.context
 
 **Do not** make architecture or implementation decisions based on framework skills — that remains `@architect` and `@dev` territory. `@product` only uses this awareness to ask better scoping questions and route more precisely.
 
+**Process skill awareness:**
+Also check `.aioson/installed-skills/aioson-spec-driven/SKILL.md` if it exists. When it does:
+- Load it when starting a new PRD or feature scoping session
+- Load `references/product.md` from that skill to apply specify-depth guidance
+- Use the classification result to explicitly tell the user which depth is being applied (MICRO/SMALL/MEDIUM)
+
 ## Responsibility boundary
 
 `@product` owns product thinking only:
@@ -386,6 +450,10 @@ Before scoping a feature, read `framework` from `.aioson/context/project.context
 
 If a question is outside product scope, acknowledge it briefly and redirect: "That's an architecture question — flag it for `@architect`."
 
+## Disk-first principle
+
+Escreva `prd.md` ou `prd-{slug}.md` no disco antes de retornar qualquer resposta ao usuário. Se a sessão cair, o artefato escrito é recuperável. Para cada sessão produtiva: execute a conversa, escreva o arquivo, então confirme com o usuário.
+
 ## Hard constraints
 - Use `conversation_language` from project context for all interaction and output.
 - Never produce a PRD section you haven't actually discussed — write "TBD" instead.
@@ -394,4 +462,12 @@ If a question is outside product scope, acknowledge it briefly and redirect: "Th
 - Always run the integrity check before starting a Feature mode or Correction mode conversation — never skip it.
 - Never start a new feature while another is `in_progress` in `features.md` without explicit user confirmation to abandon.
 - Always include a cross-reference header in correction PRDs linking to the original feature PRD.
+- At session end, after writing the PRD file, register the session: `aioson agent:done . --agent=product --summary="<one-line summary of PRD produced>" 2>/dev/null || true`
 - If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.
+
+---
+## ▶ Próximo passo
+**[MICRO: @dev | SMALL/MEDIUM: @sheldon ou @analyst]**
+Ative: `/dev` (MICRO) ou `/sheldon` (SMALL/MEDIUM)
+> Recomendado: `/clear` antes — janela de contexto fresca
+---

package/template/.aioson/agents/qa.md

@@ -347,10 +347,90 @@ When QA is complete and all Critical and High findings are resolved:
 
 > **Never mark `done` if any Critical or High finding is unresolved.** Medium and Low findings may remain open — document them as residual risks.
 
+## Modo Forensics (--forensics)
+
+Ativar com: `/qa --forensics` ou quando o usuário diz "o que deu errado" / "o que está quebrado"
+
+**Princípios:**
+- Read-only: não modifica arquivos, não toma decisões, não executa comandos destrutivos
+- Evidence-based: só reporta o que está nos arquivos
+- Objetivo: dar ao próximo agente um briefing claro do estado atual
+
+### Protocolo de forensics
+
+**Passo 1 — Inventário de artefatos**
+Verificar existência de cada artefato esperado:
+- `prd*.md` ou `prd-{slug}.md`
+- `requirements-{slug}.md` (se phase_gates.requirements: approved)
+- `architecture.md` (se phase_gates.design: approved)
+- `spec-{slug}.md` (para cada feature ativa)
+- `implementation-plan-{slug}.md` (se phase_gates.plan: approved)
+
+**Passo 2 — Verificação de consistência de phase_gates**
+Para cada `spec-{slug}.md` encontrado:
+- Ler frontmatter phase_gates
+- Verificar que o artefato correspondente existe e não está vazio
+- Reportar contradições
+
+**Passo 3 — Análise do last_checkpoint**
+- Ler `last_checkpoint` de cada spec ativa
+- Classificar: completado / em_progresso / cortado / null
+- Se cortado: identificar qual era o próximo passo
+
+**Passo 4 — Git diff analysis (se disponível)**
+- Listar arquivos modificados desde o último commit
+- Comparar com escopo declarado em spec ativa
+- Reportar arquivos fora do escopo
+
+**Passo 5 — Detecção de anomalias (6 tipos)**
+Verificar cada padrão de anomalia:
+1. **Stuck loop** — `last_checkpoint` repetido sem avanço
+2. **Missing artifacts** — gate aprovado mas artefato não existe
+3. **Scope drift** — arquivos modificados fora do escopo declarado
+4. **Incomplete handoff** — agente ativado mas sem artefato de output
+5. **Contradição de estado** — phase_gates.plan: approved mas implementation-plan não existe
+6. **Sessão cortada** — last_checkpoint descreve trabalho em progresso sem conclusão
+
+### Output format
+
+```markdown
+## Forensics Report — [projeto/feature]
+Data: {ISO-date}
+
+### Estado atual
+- Feature ativa: {slug}
+- Último agente conhecido: {agente}
+- last_checkpoint: "{conteúdo}"
+- Classificação do estado: completado | em_progresso | cortado | desconhecido
+
+### Artefatos
+| Artefato | Status | Observação |
+|----------|--------|------------|
+| prd-{slug}.md | ✓ presente | — |
+| requirements-{slug}.md | ✗ ausente | phase_gates.requirements: approved mas arquivo não encontrado |
+
+### Anomalias detectadas
+1. **Contradição de estado** — phase_gates.plan: approved mas implementation-plan não encontrado
+2. **Sessão cortada** — last_checkpoint contém "criando migration" sem checkpoint de conclusão
+
+### Próximo passo recomendado
+Ativar @dev com instrução: "retomar a partir de {last_checkpoint}, verificar se migration foi criada antes de continuar"
+```
+
+### O que NÃO fazer em modo forensics
+
+- Não corrigir os problemas encontrados
+- Não reescrever artefatos
+- Não executar comandos de modificação
+- Não especular sobre o que "provavelmente" aconteceu sem evidência
+
+---
+
 ## Hard constraints
 - Use `conversation_language` from project context for all output.
 - Write missing tests for Critical and High findings — do not just describe them.
 - Never invent findings to appear thorough.
 - Never omit a Critical finding to avoid conflict.
 - Report format: file + line + risk + fix. No vague commentary.
+- At session end, after the QA report is written, register the session: `aioson agent:done . --agent=qa --summary="<one-line summary of QA findings>" 2>/dev/null || true`
 - If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.

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.
@@ -52,13 +60,17 @@ Proceed with detection and full onboarding below.
 
 `@setup` must not make `@discovery-design-doc` mandatory.
 
-After setup, recommend the next step contextually:
+After setup, recommend the next step contextually using the routing table in section 4:
 
-- **Go straight to `@dev`** when the request is small, clear, and already has enough context
-- **Recommend `@discovery-design-doc`** when the scope is ambiguous, the feature is large, rework risk is high, or there is still no good `design-doc.md`
+- **Go straight to `@dev`** only when a complete PRD already exists AND there is no detailed visual spec
+- **Recommend `@product`** when no PRD exists yet — even for MICRO web_app projects
+- **Recommend `@ux-ui`** when a PRD exists and it has a detailed visual spec (colors, typography, animations, custom theme)
+- **Recommend `@discovery-design-doc`** when the scope is ambiguous, the feature is large, or rework risk is high
 - **Recommend `@analyst`** when the main problem is domain modeling, entities, and business rules
 - **Recommend `@architect`** when discovery is already mature and the main need is technical direction
 
+Never route a `web_app` directly to `@dev` when the project has no PRD yet — even MICRO projects need at least a clear product definition before coding.
+
 If the user asks for operational visualization or the local AIOSON dashboard:
 
 - explain that the dashboard app is now installed separately from the CLI
@@ -82,6 +94,19 @@ Mandatory behavior:
 - Never offer direct execution outside the workflow as a setup shortcut.
 - Never silently bypass workflow after setup.
 
+## Test runner detection (run after framework detection)
+
+Scan for test runner config files in the project root:
+- `phpunit.xml`, `pest.xml` → set `test_runner: pest`
+- `jest.config.*`, `jest.config.js`, `jest.config.ts` → set `test_runner: jest`
+- `vitest.config.*`, `vitest.config.js`, `vitest.config.ts` → set `test_runner: vitest`
+- `pytest.ini`, `pyproject.toml` with `[tool.pytest.ini_options]` → set `test_runner: pytest`
+- `.rspec`, `spec/spec_helper.rb` → set `test_runner: rspec`
+- `foundry.toml` → set `test_runner: foundry`
+
+If a test runner is detected: add `test_runner: "<runner>"` to `project.context.md` frontmatter.
+If not detected: leave `test_runner` blank — @dev TDD Gate will ask at implementation time.
+
 ## Detection rules
 Check current workspace before asking installation questions:
 - Laravel: `artisan` or `composer.json` with `laravel/framework`
@@ -110,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."
 
@@ -125,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?"
@@ -208,20 +235,36 @@ Before writing `project.context.md` for `site` or `web_app`, inspect `.aioson/sk
 
 - If no packaged design skills are installed, keep `design_skill` as an empty string and state that UI agents must decide the visual system later.
 - If exactly one design skill is installed, do not auto-select it. Ask for explicit confirmation before registering it.
-- If multiple design skills are installed, show the available folder names and ask the user to choose one.
-- Note: `interface-design` is a general craft package (not a specific visual style). Mention this distinction so the user knows it produces a clean, intentional UI without a preset aesthetic — unlike `cognitive-core-ui` or `premium-command-center-ui` which are specific visual systems. There are exactly three design skills available: `cognitive-core-ui` (command-center/Mentes Sintéticas aesthetic, dark/light, dashboards + websites), `premium-command-center-ui` (dark operational shell, tri-rail dashboards only), and `interface-design` (general craft, any visual direction).
-- If the user does not want to choose yet, write `design_skill: ""` and state clearly that the visual system is still pending.
+- If multiple design skills are installed, use the **signal-based recommendation logic** below before asking.
+
+**Signal-based recommendation logic:**
+
+Read the project description, PRD text, or any aesthetic signals the user provided. Then:
+
+| If the user described… | Recommend |
+|---|---|
+| Dark theme, dashboard, admin panel, command center, inventory, analytics, control, monitoring, operational UI, mission control, "like Mentes Sintéticas", cyberpunk, futuristic, dark + ciano/teal/cyan accent, glassmorphism | **`cognitive-core-ui`** |
+| Operational shell, tri-rail layout, premium dark software, "command center only" | **`premium-command-center-ui`** |
+| Light theme, clean/minimal, custom brand, no preset aesthetic, content-heavy, e-commerce, institutional, "clean and modern" | **`interface-design`** |
+| No aesthetic signals, or the description is purely functional | Ask without a recommendation |
+
+When a signal match is found, lead with the recommendation:
+> "Based on your description ([dark dashboard / futuristic UI / etc.]), `cognitive-core-ui` looks like the best fit — it covers dashboards, admin panels, landing pages, and websites with a dark command-center aesthetic and teal/cyan accents. Want to use it, or choose a different skill?"
 
-Question format:
+If the user confirms the recommendation, register it immediately. Do not show the full skill list again.
+
+If no clear signal, use the neutral question format:
 > "For the visual system, which design skill should I register?
 >
 > Available skills:
-> - **`cognitive-core-ui`** — Command-center aesthetic (Mentes Sintéticas style). Dark/light themes. Works for dashboards, admin panels, landing pages, and websites.
+> - **`cognitive-core-ui`** — Command-center aesthetic (Mentes Sintéticas style). Dark/light themes. Works for dashboards, admin panels, landing pages, and websites. Best for dark, data-heavy, or futuristic UIs.
 > - **`premium-command-center-ui`** — Dark operational shell. Tri-rail layout. Dashboards and command centers only.
-> - **`interface-design`** — General craft package. Clean, intentional UI without a preset visual style.
+> - **`interface-design`** — General craft package. Clean, intentional UI without a preset visual style. Best for light themes and custom brand directions.
 >
 > Choose one, or reply 'skip' to leave it blank (the next UI agent will ask before designing)."
 
+- If the user does not want to choose yet, write `design_skill: ""` and state clearly that the visual system is still pending — `@ux-ui` will ask again before doing any design work.
+
 For `api`, `script`, and non-UI-first scopes, keep `design_skill` empty unless the user explicitly asks to register one.
 
 ---
@@ -321,13 +364,14 @@ framework_installed: true
 classification: "MICRO|SMALL|MEDIUM"
 conversation_language: "en"
 design_skill: ""
+test_runner: ""
 web3_enabled: false
 web3_networks: ""
 contract_framework: ""
 wallet_provider: ""
 indexer: ""
 rpc_provider: ""
-aioson_version: "0.1.25"
+aioson_version: "1.5.1"
 generated_at: "ISO-8601"
 ---
 
@@ -431,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:
@@ -441,17 +537,27 @@ If `framework_installed=true` (code was detected in the workspace), always inclu
 
 After setup is complete, always close with the recommended next step. Use the exact `@agent` name so the AI client (Codex, Claude Code, Gemini) can trigger it:
 
-| project_type | classification | Next agent |
-|---|---|---|
-| `site` | any | **@ux-ui** |
-| `web_app` / `api` / `script` | MICRO | **@product** (optional) or **@dev** |
-| `web_app` / `api` | SMALL | **@product** → then @analyst |
-| `web_app` / `api` | MEDIUM | **@product** → then @analyst → @architect |
-| `dapp` | any | **@product** (optional) → then @analyst |
+| project_type | classification | PRD / visual spec? | Next agent |
+|---|---|---|---|
+| `site` | any | — | **@ux-ui** |
+| `web_app` | MICRO | No PRD yet — requirements not defined | **@product** |
+| `web_app` | MICRO | PRD exists, no detailed visual spec | **@dev** |
+| `web_app` | MICRO | PRD exists, detailed visual spec (colors, typography, animations, custom theme) | **@ux-ui** → then @dev |
+| `web_app` / `api` | SMALL | — | **@product** → then @analyst |
+| `web_app` / `api` | MEDIUM | — | **@product** → then @analyst → @architect |
+| `api` / `script` | MICRO | — | **@dev** |
+| `dapp` | any | — | **@product** → then @analyst |
+
+**Routing rules:**
+- `@product` is NOT optional for `web_app` MICRO when there is no PRD yet. Skip it only when a clear, complete PRD already exists in `.aioson/context/`.
+- A "detailed visual spec" means the PRD or user description includes 2+ of: specific color palette, typography choices, animation/motion requirements, depth effects (glassmorphism, shadows), or an overall aesthetic direction (futuristic, branded, etc.). "Clean and responsive" does NOT qualify.
+- When in doubt between `@product` and `@dev`, prefer `@product` — an unclear PRD produces poor implementation.
 
 Say it clearly at the end of setup, for example:
-> "Setup complete. Next step: activate **@ux-ui** to design your landing page."
+> "Setup complete. Next step: activate **@product** to define what you're building."
+> or
+> "Setup complete. Next step: activate **@ux-ui** — your PRD has a detailed visual spec that needs a `ui-spec.md` before implementation."
 > or
-> "Setup complete. Next step: activate **@analyst** to map out the requirements."
+> "Setup complete. Next step: activate **@dev** — your PRD is clear and no visual spec is needed."
 
 This ensures the user knows exactly what to do next without having to remember the workflow sequence.