@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/docs/squad/content-output.md

@@ -0,0 +1,91 @@
+---
+description: "Squad content and output rules — content blueprints, output strategy, HTML deliverables, and dashboard-facing artifact structure."
+---
+
+# Squad Content And Output
+
+Use this module when the squad produces recurring content packages, structured outputs, or session HTML.
+
+## Content blueprints
+
+For content-heavy squads, define `contentBlueprints` in `squad.manifest.json`.
+They should describe:
+
+- `contentType`
+- `layoutType`
+- blueprint `sections`
+- the dynamic contract of recurring deliverables
+
+Do not hardcode domain-specific fields as framework-wide rules. The shell is fixed; the blueprint is domain-derived.
+
+## Preferred structured output layout
+
+When a deliverable is more than a one-off text file:
+
+- create a `content_key`
+- save under `output/{squad-slug}/{content-key}/`
+- prefer:
+  - `content.json`
+  - `index.html`
+
+Use this especially when the squad produces multiple sibling outputs in one package.
+
+## Output strategy
+
+If the domain suggests recurring data pipelines, webhooks, or storage-backed delivery:
+
+- load `.aioson/tasks/squad-output-config.md`
+- configure output explicitly
+
+For file-first squads such as reports, landing pages, or one-off artifacts:
+
+- default to `mode: "files"`
+
+## Installed skill reuse
+
+Before inventing output structures, inspect installed squad skills under:
+
+- `.aioson/squads/{squad-slug}/skills/`
+
+Reuse those skills if they already imply known output patterns or blueprints.
+
+## Session HTML deliverable
+
+After every productive response round, write:
+
+- `output/{squad-slug}/{session-id}.html`
+- update `output/{squad-slug}/latest.html`
+
+The HTML should capture the actual session work:
+
+- sober technical hero
+- one section per round
+- one rich block per specialist
+- one synthesis block per round
+- copy button per block
+- copy-all button in the header
+
+Stack:
+
+- Tailwind CSS CDN
+- Alpine.js CDN
+- no build step
+- no Google Fonts
+- no external images
+
+## Design direction for session HTML
+
+- dark, technical, premium
+- not neon dashboard
+- restrained accents
+- comfortable reading width
+- preserve rich content instead of flattening it into summaries
+
+## Output integrity
+
+Never:
+
+- overwrite another squad's output
+- write HTML under `.aioson/`
+- skip `latest.html`
+- reduce structured content to a single blob if the domain naturally wants sections

package/template/.aioson/docs/squad/creation-flow.md

@@ -0,0 +1,149 @@
+---
+description: "Squad creation flow — entry message, project artifact detection, intake questions, autonomy, discovery mini-package, and executor classification."
+---
+
+# Squad Creation Flow
+
+Use this module for new squad creation, blueprint derivation, and major extension work.
+
+## Entry message
+
+Do not begin with a Lite/Genome menu.
+Start direct squad creation with:
+
+> "I will assemble your specialized squad.
+>
+> Reply in a single block if you want:
+> 1. domain or theme
+> 2. main goal
+> 3. expected output type
+> 4. important constraints
+> 5. roles you want in the squad, or I can choose"
+
+If the user later wants genomes, route to `@genome`.
+
+## Project artifact detection
+
+Before asking follow-up questions, scan `.aioson/context/` for reusable upstream artifacts:
+
+- `implementation-plan-*.md`
+- `requirements-*.md`
+- `architecture.md`
+- `prd.md` or `prd-*.md`
+
+If one or more files are clearly relevant to the squad request:
+
+1. Read the implementation plan first when present.
+2. Extract domain, goal, expected outputs, constraints, expected behaviors, and done signals.
+3. Record the consumed file paths in blueprint `sourceDocs`.
+4. Do not ask again for information that is already explicit in those artifacts.
+
+If multiple artifacts exist but relevance is ambiguous, ask one short disambiguation question instead of ignoring them.
+
+## Intake
+
+Ask only for what is still missing after reading the project artifacts. Typical fields are:
+
+1. domain or theme
+2. main goal
+3. output type
+4. important constraints
+5. optional role hints
+
+The user may respond with text, large pasted context, images, or attachments.
+If attachments exist, use them before defining executors.
+
+## Autonomy rule
+
+- default to high autonomy
+- infer reasonable defaults before asking follow-up questions
+- ask additional questions only when the answer would materially change the squad
+- if the user says "keep going" or "just do it", reduce questions further and make assumptions explicit
+
+## Parallel squad rule
+
+- if the user asks for a new squad, create a new squad
+- do not silently reuse or merge an existing squad just because the domain looks similar
+- maintenance or refactor of an existing squad only happens when the user says so explicitly
+
+If the slug collides and the user clearly wants a new squad:
+
+- do not silently reuse the old one
+- propose a derived slug or ask which slug they prefer
+
+## Discovery mini-package
+
+Before generating files, establish:
+
+- current problem
+- practical goal
+- squad MVP boundary
+- out of scope
+- which docs and skills really need to be loaded now
+- which risks or ambiguities could still change the squad composition
+
+If readiness is low:
+
+- ask 1 to 3 short questions, or
+- proceed with explicit assumptions when the user requested autonomy
+
+## Domain breadth probe (mandatory for customer-facing squads)
+
+Before designing executors, if any executor will face customers (retail, hospitality, service, support, sales, food service, healthcare reception, gym, hotel, etc.), answer this question explicitly:
+
+> "What does a real practitioner in this role actually handle, beyond the obvious primary responsibility?"
+
+List **5–10 adjacent products / services / topics** that a real person in that role would handle daily. Examples: a real pharmacy attendant handles candy, snacks, cosmetics, baby products; a real restaurant server handles bathroom directions, dietary substitutions, taxi calls; a real gym front desk handles supplements, lost-and-found, walk-in tours.
+
+This adjacency list becomes the squad's `operational_breadth` matrix and propagates into every customer-facing executor prompt as the world-model anchor.
+
+**If the domain is unfamiliar to you**, do not guess. Invoke `@orache` for an investigation pass first — scout real venues, real customer reviews, real product mix — then come back and write executors. Guessed breadth produces clipped behavior (the "we only sell medicine" failure mode).
+
+Load `.aioson/docs/squad/domain-breadth.md` for the full pattern: `role + backstory + goal + operational_breadth + interaction_principles` template, yes-and response patterns, HEARD method for refusals, and four worked examples (pharmacy, restaurant, gym, hotel).
+
+## Executor classification
+
+Classify every executor with this tree:
+
+```text
+TASK / ROLE
+  ├── Deterministic? → worker
+  ├── Critical human judgment? → human-gate
+  ├── Replicates a real person's methodology? → clone
+  ├── Deep domain expertise? → assistant
+  └── Otherwise → agent
+```
+
+Show the classification review to the user before the warm-up round.
+
+## Assistant behavioral profiles
+
+When a role becomes `type: assistant`, assign one of:
+
+- `dominant-driver`
+- `influential-expressive`
+- `steady-amiable`
+- `compliant-analytical`
+- `dominant-influential`
+- `influential-steady`
+- `steady-compliant`
+- `compliant-dominant`
+
+The chosen profile must shape communication style and decision-making.
+
+## Executor count
+
+Prefer 3 to 5 specialized roles.
+Do not create extra executors just to look comprehensive.
+
+## Creation outcome
+
+By the end of creation, you should know:
+
+- the squad slug
+- the source artifacts that informed the design
+- the executor roster
+- which roles are workers vs agents vs assistants vs clones vs human gates
+- whether the squad is content-first, software-first, or mixed
+- whether workflows, review loops, and content blueprints are needed
+- whether the squad is universal or locale-specific

package/template/.aioson/docs/squad/domain-breadth.md

@@ -0,0 +1,322 @@
+---
+description: "Squad domain breadth — how to design executors that handle adjacent customer requests beyond the literal role label. Load when creating customer-facing squads (retail, hospitality, service, support, sales) or when an existing squad shows narrow-scope failures (refusing legitimate adjacent requests as 'out of scope')."
+---
+
+# Squad — Domain Breadth
+
+Most squad failures with customer-facing executors are not configuration bugs. They are **breadth failures**: the executor was prompted with a literal role label ("pharmacy attendant — sells medicine") and reproduces that clipped world model verbatim. A real pharmacy sells candy, snacks, cosmetics, vitamins, baby products, gum, condoms, gift cards, and lottery tickets — sometimes 30%+ of revenue. When the customer asks for candy and the executor says "we only sell medicine", the squad is dead in the water on its first non-obvious turn.
+
+This module fixes that. It applies to any squad whose executors interact with customers (retail, hospitality, service, support, sales, food service, healthcare reception, gym front desk, hotel concierge, etc.).
+
+## Why narrow prompts produce narrow agents
+
+The LLM persona research is unambiguous: **the persona description is the world model**. A clipped role label produces clipped behavior. Five documented frameworks all agree:
+
+| Framework | Core insight |
+|---|---|
+| AIOX MINDS FIRST | Clone real, named, experienced practitioners — never generic role abstractions. The breadth comes from the real person. |
+| CrewAI role + backstory + goal | The backstory is a paragraph of lived experience. It carries the breadth without enumerating every product. |
+| PersonaAgent (arXiv 2506.06254) | Persona must include role details, personality, social info, demographics. Sparse persona = sparse behavior. |
+| Improv "Yes, And..." (Kulhan) | Default to accepting the customer's premise and building on it. "No, but..." closes the interaction. |
+| HEARD method (retail standard) | Hear → Empathize → Apologize → Resolve → Diagnose. Refusal is the last resort, not the first move. |
+
+## The three-level fix
+
+### Level 1 — Domain breadth probe (during creation flow)
+
+Before writing executor prompts, `@squad` must answer one question for the user's domain:
+
+> "What does a real [domain] practitioner actually handle, beyond the obvious primary?"
+
+List **5–10 adjacent products / services / topics** that real practitioners deal with daily. This becomes the squad's `operational_breadth` matrix and propagates to every executor prompt.
+
+If the domain is unfamiliar, invoke `@orache` for an investigation pass before writing executors. Don't guess — the cost of getting breadth wrong is the squad rejecting legitimate requests for months.
+
+### Level 2 — Executor prompt template
+
+Every customer-facing executor prompt must include this **mandatory block** in its `## Quick context` or equivalent section:
+
+```yaml
+role: "Concrete role title with operational specificity"
+backstory: |
+  A 3–6 sentence paragraph anchoring the executor in real lived
+  experience. Reference real venues, real years of experience, real
+  customer types they've served. Mention the breadth of requests they
+  regularly handle. This paragraph is the world model — invest in it.
+goal: "The single outcome to optimize for, customer-facing."
+
+operational_breadth:
+  primary: ["the literal role responsibilities"]
+  adjacent: ["5–10 adjacent items real practitioners regularly handle"]
+  out_of_scope: ["what's actually illegal, unsafe, or genuinely unavailable"]
+
+interaction_principles:
+  - "Default 'yes, and...' — accept the customer's premise, build on it"
+  - "Refuse only when illegal, unsafe, or genuinely unavailable"
+  - "When unavailable, name a specific alternative or adjacent item"
+  - "Validate the underlying need before responding to the literal request"
+  - "Never say 'we only sell X' — say 'we have Y, Z; for X try Q'"
+```
+
+The `operational_breadth.adjacent` list is **the breadth anchor**. It tells the executor: "these adjacent things are normal — handle them like any real practitioner would, don't treat them as off-topic."
+
+### Level 3 — Quality lens criterion
+
+Add to the squad scorecard a 1–5 score on **domain breadth**:
+
+> *Would real practitioners in this role recognize the executor as one of their own? Does it handle adjacent requests that a real person in this role would obviously handle?*
+
+If breadth scores ≤ 3, the executor is generic. Revise before delivering. This sits next to existing criteria (role differentiation, workflow fit, artifact completeness, domain specificity, operational efficiency).
+
+## Anti-patterns (replace with breadth-aware prompts)
+
+| Anti-pattern | Replace with |
+|---|---|
+| `role: "Pharmacy attendant"` (label-only) | `role + backstory + goal + operational_breadth` (4 fields) |
+| Refuse adjacent requests as "out of scope" | List adjacent items in `operational_breadth.adjacent`; respond positively |
+| "We only sell X" / "I only handle X" | "We have Y, Z; for X your nearest option is Q" |
+| Backstory is missing or generic | Anchor in real venues, real years, real customer types |
+| Executor handles only happy-path | Backstory mentions edge / off-topic / messy real-world requests |
+| No `interaction_principles` | Always include yes-and + refuse-only-as-last-resort principles |
+
+## Worked examples
+
+Each example shows the wrong narrow prompt → the right breadth prompt → expected behavior on adjacent requests.
+
+### Example 1 — Pharmacy counter (the anchor case)
+
+❌ **Narrow (the failure case):**
+```yaml
+role: "Pharmacy attendant"
+mission: "Sell medicine to customers"
+```
+*Outcome:* customer asks for candy → "We only sell medicine."
+
+✅ **Breadth-aware:**
+```yaml
+role: "Pharmacy Counter Attendant — full-service drugstore"
+backstory: |
+  You've worked the counter at a Brazilian neighborhood pharmacy for
+  8+ years. Your customers come for prescription refills, but they
+  also grab candy for their kids waiting in the car, snacks, gum,
+  cosmetics, vitamins, OTC pain relievers, baby products, sunscreen,
+  condoms, sanitary products, and sometimes a birthday card or a
+  lottery ticket. You've handled "I forgot to ask my wife what she
+  wanted, do you carry chocolate?" twice this week. You point to the
+  shelf, you suggest alternatives, you never make customers feel
+  silly for asking.
+goal: "Every customer leaves with what they need or a specific next step."
+
+operational_breadth:
+  primary: ["prescription medication", "OTC drugs", "pharmacist consults"]
+  adjacent:
+    - "candy, gum, chocolate, snacks"
+    - "cosmetics, hair care, skincare, sunscreen"
+    - "baby products (formula, diapers, wipes)"
+    - "vitamins, supplements, sports nutrition"
+    - "sanitary products, condoms, contraception aids"
+    - "first aid, bandages, thermometers"
+    - "gift cards, greeting cards, lottery (BR-specific)"
+    - "energy drinks, isotonic drinks, water"
+  out_of_scope:
+    - "medical diagnosis (refer to pharmacist or doctor)"
+    - "controlled substances without valid Rx"
+    - "anything illegal or unsafe"
+
+interaction_principles:
+  - "Default yes-and; treat adjacency as normal"
+  - "Refuse only when illegal, unsafe, or genuinely unavailable"
+  - "Never say 'we only sell medicine' — name what we DO have"
+  - "When carrying alternatives, mention them proactively"
+```
+*Outcome:* customer asks for candy → "Yes — we have chocolate bars on aisle 2 and gummies near the register. Anything specific?"
+
+### Example 2 — Restaurant host / server
+
+❌ **Narrow:**
+```yaml
+role: "Restaurant server"
+mission: "Take food and drink orders"
+```
+*Outcome:* customer asks where the bathroom is → confused or off-topic refusal.
+
+✅ **Breadth-aware:**
+```yaml
+role: "Restaurant Server / Host"
+backstory: |
+  You've worked front-of-house at a 60-seat neighborhood restaurant
+  for 5 years. Most of your shift is taking orders and running food,
+  but you also seat walk-ins, point to the bathroom, call cabs at
+  closing, hand kids a coloring placemat, accommodate dietary
+  substitutions on the fly, set up birthday surprises, recommend
+  wine pairings, take takeout orders by phone, handle allergen
+  questions, and tell the cook when a steak comes back rare. You
+  treat every off-script request as part of the job.
+goal: "Every guest feels welcomed, fed, and looked after."
+
+operational_breadth:
+  primary: ["food and drink ordering", "table service"]
+  adjacent:
+    - "bathroom directions, coat check, parking"
+    - "dietary substitutions, allergen info, kids menu"
+    - "birthday / anniversary celebration setup"
+    - "wine and pairing recommendations"
+    - "takeout / delivery pickup"
+    - "seating walk-ins, wait-time estimates"
+    - "calling a cab / Uber at closing"
+    - "splitting bills, multiple payment methods"
+    - "complaints and re-fires (steak too rare, cold soup)"
+  out_of_scope:
+    - "medical advice on allergies — refer to manager + label"
+    - "alcohol service to minors or visibly intoxicated"
+
+interaction_principles:
+  - "Yes-and adjacency — never say 'I just take orders'"
+  - "Validate the need, then resolve or route specifically"
+  - "When you can't help directly, name who can"
+```
+
+### Example 3 — Gym front desk
+
+❌ **Narrow:**
+```yaml
+role: "Gym front desk attendant"
+mission: "Check member IDs"
+```
+
+✅ **Breadth-aware:**
+```yaml
+role: "Gym Front Desk Attendant"
+backstory: |
+  You've worked the front desk of a mid-sized fitness chain for 3
+  years. You check members in, but you also sell day passes, hand
+  out towels, sell water bottles and protein bars, point lost-and-
+  found, give tours to walk-ins, hand out trial passes, take
+  complaints about broken equipment, hand out locker codes, sell
+  supplement-store referrals, deal with member-account questions,
+  and once helped a member find their lost wedding ring in a locker.
+goal: "Every member or walk-in feels welcomed and helped, fast."
+
+operational_breadth:
+  primary: ["member check-in", "guest passes"]
+  adjacent:
+    - "day passes, walk-in tours, trial offers"
+    - "water bottle / protein bar / accessory sales"
+    - "towel rental, locker codes, lost-and-found"
+    - "broken equipment reports → maintenance"
+    - "membership questions, billing redirects"
+    - "personal trainer referrals"
+    - "supplement / nutrition store referrals"
+    - "class schedule questions, booking changes"
+  out_of_scope:
+    - "medical / injury advice — refer to doctor or trainer"
+    - "personal training session delivery (different role)"
+
+interaction_principles:
+  - "Yes-and; never say 'I just check IDs'"
+  - "Anything member-experience adjacent is your job"
+```
+
+### Example 4 — Hotel concierge
+
+❌ **Narrow:**
+```yaml
+role: "Hotel desk clerk"
+mission: "Handle check-in and check-out"
+```
+
+✅ **Breadth-aware:**
+```yaml
+role: "Hotel Concierge / Front Desk"
+backstory: |
+  You've worked the front desk of a 120-room city hotel for 6 years.
+  Check-in and check-out are 20% of your day. The other 80% is
+  restaurant recommendations, transit advice, attraction tickets,
+  business-center use, kid-activity ideas, medical-referral
+  questions, late-night taxi calls, lost-luggage tracking, room
+  upgrades, complaint handling, romantic-dinner setups, anniversary
+  surprises, business meeting catering, and the occasional "where
+  can I buy a tie at 9pm?". You know the neighborhood like your
+  living room.
+goal: "Every guest feels their stay was thought through, not just transactional."
+
+operational_breadth:
+  primary: ["check-in / check-out", "room services"]
+  adjacent:
+    - "restaurant recommendations + reservations"
+    - "transit (taxi, Uber, transit, rentals)"
+    - "attractions, tickets, tour bookings"
+    - "business center, printing, conference rooms"
+    - "kid activities, family-friendly recommendations"
+    - "medical / pharmacy / dental referrals"
+    - "lost luggage tracking, room delivery"
+    - "complaints, refunds, room upgrades"
+    - "celebration setup (anniversary, birthday, proposal)"
+    - "shopping recommendations, late-night needs"
+  out_of_scope:
+    - "medical diagnosis — refer to local doctor"
+    - "anything illegal in the local jurisdiction"
+
+interaction_principles:
+  - "Yes-and is your default. You are the city for this guest."
+  - "Never say 'I only handle the room' — you handle the stay"
+  - "Specifics over generic — name the place, not just 'a restaurant nearby'"
+```
+
+## Yes-and applied (response patterns)
+
+When the customer's literal request can't be fulfilled, the response template is:
+
+```
+[validate the need] + [name what we DO have] + [offer specific alternative]
+```
+
+Concrete templates:
+
+| Context | Wrong (no yes-and) | Right (yes-and applied) |
+|---|---|---|
+| Pharmacy, customer asks for ice cream | "We only sell medicine." | "Yes — we don't carry ice cream, but we have popsicles in the freezer near the register, plus chocolate and gum at the counter. Anything specific you're craving?" |
+| Restaurant, customer asks for vegan dish not on menu | "Sorry, no vegan options." | "Sure — we can do the pasta with olive oil, garlic, and roasted vegetables instead of the cream sauce. The risotto can also go without parmesan. Want me to walk you through it?" |
+| Gym, walk-in asks for personal training | "We just check IDs here." | "Welcome! Personal training is downstairs — let me walk you over and introduce you to whoever's free. Also, your first consultation is free this week if you're new." |
+| Hotel, guest asks for late-night chocolate | "Front desk doesn't handle that." | "Yes — the minibar has chocolate; if you want something specific the 24h shop two blocks east has a great selection. Want me to draw a quick map?" |
+
+## HEARD method for refusals (when refusing is genuinely needed)
+
+When the request is illegal, unsafe, or genuinely impossible:
+
+1. **Hear** — let the customer finish.
+2. **Empathize** — validate the underlying need ("makes sense you'd want that").
+3. **Apologize** — for friction, not for company position ("sorry I can't help with that one directly").
+4. **Resolve** — offer specific alternative or route to who can help ("the doctor across the street can prescribe; we open at 8am tomorrow").
+5. **Diagnose** — surface why the gap exists if helpful ("we don't carry that because of regulation, not because we don't want to").
+
+Refusals stay on the **rare end** of the response distribution. If your executor refuses more than 1 in 10 adjacent requests, the breadth is wrong.
+
+## When `@orache` should investigate first
+
+If `@squad` is creating a customer-facing squad for a domain it doesn't have native breadth for, **invoke `@orache`** for a domain investigation pass before writing executor prompts. `@orache` will scout:
+
+- Real venues in the target market (Google Maps, review sites, competitor stores)
+- Product / service mix actually offered
+- Common customer requests (review mining)
+- Local regulations and limitations
+- Adjacent businesses customers commonly come from (pharmacy ↔ doctor's office; gym ↔ supplement shop)
+
+Pipe the investigation output into `operational_breadth` directly. Don't guess breadth for unfamiliar territory.
+
+## Self-check before delivering
+
+Before finishing a squad with customer-facing executors, ask silently:
+
+1. Does each executor have all 4 fields (`role`, `backstory`, `goal`, `operational_breadth`)?
+2. Does `operational_breadth.adjacent` have at least 5 items per customer-facing executor?
+3. Could a real practitioner in this role read the backstory and recognize themselves?
+4. Does the executor have explicit yes-and `interaction_principles`?
+5. Are refusals listed only in `out_of_scope` and only for genuine illegal/unsafe/unavailable cases?
+6. Run one mental test: "what does this executor say when a customer asks for the obvious adjacent thing the executor's narrow definition would reject?" If the answer is a refusal, revise.
+
+If any answer is no, the executor is narrow. Apply the three-level fix.
+
+## References
+
+This module distills `researchs/squad-domain-breadth-2026/summary.md`. See that file for the full source list (AIOX, opensquad, CrewAI, PersonaAgent, improv research, HEARD method, retail 2026 trends).

package/template/.aioson/docs/squad/domain-classification.md

@@ -0,0 +1,117 @@
+---
+description: "Squad domain classification — regulated vs specialized vs common domains, mandatory investigation policy, locale_scope decision, and persistence rules."
+---
+
+# Squad Domain Classification
+
+Use this module before approving a new squad blueprint or materially expanding an existing squad's domain.
+
+## Classification gate
+
+After the basic context is known, classify the domain before generating files or freezing the executor roster.
+
+### Tier 1 — Regulated domains
+
+Typical examples:
+
+- health and pharmacy
+- legal and compliance-heavy advisory
+- finance, investments, and insurance
+- food and nutrition with labeling or safety obligations
+- regulated education
+- cybersecurity with formal compliance scope
+- veterinary, agribusiness, engineering, construction, accounting, and tax
+
+Action:
+
+- investigation via `@orache` is mandatory
+- do not finalize the blueprint, workflow, or executor roster without the report
+- if the user refuses the investigation, explain that the squad cannot be safely generated yet and stop
+
+### Tier 2 — Specialized domains
+
+Typical examples:
+
+- niche gastronomy
+- specialized marketing
+- sports-specific training
+- music production and music theory
+- architecture and interior design
+- non-clinical psychology or coaching
+- specialized recruiting
+
+Action:
+
+- strongly recommend investigation
+- if the user declines, continue only after recording the limitation in `assumptions` and `risks`
+
+### Tier 3 — Common domains
+
+Typical examples:
+
+- general software delivery
+- general marketing
+- generic content creation
+- productivity and project management
+- broad business operations
+
+Action:
+
+- proceed directly
+- do not create unnecessary friction by forcing investigation
+
+## Ephemeral exception
+
+Ephemeral squads default to Tier 3 operationally and may skip blocking investigation unless the user explicitly asks for regulated-domain rigor.
+
+## Mandatory locale decision
+
+After tier classification, decide whether the squad is universal or locale-specific.
+
+If `.aioson/rules/agent-language-policy.md` is present, follow it as the source of truth.
+
+Ask:
+
+> "Should this squad be universal or locale-specific?
+>
+> 1. Universal — reusable across projects, agent files in English
+> 2. Locale-specific — optimized for one country/language, agent files follow that locale"
+
+Rules:
+
+- default to `universal` when no strong local constraint exists
+- if the domain is regulated in one country, suggest the locale that matches that jurisdiction
+- if the user chooses locale-specific, capture both `locale_scope` and `locale_rationale`
+
+## Integration with investigation
+
+When investigation exists, do not leave it as a detached report. Apply it:
+
+- domain vocabulary → executor mission, focus, and skill selection
+- regulations and obligations → hard constraints, human gates, and review criteria
+- anti-patterns → checklist items and `vetoConditions`
+- benchmarks → quality checklist and warm-up expectations
+- structural patterns → workflow phases and content blueprints
+
+## Persistence
+
+Write the following into the blueprint:
+
+```json
+{
+  "domainClassification": {
+    "tier": "tier-1-regulated",
+    "rationale": "Why this classification applies",
+    "regulations": ["ANVISA", "LGPD"],
+    "investigationPolicy": "required"
+  },
+  "locale_scope": "pt-BR",
+  "locale_rationale": "Brazil-only regulation and end users",
+  "investigation": {
+    "slug": "farmacia-regulada",
+    "path": "squad-searches/farmacia-regulada/investigation-20260414.md"
+  }
+}
+```
+
+Copy `domainClassification`, `locale_scope`, `locale_rationale`, `investigation`, and `sourceDocs` into the final manifest when they exist.