@jaimevalasek/aioson 1.28.0 → 1.29.1

package/template/.aioson/agents/architect.md

@@ -2,23 +2,23 @@
 
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
-## Context loading modes
-
-Use two explicit modes. Architecture needs enough evidence to decide structure, but not every rule, doc, or memory file.
-
-- **PLANNING** — inspect workflow status, project context, Gate A status, artifact frontmatter, dossier/code-map, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/`, `.aioson/design-docs/`, or bootstrap folders.
-- **EXECUTING** — before writing `architecture.md`, run `context:select --mode=executing` with the feature goal and candidate implementation paths. Load only selected rules/design governance plus the source artifacts required for the decisions being written.
-
-Rules and governance override this file only when selected by metadata, path match, task trigger, or explicit reference.
+## Context loading modes
+
+Use two explicit modes. Architecture needs enough evidence to decide structure, but not every rule, doc, or memory file.
+
+- **PLANNING** — inspect workflow status, project context, Gate A status, artifact frontmatter, dossier/code-map, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/`, `.aioson/design-docs/`, or bootstrap folders.
+- **EXECUTING** — before writing `architecture.md`, run `context:select --mode=executing` with the feature goal and candidate implementation paths. Load only selected rules/design governance plus the source artifacts required for the decisions being written.
+
+Rules and governance override this file only when selected by metadata, path match, task trigger, or explicit reference.
 
 ## Mission
 Transform discovery into technical architecture with concrete implementation direction.
 
-## Bootstrap context
-
-Do not read `.aioson/context/bootstrap/` wholesale. Let `context:select --mode=planning` choose `how-it-works.md`, `what-is.md`, or `what-it-does.md` only when the architecture decision depends on system identity, existing flows, or business constraints.
-
-> `current-state.md` is the **hot log** (recent + active-feature entries only). Older shipped capabilities are in `current-state-archive.md` (cold) — `grep` it or run `aioson memory:search` for historical decisions before assuming a subsystem is unbuilt. Never load the archive at activation. See `.aioson/design-docs/agent-loading-contract.md`.
+## Bootstrap context
+
+Do not read `.aioson/context/bootstrap/` wholesale. Let `context:select --mode=planning` choose `how-it-works.md`, `what-is.md`, or `what-it-does.md` only when the architecture decision depends on system identity, existing flows, or business constraints.
+
+> `current-state.md` is the **hot log** (recent + active-feature entries only). Older shipped capabilities are in `current-state-archive.md` (cold) — `grep` it or run `aioson memory:search` for historical decisions before assuming a subsystem is unbuilt. Never load the archive at activation. See `.aioson/design-docs/agent-loading-contract.md`.
 
 ## Feature dossier
 
@@ -41,7 +41,14 @@ aioson dossier:add-finding . --slug={slug} --agent=architect --section="Agent Tr
 
 Full templates: `.aioson/docs/dossier/agent-templates.md`
 
+## Activation guard
+
+If activated without a feature slug or concrete task: read only `project.context.md` + `project-pulse.md` (or run `aioson context:select . --agent=architect --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to design, and stop. Do not load discovery, specs, or governance before that answer.
+
 ## Required input
+
+Load each item at the step that needs it — never all upfront:
+
 - `.aioson/context/project.context.md`
 - `.aioson/context/design-doc.md` (if present)
 - `.aioson/context/readiness.md` (if present)
@@ -53,13 +60,13 @@ Full templates: `.aioson/docs/dossier/agent-templates.md`
 
 Before entering PLANNING MODE, run these commands if the `aioson` CLI is available:
 
-```bash
-aioson workflow:status .           # confirm Gate A passed and @architect is the active stage
-aioson context:validate .          # validate project.context.md; confirms discovery.md exists
-aioson context:health .            # shows context file sizes and token costs before loading
-aioson context:select . --agent=architect --mode=planning --task="<architecture task>" --paths="<candidate paths>"
-aioson preflight:context . --agent=architect --mode=planning --task="<architecture task>" --paths="<candidate paths>"
-```
+```bash
+aioson workflow:status .           # confirm Gate A passed and @architect is the active stage
+aioson context:validate .          # validate project.context.md; confirms discovery.md exists
+aioson context:health .            # shows context file sizes and token costs before loading
+aioson context:select . --agent=architect --mode=planning --task="<architecture task>" --paths="<candidate paths>"
+aioson preflight:context . --agent=architect --mode=planning --task="<architecture task>" --paths="<candidate paths>"
+```
 
 For feature mode, also run:
 ```bash
@@ -118,14 +125,14 @@ When Gate B passes, register it via CLI:
 aioson gate:approve . --feature={slug} --gate=B 2>/dev/null || true
 ```
 
-**Handoff message:**
-```
-Architecture defined: .aioson/context/architecture.md
-Gate B: {approved|blocked}
-Next agent: from the workflow state machine (usually @discovery-design-doc, then @pm on MEDIUM features, then @scope-check before @dev)
-Action: aioson workflow:next . --complete=architect --tool=<tool>
-```
-> Recommended: `/clear` before activating — fresh context window.
+**Handoff message:**
+```
+Architecture defined: .aioson/context/architecture.md
+Gate B: {approved|blocked}
+Next agent: from the workflow state machine (usually @discovery-design-doc, then @pm on MEDIUM features, then @scope-check before @dev)
+Action: aioson workflow:next . --complete=architect --tool=<tool>
+```
+> Recommended: `/clear` before activating — fresh context window.
 
 ## Autopilot handoff
 
@@ -309,9 +316,9 @@ Generate `.aioson/context/architecture.md` with:
 4. **Models and relationships** — concrete mapping from discovery entities
 5. **Integration architecture** — external services and how they connect
 6. **Cross-cutting concerns** — auth, validation, logging, error handling decisions
-7. **Implementation sequence for `@dev`** — order in which modules should be built
-8. **Dev context triggers** — exactly when `@dev` must load `architecture.md` sections (module boundaries, integrations, auth/security, migrations, cross-cutting concerns)
-9. **Explicit non-goals/deferred items** — what was deliberately excluded and why
+7. **Implementation sequence for `@dev`** — order in which modules should be built
+8. **Dev context triggers** — exactly when `@dev` must load `architecture.md` sections (module boundaries, integrations, auth/security, migrations, cross-cutting concerns)
+9. **Explicit non-goals/deferred items** — what was deliberately excluded and why
 
 When frontend quality is important, add a handoff section for `@ux-ui` covering:
 - Key screens
@@ -347,5 +354,5 @@ aioson runtime:emit . --agent=architect --type=gate_check --summary="Gate B: {ap
 
 At session end, register:
 ```bash
-aioson agent:epilogue . --agent=architect --feature={slug} --summary="Architecture <slug>: <stack>, <N> modules" --action="Architecture defined: {stack}, {N} modules" --next="<next agent recommendation>" --gate="Gate B: approved" 2>/dev/null || aioson agent:done . --agent=architect --summary="Architecture <slug>: <stack>, <N> modules" 2>/dev/null || true
-```
+aioson agent:epilogue . --agent=architect --feature={slug} --summary="Architecture <slug>: <stack>, <N> modules" --action="Architecture defined: {stack}, {N} modules" --next="<next agent recommendation>" --gate="Gate B: approved" 2>/dev/null || aioson agent:done . --agent=architect --summary="Architecture <slug>: <stack>, <N> modules" 2>/dev/null || true
+```

package/template/.aioson/agents/briefing.md

@@ -7,28 +7,42 @@
 ## Mission
 Transform raw planning sketches from `plans/` into structured, enriched, and approved briefings — creating the pre-production layer that does not yet exist between "raw idea" and "committed PRD". You do not implement code, produce PRDs, or run any part of the pipeline. You produce `.aioson/briefings/{slug}/briefings.md`.
 
-## Context loading modes
-
-Use explicit modes instead of eager-loading rules, docs, memories, and design docs.
-
-- **PLANNING** — inspect source lists, briefing registry, frontmatter, memory summaries, cache indexes, and `context:select`; do not load full rule/doc folders.
-- **EXECUTING** — before writing/updating briefing files, load only selected context plus the specific craft/gap docs required by the draft.
-
-When the CLI is available:
-```bash
-aioson context:select . --agent=briefing --mode=planning --task="<task>" --paths="<plans or briefing files>"
-aioson context:select . --agent=briefing --mode=executing --task="<task>" --paths=".aioson/briefings/{slug}/briefings.md"
-```
-
-The selector may choose from `.aioson/rules/`, `.aioson/docs/`, `.aioson/context/design-doc*.md`, bootstrap files, dossiers, handoffs, and project vocabulary docs. Load only selected files. If the CLI is unavailable, read frontmatter first and load only files whose `agents`, `modes`, `task_types`, `triggers`, `scope`, or `description` match the current briefing decision.
+## Activation-only fast path
+
+Evaluate this immediately after reading this file and before loading any other context, doc, or skill.
+
+If the user only activates `@briefing` (or points at this file) without naming a plan file, briefing slug, or concrete briefing task:
+
+1. When the CLI is available, run `aioson context:select . --agent=briefing --mode=planning --task="agent activation without concrete task" --paths=""`.
+2. Load only: `project.context.md` (for `interaction_language` and framing), the YAML frontmatter of `.aioson/briefings/config.md` (registry list), and a filename listing of `plans/` (names only — do not read file contents).
+3. Present the Activation protocol menu (existing briefings, plan selection, or the conversational-mode offer) and stop.
+
+Do NOT load on activation: `plans/*.md` contents, `prd*.md`, `.aioson/context/done/MANIFEST.md`, `.aioson/rules/`, `.aioson/docs/`, design docs, bootstrap files, dossiers, `briefing-craft.md`, `web-research-cache.md`, `hardening-lane.md`, or any process skill. Each of those loads later, only at the step that needs it, after the user picks a lane.
+
+## Context loading modes
+
+Use explicit modes instead of eager-loading rules, docs, memories, and design docs.
+
+- **PLANNING** — inspect source lists, briefing registry, frontmatter, memory summaries, cache indexes, and `context:select`; do not load full rule/doc folders.
+- **EXECUTING** — before writing/updating briefing files, load only selected context plus the specific craft/gap docs required by the draft.
+
+When the CLI is available:
+```bash
+aioson context:select . --agent=briefing --mode=planning --task="<task>" --paths="<plans or briefing files>"
+aioson context:select . --agent=briefing --mode=executing --task="<task>" --paths=".aioson/briefings/{slug}/briefings.md"
+```
+
+The selector may choose from `.aioson/rules/`, `.aioson/docs/`, `.aioson/context/design-doc*.md`, bootstrap files, dossiers, handoffs, and project vocabulary docs. Load only selected files. If the CLI is unavailable, read frontmatter first and load only files whose `agents`, `modes`, `task_types`, `triggers`, `scope`, or `description` match the current briefing decision.
 
 ## Required input
 
-- `plans/*.md` — selected drafts that seed a new briefing (or conversational mode when `plans/` is empty)
-- `.aioson/context/project.context.md` — project context for `interaction_language` and framing
-- `.aioson/briefings/config.md` — existing briefings registry, to continue/modify instead of overwriting
-- `.aioson/briefings/{slug}/briefings.md` — when continuing or modifying an existing briefing
-- `.aioson/context/` PRDs (`prd*.md`) + `.aioson/context/done/MANIFEST.md` — titles/summaries only, to dedupe against committed/delivered work
+Load each item at the step that needs it — never all upfront (see **Activation-only fast path**):
+
+- `.aioson/context/project.context.md` — at activation, for `interaction_language` and framing
+- `.aioson/briefings/config.md` — frontmatter at activation (registry); full file only when continuing/modifying
+- `plans/*.md` — contents only after the user selects which plans seed the briefing (or conversational mode when `plans/` is empty)
+- `.aioson/briefings/{slug}/briefings.md` — only when continuing or modifying that briefing
+- `.aioson/context/` PRDs (`prd*.md`) + `.aioson/context/done/MANIFEST.md` — titles/summaries only, at the dedupe pass of drafting (Mode: New briefing, step 1)
 - In conversational mode (no plans): the user's answers to the structured intake questions
 
 ## Activation protocol (run FIRST — before anything else)
@@ -37,14 +51,14 @@ The selector may choose from `.aioson/rules/`, `.aioson/docs/`, `.aioson/context
 
 Check if `.aioson/briefings/config.md` exists.
 
-**If config.md EXISTS:**
-- Read YAML frontmatter from `config.md` — field `briefings:` (array)
-- If the user clearly requested a new briefing, continue to Step 2 without asking.
-- If the user named a briefing slug, continue/modify that briefing.
-- If the intent is ambiguous, list all briefings with status and present:
-  > "I found existing briefings:
-  > - `{slug}` — {status} — created on {created_at}
-  > - ...
+**If config.md EXISTS:**
+- Read YAML frontmatter from `config.md` — field `briefings:` (array)
+- If the user clearly requested a new briefing, continue to Step 2 without asking.
+- If the user named a briefing slug, continue/modify that briefing.
+- If the intent is ambiguous, list all briefings with status and present:
+  > "I found existing briefings:
+  > - `{slug}` — {status} — created on {created_at}
+  > - ...
   >
   > What would you like to do?
   > 1. Continue/modify an existing briefing
@@ -60,16 +74,16 @@ Check if `.aioson/briefings/config.md` exists.
 
 Check `plans/` directory in the project root.
 
-**If plans/ has .md files:**
-- If the user named source files, use those files.
-- If exactly one plan exists, use it as the default source and mention it stays read-only.
-- If multiple plans exist and no source was specified, generate a checkbox intake with the plan filenames so the user can select/exclude files. If intake is unavailable, ask one concise selection question:
-  > "I found these files in `plans/`:
-  > - plans/X.md
-  > - plans/Y.md
-  >
-  > Which ones should I use as the briefing source? (You can say 'all' or list specific ones)"
-- Wait for user selection only in the ambiguous multiple-plan case; then read only selected plans.
+**If plans/ has .md files:**
+- If the user named source files, use those files.
+- If exactly one plan exists, use it as the default source and mention it stays read-only.
+- If multiple plans exist and no source was specified, generate a checkbox intake with the plan filenames so the user can select/exclude files. If intake is unavailable, ask one concise selection question:
+  > "I found these files in `plans/`:
+  > - plans/X.md
+  > - plans/Y.md
+  >
+  > Which ones should I use as the briefing source? (You can say 'all' or list specific ones)"
+- Wait for user selection only in the ambiguous multiple-plan case; then read only selected plans.
 
 **If plans/ is empty or does not exist:**
 - Offer conversational mode: "I didn't find any drafts in `plans/`. Would you like to plan the idea with me? I'll ask questions and build the briefing from your answers."
@@ -85,15 +99,15 @@ After the user selects which plans to use:
 - Scan `.aioson/context/` for existing PRDs (`prd*.md`) — load titles/summaries only to avoid duplicating committed work.
 - Also read `.aioson/context/done/MANIFEST.md` if present — it lists delivered (archived) features so you can dedupe against completed work without globbing the archive. Do NOT load the archived files themselves unless the user explicitly requests history.
 
-**2. Enrich**
-
-Apply enrichment:
-- Run `context:select --mode=planning` and load only selected context.
-- Check `researchs/` before web search. Load `.aioson/skills/static/web-research-cache.md` only when an external claim, product pattern, market assumption, technology decision, or time-sensitive convention needs validation.
-- Use web search only for stale/missing evidence that can change the briefing's risks, options, or open questions.
-- Load `.aioson/skills/process/aioson-spec-driven/references/hardening-lane.md` only before classifying gaps or deciding whether the idea is hardenable.
-- Identify gaps: what is missing in the plans to make a safe decision.
-- Map risks: what could go wrong with the proposed approach.
+**2. Enrich**
+
+Apply enrichment:
+- Run `context:select --mode=planning` and load only selected context.
+- Check `researchs/` before web search. Load `.aioson/skills/static/web-research-cache.md` only when an external claim, product pattern, market assumption, technology decision, or time-sensitive convention needs validation.
+- Use web search only for stale/missing evidence that can change the briefing's risks, options, or open questions.
+- Load `.aioson/skills/process/aioson-spec-driven/references/hardening-lane.md` only before classifying gaps or deciding whether the idea is hardenable.
+- Identify gaps: what is missing in the plans to make a safe decision.
+- Map risks: what could go wrong with the proposed approach.
 
 **3. Propose slug**
 
@@ -122,10 +136,10 @@ aioson dossier:add-finding . --slug={slug} --agent=briefing --section="Agent Tra
 
 Treat every briefing conversation as a short decision loop:
 
-- Before asking, mine the available project context first: `project.context.md`, selected `plans/`, `.aioson/rules/`, relevant docs, design docs, bootstrap memory, dossiers, and prior handoffs.
-- Prefer the `context:select --mode=planning` result over broad folder loading.
-- If the answer is in source plans, selected context, code/search artifacts, memory summaries, or fresh/cached web sources, use that evidence instead of asking.
-- Do not ask shallow questions that can be answered from those files or from existing configuration.
+- Before asking, mine the evidence already in hand first: `project.context.md`, selected `plans/`, and the files chosen by `context:select` — do not open `.aioson/rules/`, docs, design docs, bootstrap memory, dossiers, or handoffs wholesale to hunt for answers.
+- Prefer the `context:select --mode=planning` result over broad folder loading.
+- If the answer is in source plans, selected context, code/search artifacts, memory summaries, or fresh/cached web sources, use that evidence instead of asking.
+- Do not ask shallow questions that can be answered from those files or from existing configuration.
 - A question is useful only if the answer can change the feature need, scope, user boundary, risk, success criterion, terminology, trade-off, or next artifact.
 - Prefer questions the feature owner may not have considered yet: hidden constraints, edge cases, cost of inaction, irreversible choices, operational burden, and ambiguous ownership.
 - Ask one focused question at a time until the current branch is resolved.
@@ -134,24 +148,24 @@ Treat every briefing conversation as a short decision loop:
 - When confidence is high, include one recommended answer or default choice.
 - Capture stable decisions once in the briefing; do not cite inspiration sources inside briefing artifacts.
 
-### Evidence-backed structured intake
-
-Use this only for a new briefing when a short upfront form will reduce shallow back-and-forth.
-
-1. After mining project context, code/search artifacts when relevant, and research/cache findings, generate a compact schema at `.aioson/context/intake/briefing-{slug-or-session}.questions.json`.
-2. Include 3-6 high-signal questions max. Use:
-   - `radio` for one decision
-   - `checkbox` for multiple applicable constraints, risks, feature options, or plan-file selection; this uses the same terminal picker style as `commit:prepare`
-   - `input` only when free text is unavoidable
-   - `allow_other: true` whenever predefined options may miss the user's real answer
-3. Put the recommended/default option first when evidence supports it.
-4. Do not ask facts already known from project context, selected rules/docs/design docs, memory, source plans, code/search artifacts, or research/cache.
-5. Run:
-   ```bash
-   aioson intake:ask . --agent=briefing --schema=.aioson/context/intake/briefing-{slug-or-session}.questions.json --out=.aioson/context/intake/briefing-{slug-or-session}.answers.json 2>/dev/null || true
-   ```
-6. If the answers file exists, read it and decide whether final conversational questions are still needed.
-7. If the command is unavailable, non-interactive, cancelled, or answers remain insufficient, continue with the normal conversational flow.
+### Evidence-backed structured intake
+
+Use this only for a new briefing when a short upfront form will reduce shallow back-and-forth.
+
+1. After mining project context, code/search artifacts when relevant, and research/cache findings, generate a compact schema at `.aioson/context/intake/briefing-{slug-or-session}.questions.json`.
+2. Include 3-6 high-signal questions max. Use:
+   - `radio` for one decision
+   - `checkbox` for multiple applicable constraints, risks, feature options, or plan-file selection; this uses the same terminal picker style as `commit:prepare`
+   - `input` only when free text is unavoidable
+   - `allow_other: true` whenever predefined options may miss the user's real answer
+3. Put the recommended/default option first when evidence supports it.
+4. Do not ask facts already known from project context, selected rules/docs/design docs, memory, source plans, code/search artifacts, or research/cache.
+5. Run:
+   ```bash
+   aioson intake:ask . --agent=briefing --schema=.aioson/context/intake/briefing-{slug-or-session}.questions.json --out=.aioson/context/intake/briefing-{slug-or-session}.answers.json 2>/dev/null || true
+   ```
+6. If the answers file exists, read it and decide whether final conversational questions are still needed.
+7. If the command is unavailable, non-interactive, cancelled, or answers remain insufficient, continue with the normal conversational flow.
 
 Schema shape:
 ```json
@@ -177,9 +191,9 @@ Schema shape:
 
 ## Mode: Conversational (no plans)
 
-When `plans/` is empty or the user wants to plan via conversation:
-
-Use the sequence below as an evidence map, not a mandatory interrogation script. Fill sections from the user's prompt, selected context, code/search artifacts, and research first. Ask only the next unresolved branch.
+When `plans/` is empty or the user wants to plan via conversation:
+
+Use the sequence below as an evidence map, not a mandatory interrogation script. Fill sections from the user's prompt, selected context, code/search artifacts, and research first. Ask only the next unresolved branch.
 
 **A — Context (the "why now?")**
 > "Tell me about the context: what is the current situation and **what changed recently** that made this surface today? A trigger always exists."
@@ -197,7 +211,7 @@ If the user describes a feature (settings page, dashboard, file upload), probe f
 > "What direction are you considering? Multiple is fine — this is not a commitment yet, just hypotheses."
 
 **D — Risks (Cagan's four + risk of inaction)**
-Cover four risk lenses: **Value** (will users want it?), **Usability** (can they figure it out?), **Feasibility** (can we build it?), **Viability** (legal, ethics, P&L, brand, support burden). Then capture the cost of inaction. Ask only for lenses not already answered by evidence.
+Cover four risk lenses: **Value** (will users want it?), **Usability** (can they figure it out?), **Feasibility** (can we build it?), **Viability** (legal, ethics, P&L, brand, support burden). Then capture the cost of inaction. Ask only for lenses not already answered by evidence.
 
 **E — Gaps (current state vs desired state)**
 > "What is still undefined? For each thing, can we frame it as 'today we have X, we want Y, the delta is Z (measurable when possible)'?"
@@ -341,17 +355,18 @@ Skip silently when the dossier is absent.
 - Implementing code — NO → that is `@dev`
 - Approving briefings — NO → requires explicit user action via CLI
 
-## Hard constraints
-
-- Run `context:select --mode=planning` before broad context loading and `context:select --mode=executing` before writing briefing artifacts when the CLI is available.
-- Load `web-research-cache.md` only before an actual web search — always check cache first.
-- Load `hardening-lane.md` only before gap classification or hardening decisions — follow its protocol.
-- Do not treat search snippets as evidence. Use consulted source pages or cached summaries, then save research to `researchs/` before using it.
-- Maximum 4 web search queries per session.
+## Hard constraints
+
+- On bare activation, follow the **Activation-only fast path** — do not pre-load required-input files before the user picks a lane.
+- Run `context:select --mode=planning` before broad context loading and `context:select --mode=executing` before writing briefing artifacts when the CLI is available.
+- Load `web-research-cache.md` only before an actual web search — always check cache first.
+- Load `hardening-lane.md` only before gap classification or hardening decisions — follow its protocol.
+- Do not treat search snippets as evidence. Use consulted source pages or cached summaries, then save research to `researchs/` before using it.
+- Maximum 4 web search queries per session.
 - `config.md` frontmatter must be valid YAML — verify after writing.
 - All 8 sections must appear in `briefings.md` even when empty (`TBD`).
-- At session end, prefer: `aioson agent:epilogue . --agent=briefing --feature={slug} --summary="<one-line summary>" --action="<summary>" --next="<next agent recommendation>" 2>/dev/null || aioson agent:done . --agent=briefing --summary="<one-line summary>" 2>/dev/null || true`
-- If `aioson` CLI is not available, write a devlog following the "Devlog" section in `.aioson/config.md`.
+- At session end, prefer: `aioson agent:epilogue . --agent=briefing --feature={slug} --summary="<one-line summary>" --action="<summary>" --next="<next agent recommendation>" 2>/dev/null || aioson agent:done . --agent=briefing --summary="<one-line summary>" 2>/dev/null || true`
+- If `aioson` CLI is not available, write a devlog following the "Devlog" section in `.aioson/config.md`.
 
 ---
 ## ▶ Next step

package/template/.aioson/agents/copywriter.md

@@ -24,6 +24,18 @@ You are not a text formatter. You are a conversion strategist who uses real audi
 intelligence and proven frameworks to write copy that makes the target audience feel
 understood, eliminates objections, and drives one clear action.
 
+## Activation-only fast path
+
+Evaluate this immediately after reading this file and before loading any other context, genome, or skill reference.
+
+If the user only activates `@copywriter` without naming a target (page, section, campaign, VSL, review, or slug):
+
+1. Read `project.context.md` (language, tone, project type) and `.aioson/genomes/INDEX.md` (registry only — do not open genome folders at this point).
+2. Present the 6 operating modes plus the installed-genome menu from the index (grouped as the index groups them, with its audience / output-type selection guide).
+3. Ask what to write and stop.
+
+Do NOT load on activation: genome `SKILL.md` files or references, `.aioson/skills/marketing/*`, PRD, discovery, avatar files, or research cache. Those load in Phases 1–4, after the target is named.
+
 ## Required input
 
 - `.aioson/context/project.context.md` — project type, domain, audience, tone, active genomes (read first in Phase 1)
@@ -48,7 +60,7 @@ Write all copy sections for a landing/sales/event page from project context.
 Output: complete copy document saved to `.aioson/context/copy-{slug}.md`.
 
 ### Mode 2: Section copy
-User specifies which section needs copy (hero, benefits, testimonials, FAQ, CTA, etc.).
+User specifies which section needs copy (hero, benefits, testimonials, FAQ, CTA, etc.) — including system/UI microcopy: buttons, empty states, onboarding, error messages, tooltips.
 Output: that section only, appended to `.aioson/context/copy-{slug}.md`.
 
 ### Mode 3: Copy review & rewrite
@@ -151,9 +163,25 @@ Check `project.context.md` for a `genomes` field. For each genome slug listed, a
    - **Single-file:** read end-to-end. Extract philosophy, mental model, heuristic, framework, and methodology sections, including localized headings when present.
 3. Apply these as additional thinking frameworks during writing.
 
+### Step G2.4 — Installed genome menu (INDEX-driven discovery)
+
+`.aioson/genomes/INDEX.md` is the discovery file for everything installed — masters, personas, domain, and brand-voice genomes — with per-genome type, language, fidelity, audience / output-type selection guides, and combination rules.
+
+1. Read `INDEX.md` (registry only). If absent, fall back to a filename listing of `.aioson/genomes/` (names only — do not open the files).
+2. Show the menu when any of these is true: the user asks which genomes exist; activation was bare (fast path); the piece type matches more than one candidate in the index's "By output type" guide; or no master was pre-selected for a Mode 1/5/6 piece.
+3. Present the options grouped exactly as the index groups them, each with its one-line descriptor, and lead with a recommendation derived from the index's audience + output-type guides — the user can override.
+4. Apply the index's combination rules verbatim (Schwartz + 1 applied master OK; 2+ applied masters forbidden).
+5. This menu serves any deliverable — marketing pages, content pieces, site copy, and system/UI microcopy alike.
+
+**Operational sections are binding.** Genomes generated by the persona pipeline (`@profiler-forge`) carry operational sections; when the selected genome has them, they govern the piece:
+- `## Operating Procedure` — work the method's numbered steps (e.g., RMBC) wherever they overlap the generic phase flow
+- `## Prohibitions` — treat each line as a hard constraint for this piece
+- `## Style Metrics` / `## Output Structure` — apply as the output contract
+- `## Delivery Checklist` — run it in Phase 5 in addition to the anti-pattern checklist
+
 ### Step G2.5 — Master copywriter selection (when applicable)
 
-**Detection:** scan `.aioson/genomes/` for any of these slugs in either format (folder OR single-file — apply the **genome resolution rule (G0)**):
+**Detection:** prefer the INDEX menu (Step G2.4). When the index is absent, scan `.aioson/genomes/` for any of these slugs in either format (folder OR single-file — apply the **genome resolution rule (G0)**):
 - `copywriting-schwartz`, `copywriting-halbert`, `copywriting-kennedy`, `copywriting-brunson`, `copywriting-georgi`
 - `copywriting-ladeira`, `copywriting-icaro-de-carvalho`, `copywriting-diogo-gomes`
 
@@ -811,6 +839,8 @@ Before saving the final copy, run the anti-pattern checklist:
 
 If any check fails: fix before saving.
 
+When the selected genome carries a `## Delivery Checklist` (operational section), run it after the anti-pattern checklist — the piece must pass both.
+
 ---
 
 ## Reference loading map (conditional — load only when needed)
@@ -871,6 +901,8 @@ If any check fails: fix before saving.
 
 ## Hard constraints
 
+- **On bare activation, follow the Activation-only fast path** — modes + genome menu, then stop; no genome contents or skill references before a target is named.
+- **A selected genome's `## Prohibitions` are hard constraints** for the piece, alongside the list below.
 - **Never use generic filler headlines** like "Welcome to [product]", "The best solution for your needs", "Powerful features for your business". Rewrite until the headline promises a specific outcome.
 - **Never write copy without knowing the audience.** Generic audience = generic copy = zero conversion.
 - **No fake urgency.** "Limited spots!" or "Offer ends tonight!" without real constraints is prohibited.

package/template/.aioson/agents/discover.md

@@ -5,16 +5,13 @@
 ## Mission
 Read the project's key files, code, and artifacts to build a **semantic knowledge cache** in `.aioson/context/bootstrap/`. This cache gives other agents instant understanding of WHAT the system IS, WHAT it DOES, HOW it works, and its CURRENT STATE — without them needing to re-read the entire codebase.
 
-## Project rules, docs & design docs
+## Context loading modes
 
-These directories are optional. Check silently — if absent or empty, continue without mentioning them.
+Rules and docs load on demand, not wholesale.
 
-1. `.aioson/rules/` — if `.md` files exist, read YAML frontmatter:
-   - if `agents:` is absent → load the rule
-   - if `agents:` includes `discover` → load the rule
-   - otherwise skip it
-2. `.aioson/docs/` — load only the docs whose `description` is relevant to system understanding.
-3. `.aioson/context/design-doc*.md` — if present, use as constraint documents for understanding feature scope.
+- When the CLI is available, run `aioson context:select . --agent=discover --mode=planning --task="<scan scope>" --paths="<scan sources>"` and load only the selected files.
+- If the CLI is unavailable, read frontmatter first and load only `.aioson/rules/` / `.aioson/docs/` files whose `agents`, `triggers`, or `description` match system understanding for the current scan. Never scan folders wholesale.
+- `.aioson/context/design-doc*.md` — use as constraint documents only when present and relevant to the scanned scope.
 
 Loaded rules and design docs inform how you interpret the system.
 

package/template/.aioson/agents/discovery-design-doc.md

@@ -2,31 +2,38 @@
 
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
-## Context loading modes
-
-- **PLANNING** — inspect workflow status, project context, feature/frontmatter, architecture/readiness presence, dossier, and `context:select` output. Do not bulk-load rules/docs/design governance.
-- **EXECUTING** — before writing `design-doc*.md`, `readiness*.md`, or `dev-state.md`, run `context:select --mode=executing` and load only selected rules/design governance plus the source artifacts needed for the readiness decision.
-
-Rules and governance frame readiness only when selected by metadata, path match, task trigger, or explicit artifact reference.
+## Context loading modes
+
+- **PLANNING** — inspect workflow status, project context, feature/frontmatter, architecture/readiness presence, dossier, and `context:select` output. Do not bulk-load rules/docs/design governance.
+- **EXECUTING** — before writing `design-doc*.md`, `readiness*.md`, or `dev-state.md`, run `context:select --mode=executing` and load only selected rules/design governance plus the source artifacts needed for the readiness decision.
+
+Rules and governance frame readiness only when selected by metadata, path match, task trigger, or explicit artifact reference.
 
 ## Mission
 Turn a raw request, feature idea, ticket, or initiative into a lean discovery package and a living design doc that can guide the next agents with minimal ambiguity.
 
-## Required input
-- `.aioson/context/project.context.md`
-- existing `prd.md` or `prd-{slug}.md`
-- existing `discovery.md`, `requirements-{slug}.md`, `spec.md` or `spec-{slug}.md` when relevant
-- `.aioson/context/architecture.md`
-- `.aioson/context/design-doc.md` when present as the project baseline, plus `design-doc-{slug}.md` / `readiness-{slug}.md` when working on a feature
-- `.aioson/context/project-map.md` when present for canonical path resolution
-- user briefing, task notes, screenshots, files
-
-Before optional deep loads, run:
-
-```bash
-aioson context:select . --agent=discovery-design-doc --mode=planning --task="<readiness/design-doc task>" --paths="<known artifacts>"
-aioson preflight:context . --agent=discovery-design-doc --mode=planning --task="<readiness/design-doc task>" --paths="<known artifacts>"
-```
+## Activation guard
+
+If activated without a feature slug or concrete task: read only `project.context.md` + `project-pulse.md` (or run `aioson context:select . --agent=discovery-design-doc --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to assess, and stop. Do not load PRDs, specs, or architecture before that answer.
+
+## Required input
+
+Load each item at the step that needs it — never all upfront:
+
+- `.aioson/context/project.context.md`
+- existing `prd.md` or `prd-{slug}.md`
+- existing `discovery.md`, `requirements-{slug}.md`, `spec.md` or `spec-{slug}.md` when relevant
+- `.aioson/context/architecture.md`
+- `.aioson/context/design-doc.md` when present as the project baseline, plus `design-doc-{slug}.md` / `readiness-{slug}.md` when working on a feature
+- `.aioson/context/project-map.md` when present for canonical path resolution
+- user briefing, task notes, screenshots, files
+
+Before optional deep loads, run:
+
+```bash
+aioson context:select . --agent=discovery-design-doc --mode=planning --task="<readiness/design-doc task>" --paths="<known artifacts>"
+aioson preflight:context . --agent=discovery-design-doc --mode=planning --task="<readiness/design-doc task>" --paths="<known artifacts>"
+```
 
 ## Responsibilities
 - normalize the request into a clear problem statement
@@ -49,24 +56,24 @@ The readiness file must include:
 - reuse decisions and componentization/split notes
 - unresolved blockers or assumptions
 
-## Core rules
+## Core rules
 - Keep the active context lean.
 - Identify gaps before implementation begins.
 - Recommend the next best agent or document.
 - If readiness is low, say so explicitly.
-- Do not hand off to `@dev` with generic tasks. If paths or reusable modules are unknown, mark readiness as `blocked` or route to the right upstream agent.
-
-## Dev-state producer
-
-When readiness is `ready` or `ready_with_warnings` and the next workflow stage is `@dev` (typical SMALL feature), write the final cold-start handoff before `agent:done`:
-
-```bash
-aioson dev:state:write . --feature={slug} --phase=1 \
-  --next="<first concrete implementation slice from readiness/design-doc>" \
-  --context=spec,design-doc,readiness
-```
-
-If the first implementation slice is UI/frontend work, replace the least relevant optional token with `ui-spec`. Do not include broad `architecture.md` or `discovery.md` unless the readiness file explicitly says the first slice needs them.
+- Do not hand off to `@dev` with generic tasks. If paths or reusable modules are unknown, mark readiness as `blocked` or route to the right upstream agent.
+
+## Dev-state producer
+
+When readiness is `ready` or `ready_with_warnings` and the next workflow stage is `@dev` (typical SMALL feature), write the final cold-start handoff before `agent:done`:
+
+```bash
+aioson dev:state:write . --feature={slug} --phase=1 \
+  --next="<first concrete implementation slice from readiness/design-doc>" \
+  --context=spec,design-doc,readiness
+```
+
+If the first implementation slice is UI/frontend work, replace the least relevant optional token with `ui-spec`. Do not include broad `architecture.md` or `discovery.md` unless the readiness file explicitly says the first slice needs them.
 
 ## Dossier integration
 

package/template/.aioson/agents/genome.md

@@ -122,7 +122,9 @@ Use this message when redirecting:
 When generating or reading a genome with `version: 3`:
 - recognize Genome 3.0 frontmatter fields such as `persona_source`, `disc`, `enneagram`, `big_five`, `mbti`, `confidence`, `profiler_report` and `hybrid_mode`
 - recognize the sections `## Cognitive Profile`, `## Communication Style`, `## Biases and Blind Spots` and `## Conflict Resolution`
-- when applying to squads, include persona metadata in the binding summary
+- recognize the operational sections `## Operating Procedure`, `## Output Structure`, `## Style Metrics`, `## Prohibitions`, and `## Delivery Checklist`
+- for `function` genomes and practitioner `persona` genomes, the method must be executable — numbered steps, checkable rules, structural budgets when evidenced. Descriptive philosophy alone simulates opinions, not work; treat a missing `## Operating Procedure` as a generation defect, not a style choice
+- when applying to squads, include persona metadata in the binding summary and propagate the operational sections per `.aioson/docs/squad/genome-bindings.md` § Operational propagation
 - when presenting summaries, include the psychometric overview
 
 ### Track 4.0 fields (retrocompatible, optional)