@jaimevalasek/aioson 1.6.0 → 1.7.2

package/template/.aioson/rules/data-format-convention.md

@@ -0,0 +1,136 @@
+---
+name: data-format-convention
+description: Which file format to use when producing or consuming structured data — YAML for agent-readable reference data, Markdown for narrative, JSON for machine-consumed data
+priority: 8
+version: 1.0.0
+---
+
+# Data Format Convention
+
+Use the right format for the right consumer. The same data structure reads very differently depending on who (or what) will consume it next.
+
+## The three formats and their consumers
+
+### YAML — structured data consumed by agents
+
+Use `.yaml` when the output is structured reference data that **another agent or squad executor will read field-by-field** to make decisions or produce content.
+
+LLMs read YAML more accurately than JSON for structured reference data because YAML allows comments, avoids excessive punctuation, and mirrors natural document structure.
+
+**Use YAML for:**
+- ICP definitions, persona profiles, audience segments
+- Offer sheets, product definitions, pricing structures
+- Brand guidelines (structured parts: tone, values, vocabulary, positioning)
+- Competitive analysis snapshots (structured fields)
+- Briefing data that a copy squad or design squad will consume
+- Entity catalogs referenced across multiple sessions
+
+**Naming:** `{slug}.yaml` in the relevant squad output or context directory.
+
+**Example — ICP profile (`icp-primary.yaml`):**
+```yaml
+# ICP — Primary Audience
+# Created by: @research-squad | Updated: 2026-04-02
+
+profile:
+  name: "Empreendedor Refém"
+  description: "Dono de negócio que depende de agências ou devs externos"
+
+pain_points:
+  - Perda de controle sobre o produto
+  - Atrasos e custos imprevisíveis
+  - Não consegue validar qualidade do que recebe
+
+desired_outcome: "Autonomia e velocidade — entregar sem depender de terceiros"
+
+buying_trigger: "Prazo vencendo ou fatura chegando de dev que atrasou"
+
+messaging:
+  primary: "Retome o controle do seu produto"
+  objection_1: "Não preciso saber programar?"
+  objection_1_answer: "Não. Você vai orquestrar, não digitar código."
+
+channels: [instagram, linkedin, youtube]
+```
+
+---
+
+### Markdown — narrative content consumed by humans and agents linearly
+
+Use `.md` when the output is narrative — content that flows as text and benefits from headers, lists, and prose.
+
+**Use Markdown for:**
+- Reports, analyses, article drafts
+- Scripts, hooks, copy blocks
+- Agent instructions and rules (this file is an example)
+- Specs, PRDs, discovery documents
+- Any output meant to be read from top to bottom
+
+**Never use YAML or JSON for:** articles, scripts, agent instructions, PRDs, analysis narratives, README files.
+
+---
+
+### JSON — structured data consumed by machines
+
+Use `.json` when the output is consumed by code — CLIs, APIs, webhooks, dashboards, or configuration parsers.
+
+**Use JSON for:**
+- `squad.manifest.json` — consumed by the AIOSON CLI and dashboard
+- `content.json` — consumed by the webhook server and dashboard
+- API payloads and webhook responses
+- CLI configuration files
+- Any file that `JSON.parse()` will read programmatically
+
+**Never change to YAML:** `squad.manifest.json`, `content.json`, `squad.json`, `aioson-models.json`. These are machine-consumed and must stay JSON for CLI compatibility.
+
+---
+
+## Decision rule (apply in this order)
+
+```
+Will a machine (CLI, API, webhook, dashboard) consume this file?
+  YES → JSON
+
+Will a human or agent read this top-to-bottom as narrative?
+  YES → Markdown
+
+Will an agent reference specific fields to make decisions or produce content?
+  YES → YAML
+```
+
+If uncertain: prefer Markdown. Only use YAML when the structured fields are the point — not the prose.
+
+---
+
+## Squad executor guidance
+
+When a squad executor produces output, choose the format based on what happens next:
+
+| Output type | Format | Example |
+|---|---|---|
+| Report, article, script | `.md` | `output/content-squad/ep-001/script.md` |
+| ICP, persona, audience profile | `.yaml` | `output/research-squad/icp-primary.yaml` |
+| Brand data, offer sheet | `.yaml` | `output/brand-squad/offer-advanced.yaml` |
+| Competitive analysis (structured) | `.yaml` | `output/research-squad/competitors.yaml` |
+| Competitive analysis (narrative) | `.md` | `output/research-squad/market-report.md` |
+| Webhook payload, API response | `.json` | handled by `content.json` convention |
+| Squad manifest, config | `.json` | `squad.manifest.json` (do not change) |
+
+**Cross-squad consumption:** when Squad A produces data that Squad B will consume, prefer YAML for structured reference data. The receiving squad's executor can reference `output/squad-a/{file}.yaml` directly and access fields with precision — more reliable than parsing a Markdown table.
+
+---
+
+## What NOT to change
+
+- Files with `.json` extension consumed by the AIOSON CLI or dashboard
+- Agent instruction files (`agents/*.md`) — narrative, not data
+- Existing specs and context files (`spec-*.md`, `discovery.md`, `architecture.md`) — mixed narrative + structure, Markdown is correct
+- YAML frontmatter inside `.md` files — this is already the right pattern for metadata
+
+---
+
+## Why this matters
+
+The same structured content stored as JSON or Markdown loses precision when an agent reads it. A JSON blob requires the agent to mentally parse brackets and quotes while tracking field relationships. A Markdown table requires the agent to infer column semantics from headers. A YAML document makes field names, nesting, and relationships immediately legible — the LLM spends its attention on the content, not the syntax.
+
+For squads that pass structured data between executors across sessions, this compounds: each session starts fresh, and a YAML profile loads faster and more accurately into working context than an equivalent JSON or Markdown representation.

package/template/.aioson/rules/example-monetary-values.md

@@ -0,0 +1,30 @@
+---
+name: monetary-values
+description: All monetary values must be stored as integer cents, never as floats
+agents: [dev, architect, qa]
+priority: 5
+version: 1.0.0
+---
+
+# Monetary Values Convention
+
+All monetary values in this project MUST be stored and calculated as integer cents.
+
+## Rule
+
+- NEVER use float or decimal types for money fields
+- Store as integer: `1000` = R$ 10,00 or USD $10.00
+- Display formatting is a UI concern only — format at the presentation layer, never in persistence or business logic
+- This applies to: database columns, API payloads, internal calculations, test fixtures
+
+## Rationale
+
+Float arithmetic produces rounding errors in financial calculations.
+Example: `0.1 + 0.2 === 0.30000000000000004` in most languages.
+Using integer cents eliminates this class of bug entirely.
+
+## Applies to
+
+- Database migrations: column type must be integer or bigint, not decimal/float
+- API contracts: monetary fields must be documented as integer cents
+- @qa: test fixtures must use integer cents; any float in a money field is a bug

package/template/.aioson/schemas/squad-manifest.schema.json

@@ -98,9 +98,9 @@
           "title": { "type": "string" },
           "type": {
             "type": "string",
-            "enum": ["worker", "agent", "clone", "assistant", "human-gate"],
+            "enum": ["worker", "agent", "clone", "assistant", "human-gate", "research", "reviewer", "skill"],
             "default": "agent",
-            "description": "Executor type: worker (deterministic script, no LLM), agent (LLM with defined role), clone (cognitive replica of real person), assistant (domain specialist with behavioral profile), human-gate (human approval checkpoint)"
+            "description": "Executor type: worker (deterministic script, no LLM), agent (LLM with defined role), clone (cognitive replica of real person), assistant (domain specialist with behavioral profile), human-gate (human approval checkpoint), research (web research with cache, no LLM), reviewer (cross-AI review synthesis), skill (external Agent Skills Standard skill)"
           },
           "role": { "type": "string" },
           "file": { "type": "string" },
@@ -121,6 +121,14 @@
             "type": "string",
             "description": "Script path for worker executors"
           },
+          "skill": {
+            "type": "string",
+            "description": "Agent Skills Standard skill identifier (for type: 'skill'). E.g. '@anthropic/code-review'"
+          },
+          "source": {
+            "type": "string",
+            "description": "Skill source path or package. E.g. 'npm:@org/skill', './skills/my-skill/'"
+          },
           "domain": {
             "type": "string",
             "description": "Specialized domain for assistant executors"
@@ -198,11 +206,85 @@
                 "order": { "type": "integer", "minimum": 1 },
                 "file": { "type": "string", "description": "Path to the task .md file" },
                 "input": { "type": "string", "description": "What this task receives" },
-                "output": { "type": "string", "description": "What this task produces" }
+                "output": { "type": "string", "description": "What this task produces" },
+                "review_loop": {
+                  "type": "boolean",
+                  "default": false,
+                  "description": "Enable evaluator-optimizer loop: dev implements, qa evaluates, repeat up to max_review_iterations"
+                },
+                "review_criteria": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Criteria the evaluator uses to PASS/FAIL the output (used with review_loop: true)"
+                },
+                "max_review_iterations": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 5,
+                  "default": 3,
+                  "description": "Maximum dev→qa iterations before escalating to human (used with review_loop: true)"
+                },
+                "voting": {
+                  "type": "object",
+                  "description": "Sampling-and-Voting: run N parallel instances and reach consensus. Best for critical decisions.",
+                  "properties": {
+                    "instances": {
+                      "type": "integer",
+                      "minimum": 2,
+                      "maximum": 10,
+                      "default": 3,
+                      "description": "Number of parallel instances to spawn"
+                    },
+                    "threshold": {
+                      "type": "number",
+                      "minimum": 0.5,
+                      "maximum": 1,
+                      "default": 0.66,
+                      "description": "Minimum consensus fraction to accept result (0.66 = 66%)"
+                    },
+                    "on_no_consensus": {
+                      "type": "string",
+                      "enum": ["escalate", "use_majority", "fail"],
+                      "default": "escalate",
+                      "description": "What to do when consensus < threshold"
+                    }
+                  }
+                }
               }
             },
             "description": "Granular tasks within this executor, executed in order"
           },
+          "research": {
+            "type": "object",
+            "description": "Configuration for research executor type (type: 'research')",
+            "properties": {
+              "topic": { "type": "string", "description": "Cache key / topic slug (e.g. 'youtube-shorts-2026')" },
+              "urls": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "URLs to scrape for this research topic"
+              },
+              "cache_hours": { "type": "integer", "default": 168, "description": "Cache TTL in hours (default 168 = 7 days)" },
+              "cache_dir": { "type": "string", "default": "researchs/", "description": "Base directory for research cache" },
+              "max_sources": { "type": "integer", "default": 5, "description": "Maximum number of URLs to scrape" }
+            }
+          },
+          "cross_ai": {
+            "type": "boolean",
+            "description": "If true (for reviewer type), send to multiple AI CLIs and synthesize responses"
+          },
+          "review": {
+            "type": "object",
+            "description": "Configuration for reviewer executor type",
+            "properties": {
+              "detect_clis": {
+                "type": "array",
+                "items": { "type": "string", "enum": ["claude", "gemini", "codex"] }
+              },
+              "exclude_current": { "type": "boolean", "default": true },
+              "synthesize_to": { "type": "string", "description": "Output path for REVIEWS.md" }
+            }
+          },
           "formats": {
             "type": "array",
             "items": { "type": "string" },
@@ -705,5 +787,44 @@
       }
     }
   },
+  "depends_on": {
+    "type": "array",
+    "description": "Inter-squad dependencies: this squad will consume published events from these squads before starting a run",
+    "items": {
+      "type": "object",
+      "required": ["squad", "event"],
+      "properties": {
+        "squad": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*[a-z0-9]$",
+          "description": "Slug of the squad whose events this squad depends on"
+        },
+        "event": {
+          "type": "string",
+          "description": "Event pattern to subscribe to (e.g. 'episode.created', 'review.*', '*')"
+        },
+        "input_mapping": {
+          "type": "object",
+          "description": "Maps event payload fields to task context fields",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    }
+  },
+  "hooks": {
+    "type": "object",
+    "description": "Hook scripts that gate squad execution (exit 0=allow, exit 2=deny)",
+    "properties": {
+      "pre_run": {
+        "type": "string",
+        "description": "Shell command to run before squad:autorun starts. Exit code 2 aborts the run."
+      }
+    }
+  },
+  "subscriptions": {
+    "type": "array",
+    "description": "Event patterns this squad subscribes to (consumed at the start of each autorun). Short form of depends_on[*].event.",
+    "items": { "type": "string" }
+  },
   "additionalProperties": true
 }

package/template/.aioson/skills/design/cognitive-core-ui/references/motion.md

@@ -4,6 +4,8 @@ Read after `design-tokens.md`. Add to context only when motion materially improv
 
 Motion is **purposeful and restrained**. Dashboards use minimal motion. Landing pages use more dramatic entrances and scroll effects.
 
+> **For landing pages / sales pages / event pages:** also load `skills/static/landing-page-forge.md` — it provides GSAP and AnimeJS integration patterns for horizontal scroll, magnetic mouse effects, hero sequences, and the full performance + tracking checklist.
+
 ---
 
 ## Principles

package/template/.aioson/skills/design/pt.squarespace.com/.skill-meta.json

@@ -0,0 +1,31 @@
+{
+  "id": "pt.squarespace.com",
+  "name": "Squarespace Design System",
+  "source": "https://pt.squarespace.com/",
+  "extractedAt": "2026-03-31",
+  "theme": "light-dark",
+  "baseUnit": "4px",
+  "referenceSkill": null,
+  "type": "extracted",
+  "designPillars": [
+    "Sharp minimalism — zero border-radius",
+    "Bold typographic hierarchy — Clarkson font family",
+    "High contrast — black/white with teal accents"
+  ],
+  "colors": {
+    "primary": "#000000",
+    "accent": "#1E4C41",
+    "background": "#FFFFFF",
+    "surface": "#F5F5F4"
+  },
+  "fonts": {
+    "display": "Clarkson, Helvetica, sans-serif",
+    "body": "Helvetica Neue, Helvetica, Arial, sans-serif",
+    "serif": "Clarkson Serif, Georgia, serif"
+  },
+  "breakpoints": {
+    "desktop": 1440,
+    "tablet": 768,
+    "mobile": 390
+  }
+}

package/template/.aioson/skills/design/pt.squarespace.com/SKILL.md

@@ -0,0 +1,66 @@
+# Squarespace (pt.squarespace.com) Design System
+
+> Extracted from https://pt.squarespace.com/ on 2026-03-31.
+> Deep analysis completed 2026-04-01 via static file extraction (CSS/JS/fonts/media from saved site).
+> Visual clone skill — do not use in unrelated projects without adapting the tokens.
+
+## Identity
+
+**Theme:** light (with dark hero/footer sections)
+**Personality:** Clean, professional SaaS aesthetic with strong typographic hierarchy, minimal decoration, and bold black-white contrast punctuated by occasional teal accents.
+
+## Design pillars
+
+1. **Sharp minimalism** — Zero border-radius throughout; geometric precision dominates
+2. **Bold typographic hierarchy** — Large headlines (Clarkson 300), clear size differentiation
+3. **High contrast** — Black and white with teal accent; no gradients, no shadows
+
+## Animation philosophy
+
+**CSS-first, zero third-party libraries.** No GSAP, no Framer Motion, no AOS, no Lottie.
+All animations are pure `@keyframes` + class toggling + `IntersectionObserver`.
+
+Signature effects:
+- CTA hover: `mix-blend-mode: difference` pseudo-element (not a color transition)
+- Mobile menu: `clip-path: polygon()` swipe animation (not `translateX`)
+- Link underline: `background-position` animated on two linear-gradients
+- Scroll reveals: `IntersectionObserver` adds `.in-view`, CSS handles transition
+
+## Local assets available
+
+These files were extracted from the saved site and are ready to use directly:
+
+**Fonts** (`public/fonts/`):
+- `clarkson-300.woff2` — Clarkson Light (hero headlines)
+- `clarkson-400.woff2` — Clarkson Regular (body, nav)
+- `clarkson-500.woff2` — Clarkson Medium (CTAs, labels)
+- `clarkson-serif-300.woff2` — Clarkson Serif Light
+- `clarkson-serif-400.woff2` — Clarkson Serif Regular
+
+**Videos** (`public/videos/pt.squarespace.com/`):
+- `video-desktop.webm` + `.mp4` — Hero background video (1280×720)
+- `video-mobile.webm` + `.mp4` — Hero background video, portrait-optimized
+- `templates.webm` + `.mp4` — Template showcase animation
+- `blueprint-ai.webm` + `.mp4` — AI blueprint feature demo
+- `design-intelligence-3.mp4` — Design intelligence card video
+- `conversion-centered.mp4` — Final CTA section video
+
+> Reference files — replace with your own assets before publishing.
+
+## When to use
+
+Activate when building projects that need a professional, clean SaaS website aesthetic inspired by Squarespace's homepage — minimal, typography-forward, with dark hero sections and teal accents.
+
+## Activation
+
+Load `references/design-tokens.md` before writing any component.
+Load `references/motion.md` before implementing any animation or interaction.
+Load `references/components.md` to get the real class naming conventions and hover mechanics.
+
+## Skill files
+
+- `references/design-tokens.md` — CSS custom properties (colors, typography, spacing, real easing curves)
+- `references/components.md` — Component patterns, real class names, CTA hover mechanics
+- `references/patterns.md` — Page layout patterns with real section IDs
+- `references/motion.md` — All 12 extracted @keyframes, exact timings, animation usage map
+- `references/websites.md` — Complete page topology including all 11 sections