@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/skills/process/aioson-spec-driven/references/hardening-lane.md

@@ -1,49 +1,49 @@
-# Hardening Lane — From Exploration to Reliable Execution
-
-> Use when input is vague, exploratory, or "vibe-style" and needs to be converted into a spec pack before implementation.
-
-## Two lanes
-
-### Lane 1 — Exploration / Vibe
-- Goal: discover value, direction, and feasibility
-- Tolerates: back-and-forth, open questions, incomplete scope
-- Good for: MVPs, ideas, experiments, early discovery
-- Output: notes, rough PRD, conversation log
-
-### Lane 2 — Spec Hardening
-- Goal: convert exploration into reliable, maintainable execution
-- Requires: requirements, design decisions, checkpoints, and tests
-- Good for: code that will survive, grow, and be maintained
-- Output: spec pack (PRD + requirements + architecture + implementation plan)
-
-**AIOSON's identity is Lane 2.** It does not compete with vibe coding — it is the hardening layer that converts exploration into software that works in production.
-
-## When to harden
-
-Harden before coding when ANY of these are true:
-- The feature involves new entities or database changes
-- The feature integrates with an external service
-- Multiple user types are involved
-- The behavior in error or edge cases matters for production quality
-- Another developer (or AI session) will need to continue this work later
-
-Skip hardening (go direct from PRD to @dev) ONLY when:
-- Classification is confirmed MICRO
-- No new entities, no integrations, pure UI/CRUD
-- The full spec can fit in one session context without losing state
-
-## Signals that input is in vibe mode (not yet hardenable)
-
-- "I want something like X" without defining what X actually does
-- Requirements expressed as UI descriptions ("there should be a button that does Y")
-- No mention of what happens when things go wrong
-- No mention of who can do what (permissions, roles)
-- Scope keeps expanding during the conversation
-
-## What to do when input is in vibe mode
-
-Do not start implementation. Instead:
-1. Acknowledge: "This is still in exploration mode — let's harden it before coding."
-2. Route to @product if no PRD exists yet.
-3. Route to @sheldon if PRD exists but has gaps.
-4. Only proceed to @analyst / @architect / @dev after Gate A is passed.
+# Hardening Lane — From Exploration to Reliable Execution
+
+> Use when input is vague, exploratory, or "vibe-style" and needs to be converted into a spec pack before implementation.
+
+## Two lanes
+
+### Lane 1 — Exploration / Vibe
+- Goal: discover value, direction, and feasibility
+- Tolerates: back-and-forth, open questions, incomplete scope
+- Good for: MVPs, ideas, experiments, early discovery
+- Output: notes, rough PRD, conversation log
+
+### Lane 2 — Spec Hardening
+- Goal: convert exploration into reliable, maintainable execution
+- Requires: requirements, design decisions, checkpoints, and tests
+- Good for: code that will survive, grow, and be maintained
+- Output: spec pack (PRD + requirements + architecture + implementation plan)
+
+**AIOSON's identity is Lane 2.** It does not compete with vibe coding — it is the hardening layer that converts exploration into software that works in production.
+
+## When to harden
+
+Harden before coding when ANY of these are true:
+- The feature involves new entities or database changes
+- The feature integrates with an external service
+- Multiple user types are involved
+- The behavior in error or edge cases matters for production quality
+- Another developer (or AI session) will need to continue this work later
+
+Skip hardening (go direct from PRD to @dev) ONLY when:
+- Classification is confirmed MICRO
+- No new entities, no integrations, pure UI/CRUD
+- The full spec can fit in one session context without losing state
+
+## Signals that input is in vibe mode (not yet hardenable)
+
+- "I want something like X" without defining what X actually does
+- Requirements expressed as UI descriptions ("there should be a button that does Y")
+- No mention of what happens when things go wrong
+- No mention of who can do what (permissions, roles)
+- Scope keeps expanding during the conversation
+
+## What to do when input is in vibe mode
+
+Do not start implementation. Instead:
+1. Acknowledge: "This is still in exploration mode — let's harden it before coding."
+2. Route to @product if no PRD exists yet.
+3. Route to @sheldon if PRD exists but has gaps.
+4. Only proceed to @analyst / @architect / @dev after Gate A is passed.

package/template/.aioson/skills/process/aioson-spec-driven/references/maintenance-and-state.md

@@ -1,101 +1,101 @@
-# Maintenance and State — Writing Useful Checkpoints
-
-> Use when writing or reading `spec*.md`, updating checkpoints, or retaking work after a session break.
-
-## The purpose of spec-{slug}.md
-
-It is not just an implementation log. It is the **living memory** of a feature across all sessions, agents, and tools.
-
-A well-written `spec-{slug}.md` allows:
-- @deyvin to resume from the last checkpoint without re-reading the entire spec pack
-- @qa to know what was decided and what was deferred
-- A future developer (or AI) to understand *why* the code was written the way it was
-
-A poorly written `spec-{slug}.md` forces every new session to rediscover what was already decided.
-
-## What to write in phase_gates
-
-```yaml
-phase_gates:
-  requirements: approved      # requirements are locked — no new scope without PRD change
-  design: approved            # architecture is locked — no structural changes without @architect
-  plan: approved              # execution sequence is locked — @dev follows plan, not instinct
-```
-
-Never mark a gate as `approved` if there are unresolved items in that phase.
-
-## What to write in last_checkpoint
-
-Format: `{phase-name}: {what was completed} — {what is next}`
-
-Examples:
-- `migration: users table created and seeded — next: implement CreateUser action`
-- `auth: login and register complete, password reset pending — next: implement ResetPassword action`
-- `api: GET /products and POST /products done — next: implement PATCH /products/{id}`
-
-This one line is what @deyvin reads first. Make it actionable.
-
-## What to write in pending_review
-
-List items that need human verification before the next phase begins:
-
-```yaml
-pending_review:
-  - "Confirm: should password reset expire after 1h or 24h? (decision was deferred)"
-  - "Review: CreateUser action sends email — confirm SMTP config in staging before testing"
-```
-
-## What to write in Key decisions
-
-Format: `[ISO-date] [decision] — [reason this decision reduces future debug or maintenance cost]`
-
-Bad example:
-- `2026-03-28 Used soft deletes`
-
-Good example:
-- `2026-03-28 Used soft deletes on users table — reason: billing history must remain intact after account deletion; hard delete would orphan invoices`
-
-The reason is what makes the decision useful in 6 months.
-
-## spec_version field
-
-- Seeded at `1` by @analyst when creating the skeleton
-- Incremented by any agent that modifies the spec body (entities, decisions, edge cases — NOT just `last_checkpoint` or `pending_review`)
-- @dev checks at session start: if version changed since last `dev-state.md` update, read the spec diff before continuing
-- @qa checks at review: if version doesn't match what @dev reported, flag as potential drift
-
-## Unified resumption fields
-
-Every agent that produces or updates a persistent artifact should include these fields in the artifact's frontmatter or closing section:
-
-### In frontmatter (machine-readable):
-- `last_agent: {agent-name}` — who was here last
-- `last_session: {ISO-date}` — when
-- `session_result: completed | interrupted | blocked` — what happened
-
-### In closing section (human-readable):
-```
-## Session close — {ISO-date}
-Agent: @{name}
-Result: {completed | interrupted | blocked}
-Next: {clear instruction for next agent or next session}
-```
-
-### Which artifact each agent updates:
-| Agent | Primary artifact |
-|-------|-----------------|
-| @product | `prd.md` or `prd-{slug}.md` |
-| @sheldon | `sheldon-enrichment-{slug}.md` |
-| @analyst | `discovery.md` or `requirements-{slug}.md` |
-| @architect | `architecture.md` |
-| @dev | `dev-state.md` (already does this) |
-| @deyvin | `dev-state.md` or `spec-{slug}.md` |
-| @qa | QA report file |
-
-## How @deyvin should use this file
-
-1. Read `phase_gates` first — know which phases are locked
-2. Read `last_checkpoint` — start from there, not from the beginning
-3. Read `pending_review` — these may need user input before proceeding
-4. Read `Key decisions` only if the next task involves re-touching those areas
-5. Do NOT re-read the full spec pack unless `last_checkpoint` is null or unclear
+# Maintenance and State — Writing Useful Checkpoints
+
+> Use when writing or reading `spec*.md`, updating checkpoints, or retaking work after a session break.
+
+## The purpose of spec-{slug}.md
+
+It is not just an implementation log. It is the **living memory** of a feature across all sessions, agents, and tools.
+
+A well-written `spec-{slug}.md` allows:
+- @deyvin to resume from the last checkpoint without re-reading the entire spec pack
+- @qa to know what was decided and what was deferred
+- A future developer (or AI) to understand *why* the code was written the way it was
+
+A poorly written `spec-{slug}.md` forces every new session to rediscover what was already decided.
+
+## What to write in phase_gates
+
+```yaml
+phase_gates:
+  requirements: approved      # requirements are locked — no new scope without PRD change
+  design: approved            # architecture is locked — no structural changes without @architect
+  plan: approved              # execution sequence is locked — @dev follows plan, not instinct
+```
+
+Never mark a gate as `approved` if there are unresolved items in that phase.
+
+## What to write in last_checkpoint
+
+Format: `{phase-name}: {what was completed} — {what is next}`
+
+Examples:
+- `migration: users table created and seeded — next: implement CreateUser action`
+- `auth: login and register complete, password reset pending — next: implement ResetPassword action`
+- `api: GET /products and POST /products done — next: implement PATCH /products/{id}`
+
+This one line is what @deyvin reads first. Make it actionable.
+
+## What to write in pending_review
+
+List items that need human verification before the next phase begins:
+
+```yaml
+pending_review:
+  - "Confirm: should password reset expire after 1h or 24h? (decision was deferred)"
+  - "Review: CreateUser action sends email — confirm SMTP config in staging before testing"
+```
+
+## What to write in Key decisions
+
+Format: `[ISO-date] [decision] — [reason this decision reduces future debug or maintenance cost]`
+
+Bad example:
+- `2026-03-28 Used soft deletes`
+
+Good example:
+- `2026-03-28 Used soft deletes on users table — reason: billing history must remain intact after account deletion; hard delete would orphan invoices`
+
+The reason is what makes the decision useful in 6 months.
+
+## spec_version field
+
+- Seeded at `1` by @analyst when creating the skeleton
+- Incremented by any agent that modifies the spec body (entities, decisions, edge cases — NOT just `last_checkpoint` or `pending_review`)
+- @dev checks at session start: if version changed since last `dev-state.md` update, read the spec diff before continuing
+- @qa checks at review: if version doesn't match what @dev reported, flag as potential drift
+
+## Unified resumption fields
+
+Every agent that produces or updates a persistent artifact should include these fields in the artifact's frontmatter or closing section:
+
+### In frontmatter (machine-readable):
+- `last_agent: {agent-name}` — who was here last
+- `last_session: {ISO-date}` — when
+- `session_result: completed | interrupted | blocked` — what happened
+
+### In closing section (human-readable):
+```
+## Session close — {ISO-date}
+Agent: @{name}
+Result: {completed | interrupted | blocked}
+Next: {clear instruction for next agent or next session}
+```
+
+### Which artifact each agent updates:
+| Agent | Primary artifact |
+|-------|-----------------|
+| @product | `prd.md` or `prd-{slug}.md` |
+| @sheldon | `sheldon-enrichment-{slug}.md` |
+| @analyst | `discovery.md` or `requirements-{slug}.md` |
+| @architect | `architecture.md` |
+| @dev | `dev-state.md` (already does this) |
+| @deyvin | `dev-state.md` or `spec-{slug}.md` |
+| @qa | QA report file |
+
+## How @deyvin should use this file
+
+1. Read `phase_gates` first — know which phases are locked
+2. Read `last_checkpoint` — start from there, not from the beginning
+3. Read `pending_review` — these may need user input before proceeding
+4. Read `Key decisions` only if the next task involves re-touching those areas
+5. Do NOT re-read the full spec pack unless `last_checkpoint` is null or unclear

package/template/.aioson/skills/process/aioson-spec-driven/references/pm.md

@@ -0,0 +1,30 @@
+# Spec-Driven Reference — @pm
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for backlog and delivery planning
+
+### Always load when this skill is active
+
+- `approval-gates.md` — @pm owns Gate C; use it to know exactly what must be true before `phase_gates.plan` can be set to `approved` and before handing off to @dev or @orchestrator
+- `classification-map.md` — use to calibrate sprint sizing and decide how many delivery phases are appropriate for MICRO/SMALL/MEDIUM
+
+### Load when plan structure is ambiguous
+
+- `artifact-map.md` — use to understand which artifacts @pm may read (prd, requirements, spec, architecture) vs. which it must not overwrite (@analyst's requirements, @architect's architecture)
+- `maintenance-and-state.md` — use when retaking a sprint session or checking if a spec-{slug}.md checkpoint needs updating before continuing
+
+### Do not load for @pm
+
+- `hardening-lane.md` — @pm receives hardened input from @product and @analyst; if input is still vague, send it back upstream, do not harden it yourself
+- `qa.md` — Gate D belongs to @qa, not @pm
+
+## Behavioral notes for @pm under SDD
+
+- @pm is the **Gate C owner** — the plan is not complete until `spec-{slug}.md` has `phase_gates.plan: approved` and `implementation-plan-{slug}.md` (if MEDIUM) has `status: approved`
+- Gate C is **blocking in MEDIUM** — @dev and @orchestrator must not execute without Gate C passing
+- Gate C is **informational in SMALL** — flag if the plan looks thin, but do not block
+- Gate C is **skipped in MICRO** — @dev reads prd.md directly; @pm does not run for MICRO
+- ACs produced by @pm must match or extend the ACs in `conformance-{slug}.yaml` when it exists — never contradict the analyst's behavioral contracts
+- @pm adds delivery phases and prioritization; it does NOT rewrite Vision, Problem, Users, or Flows — those belong to @product
+- At session end, always tell the user explicitly: "Gate C passed — activate [@orchestrator / @dev]" OR "Gate C blocked — [reason]"

package/template/.aioson/skills/process/aioson-spec-driven/references/product.md

@@ -1,25 +1,25 @@
-# Spec-Driven Reference — @product
-
-> Router file. Do not duplicate logic from the generic references — load those directly.
-
-## Which references to load for PRD and feature scoping
-
-### Always load when this skill is active
-
-- `classification-map.md` — use to declare MICRO/SMALL/MEDIUM at the start of scoping; classification controls PRD depth, whether a `## Specify depth` section is required, and which downstream phases are mandatory
-- `artifact-map.md` — use to understand what @product's PRD feeds into downstream; helps scope the PRD correctly without over-specifying what belongs to @analyst or @architect
-
-### Load when input is still ambiguous or exploratory
-
-- `hardening-lane.md` — use to detect if the request is still in vibe mode and needs more discovery before a PRD can be written
-
-### Do not load for @product
-
-- `approval-gates.md` — @product produces the PRD; Gate A is evaluated by @analyst after @product hands off
-- `maintenance-and-state.md` — this is for execution/continuation sessions
-
-## Behavioral notes
-
-- Classification (MICRO/SMALL/MEDIUM) from `classification-map.md` must be declared in the PRD — it is the signal that controls all downstream process depth
-- @product does not write requirements (`requirements-{slug}.md`) — those belong to @analyst; see `artifact-map.md` for the boundary
-- If classification is MEDIUM, the PRD must include a `## Specify depth` section per `classification-map.md`
+# Spec-Driven Reference — @product
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for PRD and feature scoping
+
+### Always load when this skill is active
+
+- `classification-map.md` — use to declare MICRO/SMALL/MEDIUM at the start of scoping; classification controls PRD depth, whether a `## Specify depth` section is required, and which downstream phases are mandatory
+- `artifact-map.md` — use to understand what @product's PRD feeds into downstream; helps scope the PRD correctly without over-specifying what belongs to @analyst or @architect
+
+### Load when input is still ambiguous or exploratory
+
+- `hardening-lane.md` — use to detect if the request is still in vibe mode and needs more discovery before a PRD can be written
+
+### Do not load for @product
+
+- `approval-gates.md` — @product produces the PRD; Gate A is evaluated by @analyst after @product hands off
+- `maintenance-and-state.md` — this is for execution/continuation sessions
+
+## Behavioral notes
+
+- Classification (MICRO/SMALL/MEDIUM) from `classification-map.md` must be declared in the PRD — it is the signal that controls all downstream process depth
+- @product does not write requirements (`requirements-{slug}.md`) — those belong to @analyst; see `artifact-map.md` for the boundary
+- If classification is MEDIUM, the PRD must include a `## Specify depth` section per `classification-map.md`

package/template/.aioson/skills/process/aioson-spec-driven/references/qa.md

@@ -1,30 +1,30 @@
-# Spec-Driven Reference — @qa
-
-> Router file. Do not duplicate logic from the generic references — load those directly.
-
-## Which references to load for quality verification
-
-### Always load when this skill is active
-
-- `approval-gates.md` — Gate D (execution verification) defines done criteria; @qa is the external verifier of Gate D claims
-- `artifact-map.md` — use to verify that all artifacts claimed by upstream agents actually exist and are substantive
-
-### Load when evaluating AC coverage
-
-- `classification-map.md` — use to calibrate verification depth: MICRO gets happy path + auth only; MEDIUM gets full checklist + invariant tests
-
-### Load when investigating failures or forensics
-
-- `maintenance-and-state.md` — use to read `phase_gates`, `last_checkpoint`, and `pending_review` from `spec-{slug}.md` during forensics mode
-
-### Do not load for @qa
-
-- `hardening-lane.md` — @qa activates after implementation; hardening is not relevant
-- `ui-language.md` — @qa produces structured reports, not interactive checkpoints
-
-## Behavioral notes
-
-- @qa is the external verifier of @dev's Gate D self-certification — "I think it works" from @dev is not evidence until @qa confirms
-- Gate D verification from `approval-gates.md` maps directly to @qa's adversarial probe protocol: truths = behavior tests, artifacts = file existence checks, key_links = wiring verification
-- For MEDIUM projects, @qa should verify that `spec_version` in `spec-{slug}.md` matches the version that @dev was working from — if not, flag as potential drift
-- AC coverage mapping in the QA report should use the same `AC-{slug}-{N}` format from `requirements-{slug}.md`
+# Spec-Driven Reference — @qa
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for quality verification
+
+### Always load when this skill is active
+
+- `approval-gates.md` — Gate D (execution verification) defines done criteria; @qa is the external verifier of Gate D claims
+- `artifact-map.md` — use to verify that all artifacts claimed by upstream agents actually exist and are substantive
+
+### Load when evaluating AC coverage
+
+- `classification-map.md` — use to calibrate verification depth: MICRO gets happy path + auth only; MEDIUM gets full checklist + invariant tests
+
+### Load when investigating failures or forensics
+
+- `maintenance-and-state.md` — use to read `phase_gates`, `last_checkpoint`, and `pending_review` from `spec-{slug}.md` during forensics mode
+
+### Do not load for @qa
+
+- `hardening-lane.md` — @qa activates after implementation; hardening is not relevant
+- `ui-language.md` — @qa produces structured reports, not interactive checkpoints
+
+## Behavioral notes
+
+- @qa is the external verifier of @dev's Gate D self-certification — "I think it works" from @dev is not evidence until @qa confirms
+- Gate D verification from `approval-gates.md` maps directly to @qa's adversarial probe protocol: truths = behavior tests, artifacts = file existence checks, key_links = wiring verification
+- For MEDIUM projects, @qa should verify that `spec_version` in `spec-{slug}.md` matches the version that @dev was working from — if not, flag as potential drift
+- AC coverage mapping in the QA report should use the same `AC-{slug}-{N}` format from `requirements-{slug}.md`

package/template/.aioson/skills/process/aioson-spec-driven/references/sheldon.md

@@ -1,25 +1,25 @@
-# Spec-Driven Reference — @sheldon
-
-> Router file. Do not duplicate logic from the generic references — load those directly.
-
-## Which references to load for enrichment and validation
-
-### Always load when this skill is active
-
-- `hardening-lane.md` — @sheldon's primary job is to move input from Lane 1 (exploration) to Lane 2 (spec hardening); use this to identify vibe signals and what is missing
-- `classification-map.md` — use to determine enrichment depth: MEDIUM requires Modo C (full validation), MICRO/SMALL have lighter enrichment expectations
-
-### Load when evaluating PRD readiness for handoff
-
-- `approval-gates.md` — use Gate A criteria as the readiness checklist @sheldon applies before recommending @analyst activation
-
-### Do not load for @sheldon
-
-- `maintenance-and-state.md` — enrichment is a pre-execution phase; spec state is not relevant yet
-- `artifact-map.md` — load only if @sheldon needs to verify that the right PRD artifact exists before enriching
-
-## Behavioral notes
-
-- @sheldon activates before @analyst — its output (`sheldon-enrichment-{slug}.md`) feeds @analyst
-- Vibe detection from `hardening-lane.md` determines whether to proceed with enrichment or route back to @product
-- MEDIUM classification triggers Modo C: @sheldon must validate completeness more strictly than MICRO/SMALL
+# Spec-Driven Reference — @sheldon
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for enrichment and validation
+
+### Always load when this skill is active
+
+- `hardening-lane.md` — @sheldon's primary job is to move input from Lane 1 (exploration) to Lane 2 (spec hardening); use this to identify vibe signals and what is missing
+- `classification-map.md` — use to determine enrichment depth: MEDIUM requires Modo C (full validation), MICRO/SMALL have lighter enrichment expectations
+
+### Load when evaluating PRD readiness for handoff
+
+- `approval-gates.md` — use Gate A criteria as the readiness checklist @sheldon applies before recommending @analyst activation
+
+### Do not load for @sheldon
+
+- `maintenance-and-state.md` — enrichment is a pre-execution phase; spec state is not relevant yet
+- `artifact-map.md` — load only if @sheldon needs to verify that the right PRD artifact exists before enriching
+
+## Behavioral notes
+
+- @sheldon activates before @analyst — its output (`sheldon-enrichment-{slug}.md`) feeds @analyst
+- Vibe detection from `hardening-lane.md` determines whether to proceed with enrichment or route back to @product
+- MEDIUM classification triggers Modo C: @sheldon must validate completeness more strictly than MICRO/SMALL

package/template/.aioson/skills/process/aioson-spec-driven/references/ui-language.md

@@ -1,75 +1,75 @@
-# UI Language — AIOSON Visual Standards
-
-> Carregue quando um agente precisa apresentar opções, status ou checkpoints ao usuário.
-
-## Status symbols
-✓ completo / aprovado
-✗ falhou / bloqueado
-◆ em progresso
-○ pendente
-⚠ atenção necessária
-⚡ auto-aprovado
-
-## Stage banner
-Usar ao iniciar fase principal:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- AIOSON ► @{AGENT} — {FASE}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## Checkpoint verify (confirmação visual)
-Usar: após implementação que o usuário precisa ver
-```
-┌─────────────────────────────────────────────┐
-│  ✓ VERIFICAR: {título}                      │
-│  {instrução específica}                      │
-│  Confirmar? [s/n]                           │
-└─────────────────────────────────────────────┘
-```
-
-## Checkpoint decision (AskUserQuestion — radio)
-Usar: quando há bifurcação com outcomes diferentes
-→ AskUserQuestion com multiSelect: false, 2-4 opções
-
-```
-┌─────────────────────────────────────────────┐
-│  ◆ DECISÃO NECESSÁRIA                      │
-│                                             │
-│  {contexto da decisão}                      │
-│                                             │
-│  1. {opção A} — {consequências}            │
-│  2. {opção B} — {consequências}            │
-│                                             │
-│  Escolha [1/2]:                            │
-└─────────────────────────────────────────────┘
-```
-
-## Checkpoint action (passo manual)
-Usar: apenas para passos que o agente literalmente não pode executar
-```
-┌─────────────────────────────────────────────┐
-│  ⚠ AÇÃO MANUAL NECESSÁRIA                  │
-│                                             │
-│  {instrução específica}                      │
-│  {onde executar}                             │
-│                                             │
-│  Avise quando estiver pronto.              │
-└─────────────────────────────────────────────┘
-```
-
-## Checkpoint multi-select (AskUserQuestion — checkbox)
-Usar: seleção múltipla (skills, requirements, itens de sprint)
-→ AskUserQuestion com multiSelect: true
-
-## Progress bar
-Usar para fases longas com steps definidos:
-```
-Progresso: ████████░░ 80% (4/5 steps)
-```
-
-## Regras
-- Header máximo 12 caracteres
-- Máximo 4 opções em radio; máximo 8 em checkbox
-- Incluir opção "Nenhuma/Pular" em checkbox quando pertinente
-- Não usar checkbox para decisões que mudam arquitetura (use radio)
+# UI Language — AIOSON Visual Standards
+
+> Carregue quando um agente precisa apresentar opções, status ou checkpoints ao usuário.
+
+## Status symbols
+✓ completo / aprovado
+✗ falhou / bloqueado
+◆ em progresso
+○ pendente
+⚠ atenção necessária
+⚡ auto-aprovado
+
+## Stage banner
+Usar ao iniciar fase principal:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ AIOSON ► @{AGENT} — {FASE}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Checkpoint verify (confirmação visual)
+Usar: após implementação que o usuário precisa ver
+```
+┌─────────────────────────────────────────────┐
+│  ✓ VERIFICAR: {título}                      │
+│  {instrução específica}                      │
+│  Confirmar? [s/n]                           │
+└─────────────────────────────────────────────┘
+```
+
+## Checkpoint decision (AskUserQuestion — radio)
+Usar: quando há bifurcação com outcomes diferentes
+→ AskUserQuestion com multiSelect: false, 2-4 opções
+
+```
+┌─────────────────────────────────────────────┐
+│  ◆ DECISÃO NECESSÁRIA                      │
+│                                             │
+│  {contexto da decisão}                      │
+│                                             │
+│  1. {opção A} — {consequências}            │
+│  2. {opção B} — {consequências}            │
+│                                             │
+│  Escolha [1/2]:                            │
+└─────────────────────────────────────────────┘
+```
+
+## Checkpoint action (passo manual)
+Usar: apenas para passos que o agente literalmente não pode executar
+```
+┌─────────────────────────────────────────────┐
+│  ⚠ AÇÃO MANUAL NECESSÁRIA                  │
+│                                             │
+│  {instrução específica}                      │
+│  {onde executar}                             │
+│                                             │
+│  Avise quando estiver pronto.              │
+└─────────────────────────────────────────────┘
+```
+
+## Checkpoint multi-select (AskUserQuestion — checkbox)
+Usar: seleção múltipla (skills, requirements, itens de sprint)
+→ AskUserQuestion com multiSelect: true
+
+## Progress bar
+Usar para fases longas com steps definidos:
+```
+Progresso: ████████░░ 80% (4/5 steps)
+```
+
+## Regras
+- Header máximo 12 caracteres
+- Máximo 4 opções em radio; máximo 8 em checkbox
+- Incluir opção "Nenhuma/Pular" em checkbox quando pertinente
+- Não usar checkbox para decisões que mudam arquitetura (use radio)