@jaimevalasek/aioson 1.7.0 → 1.8.0

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

@@ -7,104 +7,52 @@ 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.
+## Decision rule (apply in order)
 
-## The three formats and their consumers
+```
+Will a machine (CLI, API, webhook, dashboard) consume this? → JSON
+Will human/agent read top-to-bottom as narrative?          → Markdown
+Will an agent reference specific fields to make decisions? → YAML
+```
 
-### YAML — structured data consumed by agents
+If uncertain: prefer Markdown. Only use YAML when structured fields are the point.
 
-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.
+## The three formats
 
-LLMs read YAML more accurately than JSON for structured reference data because YAML allows comments, avoids excessive punctuation, and mirrors natural document structure.
+### YAML — structured data for agent field-by-field consumption
 
-**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
+LLMs read YAML more accurately than JSON for reference data (comments allowed, less punctuation).
 
-**Naming:** `{slug}.yaml` in the relevant squad output or context directory.
+Use for: ICP profiles, persona profiles, audience segments, offer sheets, pricing structures, brand guidelines (structured parts), competitive analysis (structured), briefing data for copy/design squads.
 
-**Example — ICP profile (`icp-primary.yaml`):**
+**Example (`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"
-
+desired_outcome: "Autonomia e velocidade"
 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 for humans and linear agent reading
 
-### Markdown — narrative content consumed by humans and agents linearly
+Use for: reports, analyses, article drafts, scripts, agent instructions, specs, PRDs, discovery docs, README files, any output read top-to-bottom.
 
-Use `.md` when the output is narrative — content that flows as text and benefits from headers, lists, and prose.
+Never use YAML or JSON for: articles, scripts, agent instructions, PRDs, analysis narratives.
 
-**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
+### JSON — structured data for machine consumption
 
-**Never use YAML or JSON for:** articles, scripts, agent instructions, PRDs, analysis narratives, README files.
+Use for: `squad.manifest.json`, `content.json`, API payloads, webhook responses, CLI config 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` — machine-consumed, must stay JSON for CLI compatibility.
 
-**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:
+## Squad executor output format
 
 | Output type | Format | Example |
 |---|---|---|
@@ -116,21 +64,11 @@ When a squad executor produces output, choose the format based on what happens n
 | 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.
-
----
+**Cross-squad consumption:** when Squad A produces data for Squad B, prefer YAML for structured reference — more reliable than parsing a Markdown table.
 
 ## What NOT to change
 
-- Files with `.json` extension consumed by the AIOSON CLI or dashboard
+- `.json` files consumed by 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.
+- Existing specs and context files — Markdown is correct
+- YAML frontmatter inside `.md` files

package/template/.aioson/rules/disk-first-artifacts.md

@@ -0,0 +1,44 @@
+---
+name: disk-first-artifacts
+description: Todo artefato gerado por um agente deve ser gravado em disco antes do fim da sessão — nunca apenas exibido no chat
+priority: 10
+version: 1.0.0
+---
+
+# Disk-First: Artifacts Always on Disk
+
+Every artifact produced by an AIOSON agent MUST be written to disk before session end. Showing in chat does not count as delivery — the next agent starts without context and the work is lost.
+
+## Mandatory artifacts by agent
+
+| Agent | Mandatory artifact | Path |
+|---|---|---|
+| `@product` | PRD | `.aioson/context/prd.md` or `prd-{slug}.md` |
+| `@product` | features.md | `.aioson/context/features.md` |
+| `@analyst` | Discovery | `.aioson/context/discovery.md` |
+| `@analyst` | Requirements | `.aioson/context/requirements-{slug}.md` |
+| `@architect` | Architecture | `.aioson/context/architecture.md` |
+| `@ux-ui` | UI Spec | `.aioson/context/ui-spec-{slug}.md` |
+| `@sheldon` | Manifest | `.aioson/plans/{slug}/manifest.md` |
+| `@pm` | Implementation Plan | `.aioson/context/implementation-plan-{slug}.md` |
+| `@dev` | Feature spec | `.aioson/context/spec-{slug}.md` |
+| `@qa` | QA report | `.aioson/context/qa-report-{slug}.md` |
+| `@squad` | Squad manifest | `.aioson/squads/{slug}/squad.manifest.json` |
+| `@squad` | Agent prompts | `.aioson/squads/{slug}/agents/{agent}.md` |
+
+## Correct delivery pattern
+
+```
+✅ Write artifact to disk → inform user of path.
+❌ Show in chat → ask "Can I save?" → Do NOT do this.
+```
+
+Exceptions: drafts shown mid-session for validation (before final save), artifacts explicitly cancelled by user.
+
+`project-pulse.md` must be updated at session end regardless of other artifacts.
+
+## On violation detected
+
+1. Write the artifact before closing — never defer to next session.
+2. If content was shown in chat, use it to write the file now.
+3. Update `project-pulse.md`.

package/template/.aioson/rules/output-brevity.md

@@ -0,0 +1,44 @@
+---
+name: output-brevity
+description: All agents must produce terse, direct output — no preambles, no trailing summaries, no narration of actions
+priority: 8
+version: 1.0.0
+---
+
+# Output Brevity
+
+All agents produce direct output. No padding.
+
+## What to eliminate
+
+- Preambles: "I will now...", "Let me...", "I'm going to..."
+- Trailing summaries: "In summary, I have...", "To recap what was done..."
+- Action narration: "Reading the file...", "Now I'll check..."
+- Filler acknowledgements: "Great!", "Sure!", "Of course!", "Absolutely!"
+- Restating the user's request before answering it
+
+## What to keep
+
+- Artifact content — complete and uncompressed
+- Technical explanations when genuinely non-obvious
+- Questions when clarification is required
+- Security warnings, irreversible action confirmations — revert to full prose for these
+
+## Pattern
+
+```
+❌  "I'll analyze the project structure and then provide my findings..."
+✅  [analysis output directly]
+
+❌  "In summary, I've created 3 files and updated the spec."
+✅  "Created: spec-auth.md, prd-auth.md, features.md"
+
+❌  "Great question! Let me explain how this works..."
+✅  [explanation directly]
+```
+
+## Exceptions — use full prose
+
+- Security warnings or destructive action confirmations
+- Multi-step sequences where brevity would cause ambiguity
+- User appears confused or has contradictory requirements

package/template/.aioson/rules/prd-section-ownership.md

@@ -0,0 +1,49 @@
+---
+name: prd-section-ownership
+description: Define qual agente é dono de cada seção do PRD — outros agentes não podem modificar seções que não são suas
+priority: 9
+version: 1.0.0
+agents: [product, pm, analyst, architect, ux-ui, sheldon]
+---
+
+# PRD Section Ownership
+
+`prd.md` and `prd-{slug}.md` are shared documents. Each section has one owner — others may only read or append sub-sections, never replace.
+
+## Ownership table
+
+| PRD Section | Owner | Others may |
+|---|---|---|
+| `## Objetivo` | `@product` | Read only |
+| `## Problema` | `@product` | Read only |
+| `## Usuários e Personas` | `@product` | Read only |
+| `## Funcionalidades` | `@product` | Read only |
+| `## Critérios de Aceite` | `@product` (structure) / `@pm` (enrichment) | `@analyst`, `@architect` add technical sub-items |
+| `## Fases de Entrega` | `@pm` | Read only |
+| `## Restrições Técnicas` | `@architect` | Read only |
+| `## Considerações de UX` | `@ux-ui` | Read only |
+| `## Riscos` | `@pm` | `@analyst`, `@architect` add new risks only |
+| `## Decisões Registradas` | `@sheldon` (project) / `@pm` (feature) | Read only |
+
+## Modification rule
+
+An agent may only modify sections it owns. Non-owners may only **add** a new sub-section at the end — never replace or rewrite existing content.
+
+## Safe addition pattern
+
+```markdown
+## Critérios de Aceite
+<!-- @product: owner of this section -->
+
+- CA-01: User can schedule an appointment
+- CA-02: System sends confirmation email
+
+### Technical criteria (added by @analyst)
+- CA-T01: Scheduling validates availability via DB query before confirming
+- CA-T02: Email queue uses BullMQ with 3x retry
+```
+
+## On violation detected
+
+1. Do not overwrite the section.
+2. Create a sub-section with explicit attribution (`<!-- added by @{agent} -->`), OR create a separate artifact (`requirements-{slug}.md`, `architecture.md`, etc.).

package/template/.aioson/rules/security-baseline.md

@@ -0,0 +1,139 @@
+---
+name: security-baseline
+description: Secure by Default baseline controls for technical agents
+priority: 10
+version: 1.0.0
+agents: [analyst, architect, dev, qa]
+---
+
+# Security Baseline — Secure by Default
+
+> Implements `Article VII — Zero Trust by Default` of the AIOSON constitution.
+> Loaded by `@analyst`, `@architect`, `@dev`, and `@qa`. Other agents must not
+> load this rule — product, copy, design and orchestration scopes are out of band.
+
+This rule defines the minimum security baseline every technical agent must
+respect. It does **not** promise absolute security. It declares concrete
+controls, expected evidence and how each project classification consumes them.
+Deviations are allowed only when recorded as an explicit decision in the
+feature `spec-{slug}.md` with N/A rationale.
+
+## Classification policy
+
+| Classification | Behavior |
+|---|---|
+| **MICRO** | **Advisory.** Controls are surfaced as recommendations. No automated blocking. `@qa` may still flag obviously dangerous patterns. |
+| **SMALL** | **Scan-oriented.** Static checks and tool-first scans run automatically. `@pentester` is **not** mandatory. Open Medium+ findings are reported but do not block by default. |
+| **MEDIUM** | **Audit-blocking.** Surface assessment runs against attack-surface map. **Open High or Critical findings block Gate D** until resolved or explicitly waived with rationale recorded in `spec-{slug}.md`. |
+
+`@pentester` (`app_target` mode) may be invoked by `@qa` for any feature with
+auth, money, ownership, file uploads, external URLs or suspicious audit
+findings — regardless of classification. It is never required by classification
+alone.
+
+## Severity scale
+
+| Severity | Examples |
+|---|---|
+| `critical` | Ownership bypass, financial race condition, committed production secret. |
+| `high` | Missing server-side validation, unsafe upload signature handling, missing rate limit on sensitive endpoint. |
+| `medium` | Unsanitized external URL, low-impact tracker, storage boundary abuse surface. |
+| `advisory` | MICRO recommendations or surfaces marked N/A with explicit rationale. |
+
+## Direct LLM mode (no CLI)
+
+When the `aioson` CLI is unavailable, agents must fall back to **checklist-only
+verification** of the controls below, record the limitation in the session
+devlog, and **must not** fabricate runtime telemetry events. Findings still
+land in `.aioson/context/security-findings-{slug}.json` (one of the few
+machine-readable exceptions allowed under `.aioson/context/`).
+
+## Controls
+
+### SEC-SBD-01 — Server-side input limits
+
+- Maps to: OWASP A03 / A04
+- Default severity: `high`
+- Owner agent: `@dev` (implements), `@analyst` (declares limits), `@qa` (verifies)
+- Applies to: analyst, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking when feature accepts user input
+- Required evidence: explicit field-length / type / range limits enforced server-side, plus negative tests asserting rejection on overflow or wrong type. N/A rationale required when feature has no user input.
+
+### SEC-SBD-02 — Upload file signature validation
+
+- Maps to: OWASP A03 / A05
+- Default severity: `high`
+- Owner agent: `@dev` (implements), `@qa` (verifies)
+- Applies to: analyst, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking when feature accepts uploads
+- Required evidence: magic-byte / file-signature validation independent of MIME header and extension; rejection test for spoofed extension. N/A when no upload surface exists.
+
+### SEC-SBD-03 — Ownership / IDOR authorization
+
+- Maps to: OWASP A01
+- Default severity: `critical`
+- Owner agent: `@dev` (implements), `@analyst` (maps surfaces), `@qa` (verifies)
+- Applies to: analyst, architect, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking on every endpoint that returns or mutates per-user data
+- Required evidence: ownership check at the data layer (not only route), and a negative test where user A attempts to access user B's resource and receives 403/404. N/A only when resource is intentionally public.
+
+### SEC-SBD-04 — Atomic critical state changes
+
+- Maps to: OWASP A04
+- Default severity: `critical`
+- Owner agent: `@architect` (designs), `@dev` (implements), `@qa` (verifies)
+- Applies to: architect, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking on money, inventory, quotas, ownership transfers, balance updates
+- Required evidence: transactional boundary (DB transaction, row lock, or equivalent) plus a concurrency test or documented invariant proving no double-spend / lost update. N/A when feature has no shared mutable state.
+
+### SEC-SBD-05 — Secrets outside code
+
+- Maps to: OWASP A02 / A05
+- Default severity: `critical` (committed) / `high` (config drift)
+- Owner agent: `@dev` (implements), `@qa` (verifies)
+- Applies to: analyst, architect, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking on any commit
+- Required evidence: secrets loaded from environment / vault / managed config; `.env` and equivalents in `.gitignore`; secret-scan pass on diff. Brownfield exception: pre-existing secret must be rotated and tracked, never silently kept.
+
+### SEC-SBD-06 — External URL sanitization
+
+- Maps to: OWASP A03 / A10
+- Default severity: `medium` (raises to `high` when URL is followed server-side)
+- Owner agent: `@dev` (implements), `@qa` (verifies)
+- Applies to: analyst, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking when feature accepts or follows external URLs
+- Required evidence: scheme allowlist, host validation, SSRF protection (private-range block) when followed server-side, escaping when rendered. N/A when no external URL is accepted.
+
+### SEC-SBD-07 — Storage default-deny / RLS boundary
+
+- Maps to: OWASP A01 / A05
+- Default severity: `critical`
+- Owner agent: `@architect` (designs), `@dev` (implements), `@qa` (verifies)
+- Applies to: architect, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking on every multi-tenant or per-user store
+- Required evidence: storage layer denies by default (RLS policies enabled, bucket private, queue ACL closed) plus a negative test from an unauthorized identity. N/A when storage is single-tenant and intentionally public.
+
+### SEC-SBD-08 — Auth enumeration / rate limiting
+
+- Maps to: OWASP A07
+- Default severity: `high`
+- Owner agent: `@dev` (implements), `@qa` (verifies)
+- Applies to: analyst, dev, qa
+- Classification policy: MICRO advisory; SMALL scan-oriented; MEDIUM audit-blocking on login, password reset, signup, OTP and any auth-adjacent endpoint
+- Required evidence: per-endpoint rate limit (per IP and per identifier), uniform error response for "user not found" vs "wrong password", lockout or backoff after N failures, and a negative test asserting enumeration is not possible. N/A when feature has no auth surface.
+
+## Out of scope (v1)
+
+The following are explicitly **not** part of this baseline and require a future
+PRD before adoption: deceptive endpoints (honeypots), jump-scare responses,
+adversarial CAPTCHAs, and any technique whose primary purpose is to deceive
+attackers. The baseline is preventive, not deceptive.
+
+## Maintenance
+
+- Control IDs are stable. Adding a control means appending `SEC-SBD-09`, never
+  renumbering or repurposing an existing ID.
+- Severity defaults can be raised per-feature in `spec-{slug}.md` with rationale; they cannot be silently lowered.
+- Changes to this rule require an explicit decision recorded in the relevant
+  feature spec and a `last_amended`-style note in the constitution if they
+  alter Article VII semantics.

package/template/.aioson/rules/spec-level-ownership.md

@@ -0,0 +1,61 @@
+---
+name: spec-level-ownership
+description: spec.md é de projeto, spec-{slug}.md é de feature — os dois níveis nunca se misturam
+priority: 9
+version: 1.0.0
+agents: [dev, qa, pm, sheldon]
+---
+
+# Spec Ownership: Project vs Feature Level
+
+Two distinct levels — never mix them.
+
+| File | Level | Owner | Content |
+|---|---|---|---|
+| `spec.md` | **Project** | `@dev` (full project) | Stack, global patterns, infrastructure — decisions affecting the whole project |
+| `spec-{slug}.md` | **Feature** | `@dev` (specific feature) | Decisions, entities, dependencies, ACs for ONE feature |
+
+## Absolute rules
+
+1. `spec.md` never receives feature-specific content → create `spec-{slug}.md` for that.
+2. `spec-{slug}.md` never receives project decisions → stack decisions go in `spec.md` or `architecture.md`.
+3. `spec-{slug}.md` is created by `@dev` at feature implementation start. One file per slug. Slug must match `prd-{slug}.md` and `implementation-plan-{slug}.md`.
+4. No `spec-{slug}.md` without a corresponding `prd-{slug}.md`.
+
+## Mandatory structure: spec-{slug}.md
+
+```markdown
+---
+feature: {slug}
+status: in_progress | done
+phase_gates:
+  requirements: approved | pending | skipped
+  design: approved | pending | skipped
+  plan: approved | pending | skipped
+---
+
+# Spec — {feature name}
+
+## Implemented entities
+## Technical decisions
+## Dependencies
+## QA approval
+(filled by @qa on feature close)
+```
+
+## Mandatory structure: spec.md (project level)
+
+```markdown
+# Spec — {project name}
+
+## Stack and infrastructure
+## Global code patterns
+## External integrations
+## Cross-feature architecture decisions
+```
+
+## On violation detected
+
+1. Do not write to the wrong file.
+2. Identify the correct level.
+3. Write to the correct file (create if needed following mandatory structure above).

package/template/.aioson/rules/squad-driver-pattern.md

@@ -0,0 +1,81 @@
+---
+name: squad-driver-pattern
+description: Territory boundaries and integration pattern for AIOSON squads — separates squad definitions (owned by @squad) from application driver code (owned by @dev)
+priority: 9
+version: 1.0.0
+agents: [dev, sheldon, pm, qa, architect]
+---
+
+# Squad Driver Pattern
+
+Two distinct layers — never mixed:
+
+```
+Layer 1 — Definition (owned by @squad)
+  .aioson/squads/{squad-slug}/
+    agents/greeting-agent.md     ← prompt and personality
+    agents/orquestrador.md       ← orchestration logic
+    squad.manifest.json          ← configuration
+    workflows/main.md            ← execution pipeline
+
+Layer 2 — Driver (owned by @dev)
+  src/services/squadRunner.js    ← loads and executes definitions
+  src/services/greetingService.js ← driver consuming greeting-agent.md
+```
+
+## Territory rules — absolute for all agents
+
+| Agent | Can create/modify | Must never touch |
+|---|---|---|
+| `@squad` | `.aioson/squads/` | Application code (`src/`, `app/`, etc.) |
+| `@dev` | Application code | `.aioson/squads/` |
+| `@pm` | Implementation plan | Either layer |
+| `@architect` | `architecture.md` | Squad files or agent code |
+
+## Correct integration pattern
+
+The application service is a **driver** — loads the squad definition and sends it to the LLM. Never embeds prompts in code.
+
+```javascript
+// CORRECT — driver consuming @squad definition
+class GreetingService {
+  async respond(message) {
+    const agentDef = fs.readFileSync(
+      '.aioson/squads/squad-greeting/agents/greeting-agent.md', 'utf-8'
+    )
+    return await llm.call({ system: agentDef, user: message })
+  }
+}
+
+// WRONG — prompt embedded in code (@dev must not do this)
+class GreetingService {
+  async respond(message) {
+    const prompt = "Voce e um atendente de farmacia..." // ← @squad territory
+    return await llm.call({ system: prompt, user: message })
+  }
+}
+```
+
+## Per-agent responsibilities
+
+**`@product` / `@sheldon`:** describe squad behavior and objective in PRDs — never literal prompts. Prompts are `@squad` territory.
+
+**`@analyst` / `@architect`:** include the driver layer as explicit component in `architecture.md`:
+```
+SquadRunner — loads definitions from .aioson/squads/ and executes via LLM API
+  dependencies: fs (read .md), llm-client (model call)
+  no domain logic — only orchestrates loading and execution
+```
+
+**`@pm`:** separate squad phases from code phases in implementation plans:
+- Squad phases → `executor: @squad`
+- Driver phases → `executor: @dev` with task "create SquadRunner that loads `.aioson/squads/{slug}/`"
+
+**`@dev`:** never write inline prompts. If a task requires creating/modifying files in `.aioson/squads/` — stop and redirect to `@squad`.
+
+**`@squad`:** read `implementation-plan` and `prd` before asking anything — context is already in artifacts.
+
+**`@qa`:** verify:
+- [ ] Squad services are drivers (load `.md`, never embed prompts)
+- [ ] No agent prompt is hardcoded in application code
+- [ ] `.aioson/squads/` was not modified by `@dev`

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

@@ -31,6 +31,30 @@
       "enum": ["content", "software", "research", "mixed"]
     },
     "domain": { "type": "string" },
+    "locale_scope": {
+      "type": "string",
+      "description": "Universal or locale-specific scope for generated agent files",
+      "pattern": "^(universal|[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*)$"
+    },
+    "locale_rationale": { "type": "string" },
+    "domainClassification": {
+      "type": "object",
+      "properties": {
+        "tier": {
+          "type": "string",
+          "enum": ["tier-1-regulated", "tier-2-specialized", "tier-3-common"]
+        },
+        "rationale": { "type": "string" },
+        "regulations": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "investigationPolicy": {
+          "type": "string",
+          "enum": ["required", "recommended", "optional"]
+        }
+      }
+    },
     "executors": {
       "type": "array",
       "items": {

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

@@ -38,6 +38,34 @@
       "enum": ["private", "public"],
       "default": "private"
     },
+    "locale_scope": {
+      "type": "string",
+      "description": "Universal or locale-specific scope for agent prompt files",
+      "pattern": "^(universal|[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*)$"
+    },
+    "locale_rationale": {
+      "type": "string",
+      "description": "Why the squad is locale-specific when locale_scope is not universal"
+    },
+    "domainClassification": {
+      "type": "object",
+      "description": "Classification of the squad domain for research and safety routing",
+      "properties": {
+        "tier": {
+          "type": "string",
+          "enum": ["tier-1-regulated", "tier-2-specialized", "tier-3-common"]
+        },
+        "rationale": { "type": "string" },
+        "regulations": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "investigationPolicy": {
+          "type": "string",
+          "enum": ["required", "recommended", "optional"]
+        }
+      }
+    },
     "ephemeral": {
       "type": "boolean",
       "default": false,
@@ -48,6 +76,22 @@
       "description": "Time-to-live for ephemeral squads (e.g. '24h', '7d'). After TTL, squad files are eligible for cleanup."
     },
     "aiosLiteCompatibility": { "type": "string" },
+    "sourceDocs": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Project artifacts consumed during squad design"
+    },
+    "investigation": {
+      "type": "object",
+      "description": "Reference to a persisted @orache investigation report",
+      "properties": {
+        "slug": { "type": "string" },
+        "path": { "type": "string" },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "dimensionsCovered": { "type": "integer", "minimum": 0, "maximum": 7 },
+        "date": { "type": "string", "format": "date" }
+      }
+    },
     "storagePolicy": {
       "type": "object",
       "properties": {

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