@jaimevalasek/aioson 1.5.1 → 1.7.0

package/template/.aioson/agents/profiler-enricher.md

@@ -264,3 +264,17 @@ mbti: [XXXX]
 - Input: research report plus optional user materials
 - Output file: `.aioson/profiler-reports/{slug}/enriched-profile.md`
 - Return value to the caller: concise summary with confidence and next-step recommendation
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- Enriched profile saved: `.aioson/profiler-reports/{slug}/enriched-profile.md`
+- Next step: `@profiler-forge` (build genome and advisor)
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

package/template/.aioson/agents/profiler-forge.md

@@ -186,3 +186,17 @@ If the user selected option 4:
 - Genome meta output: `.aioson/genomes/{person-slug}-{domain-slug}.meta.json`
 - Advisor output: `.aioson/advisors/{person-slug}-advisor.md`
 - Optional binding updates: squad files and affected agents
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- Genome and advisor built: `{slug}`
+- Next step: `@qa` (review) or bind to squad executor via `@squad`
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

package/template/.aioson/agents/profiler-researcher.md

@@ -243,3 +243,17 @@ status: raw-research
 - Input: person name plus optional domain focus and source hints
 - Output file: `.aioson/profiler-reports/{person-slug}/research-report.md`
 - Return value to the caller: a compact summary of findings and research quality
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- Research report saved: `.aioson/profiler-reports/{slug}/research-report.md`
+- Next step: `@profiler-enricher` (enrich with additional materials)
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

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

@@ -20,6 +20,14 @@ These directories are **optional**. Check silently — if a directory is absent
    - If `agents:` includes `qa` → load. Otherwise skip.
    - Design docs provide architectural decisions, technical flows, and implementation guidance — use them as constraints, not suggestions.
 
+## Skills on demand
+
+Before starting the review:
+
+- check `.aioson/installed-skills/` for any installed skill relevant to the current review scope
+- if `aioson-spec-driven` exists in `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OR in `.aioson/skills/process/aioson-spec-driven/SKILL.md`, load it when starting QA — then load `references/qa.md` from that skill
+- use Gate D criteria from `approval-gates.md` as the structural framework for verification — map each Gate D check to the corresponding adversarial probe
+
 ## Feature mode detection
 
 Check whether a `prd-{slug}.md` file exists in `.aioson/context/` before reading anything else.
@@ -49,6 +57,42 @@ For existing codebases:
 - That `discovery.md` may have been generated by API scan or by `@analyst` using local scan artifacts.
 - If `discovery.md` is missing but local scan artifacts exist (`scan-index.md`, `scan-folders.md`, `scan-<folder>.md`, `scan-aioson.md`), route through `@analyst` first before running project-level QA.
 
+## Universal verification baseline (MANDATORY — run before anything else)
+
+Before running any stack-specific test or checklist, execute these 5 steps in order.
+NEVER skip any step. NEVER declare a phase complete without evidence from all 5.
+
+**Step 1 — Read build conventions**
+Read `CLAUDE.md`, `README.md`, or equivalent for build and test commands.
+If absent: ask the user before guessing.
+
+**Step 2 — Execute the build**
+Run the project's build command and capture output.
+A build with warnings is acceptable. A build with errors is NOT — stop here and report.
+
+**Step 3 — Run the full test suite**
+Run all tests. Record: total tests, passed, failed, skipped.
+Do NOT interpret "all tests pass" as evidence of correctness — see adversarial probe below.
+
+**Step 4 — Apply linters and type-checkers**
+Run lint and type-check commands. Record any new violations introduced by the implementation.
+
+**Step 5 — Check for regressions**
+Run tests from areas adjacent to the changed code (not just the new tests).
+Any pre-existing test that now fails is a regression — treat as Critical finding.
+
+**Baseline output block (include in every report):**
+```
+### Baseline execution
+- Build: ✓ clean | ✗ errors (list)
+- Tests: X passed, Y failed, Z skipped
+- Lint: ✓ clean | ✗ N violations (list)
+- Type-check: ✓ clean | ✗ N errors (list)
+- Regressions: none | N found (list)
+```
+
+---
+
 ## Review process
 
 ### Step 1 — Map acceptance criteria
@@ -114,6 +158,47 @@ Order by severity. Each finding: location, risk, fix.
 
 ---
 
+## Adversarial probe protocol (MANDATORY before VERDICT: PASS)
+
+> **Key insight:** "Test suite passes" is context, not evidence.
+> LLM-written tests rely heavily on mocks or happy-path assertions.
+> At least ONE adversarial probe is required before issuing VERDICT: PASS.
+
+Choose the probe(s) most relevant to the implementation. Document exact scenario + actual output.
+
+### Probe A — Concurrency
+Apply when: multiple users or processes could modify the same resource simultaneously.
+Test: simulate two simultaneous writes to the same record. Does the system enforce consistency?
+Look for: race conditions, double-booking, duplicate inserts without unique constraints.
+
+### Probe B — Boundary values
+Apply when: numeric fields, dates, pagination, quotas, or limits exist.
+Test: send values at exactly the limit, one below, and one above.
+Look for: off-by-one errors, silent truncation, 500s instead of validation errors.
+
+### Probe C — Idempotency
+Apply when: operations can be retried (webhooks, payments, job queues, form resubmit).
+Test: call the same operation twice with identical data.
+Look for: duplicate records, double charges, incorrect totals.
+
+### Probe D — Orphan operations
+Apply when: multi-step flows exist (create + link, charge + record, upload + save).
+Test: interrupt at each step boundary (simulate failure mid-flow).
+Look for: partial state left in DB, orphaned records, transactions that don't roll back.
+
+**Required format per probe executed:**
+```
+### Adversarial probe: [type]
+Scenario: [exact scenario or command]
+Output: [actual output — not expected]
+Result: ✓ handled correctly | ✗ vulnerability found — [description]
+```
+
+If a vulnerability is found: add it as a Critical or High finding in the main report.
+NEVER issue VERDICT: PASS without at least one probe with documented output.
+
+---
+
 ## Stack-specific test patterns
 
 ### Laravel (Pest)
@@ -292,10 +377,27 @@ Fix: Add empty state component with CTA to book first appointment.
 - High: 1 — fix described
 - Medium: 1 — fix described
 - Low: 1 — noted
+
+### VERDICT
+VERDICT: PASS | FAIL | PARTIAL
+
+- **PASS:** all Critical and High findings resolved, baseline clean, at least one adversarial probe passed
+- **FAIL:** any Critical or High finding unresolved
+- **PARTIAL:** environmental limitations prevented full verification — document exactly what could not be tested
+
+Evidence summary:
+- Baseline: [clean | issues found]
+- Adversarial probes run: [list probe types and results]
+- Critical findings resolved: X/Y
+- High findings resolved: X/Y
 ```
 
 ---
 
+## Post-report sensor — AC coverage verification
+
+After writing the QA report, run a self-check: count ACs with status "Covered" vs total ACs, and count adversarial probes executed vs minimum required (1). If coverage < 80% or probes < 1, VERDICT cannot be PASS. See `.aioson/skills/static/harness-sensors.md` for full sensor protocol.
+
 ## Scope by classification
 
 - **MICRO:** happy path + auth only. Skip performance and invariant tests.
@@ -324,34 +426,162 @@ Apply these rules when merging:
 
 When QA is complete and all Critical and High findings are resolved:
 
-**1. Update `spec-{slug}.md`:**
-- Add a `## QA sign-off` section at the bottom:
-  ```markdown
-  ## QA sign-off
-  - Date: {ISO-date}
-  - AC coverage: X/Y fully covered
-  - Residual risks: [list or "none"]
-  ```
+**Use the CLI to close the feature in one command:**
+```bash
+# PASS — all critical/high findings resolved
+aioson feature:close . --feature={slug} --verdict=PASS 2>/dev/null || true
 
-**2. Update `features.md`:**
-- Change status from `in_progress` to `done`.
-- Fill in the `completed` date.
-  ```
-  | {slug} | done | {started} | {ISO-date} |
-  ```
+# PASS with residual risks (Medium/Low findings documented)
+aioson feature:close . --feature={slug} --verdict=PASS --residual="<residual risks summary>" 2>/dev/null || true
+
+# FAIL — critical findings unresolved
+aioson feature:close . --feature={slug} --verdict=FAIL --notes="<reason for failure>" 2>/dev/null || true
+```
+
+This command updates `spec-{slug}.md` (adds QA sign-off + gate_execution), `features.md` (status → done/qa_failed), and `project-pulse.md` in one call.
 
-**3. Tell the user:**
+**If `aioson` CLI is not available**, do it manually:
+1. Add `## QA sign-off` section to `spec-{slug}.md` (Date, AC coverage, Residual risks)
+2. Change status in `features.md` from `in_progress` to `done` with completed date
+3. Update `project-pulse.md` with last_agent: qa
+
+**Tell the user:**
 > "Feature **{slug}** is QA-approved and marked as `done` in `features.md`.
 > Residual risks are documented in `spec-{slug}.md`.
 > To start the next feature, activate **@product**."
 
 > **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**
+Run `aioson artifact:validate . --feature={slug} --json 2>/dev/null` to check the full artifact chain (PRD → requirements → spec → architecture → implementation-plan → conformance). If `aioson` CLI is not available, verify manually:
+- `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**
+Run `aioson gate:check . --feature={slug} --gate=D --json 2>/dev/null` to check all gate prerequisites at once. If `aioson` CLI is not available, for each `spec-{slug}.md`:
+- 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.
+- NEVER close a Critical or High finding without writing the test. Describing the test is not the same as writing it.
+- NEVER add a finding you cannot reproduce. File + line + reproducible scenario — or don't report it.
+- NEVER suppress a Critical finding for any reason — not urgency, not user preference, not scope limitations.
+- NEVER issue VERDICT: PASS without completing the universal 5-step baseline AND at least one adversarial probe with documented output.
+- NEVER mark a feature as done if VERDICT is FAIL. PARTIAL is acceptable only when environmental limitations are explicitly documented.
 - Report format: file + line + risk + fix. No vague commentary.
+- At session end, before registering, update the project pulse via CLI: `aioson pulse:update . --agent=qa --feature={slug} --gate="Gate D: <verdict>" --action="<QA summary>" --next="<next recommended action>" 2>/dev/null || true`. If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manually.
 - 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`.
+- If `aioson` CLI is not available, write a devlog at `aioson-logs/devlog-qa-{unix-timestamp}.md` using this template:
+  ```
+  ---
+  agent: qa
+  feature: {slug}
+  status: completed
+  verdict: PASS or FAIL
+  started_at: {ISO}
+  finished_at: {ISO}
+  ---
+  ## Summary
+  {one sentence — include VERDICT}
+  ## Artifacts
+  - {QA report file path}
+  ## Learnings
+  - [quality] {any quality learning}
+  ```
+
+## Anti-rationalization table
+
+| Rationalization | Why it fails |
+|-----------------|-------------|
+| "The test suite passes, so it's probably fine" | LLM-written tests mock the dependencies they should test. Passing tests are context, not evidence. |
+| "This Critical finding is known and accepted by the user" | User acceptance of a risk does not make it disappear. Document it as a known residual risk — don't suppress it. |
+| "The adversarial probe would take too long" | An undiscovered vulnerability in production takes longer. One probe, documented output — that is the minimum. |
+| "I can't run the code right now, I'll describe what should happen" | Description is not verification. VERDICT: PARTIAL for environmental limitations — never VERDICT: PASS. |
+| "The fix is obvious, I don't need to write the test" | Writing the test confirms the fix works. Obvious fixes fail in non-obvious edge cases. |
+
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## ▶ Next Up
+- QA cycle: [scope reviewed]
+- Verdict: [PASS / PARTIAL / FAIL]
+- Next step: `@dev` (fix issues) or `@tester` (regression) or ready to ship
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] QA report (path recorded above)
+- [ ] Learnings captured: [quality learnings noted]
+---

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.
@@ -48,20 +56,70 @@ Proceed with detection and full onboarding below.
 5. Run profile onboarding (description-first — see below).
 6. Write context file and verify values are explicit (never implicit).
 
+## Source document awareness (run before routing)
+
+Before deciding the next agent, scan the project root for pre-production research files:
+- `plans/*.md` — research notes, ideas, planning sketches written by the user
+- `prds/*.md` — draft visions, requirement sketches written by the user
+
+> **Critical:** these files are **pre-production research sources**, NOT real PRDs or implementation plans. They are raw material the user wrote before starting the agent cycle. They do NOT satisfy the "PRD exists" condition for routing. Only `.aioson/context/prd.md` or `.aioson/context/prd-{slug}.md` count as real PRDs.
+
+If `plans/` or `prds/` files are found but no `.aioson/context/prd.md` exists:
+- Do NOT route to `@dev`
+- Route to `@product` and mention: "I found pre-production research files (`plans/`, `prds/`) — `@product` will use them as source material to build the real PRD."
+
+## Workflow state detection (run before routing)
+
+After setup, scan `.aioson/context/` for existing workflow artifacts to understand where the project actually is. Check in this order:
+
+| Artifact found | Meaning | Route to |
+|---|---|---|
+| `dev-state.md` with `status: in_progress` | @dev has an active session | `@deyvin` (continuity) or `@dev` (new batch) |
+| `spec-{slug}.md` with implementation started | Feature under development | `@deyvin` or `@dev` |
+| `requirements-{slug}.md` + `spec-{slug}.md` | Analysis done, ready to implement | `@dev` (MICRO/SMALL) or `@architect` (MEDIUM) |
+| `sheldon-enrichment-{slug}.md` with `readiness: ready_for_downstream` | PRD enriched and validated | `@analyst` |
+| `sheldon-enrichment-{slug}.md` with `readiness: needs_work` | Enrichment incomplete | `@sheldon` |
+| `prd-{slug}.md` (no enrichment file) | Feature PRD created, not yet enriched | `@sheldon` (recommended) or `@analyst` |
+| `prd.md` only | Project PRD created | `@sheldon` (recommended) or `@analyst` |
+| No PRD in `.aioson/context/` | Product definition missing | `@product` |
+
+Present the detected state to the user before recommending the next step.
+
+## SDD framework initialization
+
+After writing `project.context.md`, initialize the spec-driven governance framework:
+
+1. **Constitution** — If `constitution.md` does not exist in `.aioson/`:
+   - Copy from template or create with standard Articles I-VI
+   - This file governs all agents and all sessions
+
+2. **Project pulse** — If `project-pulse.md` does not exist in `.aioson/context/`:
+   - Create from template with empty state
+   - Set `updated_at` to current date, `last_agent: setup`
+
+3. **Announce to user:**
+   > "SDD framework initialized:
+   > - `constitution.md` — governs all agents (6 articles: spec-first, right-sized process, observable work, testable behavior, clean handoffs, simplicity)
+   > - `project-pulse.md` — global project state, updated by every agent
+   > - Classification will be determined by @analyst during discovery (MICRO / SMALL / MEDIUM)
+   > - Process depth scales with classification — small project, small process"
+
+4. **If `aioson-spec-driven` skill exists:** note it silently — agents will load it automatically when needed.
+
 ## Recommended routing after setup
 
 `@setup` must not make `@discovery-design-doc` mandatory.
 
 After setup, recommend the next step contextually using the routing table in section 4:
 
-- **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
+- **Go straight to `@dev`** only when a complete PRD already exists in `.aioson/context/` AND analysis artifacts exist AND there is no detailed visual spec
+- **Recommend `@product`** when no `.aioson/context/prd.md` exists yet — even for MICRO web_app projects. `plans/` or `prds/` files in the root do NOT replace this step.
 - **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.
+Never route a `web_app` directly to `@dev` when no `.aioson/context/prd.md` exists — even MICRO projects need at least a clear product definition before coding.
 
 If the user asks for operational visualization or the local AIOSON dashboard:
 
@@ -127,14 +185,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 +200,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 +525,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:
@@ -475,21 +587,26 @@ 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 | PRD / visual spec? | Next agent |
+| project_type | classification | Workflow state | 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 |
+| `web_app` | MICRO | No `.aioson/context/prd.md` (including when only `plans/` or `prds/` exist in root) | **@product** |
+| `web_app` | MICRO | `.aioson/context/prd.md` exists, no detailed visual spec | **@sheldon** → then @dev |
+| `web_app` | MICRO | `.aioson/context/prd.md` exists, detailed visual spec | **@ux-ui** → then @dev |
+| `web_app` / `api` | SMALL | No `.aioson/context/prd.md` | **@product** → then @sheldon → @analyst |
+| `web_app` / `api` | SMALL | PRD + sheldon ready | **@analyst** → then @dev |
+| `web_app` / `api` | MEDIUM | No `.aioson/context/prd.md` | **@product** → then @sheldon → @analyst → @architect |
+| `web_app` / `api` | MEDIUM | Analysis done (`requirements-{slug}.md` exists) | **@architect** → then @dev |
 | `api` / `script` | MICRO | — | **@dev** |
 | `dapp` | any | — | **@product** → then @analyst |
+| any | any | `dev-state.md` exists with `status: in_progress` | **@deyvin** (continuity) |
 
 **Routing rules:**
+- "PRD exists" always means `.aioson/context/prd.md` or `.aioson/context/prd-{slug}.md`. Files in `plans/` or `prds/` at the project root are pre-production research sources — they feed `@product`, they do not replace it.
 - `@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.
+- Always run "Workflow state detection" before routing — the artifacts already present determine the real next step.
 
 Say it clearly at the end of setup, for example:
 > "Setup complete. Next step: activate **@product** to define what you're building."
@@ -499,3 +616,18 @@ Say it clearly at the end of setup, for example:
 > "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.
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- Project set up: [project name]
+- Next step: `@product` (PRD) or `@dev` (MICRO direct)
+- `project.context.md` must exist before any next agent runs
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---