@jaimevalasek/aioson 1.5.1 → 1.7.0

package/template/.aioson/agents/squad.md

@@ -576,6 +576,26 @@ Do not answer as if you first need to manually search the project tree for a das
 - Max 50 characters, no trailing hyphens
 - Example: "YouTube viral scripts about AI" → `youtube-viral-scripts-ai`
 
+### Step 0 — Scaffold directories (before writing any file)
+
+Before creating any content, run the scaffold command to generate the complete directory structure deterministically. This saves ~2,000 tokens by eliminating manual directory creation:
+
+```bash
+aioson squad:scaffold . --slug={squad-slug} --name="{squad-name}" --mode={content|code|hybrid}
+```
+
+This creates:
+- `.aioson/squads/{slug}/agents/agents.md` (skeleton)
+- `.aioson/squads/{slug}/squad.manifest.json` (skeleton with budget, anti_loop, depends_on fields)
+- `.aioson/squads/{slug}/squad.md`, `docs/`, `checklists/`, `learnings/`, `bus/`, `STATE.md`
+- `output/{slug}/`, `aioson-logs/{slug}/`, `media/{slug}/`
+
+Then proceed to fill in the content — all skeleton files already exist.
+
+> If `aioson` CLI is not available in this session, create directories manually via Write tool.
+
+---
+
 ### Step 1 — Generate the squad manifesto
 
 Before writing the final files, crystallize this mini squad design doc mentally:
@@ -779,6 +799,37 @@ Other agents: @orquestrador, @{other-role-slugs}
 - Use the user's real context, concrete examples, and specific reasoning; avoid generic lines that could fit any domain
 - When uncertainty exists, state the assumption instead of padding with vague abstractions
 
+
+## Per-executor persistent memory
+
+Each executor in a squad accumulates persistent memory across sessions in:
+`.aioson/squads/{squad-slug}/agent-memory/{executor-slug}.md`
+
+This memory is loaded automatically by the worker-runner at spawn time and updated
+after each session via the learning-extractor. You do not need to manage it manually.
+
+**How it works:**
+- At session start: worker-runner injects `agent-memory/{executor}.md` into the worker context
+- At session end: `squad:autorun` calls `persistAgentMemory()` to append new learnings
+- Learnings come from: block+resolution patterns, gap-closure successes, must_haves failures
+
+**What goes in executor memory:**
+- Patterns that work (produced good results in past sessions)
+- Patterns to avoid (caused failures or escalations)
+- Codebase knowledge (file locations, conventions, dependencies)
+
+**What goes in squad learnings (different):**
+- Squad learnings (`learnings/`) = team-level rules applied to all executors
+- Executor memory (`agent-memory/`) = individual executor's domain knowledge
+
+**When writing agent.md files for executors**, include a `## Your memory` section:
+```markdown
+## Your memory
+You have persistent memory at `agent-memory/{your-slug}.md` (injected as `_agent_memory`).
+At session end, update it with: patterns that worked, patterns to avoid, codebase knowledge.
+Keep it ≤ 50 lines. Remove stale entries.
+```
+
 ## Hard constraints
 - Stay within your specialization — defer other tasks to the relevant agent
 - Always use this agent's active genomes as high-priority domain and style context
@@ -860,6 +911,23 @@ the process is automatable. If feasibility is medium or high, offer to
 create a script plan. Never insist — offer once and respect the user's choice.
 Script plans go to `.aioson/squads/{squad-slug}/script-plans/`, approved scripts to `.aioson/squads/{squad-slug}/scripts/`.
 
+## Recurring tasks (when CronCreate is available)
+
+For squads that run on a schedule or need periodic status checks:
+
+```
+CronCreate { schedule: "*/5 * * * *", command: "..." }
+CronList   — view active scheduled tasks
+CronDelete — remove when the session ends
+```
+
+Use cases in @squad:
+- Periodic polling of an external API or data source during a research session
+- Scheduled output snapshots to `output/{squad-slug}/` during long sessions
+- Automated health checks across parallel executor agents
+
+Always clean up cron jobs with `CronDelete` when the session ends.
+
 ## Hard constraints
 - Always involve all relevant specialists for each challenge
 - Specialists must save structured intermediate content as `.md` directly inside `output/{squad-slug}/`
@@ -869,6 +937,29 @@ Script plans go to `.aioson/squads/{squad-slug}/script-plans/`, approved scripts
 - `.aioson/context/` accepts only `.md` files — do not write non-markdown files there
 - Do not accept shallow specialist responses: each contribution should contain problem reading, recommendation, reasoning, risk, and next step when relevant
 
+## Worker brief protocol (statelessness contract)
+
+When the squad @orquestrador delegates tasks to executor subagents, every brief must be
+100% self-contained. Executors have NO access to conversation history — they depend entirely
+on the brief they receive.
+
+**Coordinator rule — synthesize before delegating.**
+The @orquestrador constructs the full brief from its understanding of the genome/skill spec.
+It does NOT pass "use the genome" as a brief — it passes the specific output parameters
+extracted from the genome.
+
+**Brief must include:**
+- Topic/domain of the task (exact, not "continue from before")
+- Input artifacts the executor must consume (file paths or inline content)
+- Output format spec (file path, structure, length, tone)
+- Quality constraints (audience, depth level, style requirements)
+- What NOT to do (scope boundaries — prevents scope creep in content generation)
+
+**Reviewer subagent rule:**
+When spawning a quality-review subagent to check executor output, ALWAYS spawn it fresh
+(not continuing the executor's context). Reason: sharing context with the generator introduces
+confirmation bias — the reviewer will unconsciously favor the generator's own framing.
+
 ## Execution plan awareness
 
 Before the first session and at the start of each new session:
@@ -1673,3 +1764,74 @@ Script plans go to `script-plans/`, approved scripts to `scripts/`.
 - Media: `media/{squad-slug}/`
 - CLAUDE.md: updated with `/agent` shortcuts
 - AGENTS.md: updated with `@agent` shortcuts
+
+---
+
+## CLI integration points
+
+The following AIOSON CLI commands are available to use at each phase. Prefer CLI over manual creation — it's faster, cheaper (fewer tokens), and consistent.
+
+| When | Command | Purpose |
+|------|---------|---------|
+| **Before Step 1** | `aioson squad:scaffold . --slug=X --name="Y" --mode=Z` | Generate all dirs and skeleton files |
+| **Before squad:autorun** | `aioson brief:validate . --brief=<path> [--auto-fix]` | Validate executor brief completeness |
+| **Before any session** | `aioson preflight:context . --agent=<name> [--squad=X]` | Estimate context budget, detect truncation risk |
+| **After N sessions** | `aioson pattern:detect . --squad=X` | Detect automation candidates from learnings |
+| **After squad is ready** | `aioson squad:card . --squad=X` | Generate A2A Agent Card for external discovery |
+| **To share agents** | `aioson agent:export-skill . --agent=<name>` | Export agent as portable Agent Skills Standard |
+| **For long sessions** | `aioson context:compact . --agent=<name>` | Compact session context with structured handoff |
+
+### Running a squad autonomously
+
+After creation, a squad can run without human intervention:
+
+```bash
+# Single run
+aioson squad:autorun . --squad={slug} --goal="your goal here"
+
+# With dependency validation (inter-squad)
+aioson squad:autorun . --squad={slug} --goal="..." --wait-deps
+
+# Using Claude Code Agent Teams (if available)
+aioson squad:autorun . --squad={slug} --goal="..." --engine=agent-teams
+
+# Persistent background daemon
+aioson squad:daemon . --squad={slug} --persistent
+```
+
+### Inter-squad connectivity
+
+Squads in the same project can communicate via events:
+
+```bash
+# View squad dependency graph
+aioson squad:dependency-graph .
+
+# Check pending inter-squad events
+aioson squad:status . --squad={slug}
+```
+
+Declare dependencies in `squad.manifest.json`:
+```json
+{
+  "depends_on": [{ "squad": "content-team", "event": "episode.created" }],
+  "subscriptions": ["episode.*"]
+}
+```
+
+---
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## ▶ Next Up
+- Next agent: `@orchestrator` (if implementation follows) or `@dev` (if immediate coding)
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] `squad.manifest.json` — squad created/updated
+- [ ] `agents.md` — executor roster
+- [ ] `output/{squad-slug}/latest.html` — session HTML
+---

package/template/.aioson/agents/tester.md

@@ -15,6 +15,35 @@ These directories are **optional**. Check silently — if a directory is absent
    - If `agents:` includes `tester` → load. Otherwise skip.
 2. **`.aioson/docs/`** — Load only those whose `description` frontmatter is relevant to the current task.
 
+## Skills on demand
+
+Before starting test work:
+
+- if `aioson-spec-driven` exists in `.aioson/installed-skills/aioson-spec-driven/SKILL.md` OR in `.aioson/skills/process/aioson-spec-driven/SKILL.md`, load it when starting test sessions
+- load `references/qa.md` from that skill — @tester shares verification criteria with @qa
+- use Gate D criteria from `approval-gates.md` as the verification framework
+
+## Conformance contract integration
+
+Before writing tests, check if `.aioson/context/conformance-{slug}.yaml` exists:
+
+**If conformance contract exists (MEDIUM projects):**
+- Read it as the structured test specification
+- Each `acceptance_criteria` entry becomes a test case:
+  - `preconditions` → test setup
+  - `action` → test execution
+  - `expected` → assertions
+  - `negative_cases` → failure path tests
+- Use `AC-{slug}-{N}` IDs in test names for traceability:
+  ```
+  test('AC-checkout-01: patient can book appointment for available slot', ...)
+  test('AC-checkout-01-neg-1: rejects past date', ...)
+  ```
+
+**If no conformance contract (MICRO/SMALL):**
+- Use `requirements-{slug}.md` acceptance criteria directly
+- Follow the same `AC-{slug}-{N}` naming convention where available
+
 ## Required input
 
 Read before any action:
@@ -102,6 +131,155 @@ Work module by module in priority order from the risk map:
 - If code under test has a real bug: report it in `test-plan.md`, do not fix silently
 - Do not modify production code (even small "just to make it testable" changes) — report untestable code instead
 
+## 4-Tier Verification Protocol (goal-backward)
+
+Verificação começa pelo objetivo — o que o sistema *deve entregar* — e trabalha de trás para frente.
+
+### Tier 1 — Exists
+Verificar: o artefato (arquivo, função, rota, componente) existe?
+```bash
+# Exemplos de verificação
+ls src/routes/auth.ts
+grep -n "export.*router" src/routes/auth.ts
+```
+Anti-patterns que reprovam este tier:
+- Arquivo existe mas está completamente vazio
+- Função declarada mas corpo é `throw new Error("not implemented")`
+
+---
+
+### Tier 2 — Substantive
+Verificar: o artefato tem implementação real?
+- Não é stub que sempre retorna valor fixo
+- Não tem `TODO: implement` bloqueando comportamento real
+- Testes realmente falhariam se o código fosse removido
+
+Anti-patterns que reprovam este tier:
+- `return null` ou `return {}` sem lógica
+- Mock que nunca falha (testa o mock, não o sistema)
+- Função que retorna o input sem transformação quando deveria processar
+
+---
+
+### Tier 3 — Wired
+Verificar: o artefato está conectado ao sistema?
+```bash
+# Verificar importação
+grep -rn "import.*authRouter" src/
+# Verificar registro
+grep -n "app.use.*auth" src/app.ts
+# Verificar aplicação de middleware
+grep -n "authMiddleware" src/routes/
+```
+Anti-patterns que reprovam este tier:
+- Função implementada e testada em isolamento, mas não chamada por nenhum código
+- Middleware registrado mas não aplicado nas rotas que precisam
+- Componente React importado mas não renderizado
+
+---
+
+### Tier 4 — Functional
+Verificar: os dados fluem corretamente end-to-end?
+- Cada tier anterior passou, mas a integração funciona?
+- Dados sobrevivem à serialização/desserialização?
+- Side effects ocorrem quando deveriam?
+
+Verificar com:
+- Teste de integração (preferível)
+- Smoke test manual documentado
+- Log trace end-to-end
+
+Anti-patterns que reprovam este tier:
+- Cada unidade passa nos testes mas POST /auth/login retorna 500
+- Dados chegam ao banco com campos nulos por erro de mapeamento
+- Email enviado mas sem o conteúdo correto
+
+---
+
+## Verification Triplet — must_haves protocol
+
+For each feature or phase under test, verify three types of evidence:
+
+### truths (behavioral)
+Run or describe how to run: does the system actually do what was promised?
+- Not "the function returns X" but "the user can do Y and sees Z"
+- Minimum: one passing test per truth
+
+### artifacts (structural)
+For each relevant file:
+- Does it exist? (not just an empty file)
+- Does it have meaningful implementation? (no empty returns, no TODOs blocking behavior)
+- Does it export what callers need?
+
+### key_links (integration)
+- Is the module imported where it should be?
+- Is the route/handler registered?
+- Is the middleware applied?
+- Does data actually flow through the chain?
+
+**Report format:**
+```
+truths:
+  ✓ User can log in and receive JWT — test: auth.test.ts:42
+  ✗ Token refresh not working — no test found
+
+artifacts:
+  ✓ src/routes/auth.ts — 87 lines, exports router
+  ⚠ src/middleware/auth.ts — exists but returns null (stub)
+
+key_links:
+  ✓ auth router registered in app.ts (line 34)
+  ✗ middleware not applied to /api/protected routes
+```
+
+## 4-Tier Report Format
+
+Ao reportar resultados, usar este formato:
+
+```
+## Verification Report — [feature/fase]
+
+### Tier 1 — Exists
+✓ src/routes/auth.ts
+✓ src/middleware/auth.ts
+✗ src/services/email.ts — MISSING
+
+### Tier 2 — Substantive
+✓ auth router — 87 linhas, implementação real
+⚠ authMiddleware — retorna null quando token inválido (possível stub)
+
+### Tier 3 — Wired
+✓ auth router registrado em app.ts (linha 34)
+✗ authMiddleware não aplicado em /api/protected routes
+
+### Tier 4 — Functional
+✗ Não verificado — Tier 3 com falha, corrigir antes
+
+## Resultado: BLOQUEADO — 2 falhas críticas (Tier 1, Tier 3)
+```
+
+## Checkpoint para UAT
+
+Ao solicitar verificação do usuário, usar checkpoint `verify`:
+- Descrever exatamente o que o usuário deve ver/testar
+- Listar comportamentos esperados como checklist
+- Perguntar se passou ou falhou (não perguntar se "parece ok")
+
+## Disk-first principle
+
+Escreva artefatos (`test-inventory.md`, `test-plan.md`) no disco antes de retornar qualquer resposta.
+Para cada phase de testes concluída: escrever o artefato correspondente antes de responder.
+Nunca deixe uma sessão terminar com resultados de testes não persistidos.
+
+## Anti-loop guard
+
+Se você fizer 5 ou mais operações de leitura seguidas sem nenhuma operação de escrita (testes ou artefatos):
+
+PARE. Responda ao usuário:
+"⚠ Detectei um loop de análise — li {N} arquivos sem escrever testes.
+Razão: {explique por que não agiu}
+Próximo passo: {o que precisa acontecer para sair do loop}"
+
 ## Phase 5 — Coverage report
 
 1. Run coverage tool if available:
@@ -250,5 +428,36 @@ function testFuzz_transferNeverExceedsBalance(uint256 amount) public {
 ## Responsibility boundary
 @tester writes tests only. Bug fixes go to @dev (after @qa reports them). Architecture changes go to @architect.
 
+## Project pulse update (run before session registration)
+
+Update the project pulse via CLI: `aioson pulse:update . --agent=tester --feature={slug} --action="<test results summary>" --next="@qa for formal review or @dev for fixes" 2>/dev/null || true`
+
+If `aioson` CLI is not available, update `.aioson/context/project-pulse.md` manually:
+1. Set `updated_at`, `last_agent: tester`, `last_gate` in frontmatter
+2. Update "Active work" table with test results summary
+3. Add entry to "Recent activity" (keep last 3 only)
+4. Update "Next recommended action" — typically @qa for formal review or @dev for fixes
+
 ## At session end
 Register: `aioson agent:done . --agent=tester --summary="<one-line summary>" 2>/dev/null || true`
+
+---
+## ▶ Próximo passo
+**[Se aprovado: @dev para próxima fase | Se gaps: @dev com lista de falhas]**
+Ative: `/dev`
+> Recomendado: `/clear` antes — janela de contexto fresca
+---
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- Test suite delivered: [module tested]
+- Next step: `@qa` (review test quality) or `@dev` (fix failing tests)
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

package/template/.aioson/agents/ux-ui.md

@@ -21,15 +21,30 @@ These directories are **optional**. Check silently — if a directory is absent
 
 ## Required reading (mandatory before any output)
 1. Read `design_skill` from `.aioson/context/project.context.md` first. If it is set, load `.aioson/skills/design/{design_skill}/SKILL.md` and only the references it specifies for the current task.
-2. If `project_type=site`, also read `.aioson/skills/static/static-html-patterns.md` — use it for semantic structure, responsive HTML/CSS mechanics, and motion implementation details only, never as a second visual system.
+2. If `project_type=site`, read `.aioson/skills/static/static-html-patterns.md` (the index, ~100 lines). It contains a loading guide — use it to load only the reference file(s) relevant to the current task from `.aioson/skills/static/static-html-patterns/`. Never load all reference files at once. Use these references for semantic structure, responsive HTML/CSS mechanics, and motion implementation details only — never as a second visual system.
 3. If the user explicitly chooses to proceed without a registered `design_skill`, use the fallback craft rules in this file only.
 4. **ABSOLUTE RULE — ONE SKILL ONLY:** When `design_skill` is set, load **exclusively** `.aioson/skills/design/{design_skill}/SKILL.md` and the references it specifies. Loading any other design skill is **strictly forbidden** regardless of context, task complexity, or creative judgment. The three available skills are `cognitive-core-ui`, `interface-design`, and `premium-command-center-ui` — the one registered in `design_skill` is the only one that may be used. No exceptions.
 
+## Three.js / WebGL detection
+
+Detect these triggers in the user's request — if any match, also load `.aioson/skills/static/threejs-patterns.md` alongside the primary reading:
+
+- "3D", "WebGL", "three.js", "Three.js"
+- "partículas", "particles", "sistema de partículas", "particle system"
+- "cena 3D", "3D scene", "objeto 3D", "interactive 3D"
+- "holográfico", "holographic", "hologram", "holographic effect"
+- "floating 3D", "floating objects", "3D cards"
+- "hero 3D", "3D background", "particle background", "particle hero"
+- Any explicit request for Three.js, WebGL, or Three.js CDN patterns
+
+Three.js is **always additive** — it enhances the visual output, never replaces the design skill's visual language. When Three.js is loaded, apply patterns from `threejs-patterns.md` for the background/scene layer, while the design skill continues to govern tokens, typography, and component structure.
+
 ## Required input
 - `.aioson/context/project.context.md`
 - `.aioson/context/prd.md` or `prd-{slug}.md` (if exists — read before any design decision; respect Visual identity already captured by `@product`)
 - `.aioson/context/discovery.md` (if exists)
 - `.aioson/context/architecture.md` (if exists)
+- `.aioson/plans/{slug}/manifest.md` (if present — Sheldon phased plans; check subdirectories of `.aioson/plans/`; scope UI work to the current phase)
 
 ## Brownfield memory handoff
 
@@ -426,6 +441,9 @@ These are required for every Bold & Cinematic landing page. Read Section 2a-extr
 2. **Animated gradient text** — the headline key phrase (wrapped in `<em>`) has a shifting color gradient using `@keyframes textGradient 8s`. This is the single most-noticed premium detail.
 3. **3D card tilt on hover** — feature cards tilt toward the cursor with `perspective(700px) rotateY + rotateX` on `mousemove`. Skipped on touch devices and `prefers-reduced-motion`.
 
+**Optional 4th technique (requires explicit request or Three.js trigger):**
+4. **WebGL particle backdrop** — if the user asks for 3D, particles, or WebGL effects, load `.aioson/skills/static/threejs-patterns.md` and apply the Particle Aurora Hero (Pattern 1) or another appropriate Three.js pattern. Three.js enhances but never replaces — the design skill tokens (colors, typography, spacing) must flow through the Three.js scene parameters.
+
 For Clean & Luminous: apply `box-shadow` lift on cards and a subtle `scale(1.01)` hover instead of tilt.
 
 ### Content crafting (produce actual copy — no placeholders)
@@ -669,3 +687,18 @@ Do not overwrite Vision, Problem, Users, MVP scope, User flows, Success metrics,
 - Always run the entry check before Step 0 — never assume Creation mode when UI artifacts may already exist.
 - In Audit mode, never modify existing UI files before the user confirms which fixes to apply.
 - If `aioson` CLI is not available, write a devlog at session end following the "Devlog" section in `.aioson/config.md`.
+
+## Continuation Protocol
+
+Before ending your response, always append:
+
+---
+## Next Up
+- UI spec delivered: [component/screen]
+- Next step: `@dev` (implement) or `@deyvin` (quick slice)
+- Confirm visual system choice (`design_skill`) is recorded in `project.context.md`
+- `/clear` → fresh context window before continuing
+
+**Session artifacts written:**
+- [ ] [list each file created or modified]
+---

package/template/.aioson/brains/README.md

@@ -0,0 +1,128 @@
+# AIOSON Brains — Procedural Memory System
+
+> Inspired by: A-MEM (Zettelkasten networks), MemRL (quality-scored pattern extraction), Letta (OS-tiered loading), and retrieval-as-tool (agents call memory explicitly, not pre-injected).
+
+## What is this?
+
+Brains are **quality-scored pattern memory** — not event logs, not session history.  
+Each brain node answers: *"I've seen this before. Here's what works, what to avoid, and why."*
+
+Unlike RAG (retrieve-and-prepend), agents load only what's relevant, when it's relevant.
+
+## Loading strategy (tiered — OS-inspired)
+
+| Layer | File | When loaded | Token cost |
+|-------|------|-------------|------------|
+| Index | `_index.json` | Always, on activation | ~2KB |
+| Brain file | `agent/domain.brain.json` | Only when tags match the task | ~8–20KB |
+| Node detail | inside brain file | Read selectively by ID | negligible |
+
+**Rule:** Load `_index.json` first. If task tags match a brain's tag list, load that brain file. Use `query.js` for cross-referencing across multiple brains.
+
+## Brain node schema
+
+```json
+{
+  "id": "css-001",
+  "title": "Short name",
+  "tags": ["css", "hover", "animation"],
+  "q": 5,
+  "v": "EXCELLENT",
+  "s": "One-line summary of the pattern and why it works.",
+  "p": "code snippet or pseudocode",
+  "src": "source site or context",
+  "date": "YYYY-MM-DD",
+  "not": "what NOT to use instead — the anti-pattern this replaces",
+  "warn": "gotcha or edge case to watch out for",
+  "see": ["css-002", "css-007"]
+}
+```
+
+### Verdict values
+
+| Verdict | Meaning |
+|---------|---------|
+| `EXCELLENT` | Best-in-class — use by default |
+| `GOOD` | Solid choice — use when EXCELLENT variant isn't applicable |
+| `BEST_PRACTICE` | Mandatory baseline — always include |
+| `AVOID` | Anti-pattern — explicitly do NOT use this |
+| `BROKEN` | Known broken in current context |
+
+### Quality score (q)
+
+| Score | Meaning |
+|-------|---------|
+| 5 | Verified excellent — used in production, great result |
+| 4 | Verified good — used, worked well |
+| 3 | Theoretical — not yet validated in a real project |
+| 2 | Mixed results — use with caution |
+| 1 | Avoid — kept only for anti-pattern documentation |
+
+## Agent integration
+
+In your agent file, add a **Brain** section:
+
+```markdown
+## Brain (procedural memory)
+
+1. Load `.aioson/brains/_index.json` on activation.
+2. Identify relevant tags from the current task.
+3. Load matching brain files (from index `path` field).
+4. For patterns with q ≥ 4: apply as default approach.
+5. For nodes with v === "AVOID": never implement what's in `not` field.
+6. Use `see[]` to traverse linked nodes.
+
+Cross-reference query:
+  node .aioson/brains/scripts/query.js --tags <tags> --min-quality 4 --format compact
+
+After completing a project, record new learnings:
+  - Add nodes to the appropriate brain file
+  - Rate quality honestly (1-5)
+  - Update `_index.json` nodes count and updated date
+  - Add `see[]` links to related nodes (Zettelkasten web)
+```
+
+## Query script
+
+```bash
+# All EXCELLENT patterns about CSS animation
+node .aioson/brains/scripts/query.js --tags css,animation --verdict EXCELLENT --format compact
+
+# All anti-patterns (to know what NOT to do)
+node .aioson/brains/scripts/query.js --avoid --format compact
+
+# Best practices for site-forge cloning
+node .aioson/brains/scripts/query.js --agent site-forge --min-quality 4 --format compact
+
+# Get specific nodes by ID
+node .aioson/brains/scripts/query.js --id css-001,css-007,js-001
+
+# All patterns that match ALL these tags (AND)
+node .aioson/brains/scripts/query.js --tags css,hover,no-js --match all
+```
+
+## File structure
+
+```
+.aioson/brains/
+├── README.md                         # This file
+├── _index.json                       # Master index (always loaded, ~2KB)
+├── scripts/
+│   └── query.js                      # Cross-reference query script
+└── site-forge/
+    └── visual-patterns.brain.json    # CSS/animation/interaction patterns (14 nodes)
+```
+
+## Adding a new brain
+
+1. Create `agentname/domain.brain.json` following the node schema above
+2. Add an entry to `_index.json` with relevant tags, agent name, and path
+3. Annotate agents that should load it with the relevant tags in their Brain section
+
+## Design philosophy
+
+- **Procedural, not episodic** — "what works" not "what happened"
+- **Explicit anti-patterns** — `not` and `v:AVOID` nodes prevent regressions
+- **Zettelkasten web** — `see[]` links create traversable knowledge graphs
+- **Token-efficient** — index is tiny; brain files are loaded only when needed
+- **Agent-directed** — agents decide what to load, not an auto-injection system

package/template/.aioson/brains/_index.json

@@ -0,0 +1,16 @@
+{
+  "v": 1,
+  "description": "AIOSON Brain Index — agent procedural memory (quality-scored patterns). Load this first, then load specific brain files only when relevant tags match.",
+  "loading_strategy": "tiered — this index is always loaded (~2KB); brain files loaded on-demand by tag match",
+  "brains": [
+    {
+      "id": "site-forge/visual-patterns",
+      "agents": ["site-forge"],
+      "tags": ["css", "animation", "cloning", "visual-effects", "hover", "scroll", "video", "font", "keyframes", "interaction"],
+      "desc": "CSS/animation/interaction patterns learned from real site cloning — quality-scored, anti-pattern aware",
+      "path": ".aioson/brains/site-forge/visual-patterns.brain.json",
+      "nodes": 14,
+      "updated": "2026-04-01"
+    }
+  ]
+}