@jaimevalasek/aioson 1.23.0 → 1.23.1

package/template/.aioson/agents/ux-ui.md

@@ -5,19 +5,14 @@
 ## Mission
 Produce UI/UX that makes the user proud to show the result. Generic output is failure.
 
-## Project rules, docs & design docs
-
-These directories are **optional**. Check silently. If a directory is absent or empty, move on without mentioning it.
-
-1. **`.aioson/rules/`** — If `.md` files exist, read each file's YAML frontmatter:
-   - If `agents:` is absent → load (universal rule).
-   - If `agents:` includes `ux-ui` → load. Otherwise skip.
-   - Loaded rules **override** the default conventions in this file.
-2. **`.aioson/docs/`** — If files exist, load only those whose `description` frontmatter is relevant to the current task, or that are explicitly referenced by a loaded rule.
-3. **`.aioson/context/design-doc*.md`** — If `design-doc.md` or `design-doc-{slug}.md` files exist, read each file's YAML frontmatter:
-   - If `agents:` is absent → load when the `scope` or `description` matches the current task.
-   - If `agents:` includes `ux-ui` → load. Otherwise skip.
-   - Design docs provide architectural decisions, technical flows, and implementation guidance — use them as constraints, not suggestions.
+## Context loading modes
+
+Use two explicit modes so visual work loads the right evidence without pulling every UX module.
+
+- **PLANNING** — inspect project context, design skill field, PRD/frontmatter, active feature/dossier, artifact presence, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/ux-ui/`, `.aioson/design-docs/`, or design skills.
+- **EXECUTING** — after deriving the primary operation, run `context:select --mode=executing` and load only selected rules/design docs plus the required UX modules for that operation.
+
+Rules and design docs override this file only when selected by metadata, operation trigger, path match, or explicit artifact reference.
 
 ## Step 0 — Design skill gate
 
@@ -42,13 +37,20 @@ Apply when `project_type=site` and the operation is `default-create` or `refine-
 3. **If present:** read the copy file before any layout decision. The page structure (sections, headings, CTAs) must mirror the structure declared in the copy document. Treat the copy as the source of truth for textual content — never paraphrase, never insert placeholders, never reorder sections without the user's explicit instruction.
 4. The `audit`, `research`, `tokens`, `component-map`, and `a11y` submodes do not trigger this gate. They may run on existing UI without copy.
 
-## Required input
-- `.aioson/context/project.context.md`
-- `.aioson/context/prd.md` or `prd-{slug}.md` when present
-- `.aioson/context/discovery.md` when present
-- `.aioson/context/architecture.md` when present
-- `.aioson/context/spec-{slug}.md` (feature mode, if present)
-- `.aioson/context/spec.md` (project mode, if present)
+## Required input
+- `.aioson/context/project.context.md`
+- `.aioson/context/prd.md` or `prd-{slug}.md` when present
+- `.aioson/context/discovery.md` when selected because current flows/entities affect UI
+- `.aioson/context/architecture.md` when selected because component boundaries, routes, or frontend architecture affect UI
+- `.aioson/context/spec-{slug}.md` (feature mode, if present)
+- `.aioson/context/spec.md` (project mode, if present)
+
+Before loading optional inputs, run:
+
+```bash
+aioson context:select . --agent=ux-ui --mode=planning --task="<ux task>" --paths="<known UI paths>"
+aioson preflight:context . --agent=ux-ui --mode=planning --task="<ux task>" --paths="<known UI paths>"
+```
 
 ## Sheldon plan detection (RDA-03)
 
@@ -128,7 +130,7 @@ Before acting, derive one primary `operation`:
 - `component-map`
 - `a11y`
 
-Then build `required_modules` using this map:
+Then build `required_modules` using this map:
 
 | Condition | Required modules |
 |---|---|
@@ -140,14 +142,15 @@ Then build `required_modules` using this map:
 | `component-map` | `.aioson/docs/ux-ui/component-map.md` |
 | `a11y` | `.aioson/docs/ux-ui/accessibility-audit.md` |
 
-Preflight rules:
-
-1. If the operation creates or revises visual direction, load `design-gate.md` before layout or token decisions.
-2. If the operation is `default-create` or `refine-spec`, run the entry check from `design-execution.md` before producing output.
+Preflight rules:
+
+1. If the operation creates or revises visual direction, load `design-gate.md` before layout or token decisions.
+2. If the operation is `default-create` or `refine-spec`, run the entry check from `design-execution.md` before producing output.
 3. If existing UI artifacts are found and the user chooses **Audit**, switch the operation to `audit`.
 4. If the user chooses **Rebuild**, confirm overwrite before continuing.
-5. Do not proceed until every required module has been loaded.
-6. Do not preload ux-ui modules that are not required.
+5. Do not proceed until every required module has been loaded.
+6. Do not preload ux-ui modules that are not required.
+7. Before writing `ui-spec.md`, run `context:select --mode=executing` with the UI paths/components being specified and load only the selected rules/design governance.
 
 ## Output contract
 
@@ -156,9 +159,11 @@ Preflight rules:
 - `.aioson/context/ui-spec.md`
 - `.aioson/context/project.context.md` only if the `design_skill` selection was confirmed in this session
 
-**Creation mode — `project_type≠site`:**
-- `.aioson/context/ui-spec.md`
-- `.aioson/context/project.context.md` only if the `design_skill` selection was confirmed in this session
+**Creation mode — `project_type≠site`:**
+- `.aioson/context/ui-spec.md`
+- `.aioson/context/project.context.md` only if the `design_skill` selection was confirmed in this session
+
+`ui-spec.md` is the canonical downstream UI artifact. `@dev` reads it only when implementing UI components, frontend routes, interaction states, copy placement, or visual QA fixes.
 
 **Submode outputs:**
 - `research` → `.aioson/context/ui-research.md`
@@ -192,4 +197,4 @@ Do not overwrite sections owned by `@product` or `@analyst`.
 - If `aioson` CLI is not available, write a devlog at session end following `.aioson/config.md`.
 
 ## Observability
-At session end, register: `aioson agent:done . --agent=ux-ui --summary="UI spec <slug>: <N> components, design=<skill>" 2>/dev/null || true`
+At session end, prefer: `aioson agent:epilogue . --agent=ux-ui --feature=<slug> --summary="UI spec <slug>: <N> components, design=<skill>" 2>/dev/null || aioson agent:done . --agent=ux-ui --summary="UI spec <slug>: <N> components, design=<skill>" 2>/dev/null || true`

package/template/.aioson/agents/validator.md

@@ -100,12 +100,12 @@ aioson dossier:add-finding . --slug={slug} --agent=validator --section="Agent Tr
 
 Skip silently when the dossier is absent — `progress.json` remains the canonical machine output.
 
-## Observability
-At session end, register: `aioson agent:done . --agent=validator --summary="Validated <slug> phase <N>: score=<0|1>, ready_for_done=<bool>" 2>/dev/null || true`
+## Observability
+At session end, register: `aioson agent:epilogue . --agent=validator --feature=<slug> --summary="Validated <slug> phase <N>: score=<0|1>, ready_for_done=<bool>" --no-dossier 2>/dev/null || aioson agent:done . --agent=validator --summary="Validated <slug> phase <N>: score=<0|1>, ready_for_done=<bool>" 2>/dev/null || true`
 
 ## Autopilot handoff (post-dev cycle)
 
-When `auto_handoff: true` is set in `project.context.md`, after the verdict and `agent:done` (`.aioson/docs/autopilot-handoff.md`):
+When `auto_handoff: true` is set in `project.context.md`, after the verdict and `agent:epilogue`/`agent:done` (`.aioson/docs/autopilot-handoff.md`):
 - Score 0 / FAIL → `Skill(aioson:agent:dev)` with `"fix @validator findings — autopilot handoff"`.
 - Score 1 / PASS → **STOP**. The feature is verification-clean; recommend the human run `aioson feature:close . --feature={slug}`. **Never auto-run `feature:close`** — the close is the human gate.
 

package/template/.aioson/config/autonomy-protocol.json

@@ -32,6 +32,7 @@
         "workflow:status",
         "runtime:emit",
         "agent:done",
+        "review-cycle:status",
         "brain:query",
         "doctor"
       ]
@@ -48,6 +49,10 @@
         "memory:trim",
         "workflow:next",
         "workflow:heal",
+        "agent:epilogue",
+        "review-cycle:advance",
+        "review-cycle:resolve",
+        "review-cycle:reset",
         "live:handoff",
         "live:close",
         "dossier:add-codemap",
@@ -56,8 +61,10 @@
         "notify"
       ],
       "write_paths": [
+        ".aioson/context/**",
         ".aioson/context/bootstrap/**",
         ".aioson/context/features/**",
+        ".aioson/plans/**",
         ".aioson/runtime/**"
       ]
     },

package/template/.aioson/design-docs/code-reuse.md

@@ -1,12 +1,17 @@
 ---
-description: "DRY principles, reuse hierarchy, and composition patterns"
-scope: "governance"
-agents: []
----
+description: "DRY principles, reuse hierarchy, and composition patterns"
+scope: "governance"
+agents: [dev, deyvin, architect]
+modes: [planning, executing]
+task_types: [implementation-architecture, file-creation, refactor, reuse]
+load_tier: trigger
+triggers: [creating files, adding shared utility, reusing code, avoiding duplication, extending existing module]
+paths: [src/**, app/**, lib/**, template/**]
+---
 
 # Code Reuse — Governance Rules
 
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+> Loaded by the context selector when creating files, reusing code, extending modules, or avoiding duplication is in scope. Override per-project via `.aioson/rules/`.
 
 ## Before creating any new file
 

package/template/.aioson/design-docs/componentization.md

@@ -1,12 +1,17 @@
 ---
-description: "When and how to extract components, modules, and abstractions"
-scope: "governance"
-agents: []
----
+description: "When and how to extract components, modules, and abstractions"
+scope: "governance"
+agents: [dev, deyvin, architect]
+modes: [planning, executing]
+task_types: [implementation-architecture, module-boundary, refactor, extraction]
+load_tier: trigger
+triggers: [extract component, extract module, split module, abstraction, componentization, refactor duplicated logic]
+paths: [src/**, app/**, lib/**, template/**]
+---
 
 # Componentization — Governance Rules
 
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+> Loaded by the context selector when extraction, module boundaries, duplication, or abstraction decisions are in scope. Override per-project via `.aioson/rules/`.
 
 ## When to extract
 

package/template/.aioson/design-docs/file-size.md

@@ -1,12 +1,17 @@
 ---
-description: "File size guidelines, alert thresholds, and split strategies"
-scope: "governance"
-agents: []
----
+description: "File size guidelines, alert thresholds, and split strategies"
+scope: "governance"
+agents: [dev, deyvin, architect]
+modes: [planning, executing]
+task_types: [implementation, refactor, extraction, file-size]
+load_tier: trigger
+triggers: [large file, over 500 lines, split file, extract module, file size, growing file]
+paths: [src/**, app/**, lib/**, template/**, tests/**]
+---
 
 # File Size — Governance Rules
 
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+> Loaded by the context selector when file size, split, extraction, or large-file risk is in scope. Override per-project via `.aioson/rules/`.
 
 ## Thresholds
 

package/template/.aioson/design-docs/folder-structure.md

@@ -1,12 +1,17 @@
 ---
-description: "Universal folder organization rules — hierarchy, depth, naming, grouping"
-scope: "governance"
-agents: []
----
+description: "Universal folder organization rules — hierarchy, depth, naming, grouping"
+scope: "governance"
+agents: [dev, deyvin, architect]
+modes: [planning, executing]
+task_types: [implementation-architecture, file-creation, module-boundary, refactor]
+load_tier: trigger
+triggers: [creating files, moving files, splitting modules, designing implementation structure, folder structure]
+paths: [src/**, app/**, lib/**, template/**, tests/**]
+---
 
 # Folder Structure — Governance Rules
 
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+> Loaded by the context selector when implementation structure, file creation, moves, or module boundaries are in scope. Override per-project via `.aioson/rules/`.
 
 ## Depth
 

package/template/.aioson/design-docs/naming.md

@@ -1,12 +1,17 @@
 ---
-description: "Naming conventions for files, variables, functions, and classes"
-scope: "governance"
-agents: []
----
+description: "Naming conventions for files, variables, functions, and classes"
+scope: "governance"
+agents: [dev, deyvin, architect]
+modes: [planning, executing]
+task_types: [implementation-architecture, file-creation, naming, refactor]
+load_tier: trigger
+triggers: [naming files, naming APIs, creating files, adding functions, adding classes, choosing names]
+paths: [src/**, app/**, lib/**, template/**, tests/**]
+---
 
 # Naming — Governance Rules
 
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+> Loaded by the context selector when naming files, APIs, functions, classes, or implementation paths is in scope. Override per-project via `.aioson/rules/`.
 
 ## Files
 

package/template/.aioson/docs/autonomy-protocol.md

@@ -14,8 +14,8 @@ Visual notifier: `aioson notify --level=info|warn|block`.
 
 | Tier | Intent | UX | Examples |
 |---|---|---|---|
-| `tier1_silent`   | Read-only and telemetry. Auto-execute, no notification.                | none           | `git status`, `aioson preflight`, `aioson context:health`, `agent:done` |
-| `tier2_notified` | Mutates AIOSON memory (`bootstrap/`, `features/`, `runtime/`). Auto-execute with **inline notify** (ℹ).         | `ℹ [topic] msg` | `memory:reflect-prepare`, `memory:reflect-commit`, `workflow:next`, `dossier:*` |
+| `tier1_silent`   | Read-only and telemetry. Auto-execute, no notification.                | none           | `git status`, `aioson preflight`, `aioson context:health`, `agent:done`, `review-cycle:status` |
+| `tier2_notified` | Mutates AIOSON memory (`bootstrap/`, `features/`, `runtime/`). Auto-execute with **inline notify** (ℹ).         | `ℹ [topic] msg` | `memory:reflect-prepare`, `memory:reflect-commit`, `workflow:next`, `dossier:*`, `agent:epilogue`, `review-cycle:advance|resolve|reset` |
 | `tier3_blocking` | Irreversible or external (publish, push, npm registry). **Never** auto-executed; the CLI returns exit 2 and waits for a human. | `⛔ [topic] msg` | `git push *`, `npm publish *`, `cloud:publish:*`, `genome:publish` |
 
 A tool opts into tiers via `derived_from_tiers`:

package/template/.aioson/docs/autopilot-handoff.md

@@ -9,13 +9,21 @@ Opt-in protocol that removes manual handoff confirmations in the deterministic s
 1. **Pre-dev chain (`@analyst` → `@dev`):** `@analyst`, `@scope-check`, `@architect`, `@discovery-design-doc`, and `@pm` (MEDIUM only). Upstream agents (`@briefing`, `@product`, `@sheldon`) always stay manual — they end on genuine human decisions.
 2. **Post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` → `@validator`):** once a human starts `@dev`, the implementation and review agents chain automatically until the feature is ready to close. `@qa` is the hub: it owns the routing to the specialized agents and the corrections loop.
 
-## Activation
-
-Autopilot is active only when ALL are true:
-
-1. `project.context.md` frontmatter has `auto_handoff: true` (absent or `false` = manual handoffs, current behavior).
-2. A feature workflow is active (feature slug known, classification SMALL or MEDIUM).
-3. The current agent's own gate/verdict passed (see stop conditions).
+## Activation
+
+Autopilot is active only when ALL are true:
+
+1. `project.context.md` frontmatter has `auto_handoff: true` (absent or `false` = manual handoffs, current behavior).
+2. A feature workflow is active (feature slug known, classification SMALL or MEDIUM).
+3. The current agent's own gate/verdict passed (see stop conditions).
+
+Preferred runtime entrypoint:
+
+```bash
+aioson workflow:execute . --feature={slug} --tool=<tool> --agentic
+```
+
+`workflow:execute --agentic` is the central orchestration contract. It writes `.aioson/context/workflow-execute.json` with `agentic_policy`, including the review-loop caps, sidecar/scout policy, lane guard, current checkpoint, and resumable command. Prompt-level `Skill(aioson:agent:<next>)` chaining remains a compatibility fallback for clients that cannot let the gateway consume this checkpoint.
 
 ## Routing — deterministic, never LLM-chosen
 
@@ -26,19 +34,22 @@ The next agent comes from the workflow state machine and on-disk evidence, not f
 
 Never skip a stage, reorder, or pick an agent the state machine / routing table did not name.
 
-## Auto-invoke pattern
-
-When autopilot is active and no stop condition applies:
-
-1. Finish your own closing duties first (artifacts on disk, gate registration, dossier/spec updates, `pulse:update`, `agent:done`).
-2. Emit a one-line transition notice: `Autopilot: @<current> done → invoking @<next> (Ctrl+C to interrupt)`.
-3. Invoke `Skill(aioson:agent:<next>)` with the task `"continue feature {slug} — autopilot handoff from @<current>"`. No user prompt — Ctrl+C interrupts.
+## Auto-invoke pattern
+
+When autopilot is active and no stop condition applies:
+
+1. Finish your own closing duties first (artifacts on disk, gate registration, dossier/spec updates, `agent:epilogue`; `agent:done` remains the fallback).
+2. If the runtime checkpoint contains `agentic_policy.enabled=true`, let the gateway continue from `.aioson/context/workflow-execute.json`; do not ask the user to confirm the next deterministic stage.
+3. If no runtime gateway is available, emit a one-line transition notice: `Autopilot: @<current> done → invoking @<next> (Ctrl+C to interrupt)`.
+4. Invoke `Skill(aioson:agent:<next>)` with the task `"continue feature {slug} — autopilot handoff from @<current>"`. No user prompt — Ctrl+C interrupts.
 
 ## Segment 1 — pre-dev chain (`@analyst` → `@dev`)
 
-`@analyst` → `@scope-check` → `@architect` → `@discovery-design-doc` → (`@pm` on MEDIUM) → **STOP before `@dev`**.
-
-The pre-dev chain stops before the FIRST `@dev` activation. The human clears context (`/clear`) and starts implementation with a fresh budget — `@dev` is a heavy phase and benefits from a clean context window. Produce `dev-state.md` (the dev handoff producer), emit the standard handoff message, and recommend `/clear` + `/dev`. **Never auto-invoke the initial `@dev` entry.**
+SMALL feature: `@analyst` → `@scope-check` → `@architect` → `@discovery-design-doc` → `@dev`.
+
+MEDIUM feature: `@analyst` → `@architect` → `@discovery-design-doc` → `@pm` → `@scope-check` → `@dev`.
+
+The prompt-only fallback still stops before the FIRST `@dev` activation because `@dev` is a heavy phase and benefits from a fresh context window. Runtime agentic mode may cross this boundary only by starting a fresh `@dev` activation from the checkpoint/context package, not by carrying the upstream chat context forward. If the gateway cannot start that fresh activation, stop with the normal `/clear` + `/dev` recommendation.
 
 ## Segment 2 — post-dev review cycle (hub = `@qa`)
 
@@ -49,8 +60,8 @@ Routing table (each row is followed only when autopilot is active and no stop co
 | Current | Condition | Auto-invoke |
 |---|---|---|
 | `@dev` (first pass) | tests green, gates clear, no open corrections cycle | `@qa` |
-| `@dev` (corrections) | corrections applied, tests green (`qa-dev-cycle.json` present) | `@qa` (re-verify) |
-| `@qa` | verdict **FAIL** (Critical/High) | `@dev` via the corrections auto-cycle (cap 2, security gate) |
+| `@dev` (corrections) | corrections applied, tests green (`review-cycle:status` active; `qa-dev-cycle.json` is legacy QA compatibility) | `@qa` (re-verify) |
+| `@qa` | verdict **FAIL** (Critical/High) | `@dev` via the corrections auto-cycle (cap 3, security gate) |
 | `@qa` | verdict **PASS** + `@tester` trigger fires AND `@tester` not yet run clean | `@tester` |
 | `@qa` | verdict **PASS** + `@pentester` trigger fires AND `@pentester` not yet run clean | `@pentester` |
 | `@qa` | verdict **PASS** + harness contract present AND `@validator` not yet PASS | `@validator` |
@@ -69,8 +80,8 @@ Routing table (each row is followed only when autopilot is active and no stop co
 ## Stop conditions — break the chain and emit the normal manual handoff
 
 1. **`feature:close` / publish** — ALWAYS the human gate. When `@qa` (PASS, nothing pending) or `@validator` (PASS) is the last clean step, STOP and recommend `aioson feature:close . --feature={slug}`. Never auto-run `feature:close`, `feature:archive`, `npm publish`, or any publish/close action.
-2. **First `@dev` entry** — the pre-dev chain stops here (Segment 1). The human clears context and starts implementation.
-3. **Corrections cap reached** — the `@qa`↔`@dev` auto-cycle is bounded at 2 rounds (`qa-dev-cycle.json`); when exhausted, stop and escalate to the human.
+2. **First `@dev` entry without runtime gateway** — prompt-only clients stop here (Segment 1). Runtime agentic mode may continue only through a fresh checkpointed `@dev` activation.
+3. **Corrections cap reached** — review cycles are bounded by `agentic_policy.review_cycle` (default 3); when `review-cycle:advance` returns `stop_cycle_limit`, stop and escalate to the human.
 4. **Critical security finding** — the `@qa` corrections security gate (auth/secret/credential/session/password/token/PII/encryption keywords) blocks the auto-loop; stop and require human intervention.
 5. **Verdict not clean / gate or readiness blocked** — `@scope-check` not `approved`/`patched`, `@architect` Gate B blocked, `@discovery-design-doc` readiness `blocked`, `@pm` Gate C blocked, `@validator` FAIL with no safe corrections path: stop and route to the owner manually.
 6. **Context budget** — estimated usage ≥ `context_warning_threshold` (`.aioson/config.md`): write the compaction checkpoint to `.aioson/context/last-handoff.json`, stop, and recommend `/clear`. The workflow resumes from `workflow.state.json` — the next session re-enters autopilot automatically.

package/template/.aioson/docs/briefing/briefing-craft.md

@@ -1,6 +1,12 @@
----
-description: "Oracle deep guide — strong vs weak briefing examples, JTBD problem framing, Opportunity Solution Tree, Cagan's four risks, gap analysis, open-questions taxonomy, conversation playbook. Load when an existing briefing feels weak, when the conversation goes generic, or when a complex Themes section needs partitioning."
----
+---
+description: "Oracle deep guide — strong vs weak briefing examples, JTBD problem framing, Opportunity Solution Tree, Cagan's four risks, gap analysis, open-questions taxonomy, conversation playbook. Load when an existing briefing feels weak, when the conversation goes generic, or when a complex Themes section needs partitioning."
+agents: [briefing]
+modes: [planning, executing]
+task_types: [briefing-craft, jtbd-framing, opportunity-mapping, gap-classification, briefing-quality]
+load_tier: justified
+triggers: [weak briefing, generic conversation, JTBD, opportunity solution tree, four risks, more than 3 open questions, complex themes, switch interview]
+tags: [briefing, jtbd, gaps, risks]
+---
 
 # Oracle — Briefing Craft
 

package/template/.aioson/docs/deyvin/continuity-recovery.md

@@ -4,25 +4,21 @@ description: "Deyvin continuity recovery — session start order, resumption rul
 
 # Deyvin Continuity Recovery
 
-Load this module at the start of every `@deyvin` session before touching code.
+Load this module only when the task is continuity recovery, recent-work reconstruction, stale-state diagnosis, or resuming an existing slice.
 
 ## Session start order
 
-Build context in this order:
-
-1. If `aioson` is available, run `aioson memory:summary . --last=5` as the fast continuity bootstrap
-2. Read `.aioson/context/project.context.md`
-3. Check `.aioson/rules/`; load universal rules and rules targeted at `deyvin`
-4. Check `.aioson/docs/`; load docs referenced by rules or relevant to the task
-5. If the task is specific, run `aioson context:pack . --agent=deyvin --goal="<task>"` and read the generated pack
-6. Read `.aioson/context/memory-index.md` if present
-7. Read `.aioson/context/spec-current.md` and `.aioson/context/spec-history.md` if present
-8. Read `.aioson/context/spec.md` if present
-9. Read `.aioson/context/features.md` if present; if a feature is in progress, also read `prd-{slug}.md`, `requirements-{slug}.md`, and `spec-{slug}.md`
-10. Read `.aioson/context/skeleton-system.md`, `discovery.md`, and `architecture.md` as needed
-11. When the task matches procedural tags, run `aioson brain:query . --tags=<tags> --min-quality=4`
-12. Inspect recent runtime state in `.aioson/runtime/aios.sqlite` when memory summary is insufficient
-13. Use Git only as a fallback after memory + runtime + rules/docs
+Build context in this order:
+
+1. If `aioson` is available, run `aioson memory:summary . --last=5` as the fast continuity bootstrap.
+2. Read `.aioson/context/project.context.md`
+3. Run `aioson context:select . --agent=deyvin --mode=planning --task="<task>" --paths="<known paths>"`.
+4. Load only the selected PLANNING files. Do not load full `.aioson/rules/`, `.aioson/docs/`, `.aioson/design-docs/`, `discovery.md`, or `architecture.md` from this step alone.
+5. If a feature slug is known, load its dossier/spec only when `context:select`, `dev-state.md`, or `project-pulse.md` points to that slug; use `spec-current.md` for active spec and `spec-history.md` only for history.
+6. If code inspection/editing is about to start, run `aioson context:select . --agent=deyvin --mode=executing --task="<task>" --paths="<files to touch>"` and load only the selected EXECUTING files.
+7. When the task matches procedural tags, run `aioson brain:query . --tags=<tags> --min-quality=4`.
+8. Inspect recent runtime state in `.aioson/runtime/aios.sqlite` when memory summary is insufficient.
+9. Use Git only as a fallback after memory + runtime + selected rules/docs.
 
 If the user asks what happened recently, answer from memory and runtime first. Go to Git only if those sources are insufficient.
 
@@ -39,12 +35,12 @@ Do not duplicate or rewrite the shared SDD references inside `@deyvin`.
 
 ## Brownfield guardrails
 
-If `framework_installed=true` in `project.context.md` and the task depends on existing system behavior:
-
-- prefer `discovery.md` + `spec.md` as the primary memory pair
-- use `skeleton-system.md` or `memory-index.md` first for faster orientation
-- if `discovery.md` is missing but scan artifacts exist, stop and hand off to `@analyst`
-- if broad architecture decisions are required, hand off to `@architect`
+If `framework_installed=true` in `project.context.md` and the task depends on existing system behavior:
+
+- prefer selected module memory, `memory-index.md`, dossier, or spec before opening broad `discovery.md` / `architecture.md`
+- use `skeleton-system.md` or `memory-index.md` first for faster orientation
+- if `discovery.md` is missing but scan artifacts exist, stop and hand off to `@analyst`
+- if broad architecture decisions are required, hand off to `@architect`
 
 ## Git fallback
 

package/template/.aioson/docs/product/conversation-playbook.md

@@ -1,6 +1,11 @@
----
-description: "Product conversation playbook — opening messages, batching rules, proactive triggers, conversation phases, and finalize/surprise handling."
----
+---
+description: "Product conversation playbook — opening messages, batching rules, proactive triggers, conversation phases, and finalize/surprise handling."
+agents: [product]
+modes: [planning]
+task_types: [product-conversation, product-intake, feature-definition, prd-scoping]
+load_tier: trigger
+triggers: [asking product questions, structured intake, broad product discovery, visual preferences, finalize conversation]
+---
 
 # Product Conversation Playbook
 

package/template/.aioson/docs/product/prd-contract.md

@@ -1,6 +1,11 @@
----
-description: "Product PRD contract — exact PRD structure, visual identity block, output paths, and next-step routing."
----
+---
+description: "Product PRD contract — exact PRD structure, visual identity block, output paths, and next-step routing."
+agents: [product]
+modes: [executing]
+task_types: [prd-writing, prd-finalization, output-contract, artifact-writing]
+load_tier: trigger
+triggers: [writing PRD, updating PRD, PRD contract, output path, next-step routing, visual identity]
+---
 
 # Product PRD Contract
 

package/template/.aioson/docs/product/quality-lens.md

@@ -1,6 +1,11 @@
----
-description: "Product quality lens — strong patterns, anti-pattern replacements, and a compact scorecard for higher-quality PRDs."
----
+---
+description: "Product quality lens — strong patterns, anti-pattern replacements, and a compact scorecard for higher-quality PRDs."
+agents: [product]
+modes: [executing]
+task_types: [prd-writing, prd-finalization, prd-review, quality-review]
+load_tier: trigger
+triggers: [writing PRD, updating PRD, finalize PRD, PRD quality, review scorecard]
+---
 
 # Product Quality Lens
 

package/template/.aioson/docs/product/research-loop.md

@@ -1,6 +1,11 @@
----
-description: "Product research loop — extract short keyword phrases, consult research cache, search fresh sources, and fold the findings back into the PRD conversation."
----
+---
+description: "Product research loop — extract short keyword phrases, consult research cache, search fresh sources, and fold the findings back into the PRD conversation."
+agents: [product]
+modes: [planning, executing]
+task_types: [product-research, external-validation, market-scouting, competitor-research, product-patterns]
+load_tier: trigger
+triggers: [web search, research cache, market assumptions, competitor, pricing, compliance, time-sensitive UX, external evidence]
+---
 
 # Product Research Loop
 

package/template/.aioson/docs/ux-ui/accessibility-audit.md

@@ -1,6 +1,11 @@
 ---
-description: "UI/UX accessibility audit mode — WCAG-focused scan, remediation format, and QA handoff guidance for UI accessibility issues."
----
+description: "UI/UX accessibility audit mode — WCAG-focused scan, remediation format, and QA handoff guidance for UI accessibility issues."
+agents: [ux-ui]
+modes: [planning, executing]
+task_types: [accessibility, a11y, wcag, ui-audit]
+load_tier: trigger
+triggers: [a11y, accessibility, WCAG, screen reader, keyboard navigation, contrast]
+---
 
 # UX/UI Accessibility Audit
 

package/template/.aioson/docs/ux-ui/audit-mode.md

@@ -1,6 +1,11 @@
 ---
-description: "UI/UX audit mode — inventory scan, design quality checks, severity-based reporting, and fix recommendation format for existing UI."
----
+description: "UI/UX audit mode — inventory scan, design quality checks, severity-based reporting, and fix recommendation format for existing UI."
+agents: [ux-ui]
+modes: [planning, executing]
+task_types: [ui-audit, design-review, visual-qa]
+load_tier: trigger
+triggers: [audit, existing UI, design quality, visual QA, review UI]
+---
 
 # UX/UI Audit Mode
 

package/template/.aioson/docs/ux-ui/component-map.md

@@ -1,6 +1,11 @@
 ---
-description: "UI/UX component map mode — component inventory, atomic classification, variants, states, and gap analysis between spec and implementation."
----
+description: "UI/UX component map mode — component inventory, atomic classification, variants, states, and gap analysis between spec and implementation."
+agents: [ux-ui]
+modes: [planning, executing]
+task_types: [component-map, component-inventory, ui-components]
+load_tier: trigger
+triggers: [component-map, component inventory, variants, states, duplicate components]
+---
 
 # UX/UI Component Map
 

package/template/.aioson/docs/ux-ui/design-execution.md

@@ -1,6 +1,11 @@
 ---
-description: "UI/UX design execution — entry check, refine-vs-rebuild routing, design intent, domain exploration, direction selection, and delivery quality rules."
----
+description: "UI/UX design execution — entry check, refine-vs-rebuild routing, design intent, domain exploration, direction selection, and delivery quality rules."
+agents: [ux-ui]
+modes: [executing]
+task_types: [ui-design, ui-spec-writing, refine-spec, visual-direction]
+load_tier: trigger
+triggers: [default-create, refine-spec, writing ui-spec, rebuild UI, existing UI]
+---
 
 # UX/UI Design Execution
 

package/template/.aioson/docs/ux-ui/design-gate.md

@@ -1,6 +1,11 @@
 ---
-description: "UI/UX design gate — context repair, design skill selection, isolation rules, and style ambiguity handling before visual direction is chosen."
----
+description: "UI/UX design gate — context repair, design skill selection, isolation rules, and style ambiguity handling before visual direction is chosen."
+agents: [ux-ui]
+modes: [planning, executing]
+task_types: [ui-design, design-skill-selection, visual-direction]
+load_tier: trigger
+triggers: [design skill, visual direction, style ambiguity, project_type site, project_type web_app]
+---
 
 # UX/UI Design Gate
 

package/template/.aioson/docs/ux-ui/research-mode.md

@@ -1,6 +1,11 @@
 ---
-description: "UI/UX research mode — visual benchmarking, domain patterns, anti-patterns, and directional hypotheses before design work begins."
----
+description: "UI/UX research mode — visual benchmarking, domain patterns, anti-patterns, and directional hypotheses before design work begins."
+agents: [ux-ui]
+modes: [planning]
+task_types: [ui-research, visual-benchmarking, domain-patterns]
+load_tier: trigger
+triggers: [research, benchmark, visual references, competitor UI, domain patterns]
+---
 
 # UX/UI Research Mode
 

package/template/.aioson/docs/ux-ui/site-delivery.md

@@ -1,6 +1,11 @@
 ---
-description: "UI/UX site delivery — landing-page composition rules, hero law, motion standards, copy expectations, CSS techniques, and final HTML structure."
----
+description: "UI/UX site delivery — landing-page composition rules, hero law, motion standards, copy expectations, CSS techniques, and final HTML structure."
+agents: [ux-ui]
+modes: [executing]
+task_types: [site-delivery, landing-page, static-html]
+load_tier: trigger
+triggers: [project_type site, landing page, marketing page, index.html, static site, full-page HTML]
+---
 
 # UX/UI Site Delivery