@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/genomes/copywriting-brunson/references/methodology.md

@@ -0,0 +1,112 @@
+---
+genome: copywriting-brunson
+reference: methodology
+load_priority: high
+---
+
+# Brunson Methodology — Storytelling + Mental Funnel + Value Stack + Community
+
+The Brunson method has 4 load-bearing pillars. All 4 must be active for the method to work.
+
+## The 4 pillars
+
+### Pillar 1 — Storytelling Drives Epiphanies
+
+Stories — not data, not features — produce the mental shifts that drive purchase decisions. Every Brunson sales sequence has multiple stories load-bearing the persuasion arc.
+
+Story types deployed (see `frameworks/persuasive-storytelling-5-structures.md`):
+- **Epiphany in the Mud** — personal failure that led to discovery
+- **Ambush on the Path** — pattern interrupt
+- **Trojan Horse** — initial offer that opens door to true value
+- **One Funnel Away** — so close to success, one element missing
+- **The Discoverer** — "I'm not the expert, but I discovered something"
+
+### Pillar 2 — Mental Funnel (Psychological Journey)
+
+The reader moves through 7 stages from first contact to purchase. Each stage prepares the next; skipping breaks the chain.
+
+The 7 stages:
+1. **Attraction** — first contact, hook
+2. **Qualification** — filter audience, establish fit
+3. **Authority** — establish credibility through results
+4. **Opportunity** — present new path / new opportunity
+5. **Multiplication** — value stack construction
+6. **Scarcity** — real reason to act now
+7. **Close** — clear instructions and CTA
+
+Each stage maps to specific copy elements (see `frameworks/perfect-webinar-script.md`).
+
+### Pillar 3 — Value Stack
+
+The offer's parts must visibly exceed the final price. Stack:
+- Main product (transformation, not features)
+- Complements that amplify results
+- Bonus trainings that eliminate objections
+- Access/support that ensures implementation
+- Spice bonus (unexpected element)
+- Price presentation justified by stack
+
+The sum of stacked items, when totaled, should visibly crush the final price (5-10× ratio common). See `frameworks/value-stack.md`.
+
+### Pillar 4 — Community / Movement Building
+
+People buy to **belong** to an aspirational group, not just for the product. The copy creates group identity and sense of belonging:
+
+- "You're part of something bigger"
+- "Join our movement"
+- "Become a [tribe name]"
+- Community language throughout
+
+Without this, even good copy + good offer + good story falls flat. The community/identity layer is what differentiates Brunson from generic direct response.
+
+## Why all 4 pillars together
+
+Each pillar fails alone:
+- Storytelling without funnel → entertaining but low-conversion
+- Funnel without storytelling → mechanical, no emotional bridge
+- Value stack without community → feels transactional
+- Community without value stack → tribal but no conversion
+
+Together they produce the Brunson signature: **storytelling that builds community, funneled through psychological stages, closing with irresistible value stack**.
+
+## The Hero/Guide dynamic
+
+Critical Brunson insight: the **customer is the hero**; the **copywriter is the guide**.
+
+| Mistake | Reality |
+|---------|---------|
+| You as hero ("I built this") | Customer as hero ("you're capable of this") |
+| Your story as central | Their journey as central |
+| Your credentials as authority | Your guide role as helpful |
+
+Frodo is the hero. Gandalf is the copywriter. **Inverting destroys identification** and the sale.
+
+## Origin Story role
+
+The Origin Story (see `frameworks/origin-story.md`) is the load-bearing artifact that establishes the guide role. It tells:
+- Who you were before the discovery
+- The trigger moment (epiphany)
+- The struggle to create the solution
+- The unexpected results
+- Your current mission
+- The invitation for the reader
+
+The Origin Story doesn't position you as the hero — it positions you as someone who FOUND a path that the reader (the hero) can now walk.
+
+## Modern application
+
+Brunson's method dominates 2026's:
+- Course launches (especially via webinar funnels)
+- Coaching/mentorship sales
+- Paid community sales (Brunson basically invented the modern paid community model)
+- High-ticket info-products
+- ClickFunnels-style funnel architectures
+
+The format: webinar → high-ticket sale → community membership → recurring revenue. The copy: storytelling → break beliefs → value stack → close.
+
+## What this method is NOT
+
+- **Not for serious B2B enterprise** — too aspirational/tribal a register
+- **Not for luxury minimalist brands** — Brunson's storytelling volume contradicts luxury restraint
+- **Not for regulated industries** — bold transformation claims may violate compliance
+- **Not for sober rational audiences** — see Georgi for that audience (Brunson + Georgi conflict)

package/template/.aioson/git-guard.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "description": "Project-specific overrides for aioson git:guard. allowPaths suppress both path-based and content-based checks for listed paths.",
+  "allowPaths": [],
+  "contentAllowPaths": [],
+  "blockPaths": [
+    "node_modules/**",
+    "aioson-logs/**"
+  ],
+  "allowExtensions": [],
+  "blockExtensions": []
+}

package/template/.aioson/mcp/servers.md

@@ -1,24 +1,23 @@
-# MCP Servers
-
-## Active
-- filesystem: native
-
-## Optional
-- context7: up-to-date framework docs
-- database: schema inspection
-- web-search: market and reference research
-- makopy: content generation pipelines
-
-## Local generation with AIOSON CLI
-Use:
-
-```bash
-aioson mcp:init
-```
-
-Generated files:
-- `.aioson/mcp/servers.local.json`
-- `.aioson/mcp/presets/claude.json`
-- `.aioson/mcp/presets/codex.json`
-- `.aioson/mcp/presets/gemini.json`
-- `.aioson/mcp/presets/opencode.json`
+# MCP Servers
+
+## Active
+- filesystem: native
+
+## Optional
+- context7: up-to-date framework docs
+- database: schema inspection
+- web-search: market and reference research
+
+## Local generation with AIOSON CLI
+Use:
+
+```bash
+aioson mcp:init
+```
+
+Generated files:
+- `.aioson/mcp/servers.local.json`
+- `.aioson/mcp/presets/claude.json`
+- `.aioson/mcp/presets/codex.json`
+- `.aioson/mcp/presets/gemini.json`
+- `.aioson/mcp/presets/opencode.json`

package/template/.aioson/profiler-reports/.gitkeep

@@ -1 +1 @@
-
+

package/template/.aioson/rules/README.md

@@ -1,69 +1,69 @@
-# Agent Rules
-
-Rules in this directory are loaded by agents automatically.
-Each rule file uses YAML frontmatter to declare which agents it applies to and when.
-
-Rules **override** agent default conventions. Use them for project-specific standards that must be enforced consistently across all sessions.
-
----
-
-## Frontmatter Format
-
-```yaml
----
-name: rule-name
-description: One-line description of what this rule enforces
-agents: [dev, architect]   # omit to apply to ALL agents
-priority: 10               # optional: higher = loaded first (default: 0)
-version: 1.0.0
----
-```
-
----
-
-## Field Reference
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `name` | yes | Unique identifier for the rule |
-| `description` | yes | What the rule enforces — used to decide relevance |
-| `agents` | no | List of agent names. If absent → all agents load it |
-| `priority` | no | Loading order. Higher = loaded first. Default: 0 |
-| `version` | no | Semantic version for tracking changes |
-
----
-
-## Loading Behavior
-
-- If `agents:` is absent → every agent loads the rule (universal rule)
-- If `agents:` lists agent names → only those agents load it
-- Loaded rules **override** the agent's built-in defaults
-- Rules are loaded silently — agents do not announce which rules were loaded
-- An agent named `dev` matches a rule with `agents: [dev]`
-
----
-
-## When to Create a Rule
-
-Create a rule when:
-- A convention must be enforced in every implementation session without re-stating it
-- A @dev learning has appeared in 3+ sessions and should be promoted to permanent
-- The team has decided on a project standard that differs from agent defaults
-
-Do NOT create a rule for:
-- One-time decisions (use `design-doc.md` decisions section instead)
-- Feature-scoped behavior (use `spec-{slug}.md` or `requirements-{slug}.md`)
-- External API knowledge (use `docs/` instead)
-
----
-
-## Example
-
-See `example-monetary-values.md` in this directory for a working example.
-
----
-
-## Squad Rules
-
-Rules specific to squad behavior live in `rules/squad/`.
-See `rules/squad/README.md` for the squad rules format.
+# Agent Rules
+
+Rules in this directory are loaded by agents automatically.
+Each rule file uses YAML frontmatter to declare which agents it applies to and when.
+
+Rules **override** agent default conventions. Use them for project-specific standards that must be enforced consistently across all sessions.
+
+---
+
+## Frontmatter Format
+
+```yaml
+---
+name: rule-name
+description: One-line description of what this rule enforces
+agents: [dev, architect]   # omit to apply to ALL agents
+priority: 10               # optional: higher = loaded first (default: 0)
+version: 1.0.0
+---
+```
+
+---
+
+## Field Reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Unique identifier for the rule |
+| `description` | yes | What the rule enforces — used to decide relevance |
+| `agents` | no | List of agent names. If absent → all agents load it |
+| `priority` | no | Loading order. Higher = loaded first. Default: 0 |
+| `version` | no | Semantic version for tracking changes |
+
+---
+
+## Loading Behavior
+
+- If `agents:` is absent → every agent loads the rule (universal rule)
+- If `agents:` lists agent names → only those agents load it
+- Loaded rules **override** the agent's built-in defaults
+- Rules are loaded silently — agents do not announce which rules were loaded
+- An agent named `dev` matches a rule with `agents: [dev]`
+
+---
+
+## When to Create a Rule
+
+Create a rule when:
+- A convention must be enforced in every implementation session without re-stating it
+- A @dev learning has appeared in 3+ sessions and should be promoted to permanent
+- The team has decided on a project standard that differs from agent defaults
+
+Do NOT create a rule for:
+- One-time decisions (use `design-doc.md` decisions section instead)
+- Feature-scoped behavior (use `spec-{slug}.md` or `requirements-{slug}.md`)
+- External API knowledge (use `docs/` instead)
+
+---
+
+## Example
+
+See `example-monetary-values.md` in this directory for a working example.
+
+---
+
+## Squad Rules
+
+Rules specific to squad behavior live in `rules/squad/`.
+See `rules/squad/README.md` for the squad rules format.

package/template/.aioson/rules/agent-language-policy.md

@@ -0,0 +1,93 @@
+---
+name: agent-language-policy
+description: Agent files default to English for universal reuse. Locale-specific squads may declare a locale_scope to write agent files in their native language.
+priority: 9
+version: 1.1.0
+agents: [squad, genome, orache, design-hybrid-forge, site-forge]
+---
+
+# Agent Language Policy
+
+Agent files are instruction code — default is English (maximizes LLM reasoning, universal reuse). Squads with `locale_scope` declared are the exception.
+
+## Language decision tree
+
+```
+Squad novo ou existente
+  ├── ephemeral: true → qualquer idioma
+  └── ephemeral: false
+      ├── locale_scope: "universal" (ou ausente) → agent files em INGLÊS
+      └── locale_scope: "{locale}" declarado → agent files no idioma do locale
+```
+
+## Declaring locale_scope
+
+In `squad.manifest.json`:
+
+```json
+{
+  "slug": "atendimento-farmacia",
+  "locale_scope": "pt-BR",
+  "locale_rationale": "Domínio regulado pela ANVISA — legislação, receituário e interações são exclusivamente brasileiros."
+}
+```
+
+Valid values: `"universal"` (default) or any BCP-47 code: `"pt-BR"`, `"en-US"`, `"es-MX"`, `"fr-FR"`.
+
+## When locale_scope is legitimate — ALL criteria must be true
+
+| Criterion | Question |
+|---|---|
+| Local regulation | Legislation governs a specific country? (ANVISA, OAB, NHS, FDA…) |
+| Local end user | Users interact exclusively in that language? |
+| No portability | Squad never reused in another country without full rewrite? |
+| Native domain reasoning | Technical domain richer in native language? |
+
+Justified: farmácia ANVISA, tributário eSocial, jurídico brasileiro, suporte nacional.
+Not justified: marketing digital, software dev, YouTube creator, psicologia/coaching.
+
+## Rules by layer
+
+### Universal squad
+
+| Layer | Language |
+|---|---|
+| Agent slug / name | English |
+| Agent file (mission, focus, constraints) | English |
+| Source code (vars, functions, classes) | English |
+| Agent output to user | `interaction_language` (fallback: `conversation_language`) |
+| Content docs (PRD, specs, plans) | Project language |
+
+### Locale-scoped squad
+
+| Layer | Language |
+|---|---|
+| Agent slug / name | Locale language |
+| Agent file (mission, focus, constraints) | Locale language |
+| Source code | **English — no exception** |
+| Agent output | Locale language |
+| Content docs | Locale language |
+
+## Mandatory question during squad creation
+
+Before generating any file:
+
+```
+Este squad é para uso em um país/idioma específico ou deve ser universal?
+
+1. Universal (inglês) — reutilizável em qualquer projeto, publicável no aiosforge.com
+2. Locale específico — ex: só para o Brasil, só em português
+```
+
+If (2): request locale code. If unclear: infer from domain and confirm.
+
+**Auto-inference:**
+- Domain with specific country legislation → suggest that country's locale
+- Portuguese content with clearly Brazilian audience → suggest `pt-BR`
+- Generic domain, no geographic reference → suggest universal
+
+## On file creation
+
+- Universal → write in English, no prompt needed.
+- Locale declared → write in locale language, no prompt needed.
+- Ambiguous → ask the mandatory question before generating any file.

package/template/.aioson/rules/aioson-context-boundary.md

@@ -0,0 +1,63 @@
+---
+name: aioson-context-boundary
+description: .aioson/context/ is Markdown-first with explicit machine-readable exceptions
+priority: 10
+version: 1.0.0
+agents: [product, analyst, architect, ux-ui, pm, dev, qa, sheldon]
+---
+
+# Context Boundary: .aioson/context/
+
+`.aioson/context/` is Markdown-first. Human-authored feature and project artifacts should be Markdown unless a file is one of the explicit machine-readable exceptions below.
+
+Prohibited by default: `.json`, `.yaml`/`.yml`, `.js`, `.ts`, `.py`, any non-Markdown format.
+
+Allowed machine-readable exceptions:
+
+- `.aioson/context/conformance-{slug}.yaml`
+- `.aioson/context/security-findings-{slug}.json`
+- `.aioson/context/workflow.state.json`
+- `.aioson/context/handoff-protocol.json`
+- `.aioson/context/last-handoff.json`
+- `.aioson/context/parallel/*.json`
+
+## Correct location by artifact type
+
+| Artifact type | Correct location |
+|---|---|
+| Project configuration | `.aioson/config.md` |
+| Conformance schema | `.aioson/context/conformance-{slug}.yaml` ← machine-readable exception |
+| Security findings | `.aioson/context/security-findings-{slug}.json` ← machine-readable exception |
+| Workflow handoff/runtime state | `.aioson/context/workflow.state.json`, `.aioson/context/handoff-protocol.json`, `.aioson/context/last-handoff.json` |
+| Parallel coordination machine files | `.aioson/context/parallel/*.json` |
+| Squad definitions | `.aioson/squads/{slug}/` |
+| Skill manifests | `.aioson/skills/{category}/{slug}/SKILL.md` |
+| Feature artifacts | `.aioson/context/{artifact}-{slug}.md` |
+| Project artifacts | `.aioson/context/{artifact}.md` |
+
+## Valid artifacts in .aioson/context/
+
+```
+project.context.md            ← setup
+discovery.md                  ← analyst
+requirements-{slug}.md        ← analyst
+architecture.md               ← architect
+ui-spec-{slug}.md             ← ux-ui
+prd.md / prd-{slug}.md        ← product
+spec-{slug}.md                ← dev
+implementation-plan-{slug}.md ← pm
+features.md                   ← product / pm
+project-pulse.md              ← all agents (update at session end)
+conformance-{slug}.yaml       ← conformance machine-readable exception
+security-findings-{slug}.json ← pentester/qa security findings exception
+workflow.state.json           ← workflow runtime exception
+handoff-protocol.json         ← workflow handoff exception
+last-handoff.json             ← workflow handoff exception
+parallel/*.json               ← parallel coordination exception
+```
+
+## On violation detected
+
+1. Do not create the file.
+2. Identify correct format and location.
+3. Inform user: "`.aioson/context/` is Markdown-first. Non-Markdown is allowed only for the listed machine-readable exceptions. Creating `{artifact}` in `{correct-location}` instead."

package/template/.aioson/rules/canonical-path-contract.md

@@ -0,0 +1,47 @@
+---
+name: canonical-path-contract
+description: Distinção obrigatória entre plans/ root, .aioson/plans/{slug}/, docs/pt/ e implementation-plan. Todo agente que escreve artefatos deve consultar este contrato antes de criar arquivos.
+priority: 10
+version: 1.0.0
+agents: []
+---
+
+# Canonical Path Contract
+
+Every agent that creates or writes files MUST resolve the target path using this contract before writing.
+
+## The three confusable directories
+
+| Directory | Purpose | Write rule |
+|---|---|---|
+| `plans/` (root) | Pre-production research and source material only | READ-ONLY for agents. Exception: `plans/source-manifest.md` may be updated when consuming a source plan. |
+| `.aioson/plans/{slug}/` | Active phased plan produced by `@sheldon` | Written by `@sheldon`. Consumed by `@dev` and `@qa` during execution. |
+| `docs/pt/` | Public system documentation for implemented behavior | Written only after behavior is implemented. Never used as operational planning space or scratchpad. |
+
+## Operational artifact destinations
+
+| Artifact | Correct destination | Owner |
+|---|---|---|
+| Operational feature plan (phased) | `.aioson/plans/{slug}/manifest.md` + phase files | `@sheldon` |
+| MEDIUM execution plan | `.aioson/context/implementation-plan-{slug}.md` | `@pm` |
+| PRD | `.aioson/context/prd-{slug}.md` | `@product` |
+| Requirements | `.aioson/context/requirements-{slug}.md` | `@analyst` |
+| Architecture | `.aioson/context/architecture.md` | `@architect` |
+| Spec (living memory) | `.aioson/context/spec-{slug}.md` | `@dev` |
+| QA report | `.aioson/context/qa-report-{slug}.md` | `@qa` |
+
+## Violation behaviors
+
+- If an agent is about to write a plan to `docs/pt/`: stop, use `.aioson/plans/{slug}/` instead.
+- If an agent is about to write an operational artifact to `plans/` root: stop, use the correct `.aioson/context/` or `.aioson/plans/{slug}/` path.
+- If any agent creates a file outside its write scope: stop, identify the correct path, and confirm with the user before writing.
+- Before creating any file, verify the path against `.aioson/context/project-map.md`.
+
+## When the user refers to a directory ambiguously
+
+| User says | Agent resolves to |
+|---|---|
+| "plans" or "plans folder" | Ask: root `plans/` (pre-production) or `.aioson/plans/{slug}/` (feature plan)? |
+| "docs" or "documentation" | Ask: `docs/` root (project docs) or `docs/pt/` (PT system docs) or `.aioson/docs/` (agent on-demand docs)? |
+| "context" | `.aioson/context/` (framework artifacts) |
+| "rules" | `.aioson/rules/` (agent rules) |