@jaimevalasek/aioson 1.4.0 → 1.6.0

package/template/.aioson/skills/premium-visual-design/tokens/status-extended.md

@@ -0,0 +1,142 @@
+# Status Extended Tokens
+
+Extended state and status tokens for Squad Dashboard v3 inter-squad UI.
+
+## Agent & Task State Tokens
+
+```css
+:root {
+  /* --- Blocked --- */
+  --state-blocked:        #f87171;
+  --state-blocked-bg:     rgba(248, 113, 113, 0.12);
+  --state-blocked-border: rgba(248, 113, 113, 0.30);
+
+  /* --- Ready --- */
+  --state-ready:          #4ade80;
+  --state-ready-bg:       rgba(74, 222, 128, 0.12);
+  --state-ready-border:   rgba(74, 222, 128, 0.30);
+
+  /* --- Solo (no squad context) --- */
+  --state-solo:           #8b8fa3;
+  --state-solo-bg:        rgba(139, 143, 163, 0.12);
+  --state-solo-border:    rgba(139, 143, 163, 0.25);
+
+  /* --- Auto (fully autonomous agent) --- */
+  --state-auto:           #22d3ee;
+  --state-auto-bg:        rgba(34, 211, 238, 0.12);
+  --state-auto-border:    rgba(34, 211, 238, 0.30);
+
+  /* --- Human (human-in-the-loop) --- */
+  --state-human:          #fbbf24;
+  --state-human-bg:       rgba(251, 191, 36, 0.12);
+  --state-human-border:   rgba(251, 191, 36, 0.30);
+
+  /* --- Review (awaiting review) --- */
+  --state-review:         #c084fc;
+  --state-review-bg:      rgba(192, 132, 252, 0.12);
+  --state-review-border:  rgba(192, 132, 252, 0.30);
+
+  /* --- Running (animated pulse) --- */
+  --state-running:        #6c8aff;
+  --state-running-bg:     rgba(108, 138, 255, 0.12);
+
+  /* --- Idle --- */
+  --state-idle:           #8b8fa3;
+  --state-idle-bg:        rgba(139, 143, 163, 0.10);
+
+  /* --- Error --- */
+  --state-error:          #f87171;
+  --state-error-bg:       rgba(248, 113, 113, 0.12);
+
+  /* --- Done --- */
+  --state-done:           #4ade80;
+  --state-done-bg:        rgba(74, 222, 128, 0.10);
+}
+```
+
+## Running Pulse Animation
+
+Apply to indicators when `state = running`:
+
+```css
+@keyframes state-pulse {
+  0%, 100% { opacity: 1; }
+  50%       { opacity: 0.45; }
+}
+
+.state-dot-running {
+  background: var(--state-running);
+  animation: state-pulse 1.6s ease-in-out infinite;
+}
+```
+
+## Agent Type Tokens
+
+Used by `agent-badge` component.
+
+| Type | Token | Color |
+|------|-------|-------|
+| `auto` | `--state-auto` | Cyan `#22d3ee` |
+| `human` | `--state-human` | Amber `#fbbf24` |
+| `solo` | `--state-solo` | Muted `#8b8fa3` |
+
+## Priority Tokens
+
+```css
+:root {
+  --priority-critical: #f87171;   /* red */
+  --priority-high:     #fb923c;   /* orange */
+  --priority-medium:   #fbbf24;   /* amber */
+  --priority-low:      #8b8fa3;   /* muted */
+}
+```
+
+## Notification Type Tokens
+
+Map event types to colors for notification icons:
+
+| Event type | Token | Notes |
+|-----------|-------|-------|
+| `info` | `--accent` `#6c8aff` | General info |
+| `warning` | `--warning` `#fbbf24` | Soft warning |
+| `error` | `--danger` `#f87171` | Errors |
+| `success` | `--success` `#4ade80` | Completions |
+| `merge_conflict` | `--purple` `#c084fc` | Git conflicts |
+| `context_warning` | `--warning` | Context at 85% |
+| `context_critical` | `--danger` | Context at 95% |
+| `task_completed` | `--success` | Task done |
+| `task_needs_revision` | `--state-review` | Hunk rejected |
+| `handoff` | `--accent` | Agent handoff |
+| `decision` | `--cyan` `#22d3ee` | Decision recorded |
+
+## Usage
+
+Reference tokens in component CSS. Always fall back gracefully:
+
+```css
+.task-status-badge[data-status="blocked"] {
+  background: var(--state-blocked-bg);
+  color:      var(--state-blocked);
+  border:     1px solid var(--state-blocked-border);
+}
+```
+
+Map exhaustive status values:
+
+```javascript
+const STATE_TOKEN = {
+  blocked:  'blocked',
+  ready:    'ready',
+  solo:     'solo',
+  auto:     'auto',
+  human:    'human',
+  review:   'review',
+  running:  'running',
+  idle:     'idle',
+  error:    'error',
+  done:     'done',
+  pending:  'idle',    // alias
+  active:   'running', // alias
+  completed:'done'     // alias
+};
+```

package/template/.aioson/skills/process/aioson-spec-driven/SKILL.md

@@ -0,0 +1,45 @@
+# Skill: aioson-spec-driven
+
+> Process methodology skill. Covers: phase sequencing, artifact contracts, approval gates, and hardening lane.
+> Load this file first. Then load only the `references/` file relevant to your current role and phase.
+
+## When to use
+
+Load this skill when:
+- starting spec work for a new feature or project (any agent)
+- deciding phase depth based on classification (MICRO / SMALL / MEDIUM)
+- preparing a clean handoff to the next agent
+- retaking work after a session break (check `last_checkpoint` + `phase_gates` first)
+
+Do NOT load the entire `references/` folder. Load only the file matching your current need.
+
+## What phases exist
+
+| Phase | AIOSON artifact | Primary agent | MICRO | SMALL | MEDIUM |
+|-------|----------------|---------------|-------|-------|--------|
+| Specify | `prd*.md` | @product | lite | full | full |
+| Research/Discuss | `sheldon-enrichment*.md` | @sheldon | optional | recommended | required |
+| Requirements | `requirements-{slug}.md` | @analyst | skip | required | required |
+| Design | `architecture.md`, `design-doc*.md` | @architect | skip | selective | required |
+| Tasks/Plan | `implementation-plan*.md` | @dev | optional | recommended | required |
+| Execute | code, commits, spec updates | @dev, @deyvin | — | — | — |
+| State/Resume | `spec*.md`, runtime | @dev, @deyvin | — | — | — |
+
+## Phase depth by classification
+
+- **MICRO**: Specify (lite) + Execute. Skip Requirements, Design, Plan unless complexity warrants it.
+- **SMALL**: Specify + Requirements + selective Design + Plan. @sheldon recommended before downstream.
+- **MEDIUM**: Full pack — all phases, all artifacts, @sheldon validation before @analyst, implementation plan required.
+
+## References available
+
+Load the file that matches your current context — do not load all at once:
+
+| File | Load when |
+|------|-----------|
+| `references/artifact-map.md` | You need to know which artifact lives where and who owns it |
+| `references/classification-map.md` | You need to decide phase depth for a project or feature |
+| `references/approval-gates.md` | You are preparing a handoff and need to know what must be ready |
+| `references/hardening-lane.md` | The input is vague, exploratory, or "vibe-style" and needs to be converted |
+| `references/maintenance-and-state.md` | You are writing or reading `spec*.md`, checkpoints, or retaking work |
+| `references/ui-language.md` | You need to present options, status symbols, or checkpoints to the user with consistent visual standards |

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/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/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,66 @@
+# 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.
+
+## 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/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)