@jaimevalasek/aioson 1.5.1 → 1.7.0

package/template/.aioson/brains/scripts/query.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * AIOSON Brain Query
+ * Cross-references pattern nodes across brain files by tags, quality, verdict, and agent.
+ *
+ * Usage:
+ *   node query.js --tags css,hover                    # nodes matching any of these tags
+ *   node query.js --tags css,hover --match all        # nodes matching ALL tags (AND)
+ *   node query.js --min-quality 4                     # quality >= 4 only
+ *   node query.js --agent site-forge                  # brain files for this agent
+ *   node query.js --verdict EXCELLENT,BEST_PRACTICE   # filter by verdict
+ *   node query.js --avoid                             # show only AVOID nodes (anti-patterns)
+ *   node query.js --id css-001,css-002                # fetch specific node IDs
+ *   node query.js --tags animation --format compact   # one-line per node output
+ *
+ * Output: JSON array of matching nodes (default) or compact table (--format compact)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BRAINS_DIR = path.resolve(__dirname, '..');
+const INDEX_PATH = path.join(BRAINS_DIR, '_index.json');
+
+// --- Parse args ---
+const args = process.argv.slice(2);
+const get = (flag) => { const i = args.indexOf(flag); return i !== -1 ? args[i + 1] : null; };
+const has = (flag) => args.includes(flag);
+
+const tagsRaw   = get('--tags');
+const tags      = tagsRaw ? tagsRaw.split(',').map(t => t.trim()) : [];
+const matchMode = get('--match') || 'any';       // 'any' | 'all'
+const minQ      = parseInt(get('--min-quality') || '0', 10);
+const agentFilter = get('--agent');
+const verdictRaw  = get('--verdict');
+const verdicts    = verdictRaw ? verdictRaw.split(',').map(v => v.trim().toUpperCase()) : [];
+const idRaw       = get('--id');
+const ids         = idRaw ? idRaw.split(',').map(i => i.trim()) : [];
+const avoidOnly   = has('--avoid');
+const format      = get('--format') || 'json';
+
+// --- Load index ---
+if (!fs.existsSync(INDEX_PATH)) {
+  console.error('No _index.json found at', INDEX_PATH);
+  process.exit(1);
+}
+const index = JSON.parse(fs.readFileSync(INDEX_PATH, 'utf8'));
+
+// --- Determine which brain files to load ---
+let brainFiles = index.brains;
+if (agentFilter) {
+  brainFiles = brainFiles.filter(b => b.agents.includes(agentFilter));
+}
+if (tags.length > 0) {
+  brainFiles = brainFiles.filter(b => tags.some(t => b.tags.includes(t)));
+}
+
+// --- Load nodes ---
+let nodes = [];
+for (const brain of brainFiles) {
+  const brainPath = path.join(BRAINS_DIR, '..', brain.path);
+  if (!fs.existsSync(brainPath)) {
+    process.stderr.write(`Warning: brain file not found: ${brainPath}\n`);
+    continue;
+  }
+  const data = JSON.parse(fs.readFileSync(brainPath, 'utf8'));
+  nodes.push(...(data.nodes || []).map(n => ({ ...n, _brain: brain.id })));
+}
+
+// --- Filter nodes ---
+if (ids.length > 0) {
+  nodes = nodes.filter(n => ids.includes(n.id));
+} else {
+  if (tags.length > 0) {
+    if (matchMode === 'all') {
+      nodes = nodes.filter(n => tags.every(t => (n.tags || []).includes(t)));
+    } else {
+      nodes = nodes.filter(n => tags.some(t => (n.tags || []).includes(t)));
+    }
+  }
+  if (minQ > 0) {
+    nodes = nodes.filter(n => (n.q || 0) >= minQ);
+  }
+  if (verdicts.length > 0) {
+    nodes = nodes.filter(n => verdicts.includes((n.v || '').toUpperCase()));
+  }
+  if (avoidOnly) {
+    nodes = nodes.filter(n => n.v === 'AVOID' || n.v === 'BROKEN');
+  }
+}
+
+// --- Output ---
+if (format === 'compact') {
+  const rows = nodes.map(n => `[${n.q}★ ${n.v}] ${n.id} — ${n.title}\n  ${n.s}`);
+  console.log(rows.join('\n\n') || '(no matches)');
+} else if (format === 'ids') {
+  console.log(nodes.map(n => n.id).join('\n'));
+} else {
+  console.log(JSON.stringify(nodes, null, 2));
+}
+
+// --- Stats footer ---
+process.stderr.write(`\n${nodes.length} node(s) matched across ${brainFiles.length} brain file(s)\n`);

package/template/.aioson/brains/site-forge/visual-patterns.brain.json

@@ -0,0 +1,205 @@
+{
+  "v": 1,
+  "agent": "site-forge",
+  "domain": "visual-patterns",
+  "desc": "CSS/animation/interaction patterns discovered while cloning real sites. Each node is a reusable lesson — quality-scored and anti-pattern aware. Use see[] to traverse related nodes.",
+  "updated": "2026-04-01",
+  "nodes": [
+    {
+      "id": "css-001",
+      "title": "CTA hover: mix-blend-mode:difference",
+      "tags": ["css", "hover", "cta", "button", "animation", "no-js", "blend-mode"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "White ::after pseudo-element with mix-blend-mode:difference creates color inversion on hover. Zero JS. Works on any background color automatically.",
+      "p": ".btn{position:relative;overflow:hidden} .btn::after{content:'';position:absolute;inset:0;background:white;mix-blend-mode:difference;transform:scaleX(0);transform-origin:0;transition:transform .3s cubic-bezier(.645,.045,.355,1)} .btn:hover::after{transform:scaleX(1)}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "background-color color transition on hover — color swap is weak compared to inversion effect",
+      "warn": "parent needs overflow:hidden; does not work if parent has background:transparent",
+      "see": ["css-002", "css-008"]
+    },
+    {
+      "id": "css-002",
+      "title": "Mobile menu: clip-path polygon() swipe",
+      "tags": ["css", "animation", "mobile", "menu", "drawer", "keyframes", "clip-path"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Mobile drawer wipes in from right using clip-path polygon animation — more cinematic than translateX slide. Requires @keyframes swipeIn/swipeOut.",
+      "p": "@keyframes swipeIn{0%{clip-path:polygon(101% 0%,100% 0%,101% 100%,116% 100%)}to{clip-path:polygon(0% 0%,101% 0%,101% 101%,0% 101%)}} .menu--open{animation:.6s cubic-bezier(.165,.84,.44,1) forwards swipeIn}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "transform:translateX(-100%) — generic slide, no visual drama",
+      "warn": "Menu must be position:fixed with full viewport size for clip-path to work correctly",
+      "see": ["css-001", "css-007"]
+    },
+    {
+      "id": "css-003",
+      "title": "Accordion: grid-template-rows 0fr→1fr",
+      "tags": ["css", "accordion", "animation", "no-js", "grid", "mobile"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "CSS grid transition on grid-template-rows animates height without any JS height calculation. Modern and smooth.",
+      "p": ".accordion-content{display:grid;grid-template-rows:0fr;transition:grid-template-rows .7s cubic-bezier(.165,.84,.44,1)} .accordion-content--open{grid-template-rows:1fr} .accordion-inner{overflow:hidden}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "max-height hack or JS getBoundingClientRect height calculation",
+      "warn": "Inner child needs overflow:hidden for the 0fr collapse to work",
+      "see": ["css-007"]
+    },
+    {
+      "id": "css-004",
+      "title": "Link underline: dual linear-gradient background-position",
+      "tags": ["css", "hover", "link", "underline", "animation", "keyframes"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Two linear-gradients animated via background-position create a sliding underline that enters from left on hover and exits to right on mouse-leave. Pure CSS.",
+      "p": ".link{background-image:linear-gradient(currentColor,currentColor),linear-gradient(currentColor,currentColor);background-size:100% 1px,0% 1px;background-repeat:no-repeat;background-position:-200% 100%,-100% 100%;animation:.5s cubic-bezier(.645,.045,.355,1) forwards ctaUnderlineSlideOut} .link:hover{animation:.5s cubic-bezier(.645,.045,.355,1) forwards ctaUnderlineSlideIn}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "text-decoration or border-bottom — no directional animation possible",
+      "warn": "Requires @keyframes ctaUnderlineSlideIn/Out; currentColor inherits from text color automatically",
+      "see": ["css-001", "css-007"]
+    },
+    {
+      "id": "css-005",
+      "title": "Scroll reveal: IntersectionObserver + CSS class toggle",
+      "tags": ["css", "scroll", "reveal", "animation", "no-js-lib", "intersection-observer"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "IntersectionObserver adds .in-view class at 15% threshold; CSS transition handles opacity+translateY. Zero third-party libraries needed.",
+      "p": "// JS: const obs=new IntersectionObserver(entries=>entries.forEach(e=>e.isIntersecting&&e.target.classList.add('in-view')),{threshold:.15}); document.querySelectorAll('.reveal').forEach(el=>obs.observe(el)); // CSS: .reveal{opacity:0;transform:translateY(16px);transition:opacity .8s cubic-bezier(.23,1,.32,1),transform .8s cubic-bezier(.23,1,.32,1)} .reveal.in-view{opacity:1;transform:none}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "AOS library, ScrollReveal, GSAP ScrollTrigger for basic fade-up reveals — overkill",
+      "warn": "threshold:0.15 is the sweet spot; too low fires too early, too high never fires on short sections",
+      "see": ["css-007", "css-008"]
+    },
+    {
+      "id": "css-006",
+      "title": "Staggered card reveals with nth-child delay",
+      "tags": ["css", "animation", "stagger", "cards", "scroll", "reveal"],
+      "q": 4,
+      "v": "GOOD",
+      "s": "Add transition-delay via nth-child selectors on .reveal-stagger children. 0.1s increments per card.",
+      "p": ".reveal-stagger>*:nth-child(1){transition-delay:0s} .reveal-stagger>*:nth-child(2){transition-delay:.1s} .reveal-stagger>*:nth-child(3){transition-delay:.2s} .reveal-stagger>*:nth-child(4){transition-delay:.3s} .reveal-stagger>*:nth-child(5){transition-delay:.4s}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": null,
+      "warn": "Keep delays short (0.1s increments); longer delays feel sluggish",
+      "see": ["css-005"]
+    },
+    {
+      "id": "css-007",
+      "title": "Squarespace signature easing curves",
+      "tags": ["css", "easing", "animation", "cubic-bezier", "tokens"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Three distinct easing curves used consistently: reveal=smooth deceleration, cta=power ease, menu=fast-in/slow-out. Gives a unified, professional motion feel.",
+      "p": "--ease-sqsp-reveal:cubic-bezier(.23,1,.32,1); --ease-sqsp-cta:cubic-bezier(.645,.045,.355,1); --ease-sqsp-menu:cubic-bezier(.165,.84,.44,1)",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "ease, ease-in-out, linear — generic curves flatten the personality of the site",
+      "warn": null,
+      "see": ["css-001", "css-002", "css-003", "css-004", "css-005"]
+    },
+    {
+      "id": "css-008",
+      "title": "prefers-reduced-motion global override",
+      "tags": ["css", "accessibility", "animation", "best-practice"],
+      "q": 5,
+      "v": "BEST_PRACTICE",
+      "s": "Global @media prefers-reduced-motion override that collapses all durations to 0.01ms. Always include in globals.css — never skip.",
+      "p": "@media(prefers-reduced-motion:reduce){*,*::before,*::after{animation-duration:.01ms!important;animation-iteration-count:1!important;transition-duration:.01ms!important}}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": null,
+      "warn": null,
+      "see": ["css-005"]
+    },
+    {
+      "id": "css-009",
+      "title": "Video background: autoPlay muted loop playsInline",
+      "tags": ["css", "video", "background", "hero", "mobile"],
+      "q": 4,
+      "v": "GOOD",
+      "s": "Hero video must have all 4 attributes to autoplay cross-browser. WebM first, MP4 fallback. Dark rgba overlay on top. Mobile swap via useEffect.",
+      "p": "<video autoplay muted loop playsinline preload=auto><source src=desktop.webm type=video/webm><source src=desktop.mp4 type=video/mp4></video><div style=position:absolute;inset:0;background:rgba(0,0,0,.52)></div>",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "Using background-image: url() for video — use the real <video> element",
+      "warn": "Card carousel videos use preload=none; only hero is preload=auto",
+      "see": ["css-005"]
+    },
+    {
+      "id": "js-001",
+      "title": "Extract @keyframes via document.styleSheets iteration",
+      "tags": ["js", "extraction", "keyframes", "css", "cloning", "analysis"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Iterate document.styleSheets and cssRules to extract @keyframes verbatim. This is the ONLY way to get actual @keyframes — getComputedStyle never exposes them.",
+      "p": "const kf=[]; for(const s of document.styleSheets){try{for(const r of s.cssRules){if(r instanceof CSSKeyframesRule){kf.push({name:r.name,css:r.cssText})}}}catch(e){}} console.log(JSON.stringify(kf))",
+      "src": "research — pt.squarespace.com analysis",
+      "date": "2026-04-01",
+      "not": "getComputedStyle(el).animation — returns resolved shorthand, never exposes @keyframes definitions",
+      "warn": "CORS will throw on cross-origin stylesheets — wrap in try/catch per sheet",
+      "see": ["js-002", "js-003"]
+    },
+    {
+      "id": "js-002",
+      "title": "MutationObserver scroll recording for DOM class changes",
+      "tags": ["js", "extraction", "cloning", "scroll", "animation", "mutationobserver"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Attach MutationObserver BEFORE starting scroll; record mutations at 8 checkpoints (0%, 12%, 25%, 37%, 50%, 62%, 75%, 87%, 100%). Each record: scrollY + changed elements + class diffs.",
+      "p": "const mutations=[]; const obs=new MutationObserver(ms=>ms.forEach(m=>{mutations.push({scrollY:window.scrollY,target:m.target.className,added:[...m.addedNodes].map(n=>n.className),attr:m.attributeName,old:m.oldValue})})); obs.observe(document.body,{subtree:true,attributes:true,attributeOldValue:true,childList:true}); // then scroll to each % checkpoint with 600ms settle",
+      "src": "research — pt.squarespace.com analysis",
+      "date": "2026-04-01",
+      "not": "Manual screenshot comparison — misses class toggles and DOM mutations",
+      "warn": "600ms settle time needed after each scroll to let animations complete",
+      "see": ["js-001", "js-003"]
+    },
+    {
+      "id": "js-003",
+      "title": "AVOID: getComputedStyle for animation detection",
+      "tags": ["js", "extraction", "animation", "anti-pattern"],
+      "q": 1,
+      "v": "AVOID",
+      "s": "getComputedStyle returns resolved property values — it NEVER exposes @keyframes definitions, animation timing functions are partially resolved, clip-path values may differ from source.",
+      "p": "// BAD: getComputedStyle(el).animationName → returns name only, not keyframes // BAD: getComputedStyle(el).clipPath → returns computed polygon(), but not the @keyframes that drives it",
+      "src": "research — pt.squarespace.com analysis",
+      "date": "2026-04-01",
+      "not": null,
+      "warn": "Use document.styleSheets iteration (js-001) to get real @keyframes definitions",
+      "see": ["js-001", "js-002"]
+    },
+    {
+      "id": "js-004",
+      "title": "JS library detection before choosing animation strategy",
+      "tags": ["js", "cloning", "gsap", "framer-motion", "animation", "detection"],
+      "q": 5,
+      "v": "EXCELLENT",
+      "s": "Always check window.gsap, window.ScrollTrigger, data-framer-component-type before choosing animation implementation. Wrong library choice creates double-animation or no-animation bugs.",
+      "p": "const libs={gsap:!!window.gsap,scrollTrigger:!!window.ScrollTrigger,framer:!!document.querySelector('[data-framer-component-type]'),lottie:!!window.lottie,aos:!!window.AOS}",
+      "src": "research — pt.squarespace.com analysis",
+      "date": "2026-04-01",
+      "not": "Defaulting to IntersectionObserver when GSAP is detected on the source site",
+      "warn": "Site not using GSAP does NOT mean IntersectionObserver is the right choice — read the actual @keyframes first",
+      "see": ["js-001", "js-002", "css-005"]
+    },
+    {
+      "id": "font-001",
+      "title": "Proprietary fonts: extract woff2 from saved site, serve locally",
+      "tags": ["font", "typography", "woff2", "cloning", "font-face"],
+      "q": 4,
+      "v": "GOOD",
+      "s": "When site uses proprietary font (CDN-blocked), extract woff2 files from the saved site's fonts/ directory. Serve via @font-face pointing to public/fonts/. Reference assets only — rewrite content.",
+      "p": "@font-face{font-family:'Clarkson';font-weight:300;font-display:swap;src:url('/fonts/clarkson-300.woff2') format('woff2')}",
+      "src": "pt.squarespace.com",
+      "date": "2026-04-01",
+      "not": "Trying to load proprietary fonts from CDN — 403 in production",
+      "warn": "Reference assets only — do not redistribute proprietary font files in public projects",
+      "see": []
+    }
+  ]
+}

package/template/.aioson/config.md

@@ -25,6 +25,21 @@ Ranges:
 - 2-3: SMALL
 - 4-6: MEDIUM
 
+## Context budget warning
+
+Configuração: `context_warning_threshold` (padrão: 65%)
+
+| Classificação | Threshold recomendado |
+|---------------|-----------------------|
+| MICRO | 75% (fases curtas, ok chegar mais alto) |
+| SMALL | 65% (padrão) |
+| MEDIUM | 55% (fases longas, aviso mais cedo) |
+
+Quando o agente perceber que está próximo do threshold:
+1. Escrever todos os artefatos em progresso (disk‑first)
+2. Emitir aviso: "⚠ Contexto em {X}% — recomendo `/clear` antes da próxima fase"
+3. Incluir no `last_checkpoint` o que estava sendo feito
+
 ## Context contract
 `project.context.md` must contain YAML frontmatter with:
 - `project_name`
@@ -89,34 +104,62 @@ In direct mode (LLM without CLI), agents call them manually following the rules
 When the `aioson` CLI is **not available**, agents must write a devlog file at the end of the session (or when the user asks to save progress). This is the only way to preserve session history for the dashboard when the CLI is missing.
 
 **Directory:** `aioson-logs/` (create if absent)
-**Filename:** `devlog-{YYYY-MM-DD}T{HH-MM}.md`
-**If a devlog from today already exists:** append to it instead of creating a new file.
+**Filename:** `devlog-{agent}-{unix-timestamp}.md`
 
 **Template:**
 ```markdown
 ---
-agent: "{agent-id}"
-session_start: "{ISO 8601}"
-session_end: "{ISO 8601}"
-status: completed # or partial
-summary: "One-line summary of what was accomplished"
+agent: dev
+feature: {feature-slug or "project"}
+session_key: direct-session:{unix-timestamp}:{agent}
+started_at: {ISO 8601}
+finished_at: {ISO 8601}
+status: completed
+verdict: null
+plan_step: null
 ---
 
+# Devlog: @{agent} — {feature} — {YYYY-MM-DD}
+
+## Summary
+{One sentence of what was accomplished.}
+
+## Artifacts
+- {path/to/file.ext}
+
 ## Decisions
 - {decision} → {why}
 
-## Changes
-- {file}: {what changed}
+## Learnings
+- [process] {any process learning from this session}
+- [domain] {any domain learning}
+
+## Blockers
+- {blocker or "None"}
+```
 
-## Next
-- {what should happen next session}
+**Minimum viable devlog (if session was cut short):**
+```markdown
+---
+agent: {agent}
+feature: {slug}
+status: partial
+started_at: {ISO 8601}
+finished_at: {ISO 8601}
+---
+# Devlog: @{agent} — {feature} — {date}
+## Summary
+{one sentence of what was done}
+## Learnings
+- [process] {any process learning}
 ```
 
 **Rules:**
-- Max 30 lines. This is a decision log, not a transcript.
+- Frontmatter fields `agent`, `started_at`, `finished_at` are required. All others are optional.
+- `[process]` / `[domain]` / `[quality]` / `[preference]` prefixes in Learnings enable automatic promotion to project memory.
 - Record **why** decisions were made — the "what" is in the git diff.
 - Skip the devlog for trivial sessions (quick questions, no code changes).
-- When the CLI becomes available, `aioson devlog:sync` will import file-based devlogs into SQLite for the dashboard.
+- When the CLI becomes available: `aioson devlog:process .` imports devlogs into SQLite (learnings, artifacts, decisions, verdict).
 
 ## On-demand context layers
 
@@ -228,6 +271,108 @@ When a workflow stage completes or an agent finishes via `runtime-log --finish`,
 
 Agents can read this file on activation to resume work without losing context between sessions.
 
+## Context compaction template
+
+When approaching context threshold, any agent can write a structured checkpoint to
+`.aioson/context/last-handoff.json` before compacting:
+
+```json
+{
+  "agent": "<agent-name>",
+  "session_summary": {
+    "messages_processed": "<N>",
+    "tools_used": ["<tool1>", "<tool2>"],
+    "recent_requests": ["<last 3 user requests>"],
+    "pending_work": ["<item1>", "<item2>"],
+    "key_files": ["<path1>", "<path2>"],
+    "timeline": ["<step1 done>", "<step2 done>"]
+  },
+  "compacted_at": "<ISO 8601>",
+  "resume_instruction": "Continue from this summary. Do not acknowledge it."
+}
+```
+
+After writing, prepend to the next response:
+`[Context compacted — resuming from checkpoint]`
+
+On resume: read `last-handoff.json` before loading any other context file.
+
+Agents with dedicated compaction protocols (e.g. `@orache`) define additional
+steps in their own files — this template is the shared baseline.
+
+## Hook contract (PreToolUse / PostToolUse)
+
+Hooks are shell scripts configured in `.claude/settings.json` under `hooks`.
+The harness passes context via stdin (JSON) and environment variables.
+
+### Exit codes
+| Code | Meaning |
+|------|---------|
+| 0 | Allow — continue tool execution |
+| 2 | Deny — block tool, return message to agent |
+| other non-zero | Warn — log warning, continue execution |
+
+### Environment variables
+| Variable | Description |
+|----------|-------------|
+| `HOOK_EVENT` | `PreToolUse` or `PostToolUse` |
+| `HOOK_TOOL_NAME` | Tool being executed (e.g. `Bash`, `Write`) |
+| `HOOK_TOOL_INPUT` | JSON params of the tool call |
+| `HOOK_TOOL_IS_ERROR` | `true`/`false` (PostToolUse only) |
+| `HOOK_TOOL_OUTPUT` | Tool output (PostToolUse only) |
+
+### Example: block rm -rf in Bash
+```bash
+#!/bin/bash
+INPUT=$(cat)
+if echo "$INPUT" | grep -q "rm -rf"; then
+  echo "Blocked: rm -rf not allowed in this project"
+  exit 2
+fi
+exit 0
+```
+
+## Agent file size guidelines
+
+The Claude Code harness enforces a hard limit of ~4,000 chars per auto-loaded
+instruction file (`CLAUDE.md` hierarchy). Files are truncated silently.
+Agent files in `.aioson/agents/` are read manually (not auto-loaded) so they
+are not subject to this truncation, but large files consume context budget.
+
+Recommended targets:
+
+| File type | Target | Notes |
+|-----------|--------|-------|
+| `CLAUDE.md` / `AGENTS.md` | ≤ 3,500 chars | Auto-loaded — hard truncation applies |
+| Focused agents (analyst, qa, tester) | ≤ 8,000 chars | Keep lean |
+| Generalist agents (dev, architect) | ≤ 15,000 chars | Move optional sections to `.aioson/docs/` |
+| Orchestrator agents (orchestrator, squad) | ≤ 12,000 chars | Move boilerplate to `.aioson/rules/` |
+
+When an agent file exceeds its target:
+1. Move repeated boilerplate to a shared `.aioson/rules/` file
+2. Split optional sections into `.aioson/docs/` files (loaded on demand)
+3. Use the "On-demand context layers" pattern from this config
+
+## Config tiers
+
+AIOSON supports three config tiers (precedence: local > project > user):
+
+| Tier | Location | Versioned | Purpose |
+|------|----------|-----------|---------|
+| User | `~/.aioson/config.md` | No | Personal defaults (model, locale, thresholds) |
+| Project | `.aioson/config.md` | Yes | Team standards — source of truth |
+| Local | `.aioson/config.local.md` | No | Machine overrides (local paths, env specifics) |
+
+When the same setting exists in multiple tiers, the lower tier wins (local > project > user).
+
+**Current support:**
+- Project tier: fully supported (this file)
+- Local tier: `config.local.md` is the convention — agents can read it if present
+- User tier (`~/.aioson/config.md`): **backlog** — requires CLI support; not yet read automatically
+
+Until the user tier is implemented in the CLI, use `CLAUDE.local.md` for personal
+preferences that should not affect other team members.
+
 ## Agent locale packs
 - Localized agent prompts are stored in `.aioson/locales/<locale>/agents/`.
 - Active runtime prompts are in `.aioson/agents/`.

package/template/.aioson/constitution.md

@@ -0,0 +1,33 @@
+---
+version: 1.0.0
+ratified: 2026-04-04
+last_amended: 2026-04-04
+---
+
+# AIOSON Constitution
+
+> Principles that govern all agents, all classifications, all sessions.
+> Every agent may cite these articles. No agent may override them.
+
+## Article I — Spec First
+Features begin as specifications, not code. Implementation without a spec artifact is exploration, not development.
+
+## Article II — Right-Sized Process
+MICRO, SMALL, and MEDIUM must not receive the same process depth. Applying MEDIUM ceremony to a MICRO project wastes more than it protects.
+
+## Article III — Observable Work
+Important agent actions leave visible artifacts or runtime signals. Work that exists only in conversation history is work that can be lost.
+
+## Article IV — Testable Behavior
+Acceptance criteria must be independently verifiable. "Works correctly" is not a criterion. "Returns 403 when user A accesses user B's resource" is.
+
+## Article V — Clean Handoffs
+Artifacts must be self-contained enough for the next agent to start without re-reading the full discovery chain. If the next agent needs to ask "where do I start?", the handoff failed.
+
+## Article VI — Simplicity Over Ceremony
+Do not add layers, files, or workflows unless they reduce downstream ambiguity. Three similar lines of code is better than a premature abstraction. One well-written spec is better than five thin artifacts.
+
+## Governance
+- Amendments require explicit user approval
+- Articles are numbered, not named — never renumber existing articles
+- New articles are appended, never inserted

package/template/.aioson/context/project-pulse.md

@@ -0,0 +1,34 @@
+---
+updated_at: null
+last_agent: null
+last_gate: null
+active_features: 0
+blocked: false
+blocked_reason: null
+---
+
+# Project Pulse
+
+> Global project state. Updated by every agent at session end.
+> Read this FIRST when starting any session to orient quickly.
+> Max 30 lines of content — trim older entries when growing beyond that.
+
+## Active work
+
+| Feature | Phase | Agent | Status | Last checkpoint |
+|---------|-------|-------|--------|-----------------|
+| — | — | — | — | — |
+
+## Recent activity (last 3 sessions)
+
+| Date | Agent | Action | Result |
+|------|-------|--------|--------|
+| — | — | — | — |
+
+## Blockers
+
+None.
+
+## Next recommended action
+
+No active work. Start with `@product` for a new feature or `@setup` for a new project.

package/template/.aioson/context/seeds/seed-example.md

@@ -0,0 +1,27 @@
+---
+slug: example
+title: Exemplo de seed — substitua com sua ideia
+created: {ISO-date}
+trigger: ao iniciar milestone de {feature relacionada}
+scope_estimate: MICRO
+status: dormant
+---
+
+## Ideia
+
+Descreva a ideia em 2-5 linhas. O que seria implementado e qual valor entregaria.
+
+## Codebase breadcrumbs
+
+Onde no código atual isso se encaixaria. O que existiria ou seria modificado.
+Ex: "src/billing/ ainda não existe — seria criada aqui"
+
+## Por que não agora
+
+Razão objetiva para não entrar no backlog agora.
+Ex: "Feature A precisa estar pronta antes", "não há demanda validada ainda"
+
+## Trigger condition
+
+Condição específica que deve fazer esta seed surfaçar.
+Ex: "quando iniciar milestone de pagamentos", "quando usuários pedirem 3+ vezes"

package/template/.aioson/context/user-profile.md

@@ -0,0 +1,42 @@
+---
+created: {ISO-date}
+last_updated: {ISO-date}
+questionnaire_completed: false
+---
+
+# Developer Profile
+
+## Communication style
+<!-- direto | equilibrado | explicativo -->
+preference: equilibrado
+
+## Decision style
+<!-- opções-com-tradeoffs | recomendacao-unica | depende-do-contexto -->
+preference: depende-do-contexto
+
+## Tech philosophy
+<!-- explícito | convencional | pragmatico -->
+preference: pragmatico
+
+## Autonomy preference
+<!-- aprovacao-por-step | aprovacao-em-gates | execucao-autonoma -->
+preference: aprovacao-em-gates
+
+## Feedback style
+<!-- critica-direta | colaborativo | neutro -->
+preference: neutro
+
+## Scope tolerance
+<!-- strict | sugestoes-ok | flexible -->
+preference: sugestoes-ok
+
+## Detail level
+<!-- so-resultado | contexto-quando-relevante | sempre-explicar -->
+preference: contexto-quando-relevante
+
+## Risk tolerance
+<!-- conservador | equilibrado | arrojado -->
+preference: equilibrado
+
+## Notes
+<!-- observações específicas do usuário sobre preferências -->