@jaimevalasek/aioson 1.5.1 → 1.7.0

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

@@ -0,0 +1,109 @@
+# Approval Gates — Spec-Driven Phase Transitions
+
+> Use when preparing a handoff or checking if a phase is ready to proceed.
+> Gates are blocking in MEDIUM. Informational in MICRO/SMALL.
+
+## Gate A — Requirements approval
+
+**Before leaving @product / @analyst → @architect or @dev**
+
+Required for the gate to pass:
+- [ ] Objectives are clear and unambiguous
+- [ ] Expected behaviors are described (not just features — what happens when X)
+- [ ] Constraints are explicit (what this version does NOT do)
+- [ ] Out of scope is listed
+- [ ] Open ambiguities are documented (not silently ignored)
+- [ ] Requirement IDs exist for all business rules: `REQ-{slug}-{N}`
+- [ ] Acceptance criteria exist for all behavioral requirements: `AC-{slug}-{N}`
+
+**Signal in `spec-{slug}.md`:** set `phase_gates.requirements: approved`
+
+**Not ready if:**
+- Requirements reference behavior that hasn't been decided
+- ACs are not independently verifiable (e.g., "works correctly" is not an AC)
+- There are contradictions between PRD and requirements
+
+---
+
+## Gate B — Design approval
+
+**Before leaving @architect → @dev**
+
+Required for the gate to pass:
+- [ ] Technical approach is chosen and documented
+- [ ] Module/folder structure is defined
+- [ ] Dependencies between components are explicit
+- [ ] Risks and non-goals are documented
+- [ ] Decision rationale exists for non-obvious choices
+- [ ] @dev can start without having to invent business logic or architecture
+
+**Signal in `spec-{slug}.md`:** set `phase_gates.design: approved`
+**Signal in `architecture.md`:** closing line `> **Gate B:** Architecture approved — @dev can proceed.`
+
+**Not ready if:**
+- There are open decisions that @dev would need to make up during implementation
+- The architecture introduces patterns not supported by the project's stack
+- There are circular dependencies in the module structure
+
+---
+
+## Gate C — Plan approval
+
+**Before @dev or @deyvin executes a significant batch**
+
+Required for the gate to pass:
+- [ ] Execution sequence is defined
+- [ ] Checkpoints are listed with criteria of done
+- [ ] Context package is listed (which files to read before each phase)
+- [ ] Review / QA requirements are noted
+- [ ] Decisions marked "pre-taken" are FINAL — @dev does not re-discuss
+
+**Signal in `spec-{slug}.md`:** set `phase_gates.plan: approved`
+**Signal in `implementation-plan-{slug}.md`:** status field = `approved`
+
+**Not ready if:**
+- The plan has phases with unclear done criteria
+- There are external dependencies not yet resolved
+- @dev would need to re-read the full spec from scratch to start
+
+---
+
+## Gate D — Execution verification (must_haves)
+
+**Before marking a phase or feature as complete**
+
+Required:
+- [ ] All truths verified (behavioral — not just "I think it works")
+- [ ] All artifacts verified (substantive — not stubs)
+- [ ] All key_links verified (wiring — imports, registrations, middleware)
+
+**Not complete if:**
+- Any truth has no passing test or manual verification step
+- Any artifact is empty, a stub, or missing required exports
+- Any key_link shows the code exists but isn't connected
+
+**Signal:** update `last_checkpoint` in `spec-{slug}.md` with which must_haves passed and which failed.
+
+---
+
+## Checkpoint taxonomy reference
+
+Quando qualquer agente precisa de interação humana durante execução:
+
+| Tipo | Quando | Frequência esperada |
+|------|--------|---------------------|
+| `verify` | Confirmar comportamento visível | Comum — após cada entrega testável |
+| `decision` | Bifurcação arquitetural ou de produto | Rara — apenas quando não especificado |
+| `action` | Passo que o agente não consegue executar | Muito rara — <1% dos steps |
+
+Regra: se o agente consegue executar sem risco, execute. Não peça confirmação desnecessária.
+
+---
+
+## How agents communicate gate status
+
+Each agent, at session end, should:
+1. Update `phase_gates` in `spec-{slug}.md`
+2. Tell the user clearly: "Gate [A/B/C] passed — activate [@next-agent]" OR "Gate [A/B/C] blocked — [reason]. Resolve before continuing."
+
+Never silently assume a gate is passed.

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

@@ -0,0 +1,23 @@
+# Spec-Driven Reference — @architect
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for architecture work
+
+### Always load when this skill is active
+
+- `classification-map.md` — use to determine architecture depth: MICRO skips most of this, MEDIUM requires full `architecture.md`
+- `approval-gates.md` — Gate B criteria define what @architect must produce before @dev can start; Gate A must already be passed before @architect begins
+- `artifact-map.md` — use to confirm which artifacts @architect owns (`architecture.md`, `design-doc*.md`) and which feed into it
+
+### Do not load for @architect
+
+- `hardening-lane.md` — input is expected to be already past vibe mode when @architect is activated
+- `maintenance-and-state.md` — this is for execution/continuation sessions
+
+## Behavioral notes
+
+- Classification depth from `classification-map.md` controls whether `architecture.md` is required, selective, or skippable
+- Gate B is the handoff signal — @dev must not start implementation without Gate B passing (MEDIUM) or being explicitly waived (SMALL)
+- Decision rationale is mandatory for non-obvious choices — `approval-gates.md` Gate B checklist item applies
+- `design-doc*.md` is @architect's scope-specific decision document — see `artifact-map.md`

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

@@ -0,0 +1,44 @@
+# Artifact Map — AIOSON Spec-Driven
+
+> Source of truth: which artifact lives where, who writes it, who reads it.
+
+## Artifact chain
+
+```
+prd*.md
+  → sheldon-enrichment-{slug}.md   (optional enrichment layer)
+  → requirements-{slug}.md         (entities, rules, ACs — @analyst)
+  → spec-{slug}.md                 (feature memory — @analyst seeds, @dev fills)
+  → architecture.md                (tech decisions — @architect)
+  → design-doc*.md                 (scope-specific decisions — @architect)
+  → implementation-plan-{slug}.md  (execution sequence — @dev)
+  → spec-{slug}.md (updated)       (living state during execution — @dev)
+```
+
+## Artifact ownership
+
+| Artifact | Written by | Enriched by | Read by |
+|----------|-----------|-------------|---------|
+| `prd.md` / `prd-{slug}.md` | @product | @sheldon (via sheldon-enrichment) | all downstream |
+| `sheldon-enrichment-{slug}.md` | @sheldon | @sheldon | @sheldon (re-entry), @analyst |
+| `sheldon-validation.md` | @sheldon | — | all agents before starting MEDIUM |
+| `discovery.md` | @analyst | — | @architect, @dev |
+| `requirements-{slug}.md` | @analyst | — | @architect, @dev, @qa |
+| `spec-{slug}.md` | @analyst (skeleton) | @dev (execution state) | @dev, @deyvin, @qa |
+| `spec.md` | @dev | @dev | @dev, @deyvin |
+| `architecture.md` | @architect | — | @dev, @ux-ui |
+| `design-doc*.md` | @architect | — | @dev, @ux-ui |
+| `implementation-plan-{slug}.md` | @dev | — | @dev, @deyvin |
+
+## Naming conventions
+
+- Project-level artifacts: `prd.md`, `discovery.md`, `spec.md`, `architecture.md`
+- Feature-level artifacts: always use `{slug}` suffix — `prd-{slug}.md`, `requirements-{slug}.md`, `spec-{slug}.md`
+- Enrichment: `sheldon-enrichment.md` (project) or `sheldon-enrichment-{slug}.md` (feature)
+- Plans: `.aioson/plans/{slug}/manifest.md` + `plan-{slug-fase}.md` files
+
+## What NOT to create
+
+- Do not create `.specs/` folders — use the artifact names above
+- Do not rename existing artifacts to match TLC conventions
+- Do not create a new artifact if an existing one covers the same purpose

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

@@ -0,0 +1,37 @@
+# Classification Map — Phase Depth by Project Size
+
+> Use this when deciding which phases to run and how deep to go.
+
+## Depth table
+
+| Phase | MICRO (0–1) | SMALL (2–3) | MEDIUM (4–6) |
+|-------|-------------|-------------|--------------|
+| Specify (PRD) | 1 conversation, lite template | Full PRD conversation | Full PRD + `## Specify depth` section |
+| Research (@sheldon) | Skip unless links/external sources provided | Recommended — run before @analyst | Required — run Modo C (full validation) |
+| Requirements (@analyst) | Skip — go @product → @dev | Required — `requirements-{slug}.md` | Required — with requirement IDs + ACs |
+| Design (@architect) | Skip unless auth or external integration | Selective — only if new architecture pattern | Required — full `architecture.md` |
+| Plan (implementation-plan) | Optional — suggest only if @dev asks | Recommended | Required — with gate approval + verification criteria |
+| Execute (@dev) | Direct from PRD | From requirements + spec | From approved plan only |
+| State (@dev, @deyvin) | Minimal `spec.md` note | `spec-{slug}.md` with phase_gates | Full spec pack — phase_gates + checkpoints + maintenance notes |
+
+## Scoring (from @analyst)
+
+| Dimension | Score |
+|-----------|-------|
+| User types: 1 | 0 |
+| User types: 2 | 1 |
+| User types: 3+ | 2 |
+| External integrations: 0 | 0 |
+| External integrations: 1–2 | 1 |
+| External integrations: 3+ | 2 |
+| Business rule complexity: none | 0 |
+| Business rule complexity: some | 1 |
+| Business rule complexity: complex | 2 |
+
+**0–1 = MICRO / 2–3 = SMALL / 4–6 = MEDIUM**
+
+## Gate behavior by classification
+
+- **MICRO**: gates are informational, never blocking. @dev may proceed without explicit approval.
+- **SMALL**: Gate A (requirements) is recommended before design. Gate B is optional.
+- **MEDIUM**: Gates A, B, C are required. Do not proceed to next phase without explicit user confirmation.

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

@@ -0,0 +1,47 @@
+# Spec-Driven Reference — @dev
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for implementation
+
+### Always load when this skill is active
+
+- `maintenance-and-state.md` — use to write and update `spec-{slug}.md` correctly: `phase_gates`, `last_checkpoint`, `pending_review`, and `Key decisions` format
+- `approval-gates.md` — Gate C (plan approval) must be checked before executing a significant batch; Gate D (execution verification) defines done criteria for each phase
+
+### Load when starting a new feature with classification context
+
+- `classification-map.md` — use to confirm whether an implementation plan is optional (MICRO), recommended (SMALL), or required (MEDIUM) before starting
+
+### Load when resuming or checking artifact chain
+
+- `artifact-map.md` — use to verify which upstream artifacts exist and which @dev should read before implementing
+
+### Do not load for @dev
+
+- `hardening-lane.md` — @dev activates after hardening; if the spec is still in vibe mode, stop and route back
+- `ui-language.md` — load only when producing a checkpoint or gate status presentation for the user
+
+## Spec drift detection
+
+At session start, after reading `spec-{slug}.md`:
+
+1. Compare `spec_version` in `spec-{slug}.md` with the version recorded in `dev-state.md` (`last_spec_version` field)
+2. If versions differ:
+   > "⚠ Spec changed since last session (version {old} → {new}). Reading the changes before continuing."
+   - Read the diff (Key decisions, Entities added, Edge cases sections)
+   - Update `dev-state.md` with new `last_spec_version`
+3. If versions match: proceed normally
+
+Additionally, at session start for SMALL/MEDIUM:
+4. Check if any `AC-{slug}-{N}` from `requirements-{slug}.md` has a corresponding test file
+5. If coverage is < 50%:
+   > "⚠ AC coverage is low ({N}/{M} ACs have tests). Consider writing missing tests before adding new behavior."
+   This is informational, not blocking.
+
+## Behavioral notes
+
+- `spec-{slug}.md` must be updated at the end of every implementation session — see `maintenance-and-state.md` for format
+- Gate C from `approval-gates.md` means the implementation plan is locked — do not re-discuss pre-taken decisions
+- Gate D verification must happen before marking a phase complete — not just "I think it works"
+- If `phase_gates.plan` is `pending` and classification is SMALL/MEDIUM, suggest generating an implementation plan before proceeding

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

@@ -0,0 +1,27 @@
+# Spec-Driven Reference — @deyvin
+
+> Router file. Do not duplicate logic from the generic references — load those directly.
+
+## Which references to load for continuation and resume flows
+
+### Always load when this skill is active
+
+- `maintenance-and-state.md` — @deyvin's primary job is resumption; use this to read `phase_gates`, `last_checkpoint`, and `pending_review` correctly before any action
+- `approval-gates.md` — use to check which gates are already approved before proceeding; never advance past a gate that is not yet passed
+
+### Load when the continuation context is unclear
+
+- `artifact-map.md` — use to quickly orient which artifacts exist and which are missing when resuming a session with incomplete context
+
+### Do not load for @deyvin
+
+- `hardening-lane.md` — by the time @deyvin is active, the spec pack should already be hardened
+- `classification-map.md` — classification was set in the spec and should not be re-evaluated during continuation
+- `ui-language.md` — load only when producing a checkpoint or gate status presentation for the user
+
+## Behavioral notes
+
+- `last_checkpoint` in `spec-{slug}.md` is the first thing @deyvin reads — see `maintenance-and-state.md` for format
+- Do not re-read the full spec pack unless `last_checkpoint` is null or contradictory
+- `phase_gates` from `approval-gates.md` defines what is locked — @deyvin does not re-open locked decisions
+- `pending_review` items must be surfaced to the user before proceeding past them

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

@@ -0,0 +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.

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

@@ -0,0 +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

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

@@ -0,0 +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`

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

@@ -0,0 +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`

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

@@ -0,0 +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

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

@@ -0,0 +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)