@jaimevalasek/aioson 1.28.0 → 1.29.1

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

@@ -1,9 +1,14 @@
 ---
 name: canonical-path-contract
-description: Mandatory distinction between root plans/, .aioson/plans/{slug}/, docs/pt/, and implementation-plan. Every artifact-writing agent must consult this contract before creating files.
+description: Mandatory distinction between root plans/, .aioson/plans/{slug}/, docs/pt/, and implementation-plan. Every artifact-writing agent must consult this contract before creating files.
 priority: 10
 version: 1.0.0
 agents: []
+modes: [planning, executing]
+task_types: [artifact-write, file-creation, plan-write]
+load_tier: trigger
+triggers: [writing plans, creating files, saving artifacts, choosing paths, artifact destination]
+paths: [plans/**, .aioson/plans/**, .aioson/context/**, docs/**]
 ---
 
 # Canonical Path Contract
@@ -27,9 +32,9 @@ Every agent that creates or writes files MUST resolve the target path using this
 | 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` |
-| Simple implementation plan | `.aioson/context/simple-plans/{slug}.md` | `@dev` / `@deyvin` |
-| QA report | `.aioson/context/qa-report-{slug}.md` | `@qa` |
+| Spec (living memory) | `.aioson/context/spec-{slug}.md` | `@dev` |
+| Simple implementation plan | `.aioson/context/simple-plans/{slug}.md` | `@dev` / `@deyvin` |
+| QA report | `.aioson/context/qa-report-{slug}.md` | `@qa` |
 
 ## Violation behaviors
 
@@ -44,9 +49,9 @@ Every agent that creates or writes files MUST resolve the target path using this
 |---|---|
 | "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) |
-
-## Simple plan distinction
-
-`simple-plans/{slug}.md` is not a PRD, not a Sheldon phased plan, and not a MEDIUM implementation plan. It is a lightweight implementation artifact for bounded technical work that `@dev` or `@deyvin` can execute directly under `.aioson/rules/simple-plan-lane.md`.
+| "context" | `.aioson/context/` (framework artifacts) |
+| "rules" | `.aioson/rules/` (agent rules) |
+
+## Simple plan distinction
+
+`simple-plans/{slug}.md` is not a PRD, not a Sheldon phased plan, and not a MEDIUM implementation plan. It is a lightweight implementation artifact for bounded technical work that `@dev` or `@deyvin` can execute directly under `.aioson/rules/simple-plan-lane.md`.

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

@@ -3,6 +3,11 @@ 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
+modes: [executing]
+task_types: [artifact-write, data-format]
+load_tier: trigger
+triggers: [choosing format, structured data, writing yaml, writing json, producing output, data file]
+paths: [output/**, .aioson/squads/**]
 ---
 
 # Data Format Convention
@@ -27,17 +32,17 @@ Use for: ICP profiles, persona profiles, audience segments, offer sheets, pricin
 
 **Example (`icp-primary.yaml`):**
 ```yaml
-profile:
-  name: "Agency-Dependent Founder"
-  description: "Business owner dependent on agencies or external developers"
-pain_points:
-  - Loss of control over the product
-  - Unpredictable delays and costs
-desired_outcome: "Autonomy and speed"
-buying_trigger: "Deadline approaching or delayed developer invoice arriving"
-messaging:
-  primary: "Take back control of your product"
-channels: [instagram, linkedin, youtube]
+profile:
+  name: "Agency-Dependent Founder"
+  description: "Business owner dependent on agencies or external developers"
+pain_points:
+  - Loss of control over the product
+  - Unpredictable delays and costs
+desired_outcome: "Autonomy and speed"
+buying_trigger: "Deadline approaching or delayed developer invoice arriving"
+messaging:
+  primary: "Take back control of your product"
+channels: [instagram, linkedin, youtube]
 ```
 
 ### Markdown — narrative for humans and linear agent reading

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

@@ -1,8 +1,12 @@
 ---
 name: disk-first-artifacts
-description: Every artifact generated by an agent must be written to disk before session end — never only displayed in chat
+description: Every artifact generated by an agent must be written to disk before session end — never only displayed in chat
 priority: 10
 version: 1.0.0
+modes: [executing]
+load_tier: always
+task_types: [artifact-write, delivery]
+triggers: [writing artifacts, session end, delivering output]
 ---
 
 # Disk-First: Artifacts Always on Disk
@@ -18,12 +22,12 @@ Every artifact produced by an AIOSON agent MUST be written to disk before sessio
 | `@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.md` (current canonical; `ui-spec-{slug}.md` is accepted only when explicitly feature-scoped) |
+| `@ux-ui` | UI Spec | `.aioson/context/ui-spec.md` (current canonical; `ui-spec-{slug}.md` is accepted only when explicitly feature-scoped) |
 | `@sheldon` | Manifest | `.aioson/plans/{slug}/manifest.md` |
-| `@pm` | Implementation Plan | `.aioson/context/implementation-plan-{slug}.md` |
-| `@dev` | Feature spec | `.aioson/context/spec-{slug}.md` |
-| `@dev` / `@deyvin` | Simple plan | `.aioson/context/simple-plans/{slug}.md` |
-| `@qa` | QA report | `.aioson/context/qa-report-{slug}.md` |
+| `@pm` | Implementation Plan | `.aioson/context/implementation-plan-{slug}.md` |
+| `@dev` | Feature spec | `.aioson/context/spec-{slug}.md` |
+| `@dev` / `@deyvin` | Simple plan | `.aioson/context/simple-plans/{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` |
 

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

@@ -4,6 +4,10 @@ description: All monetary values must be stored as integer cents, never as float
 agents: [dev, architect, qa]
 priority: 5
 version: 1.0.0
+modes: [planning, executing]
+task_types: [payment, billing, pricing]
+load_tier: trigger
+triggers: [money, monetary values, price, pricing, currency, cents, payment, billing, checkout, invoice, refund]
 ---
 
 # Monetary Values Convention

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

@@ -3,6 +3,8 @@ 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
+modes: [planning, executing]
+load_tier: always
 ---
 
 # Output Brevity

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

@@ -1,9 +1,14 @@
 ---
 name: prd-section-ownership
-description: Defines which agent owns each PRD section — other agents cannot modify sections they do not own
+description: Defines which agent owns each PRD section — other agents cannot modify sections they do not own
 priority: 9
 version: 1.0.0
 agents: [product, pm, analyst, architect, ux-ui, sheldon]
+modes: [planning, executing]
+task_types: [prd-edit, prd-enrichment]
+load_tier: trigger
+triggers: [prd, acceptance criteria, delivery phases, editing prd, enriching prd]
+paths: [.aioson/context/prd*.md]
 ---
 
 # PRD Section Ownership
@@ -14,16 +19,16 @@ agents: [product, pm, analyst, architect, ux-ui, sheldon]
 
 | PRD Section | Owner | Others may |
 |---|---|---|
-| `## Objective` | `@product` | Read only |
-| `## Problem` | `@product` | Read only |
-| `## Users And Personas` | `@product` | Read only |
-| `## Features` | `@product` | Read only |
-| `## Acceptance Criteria` | `@product` (structure) / `@pm` (enrichment) | `@analyst`, `@architect` add technical sub-items |
-| `## Delivery Phases` | `@pm` | Read only |
-| `## Technical Constraints` | `@architect` | Read only |
-| `## UX Considerations` | `@ux-ui` | Read only |
-| `## Risks` | `@pm` | `@analyst`, `@architect` add new risks only |
-| `## Registered Decisions` | `@sheldon` (project) / `@pm` (feature) | Read only |
+| `## Objective` | `@product` | Read only |
+| `## Problem` | `@product` | Read only |
+| `## Users And Personas` | `@product` | Read only |
+| `## Features` | `@product` | Read only |
+| `## Acceptance Criteria` | `@product` (structure) / `@pm` (enrichment) | `@analyst`, `@architect` add technical sub-items |
+| `## Delivery Phases` | `@pm` | Read only |
+| `## Technical Constraints` | `@architect` | Read only |
+| `## UX Considerations` | `@ux-ui` | Read only |
+| `## Risks` | `@pm` | `@analyst`, `@architect` add new risks only |
+| `## Registered Decisions` | `@sheldon` (project) / `@pm` (feature) | Read only |
 
 ## Modification rule
 
@@ -32,7 +37,7 @@ An agent may only modify sections it owns. Non-owners may only **add** a new sub
 ## Safe addition pattern
 
 ```markdown
-## Acceptance Criteria
+## Acceptance Criteria
 <!-- @product: owner of this section -->
 
 - CA-01: User can schedule an appointment

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

@@ -4,6 +4,10 @@ description: Secure by Default baseline controls for technical agents
 priority: 10
 version: 1.0.0
 agents: [analyst, architect, dev, qa]
+modes: [planning, executing]
+task_types: [security, auth, hardening]
+load_tier: trigger
+triggers: [security, auth, login, password, upload, secret, token, permission, ownership, rate limit, payment, multi-tenant, sanitize]
 ---
 
 # Security Baseline — Secure by Default

package/template/.aioson/rules/simple-plan-lane.md

@@ -4,6 +4,11 @@ description: Lightweight implementation lane for bounded technical work that doe
 priority: 9
 version: 1.0.0
 agents: [dev, deyvin, qa, neo]
+modes: [planning, executing]
+task_types: [simple-plan, bounded-work, refactor]
+load_tier: trigger
+triggers: [simple plan, bounded technical work, small fix, refactor, polish]
+paths: [.aioson/context/simple-plans/**]
 ---
 
 # Simple Plan Lane

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

@@ -1,9 +1,14 @@
 ---
 name: spec-level-ownership
-description: spec.md is project-level, spec-{slug}.md is feature-level — the two levels never mix
+description: spec.md is project-level, spec-{slug}.md is feature-level — the two levels never mix
 priority: 9
 version: 1.0.0
 agents: [dev, qa, pm, sheldon]
+modes: [planning, executing]
+task_types: [spec-write, spec-update]
+load_tier: trigger
+triggers: [spec, feature spec, project spec, updating spec, writing spec]
+paths: [.aioson/context/spec*.md]
 ---
 
 # Spec Ownership: Project vs Feature Level
@@ -19,16 +24,16 @@ Two distinct levels — never mix them.
 
 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`.
-5. Simple-plan work does not require `spec-{slug}.md`; keep its scope and decisions in `.aioson/context/simple-plans/{slug}.md` unless the work expands into a real feature.
+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`.
+5. Simple-plan work does not require `spec-{slug}.md`; keep its scope and decisions in `.aioson/context/simple-plans/{slug}.md` unless the work expands into a real feature.
 
 ## Mandatory structure: spec-{slug}.md
 
 ```markdown
 ---
 feature: {slug}
-status: in_progress | paused | done | abandoned
+status: in_progress | paused | done | abandoned
 phase_gates:
   requirements: approved | pending | skipped
   design: approved | pending | skipped

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

@@ -4,6 +4,11 @@ description: Territory boundaries and integration pattern for AIOSON squads —
 priority: 9
 version: 1.0.0
 agents: [dev, sheldon, pm, qa, architect]
+modes: [planning, executing]
+task_types: [squad-integration, driver]
+load_tier: trigger
+triggers: [squad, driver, embedding prompts, squad runner, llm call]
+paths: [.aioson/squads/**, src/services/**]
 ---
 
 # Squad Driver Pattern

package/template/.aioson/tasks/squad-create.md

@@ -123,6 +123,17 @@ For each executor in the blueprint, create `.aioson/squads/<slug>/agents/<execut
 - Before moving to the next executor, apply this test: would a real senior person in this role recognize themselves in this prompt? If not, deepen before continuing.
 - If `locale_scope` is locale-specific, write user-facing behavior examples in that locale's language; code identifiers remain English.
 
+### Step 5.5 - Genome Pass (bind or queue genomes)
+
+Load `.aioson/docs/squad/genome-bindings.md`. Then, for each executor whose blueprint entry plans a genome — and for every `assistant`/`clone` in a tier-1/tier-2 domain even when the blueprint is silent:
+
+1. Check `.aioson/genomes/` for an existing genome matching the planned domain/function — reuse before generating.
+2. If missing, generate it now by invoking `@genome` (Skill `aioson:agent:genome`) with the domain/function and `type`. `persona` genomes are never auto-generated — queue them for the Profiler pipeline instead.
+3. Apply the bindings: manifest `genomes` + `genomeBindings`, the executor's `## Active genomes` section, and `squad.md` (squad-level and per-agent genomes).
+4. If generation is not possible in this session, do NOT deliver empty `## Active genomes` silently: write the pending binding into the manifest (`genomeBindings` entry with `status: pending`) and put the exact `@genome` command in the creation summary.
+
+Skip this step only for tier-3 squads whose executors are all `worker` / plain `agent` types with no specialized expertise.
+
 ### Step 6 - Generate Orchestrator
 Create `.aioson/squads/<slug>/agents/orquestrador.md` following `.aioson/docs/squad/package-contract.md`, section `Orchestrator prompt`.
 If `uiCapability.mode = executor`, include routing guidance that visual demands go to `@ui-specialist`.

package/template/.aioson/tasks/squad-design.md

@@ -59,8 +59,8 @@ If the user already supplied enough context (text, docs, images), infer the answ
 Before defining executors, classify the domain using `.aioson/docs/squad/domain-classification.md`:
 
 - **Tier 1 — regulated:** investigation via `@squad investigate` / `@orache` is mandatory. Do not finalize the blueprint without a report.
-- **Tier 2 — specialized:** strongly recommend investigation. If the user refuses, record the limitation in `assumptions` and `risks`.
-- **Tier 3 — common:** proceed without unnecessary friction.
+- **Tier 2 — specialized:** run investigation by default (opt-out). If the user declines, record the limitation in `assumptions` and `risks`.
+- **Tier 3 — common:** with no `sourceDocs`, default to an `@orache` Quick Scan (announce it, let the user skip); proceed directly only when relevant sources or cached investigation already exist.
 
 If relevant investigation already exists, reuse the report instead of requesting a new one.
 
@@ -108,7 +108,7 @@ Group `workflows` into distinct work modes (originate / transform / judge / orch
 - `traces` — which `workflows`/`entities` this executor owns; an executor tracing no workflow is ceremony, so cut it
 - `confidence` (0-1) — how well sources justify this role; low = investigate or cut, never fill with padding
 - skills it will use
-- genomes it inherits
+- genomes it should inherit — record planned genomes (`type: domain|function`) for assistants/clones and specialized-domain agents; the create phase generates and binds them (`squad-create` Step 5.5)
 
 Always include an `orquestrador`. Keep 3-5 unless decomposition proves the real work requires more; do not inflate to look complete.
 

package/template/AGENTS.md

@@ -7,7 +7,7 @@ You operate as AIOSON — an AI development squad with specialized agents.
    - If missing: activate @setup agent immediately
    - If present: read it before any action
 2. Read `.aioson/config.md` only if project context is missing/invalid, setup/routing policy is needed, or the active agent explicitly asks for config details.
-3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
+3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent loads applicable rules on demand via its context loading section (`context:select` when the CLI is available, frontmatter match otherwise). Do not alarm if the directory is absent or empty.
 
 ## Project knowledge
 

package/template/CLAUDE.md

@@ -7,7 +7,7 @@ You operate as AIOSON.
    - If missing: run `/setup`
    - If present: read it before any action
 2. Read `.aioson/config.md` only if project context is missing/invalid, setup/routing policy is needed, or the active agent explicitly asks for config details.
-3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent will load applicable rules automatically via its "Project rules, docs & design docs" section. Do not alarm if the directory is absent or empty.
+3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — each agent loads applicable rules on demand via its context loading section (`context:select` when the CLI is available, frontmatter match otherwise). Do not alarm if the directory is absent or empty.
 
 ## Project knowledge