@jaimevalasek/aioson 1.3.0 → 1.4.0

package/template/.aioson/skills/design-system/patterns/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: design-patterns
+description: Page-level layout patterns for the Cognitive Core design system — dashboard shell, settings page, auth page, list-detail, command center, landing page, frontpage, and institutional page layouts. Load foundations and components first. Use when you need to compose a full page or screen layout.
+---
+
+# Patterns — Page-Level Layouts
+
+Requires: `foundations/SKILL.md` + `components/SKILL.md` loaded first.
+
+These patterns define how to compose components into full page layouts. Each pattern includes a structure diagram, which components to use, and spacing rules.
+
+## 1. Dashboard Shell
+
+The base layout for any admin/dashboard interface.
+
+```
+┌────────────────────────────────────────────────────────┐
+│  TOP BAR (sticky, bg-void, z-sticky)                   │
+├────────────────────────────────────────────────────────┤
+│  STATS ROW: [StatCard] [StatCard] [StatCard] [StatCard]│
+├────────────────────────────────────────────────────────┤
+│  TAB BAR (border-bottom)                               │
+├───────────┬────────────────────────────────────────────┤
+│ SIDEBAR   │  CONTENT                                   │
+│ 200-220px │  ┌─ Section Header ──────────────────┐    │
+│           │  │ Grid: [Card] [Card] [Card] [Card] │    │
+│           │  └───────────────────────────────────┘    │
+│           │  ┌─ Section Header ──────────────────┐    │
+│           │  │ Grid: [Card] [Card] [Card]        │    │
+│           │  └───────────────────────────────────┘    │
+└───────────┴────────────────────────────────────────────┘
+```
+
+**CSS skeleton:**
+```css
+.shell { min-height: 100vh; background: var(--bg-base); }
+.stats-row { display: flex; gap: var(--space-3); padding: var(--space-5) var(--space-5) 0; flex-wrap: wrap; }
+.main-layout { display: flex; min-height: calc(100vh - 230px); }
+.sidebar { width: 200px; flex-shrink: 0; border-right: 1px solid var(--border-subtle); padding: var(--space-4); }
+.content { flex: 1; padding: var(--space-4) var(--space-5); overflow-y: auto; }
+.card-grid { display: grid; gap: var(--space-4); grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); }
+```
+
+**Variant — with feature panels:**
+Below stats and above card grid, add a two-column row: `grid-template-columns: 1fr 280px`. Left = DNA Panel. Right = Mode Panel.
+
+## 2. Detail Page (Entity Profile)
+
+For viewing a single entity (product, user, project, contact).
+
+```
+┌────────────────────────────────────────────────────────┐
+│  TOP BAR                                               │
+├────────────────────────────────────────────────────────┤
+│  Breadcrumbs: Gallery → Entity Name                    │
+│  PROFILE HEADER (avatar, name, badges, stat cards)     │
+├────────────────────────────────────────────────────────┤
+│  TAB BAR (Geral | DNA | Comunicação | Histórico)       │
+├───────────┬────────────────────────────────────────────┤
+│ SIDEBAR   │  TAB CONTENT                               │
+│           │  (varies per tab — DNA panel, card grid,   │
+│           │   table, etc.)                             │
+└───────────┴────────────────────────────────────────────┘
+```
+
+**Breadcrumbs:** `font-size: var(--text-sm)`, `color: var(--text-muted)`, active item in `--text-primary`.
+
+## 3. Settings Page
+
+```
+┌────────────────────────────────────────────────────────┐
+│  TOP BAR                                               │
+├───────────┬────────────────────────────────────────────┤
+│ SIDEBAR   │  SETTINGS TITLE                            │
+│           │  ┌─ Card ─────────────────────────────┐   │
+│ General   │  │ SECTION LABEL                       │   │
+│ Security  │  │ [Label] [Input]                     │   │
+│ Billing   │  │ [Label] [Input]                     │   │
+│ Team      │  │ [Label] [Select]                    │   │
+│ API       │  │         [Save Button]               │   │
+│           │  └─────────────────────────────────────┘   │
+│           │  ┌─ Card ─────────────────────────────┐   │
+│           │  │ DANGER ZONE (red border accent)     │   │
+│           │  └─────────────────────────────────────┘   │
+└───────────┴────────────────────────────────────────────┘
+```
+
+- Sidebar items map to form card sections
+- Each section is a card with mono label header + form fields
+- Danger zone card: `border-color: var(--semantic-red-dim)` with red-tinted actions
+
+## 4. Auth Page (Login / Register)
+
+```
+┌────────────────────────────────────────────────────────┐
+│                   bg-void (full screen)                 │
+│                                                         │
+│              ┌─ Card (max-w 420px) ──────────┐         │
+│              │  [Logo] AppName                │         │
+│              │  SUBTITLE                      │         │
+│              │                                │         │
+│              │  MONO LABEL: email              │         │
+│              │  [Input]                        │         │
+│              │  MONO LABEL: password           │         │
+│              │  [Input]                        │         │
+│              │  [Primary Button: full width]   │         │
+│              │                                │         │
+│              │  or ─── divider ─── or         │         │
+│              │  [Secondary Button: Google]     │         │
+│              │  Link: forgot / register        │         │
+│              └────────────────────────────────┘         │
+│                                                         │
+│              radial glow behind card                    │
+└────────────────────────────────────────────────────────┘
+```
+
+- Full viewport, centered flex, `background: var(--bg-void)`
+- Card with `var(--bg-surface)`, `max-width: 420px`, `border-radius: var(--radius-xl)`
+- Optional: radial glow effect behind card (like Mode Panel)
+
+## 5. List-Detail (Split View)
+
+```
+┌────────────────────────────────────────────────────────┐
+│  TOP BAR                                               │
+├────────────────────────────────────────────────────────┤
+│  TAB BAR + Filter badges                               │
+├──────────────────────┬─────────────────────────────────┤
+│  LIST (scrollable)   │  DETAIL PANEL                   │
+│  ┌──────────────┐    │  Profile Header (compact)       │
+│  │ Item (active) │   │  Stat Cards row                 │
+│  ├──────────────┤    │  Tab sub-navigation             │
+│  │ Item          │   │  Content (DNA Panel, table,     │
+│  ├──────────────┤    │  etc.)                          │
+│  │ Item          │   │                                 │
+│  └──────────────┘    │                                 │
+└──────────────────────┴─────────────────────────────────┘
+```
+
+- List panel: `width: 340px`, `border-right: 1px solid var(--border-subtle)`
+- Active item: `background: var(--bg-elevated)`, `border-left: 3px solid var(--accent)`
+- Detail panel: flex: 1, scrollable independently
+
+## 6. Landing Page / Frontpage
+
+Default theme: **light**. Uses generous spacing and hero typography.
+
+```
+┌────────────────────────────────────────────────────────┐
+│  TOP BAR (transparent → bg-void on scroll)             │
+├────────────────────────────────────────────────────────┤
+│                                                         │
+│  HERO SECTION (padding: space-24)                      │
+│  ┌──────────────────────────────────────────────┐     │
+│  │ MONO LABEL: tagline                           │     │
+│  │ DISPLAY HEADING (text-5xl, weight-black)      │     │
+│  │ Subtitle paragraph (text-lg, text-secondary)  │     │
+│  │ [CTA Button] [Secondary Button]               │     │
+│  └──────────────────────────────────────────────┘     │
+│                                                         │
+├────────────────────────────────────────────────────────┤
+│  FEATURES SECTION (bg-surface, padding: space-20)      │
+│  Section Header (centered)                              │
+│  [InfoCard] [InfoCard] [InfoCard]  (3-col grid)        │
+│                                                         │
+├────────────────────────────────────────────────────────┤
+│  STATS SECTION (bg-base, padding: space-16)            │
+│  [StatCard] [StatCard] [StatCard] [StatCard]           │
+│                                                         │
+├────────────────────────────────────────────────────────┤
+│  SOCIAL PROOF / TESTIMONIALS (bg-surface)              │
+│  Quote cards in 2-col grid                              │
+│                                                         │
+├────────────────────────────────────────────────────────┤
+│  CTA SECTION (accent glow background)                  │
+│  Display heading + CTA button (centered)                │
+│                                                         │
+├────────────────────────────────────────────────────────┤
+│  FOOTER (bg-void)                                      │
+│  Columns: Brand | Links | Links | Newsletter           │
+└────────────────────────────────────────────────────────┘
+```
+
+**Key differences from dashboard:**
+- Sections are full-width with alternating `bg-base` / `bg-surface`
+- Spacing between sections: `padding: var(--space-20) var(--space-6)`
+- Hero heading: `--text-5xl` on desktop, `--text-3xl` on mobile
+- Content max-width: `1200px`, centered with `margin: 0 auto`
+- Section headers centered: `text-align: center`
+- CTA section: `background: var(--bg-surface)` with `radial-gradient` glow
+
+## 7. Institutional / Corporate
+
+Same as Landing Page but with these pages:
+
+- **About page**: Hero + text blocks + team card grid (avatar cards with name, role, social)
+- **Services page**: Hero + service info cards (icon + title + desc) in 3-col grid
+- **Contact page**: Two columns — left: text + info cards, right: form card
+
+Team card variant:
+```
+┌───────────────────┐
+│     [Avatar]      │
+│    Team Member    │ ← text-heading, weight-bold
+│      CEO          │ ← text-accent, italic
+│   Short bio text  │ ← text-secondary, text-sm
+│   [Social icons]  │
+└───────────────────┘
+```
+
+## Responsive Breakpoints
+
+Apply to all patterns:
+```css
+/* Mobile: single column, sidebar collapses, stats stack */
+@media (max-width: 768px) {
+  .main-layout { flex-direction: column; }
+  .sidebar { width: 100%; border-right: none; border-bottom: 1px solid var(--border-subtle); }
+  .card-grid { grid-template-columns: 1fr; }
+  .stats-row { flex-direction: column; }
+  .hero-heading { font-size: var(--text-3xl); }
+}
+/* Tablet: 2-col grid */
+@media (min-width: 768px) and (max-width: 1024px) {
+  .card-grid { grid-template-columns: repeat(2, 1fr); }
+}
+/* Desktop: 3-4 col grid */
+@media (min-width: 1024px) {
+  .card-grid { grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); }
+}
+```

package/template/.aioson/skills/squad/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: squad-skills
+description: Router and index for squad creation skills — domain knowledge, format templates, patterns, and references
+version: 1.0.0
+---
+
+# Squad Skills Router
+
+This directory contains knowledge that enriches the `@squad` agent during squad creation.
+
+## Directory structure
+
+```
+skills/squad/
+├── SKILL.md           ← you are here (router)
+├── domains/           ← domain-specific knowledge (e.g., youtube-content.md)
+├── formats/           ← content format templates (e.g., instagram-feed.md)
+├── patterns/          ← reusable structural patterns (e.g., review-loop-pattern.md)
+└── references/        ← reference materials (e.g., executor-archetypes.md)
+```
+
+## Loading strategy
+
+When creating a squad:
+
+1. **Read this file** to understand what's available
+2. **Check `domains/`** for a skill matching the squad's domain
+   - Exact match → load it
+   - Similar match → load and adapt
+   - No match → proceed with LLM knowledge
+3. **Check `patterns/`** for relevant structural patterns
+   - Review loops needed → load `review-loop-pattern.md`
+   - Multi-platform squad → load `multi-platform-pattern.md`
+   - Persona-driven squad → load `persona-based-pattern.md`
+   - Pipeline between squads → load `pipeline-pattern.md`
+4. **Check `formats/`** for content format templates
+   - Load only formats relevant to the squad's target platforms
+5. **Check `references/`** for supporting material
+   - Executor inspiration → `executor-archetypes.md`
+   - Quality gates → `checklist-templates.md`
+   - Workflow ideas → `workflow-templates.md`
+
+## NEVER load everything at once
+
+Only load skills that are directly relevant to the current squad.
+A software squad doesn't need instagram-feed.md.
+A YouTube squad doesn't need legal-consulting.md.
+
+## Adding new skills
+
+Anyone can add skills to enrich future squad creations:
+
+- **Domain skill:** Create `domains/{domain-name}.md` with recommended executors, anti-patterns, quality benchmarks, and structural patterns for that domain.
+- **Format template:** Create `formats/{format-name}.md` with content structure, sections, and block types.
+- **Pattern:** Create `patterns/{pattern-name}.md` with a reusable structural pattern.
+- **Reference:** Create `references/{reference-name}.md` with supporting material.
+
+The `@orache` investigator can suggest creating domain skills after completing an investigation.

package/template/.aioson/tasks/implementation-plan.md

@@ -0,0 +1,288 @@
+# Task: Generate Implementation Plan
+
+> Fase obrigatória entre spec completa e início de implementação.
+> Garante consistência, define sequência, e prepara context package para novo chat.
+
+## Quando executar
+
+### Automaticamente (agentes detectam)
+- /dev detecta que NÃO existe `implementation-plan.md` mas EXISTEM:
+  - `architecture.md` (SMALL/MEDIUM) ou `project.context.md` (MICRO)
+  - Pelo menos um de: `prd.md`, `prd-{slug}.md`, `readiness.md`
+- /orchestrator detecta o mesmo no Step 1
+
+### Manualmente
+- Usuário pede: "gere o plano de implementação"
+- Após /architect ou /pm finalizar seus artefatos
+
+### Feature mode
+- Detecta `prd-{slug}.md` existente sem `implementation-plan-{slug}.md`
+- Gera plan scoped à feature
+
+## Processo
+
+### Passo 1 — Inventory check
+
+Listar todos os artefatos em `.aioson/context/`. Para cada um, verificar:
+- Existe? Está completo? É consistente com os outros?
+- Sinalizar gaps e contradições
+
+Artefatos a verificar (em ordem de prioridade):
+
+| Artefato | Obrigatório para | Se ausente |
+|----------|-------------------|------------|
+| `project.context.md` | MICRO, SMALL, MEDIUM | STOP — não gere plan sem identidade |
+| `architecture.md` | SMALL, MEDIUM | Warn — plan terá sequência menos precisa |
+| `prd.md` ou `prd-{slug}.md` | Todos (se existe) | Info — plan baseado apenas em architecture |
+| `discovery.md` | SMALL, MEDIUM | Warn — risco de conflitos com entidades existentes |
+| `ui-spec.md` | Se tem UI | Info — fases de UI terão menos detalhe |
+| `readiness.md` | Se existe | Info — plan assume readiness = READY |
+| `spec.md` | Se existe | Info — sem histórico de decisões anteriores |
+| `design-doc.md` | Se existe | Info — decisões arquiteturais menos firmes |
+| `requirements-{slug}.md` | Feature mode | Warn — regras de negócio podem faltar |
+
+### Passo 2 — Cross-analysis
+
+Ler os artefatos na ordem: `project.context` → `discovery` → `architecture` → `prd` → `ui-spec` → `requirements` → `spec` → `design-doc`
+
+Buscar ativamente:
+- **Entidades fantasma:** referenciadas no PRD mas ausentes no discovery
+- **Contradições técnicas:** decisão no architecture que conflita com o PRD
+- **Dependências invisíveis:** feature no ui-spec que depende de algo não coberto
+- **Assumptions implícitas:** qualquer artefato que assume algo sem declarar
+- **Scope creep:** requisitos que parecem fora do scope declarado
+- **Riscos de integração:** pontos onde módulos diferentes precisam concordar
+
+Para cada issue encontrado, classificar:
+- **BLOCK** — não pode prosseguir sem resolver (ex: entidade central faltando)
+- **WARN** — pode prosseguir com assumption explícita (ex: campo inferido)
+- **INFO** — anotar para o dev ter consciência (ex: possível refatoração futura)
+
+### Passo 3 — Sequence planning
+
+Definir a ordem de implementação baseada em:
+
+**Dependências de dados (sempre primeiro):**
+1. Migrations / schemas / contracts
+2. Models / types / entities
+3. Repositories / data access
+
+**Dependências de lógica (depois dos dados):**
+4. Services / actions / use-cases
+5. Validação / policies / authorization
+
+**Dependências de interface (por último):**
+6. Controllers / API routes / handlers
+7. Views / components / pages
+
+**Módulos independentes:**
+- Identificar módulos que NÃO compartilham entidades → podem ser paralelos
+- Identificar módulos que COMPARTILHAM entidades → devem ser sequenciais
+- Se /orchestrator vai usar, marcar explicitamente: `parallel: true/false`
+
+**Para cada fase, definir:**
+- Título descritivo
+- O que implementar (concreto, não vago)
+- De que depende
+- Quais artefatos o /dev precisa ler
+- Critério de done (como saber que terminou)
+- Checkpoint gate (o que verificar antes de seguir)
+
+### Passo 4 — Context package
+
+O context package é o conjunto MÍNIMO de arquivos que o próximo agente ou chat precisa ler para executar o plan com qualidade máxima.
+
+**Princípios:**
+- Menos é mais — 3-5 arquivos é o ideal, nunca mais de 7
+- O implementation-plan.md SEMPRE é o primeiro arquivo
+- Artefatos já digeridos no plan NÃO precisam ser re-lidos
+- Separar "leitura obrigatória" de "leitura sob demanda"
+
+**Formato do context package:**
+
+```
+Leitura obrigatória (nesta ordem):
+1. implementation-plan.md ← este arquivo
+2. project.context.md
+3. architecture.md (se SMALL/MEDIUM)
+4. spec.md (se existe — histórico de decisões)
+
+Leitura sob demanda (quando tocar no tema):
+- discovery.md — quando tocar em entidades existentes
+- prd.md — quando tiver dúvida sobre requisito
+- ui-spec.md — quando implementar UI
+- requirements-{slug}.md — quando implementar a feature
+
+NÃO re-ler (já sintetizado neste plan):
+- [lista de artefatos cujo conteúdo relevante já está no plan]
+```
+
+### Passo 5 — Decision registry
+
+Separar decisões em duas categorias:
+
+**Decisões pré-tomadas (NÃO re-discutir):**
+- Decisões do /architect que já foram validadas
+- Escolhas de stack documentadas em project.context.md
+- Convenções definidas em rules/
+- Restrições documentadas no prd
+
+**Decisões adiadas (o /dev vai tomar):**
+- Trade-offs que só fazem sentido com código na frente
+- Escolhas de implementação (ex: eager vs lazy loading)
+- Otimizações que dependem de profiling
+
+Para cada decisão adiada: descrever o trade-off e indicar a direção preferida.
+
+### Passo 6 — Generate plan
+
+Salvar o plan como:
+- **Project mode:** `.aioson/context/implementation-plan.md`
+- **Feature mode:** `.aioson/context/implementation-plan-{slug}.md`
+
+Formato do artefato:
+
+```markdown
+---
+project: "{project_name}"
+scope: "{project | feature}"
+feature_slug: "{slug ou null}"
+created: "{ISO-8601}"
+status: "draft"
+classification: "{MICRO | SMALL | MEDIUM}"
+source_artifacts:
+  - project.context.md
+  - architecture.md
+  - prd.md
+---
+
+# Implementation Plan
+
+> Gerado após consolidação de todos os artefatos de spec.
+> Aprovado pelo usuário antes de qualquer implementação.
+> Status: draft → approved → in_progress → completed
+
+## Pre-flight check
+
+### Artefatos lidos
+- [x] project.context.md — ok
+- [x] architecture.md — ok
+- [ ] discovery.md — missing (proceeding with assumptions)
+[...]
+
+### Consistency check
+{issues encontrados, classificados como BLOCK/WARN/INFO}
+
+### Readiness verdict
+{READY | READY_WITH_ASSUMPTIONS | NOT_READY}
+
+## Execution Strategy
+
+### Fase 1 — {título} (estimativa: {N arquivos/commits})
+- **O que:** {descrição concreta — não "implementar o módulo", mas "criar migration users com campos X, Y, Z + model User com relação hasMany Orders"}
+- **Depende de:** nada
+- **Artefatos de entrada:** {lista de arquivos que o dev precisa ler}
+- **Critério de done:** {ex: migration roda sem erro, model passa nos testes de relação}
+- **Checkpoint:** {ex: verificar que a tabela users existe e tem os campos corretos}
+
+### Fase 2 — {título}
+[...]
+
+### Fases paralelas (se /orchestrator for usar)
+- Fase X e Fase Y podem rodar em paralelo (sem entidades compartilhadas)
+- Fase Z depende de X (compartilham tabela orders)
+
+## Decisões pré-tomadas
+- {decisão 1 — fonte: architecture.md — não re-discutir}
+- {decisão 2 — fonte: prd.md — validado pelo product}
+
+## Decisões adiadas
+- {decisão 1 — trade-off: A vs B — direção preferida: A porque ...}
+- {decisão 2 — depende do resultado da Fase 1}
+
+## Context Package
+
+### Leitura obrigatória (ordem importa)
+1. `implementation-plan.md` ← este arquivo
+2. `project.context.md`
+3. `architecture.md`
+4. `spec.md`
+
+### Leitura sob demanda
+- `discovery.md` — quando tocar em entidades
+- `prd.md` — quando tiver dúvida sobre requisito
+- `ui-spec.md` — quando implementar UI
+
+### NÃO re-ler
+- {artefato X — já sintetizado nas fases acima}
+
+## Instruções para o próximo agente
+
+> Para /dev ou /orchestrator:
+>
+> 1. Leia este arquivo PRIMEIRO
+> 2. Siga a sequência de fases na ordem
+> 3. Após cada fase, atualize spec.md com as decisões tomadas
+> 4. Se encontrar contradição com este plano, PARE e pergunte ao usuário
+> 5. Decisões pré-tomadas são final — não re-discutir
+> 6. Decisões adiadas são para você tomar — registre em spec.md
+> 7. Ao completar cada fase, marque o checkpoint
+```
+
+### Passo 7 — Apresentar ao usuário
+
+Mostrar resumo conciso:
+
+```
+Implementation Plan gerado.
+
+Fases: {N} ({M paralelas se orchestrator)
+Consistency: {N blocks, M warns, P infos}
+Readiness: {READY | READY_WITH_ASSUMPTIONS | NOT_READY}
+Context package: {N arquivos obrigatórios + M sob demanda}
+
+Sequência:
+1. {fase 1 — 1 linha}
+2. {fase 2 — 1 linha}
+[...]
+
+Recomendação: {iniciar novo chat para implementação / continuar aqui}
+```
+
+Perguntar:
+> "Plano de implementação pronto. Quer ajustar algo antes de começar?"
+
+Se o chat atual já consumiu muitos tokens com discovery/design:
+> "Recomendo iniciar um novo chat para a implementação — o context package está definido no plano."
+
+## Adaptação por classificação
+
+### MICRO
+- Plan é **opcional** (overhead pode não valer)
+- Se gerado: 1-3 fases, sem cross-analysis profunda
+- Context package: só `project.context.md` + `implementation-plan.md`
+- Pular passo 2 (cross-analysis) se artefatos são mínimos
+
+### SMALL
+- Plan é **recomendado**
+- 3-5 fases típicas
+- Context package: 3-4 arquivos
+- Cross-analysis: PRD ↔ architecture + discovery ↔ PRD
+
+### MEDIUM
+- Plan é **obrigatório** (orchestrator precisa antes de paralelizar)
+- 5-10 fases com dependências explícitas
+- Context package: 4-5 arquivos + subagent-specific packages
+- Cross-analysis: completa entre todos os artefatos
+- Marcar fases paralelas explicitamente
+
+## Regras
+
+- NÃO comece a implementar nesta task — SÓ planeje
+- NÃO ignore gaps BLOCK — sinalize e PARE
+- NÃO invente requisitos — se não está nos artefatos, é uma decisão adiada
+- O plan é um ARTEFATO PERSISTENTE — salve em arquivo, nunca só no chat
+- Se readiness = NOT_READY, PARE e diga o que falta antes de gerar fases
+- Cada fase deve ser CONCRETA o suficiente para o /dev executar sem ambiguidade
+- Fases vagas como "implementar o backend" são proibidas — detalhe QUAIS arquivos, QUAIS entidades
+- Após aprovação do usuário, mude status de `draft` para `approved`

package/template/.aioson/tasks/squad-create.md

@@ -32,7 +32,7 @@ Leia `.aioson/squads/.designs/<slug>.blueprint.json` e valide que os campos obri
 └── squad.manifest.json        # Manifesto JSON formal
 
 output/<slug>/                  # Diretório de output
-aios-logs/<slug>/               # Diretório de logs
+aioson-logs/<slug>/               # Diretório de logs
 media/<slug>/                   # Diretório de mídia
 ```