@jaimevalasek/aioson 1.23.0 → 1.23.3

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
 

package/template/.aioson/docs/ux-ui/token-contract.md

@@ -1,6 +1,11 @@
 ---
-description: "UI/UX token contract mode — extraction and normalization of design tokens for colors, spacing, typography, and semantic ownership."
----
+description: "UI/UX token contract mode — extraction and normalization of design tokens for colors, spacing, typography, and semantic ownership."
+agents: [ux-ui]
+modes: [executing]
+task_types: [design-tokens, token-contract, visual-system]
+load_tier: trigger
+triggers: [tokens, design tokens, colors, spacing, typography, visual system]
+---
 
 # UX/UI Token Contract
 

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

@@ -44,7 +44,7 @@ project.context.md            ← setup
 discovery.md                  ← analyst
 requirements-{slug}.md        ← analyst
 architecture.md               ← architect
-ui-spec-{slug}.md             ← ux-ui
+ui-spec.md / ui-spec-{slug}.md ← ux-ui (`ui-spec.md` is the current canonical runtime artifact)
 prd.md / prd-{slug}.md        ← product
 spec-{slug}.md                ← dev
 implementation-plan-{slug}.md ← pm

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

@@ -18,7 +18,7 @@ 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-{slug}.md` |
+| `@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` |

package/template/.aioson/skills/process/aioson-spec-driven/SKILL.md

@@ -5,13 +5,15 @@
 
 ## When to use
 
-Load this skill when:
-- starting spec work for a new feature or project (any agent)
-- deciding phase depth based on classification (MICRO / SMALL / MEDIUM)
-- preparing a clean handoff to the next agent
-- retaking work after a session break (check `last_checkpoint` + `phase_gates` first)
-
-Do NOT load the entire `references/` folder. Load only the file matching your current need.
+Load this skill when:
+- starting spec work for a new feature or project (any agent)
+- deciding phase depth based on classification (MICRO / SMALL / MEDIUM)
+- preparing a clean handoff to the next agent
+- retaking work after a session break (check `last_checkpoint` + `phase_gates` first)
+
+Do not load this skill for `@deyvin` activation-only recovery. A bare `@deyvin` activation is status recovery, not spec work; run Deyvin's fast path and stop before opening this file.
+
+Do NOT load the entire `references/` folder. Load only the file matching your current need.
 
 ## What phases exist
 

package/template/.aioson/skills/process/aioson-spec-driven/references/approval-gates.md

@@ -54,7 +54,7 @@ Required for the gate to pass:
 Required for the gate to pass:
 - [ ] Execution sequence is defined
 - [ ] Checkpoints are listed with criteria of done
-- [ ] Context package is listed (which files to read before each phase)
+- [ ] Context package is listed as a short primary activation package plus phase-triggered loads (which files to read before each phase, and why)
 - [ ] Review / QA requirements are noted
 - [ ] Decisions marked "pre-taken" are FINAL — @dev does not re-discuss
 

package/template/.aioson/skills/process/aioson-spec-driven/references/architect.md

@@ -19,5 +19,6 @@
 
 - Classification depth from `classification-map.md` controls whether `architecture.md` is required, selective, or skippable
 - Gate B is the handoff signal — @dev must not start implementation without Gate B passing (MEDIUM) or being explicitly waived (SMALL)
-- Decision rationale is mandatory for non-obvious choices — `approval-gates.md` Gate B checklist item applies
-- `design-doc*.md` is @architect's scope-specific decision document — see `artifact-map.md`
+- Decision rationale is mandatory for non-obvious choices — `approval-gates.md` Gate B checklist item applies
+- `design-doc*.md` is @architect's scope-specific decision document — see `artifact-map.md`
+- `architecture.md` should include dev context triggers so @dev knows when to load architecture sections instead of reading the full file at activation

package/template/.aioson/skills/process/aioson-spec-driven/references/artifact-map.md

@@ -8,11 +8,12 @@
 prd*.md
   → sheldon-enrichment-{slug}.md   (optional enrichment layer)
   → requirements-{slug}.md         (entities, rules, ACs — @analyst)
-  → spec-{slug}.md                 (feature memory — @analyst seeds, @dev fills)
-  → architecture.md                (tech decisions — @architect)
-  → design-doc*.md                 (scope-specific decisions — @architect)
-  → implementation-plan-{slug}.md  (execution sequence — @pm for MEDIUM, AC-SDLC-15)
-  → spec-{slug}.md (updated)       (living state during execution — @dev)
+  → spec-{slug}.md                 (feature memory — @analyst seeds, @dev fills)
+  → architecture.md                (tech decisions — @architect)
+  → ui-spec.md                     (UI/UX contract — @ux-ui when UI is in scope)
+  → design-doc*.md                 (scope-specific decisions — @architect)
+  → implementation-plan-{slug}.md  (execution sequence — @pm for MEDIUM, AC-SDLC-15)
+  → spec-{slug}.md (updated)       (living state during execution — @dev)
 ```
 
 ## Artifact ownership
@@ -26,13 +27,24 @@ prd*.md
 | `requirements-{slug}.md` | @analyst | — | @architect, @dev, @qa |
 | `spec-{slug}.md` | @analyst (skeleton) | @dev (execution state) | @dev, @deyvin, @qa |
 | `spec.md` | @dev | @dev | @dev, @deyvin |
-| `architecture.md` | @architect | — | @dev, @ux-ui |
-| `design-doc*.md` | @architect | — | @dev, @ux-ui |
-| `implementation-plan-{slug}.md` | @pm (MEDIUM, AC-SDLC-15) | — | @dev, @deyvin, @orchestrator |
+| `architecture.md` | @architect | — | @dev, @ux-ui |
+| `design-doc*.md` | @architect | — | @dev, @ux-ui |
+| `ui-spec.md` | @ux-ui | — | @dev only for UI/frontend implementation, @pm/@orchestrator when UI phases exist |
+| `implementation-plan-{slug}.md` | @pm (MEDIUM, AC-SDLC-15) | — | @dev, @deyvin, @orchestrator |
+
+## Dev context contract
+
+`@dev` should not activate with the entire artifact chain loaded. The final pre-dev agent writes `dev-state.md` with a short primary package, and `implementation-plan-{slug}.md` carries phase-triggered loads:
+
+- `requirements-{slug}.md` — data, rules, ACs, migrations, edge cases
+- `architecture.md` — module boundaries, integrations, security, cross-cutting concerns
+- `design-doc*.md` / `readiness*.md` — implementation paths, reuse decisions, readiness blockers
+- `ui-spec.md` — UI components, frontend routes, interaction states, visual QA
+- PRD / Sheldon enrichment — only for product ambiguity
 
 ## Naming conventions
 
-- Project-level artifacts: `prd.md`, `discovery.md`, `spec.md`, `architecture.md`
+- Project-level artifacts: `prd.md`, `discovery.md`, `spec.md`, `architecture.md`, `ui-spec.md`
 - Feature-level artifacts: always use `{slug}` suffix — `prd-{slug}.md`, `requirements-{slug}.md`, `spec-{slug}.md`
 - Enrichment: `sheldon-enrichment.md` (project) or `sheldon-enrichment-{slug}.md` (feature)
 - Plans: `.aioson/plans/{slug}/manifest.md` + `plan-{slug-fase}.md` files

package/template/.aioson/skills/process/aioson-spec-driven/references/dev.md

@@ -8,7 +8,7 @@
 
 - `maintenance-and-state.md` — use to write and update `spec-{slug}.md` correctly: `phase_gates`, `last_checkpoint`, `pending_review`, and `Key decisions` format
 - `approval-gates.md` — Gate C (plan approval) must be checked before executing a significant batch; Gate D (execution verification) defines done criteria for each phase
-- For SMALL/MEDIUM work, confirm `.aioson/context/design-doc.md` and `.aioson/context/readiness.md` were produced by `@discovery-design-doc` before implementation starts
+- For SMALL/MEDIUM work, confirm `.aioson/context/design-doc*.md` and `.aioson/context/readiness*.md` were produced by `@discovery-design-doc` before implementation starts. Load them only when `dev-state.md`, readiness, the plan, or touched paths require their details.
 
 ### Load when starting a new feature with classification context
 
@@ -44,6 +44,7 @@ Additionally, at session start for SMALL/MEDIUM:
 
 - `spec-{slug}.md` must be updated at the end of every implementation session — see `maintenance-and-state.md` for format
 - Gate C from `approval-gates.md` means the implementation plan is locked — do not re-discuss pre-taken decisions
+- Treat `dev-state.md` as the primary activation package and `implementation-plan-{slug}.md` as the source for phase-triggered context loads
 - Gate D verification must happen before marking a phase complete — not just "I think it works"
 - If `phase_gates.plan` is `pending` and classification is SMALL/MEDIUM, suggest generating an implementation plan before proceeding
 - If `design-doc.md` or `readiness.md` is missing for SMALL/MEDIUM, route to `@discovery-design-doc` instead of coding first

package/template/.aioson/skills/process/aioson-spec-driven/references/deyvin.md

@@ -2,17 +2,21 @@
 
 > Router file. Do not duplicate logic from the generic references — load those directly.
 
-## Which references to load for continuation and resume flows
-
-### Always load when this skill is active
-
-- `maintenance-and-state.md` — @deyvin's primary job is resumption; use this to read `phase_gates`, `last_checkpoint`, and `pending_review` correctly before any action
-- `approval-gates.md` — use to check which gates are already approved before proceeding; never advance past a gate that is not yet passed
-
-### Load when the continuation context is unclear
-
-- `artifact-map.md` — use to quickly orient which artifacts exist and which are missing when resuming a session with incomplete context
-
+## Which references to load for continuation and resume flows
+
+### Activation-only sessions
+
+If the user only activates `@deyvin` without a concrete task, stop after the lightweight context summary from `context:select`. Do not load this reference's downstream files.
+
+### Load only for concrete continuation
+
+- `maintenance-and-state.md` — load when the concrete task requires reading or writing `spec*.md`, `last_checkpoint`, or `pending_review`
+- `approval-gates.md` — load when the next action could cross a phase gate, approve/deny readiness, or continue implementation past Gate C/D
+
+### Load when the continuation context is unclear
+
+- `artifact-map.md` — use to quickly orient which artifacts exist and which are missing after a concrete continuation task names a feature but the selected artifacts contradict each other
+
 ### Do not load for @deyvin
 
 - `hardening-lane.md` — by the time @deyvin is active, the spec pack should already be hardened
@@ -21,7 +25,7 @@
 
 ## Behavioral notes
 
-- `last_checkpoint` in `spec-{slug}.md` is the first thing @deyvin reads — see `maintenance-and-state.md` for format
-- Do not re-read the full spec pack unless `last_checkpoint` is null or contradictory
-- `phase_gates` from `approval-gates.md` defines what is locked — @deyvin does not re-open locked decisions
-- `pending_review` items must be surfaced to the user before proceeding past them
+- `last_checkpoint` in `spec-{slug}.md` is the first thing @deyvin reads only after a concrete continuation task selects that spec — see `maintenance-and-state.md` for format
+- Do not re-read the full spec pack unless `last_checkpoint` is null or contradictory
+- `phase_gates` from `approval-gates.md` defines what is locked — @deyvin does not re-open locked decisions
+- `pending_review` items must be surfaced to the user before proceeding past them

package/template/.aioson/skills/process/aioson-spec-driven/references/pm.md

@@ -22,7 +22,8 @@
 ## Behavioral notes for @pm under SDD
 
 - @pm is the **Gate C owner** — the plan is not complete until `spec-{slug}.md` has `phase_gates.plan: approved` and `implementation-plan-{slug}.md` (if MEDIUM) has `status: approved`
-- Gate C is **blocking in MEDIUM** — @dev and @orchestrator must not execute without Gate C passing
+- Gate C is **blocking in MEDIUM** — @dev and @orchestrator must not execute without Gate C passing
+- The implementation plan's context package must stay short at activation and list phase-triggered loads separately; @dev should not need to re-read the whole artifact chain to start
 - Gate C is **informational in SMALL** — flag if the plan looks thin, but do not block
 - Gate C is **skipped in MICRO** — @dev reads prd.md directly; @pm does not run for MICRO
 - ACs produced by @pm must match or extend the ACs in `conformance-{slug}.yaml` when it exists — never contradict the analyst's behavioral contracts

package/template/.aioson/skills/static/web-research-cache.md

@@ -26,11 +26,31 @@ Before running any WebSearch:
 4. If `searched_at` is within the last **7 days** → use the cached result, do not search again
 5. If older than 7 days or missing → proceed to search
 
-## Step 2 — Run the search
-
-- Formulate the query including the **current year** so results are fresh
-- Maximum **4 queries per session** — focus on the decisions with highest risk of being outdated
-- If WebSearch fails for a query: record the error in `summary.md` and continue — do not block
+## Step 2 — Run the search
+
+- Formulate the query including the **current year** when recency matters
+- Prefer specific keyword phrases over broad prompts: user segment, domain noun, workflow, technology, pricing/compliance/risk term
+- For technical/library decisions, prefer primary sources first: official docs, changelog/release notes, GitHub repo, standards, or vendor API reference
+- For product/domain decisions, prefer sources that expose real patterns: official product docs, pricing pages, support docs, market reports, competitor docs, or credible case studies
+- Open/extract the source pages before using them. Search result snippets are routing signals, not evidence.
+- Run at most one query expansion pass if the first query returns weak results: add domain/source constraints, synonyms, or the concrete decision being evaluated
+- Maximum **4 queries per session** — focus on decisions with highest risk of being outdated or materially wrong
+- If WebSearch fails for a query: record the error in `summary.md` and continue — do not block
+
+## Search quality model
+
+Good research is a pipeline, not a single search call:
+
+1. **Plan** — name the decision and what would change if the answer is different.
+2. **Search** — retrieve candidate sources.
+3. **Read/extract** — inspect the pages that actually support the finding.
+4. **Compress** — keep only source-grounded deltas that change options, risks, defaults, or open questions.
+
+Optional provider guidance for future integrations:
+
+- Agent/RAG search APIs such as Tavily, Exa, Firecrawl, or Brave can improve retrieval and extraction, especially when they return page content, highlights, or grounded answers.
+- Open-source extraction tools such as Crawl4AI are useful when AIOSON needs self-hosted crawling/scraping.
+- Do not make any provider mandatory in the core prompt. Use adapters behind the same cache contract so agents keep working with built-in web tools.
 
 ## Step 3 — Save results
 
@@ -106,9 +126,10 @@ If all findings are `confirmed`:
 
 ## Rules
 
-- **Never search without saving** — unsaved results are lost after the session
-- **Never block on search failure** — record the error and continue
-- **Never show `confirmed` findings** — they add noise without value
+- **Never search without saving** — unsaved results are lost after the session
+- **Never block on search failure** — record the error and continue
+- **Never use snippets as final evidence** — inspect source pages or use cached summaries
+- **Never show `confirmed` findings** — they add noise without value
 - **Never modify the PRD/plan without user confirmation** — surface findings, let the user decide
 - **Cache is shared across all agents** — if another agent already searched the same topic this week, use their result
 - `@product`, `@sheldon`, and `@squad` should derive short keyword phrases from the active task and scout the cache before finalizing substantial output

package/template/AGENTS.md

@@ -2,12 +2,12 @@
 
 You operate as AIOSON — an AI development squad with specialized agents.
 
-## Mandatory first action
-1. Read `.aioson/config.md`
-2. Check whether `.aioson/context/project.context.md` exists
-   - If missing: activate @setup agent immediately
-   - If present: read it before any action
-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.
+## Mandatory first action
+1. Check whether `.aioson/context/project.context.md` exists
+   - 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.
 
 ## Project knowledge
 
@@ -167,8 +167,8 @@ AIOSON uses the `aioson-spec-driven` process skill to enforce specification-firs
 
 Gates are blocking in MEDIUM, informational in MICRO/SMALL.
 
-### How agents load SDD
-Each agent checks for `aioson-spec-driven` in `.aioson/installed-skills/` or `.aioson/skills/process/` and loads its role-specific reference file (e.g., `references/dev.md`, `references/qa.md`).
+### How agents load SDD
+For concrete spec/workflow work, the active agent checks for `aioson-spec-driven` in `.aioson/installed-skills/` or `.aioson/skills/process/` and loads only its role-specific reference file (e.g., `references/dev.md`, `references/qa.md`). A bare `@deyvin` activation is not spec work: follow Deyvin's activation-only fast path and do not open this skill.
 
 ### Project pulse convention
 Every agent updates `project-pulse.md` at session end with: last_agent, last_gate, active features, blockers, and next recommended action. This enables crash recovery — any agent can read project-pulse.md and know where to resume.
@@ -179,9 +179,9 @@ Located at: `.aioson/skills/process/aioson-spec-driven/SKILL.md`
 
 This is a first-party process skill. It teaches agents how phases connect, when to apply which depth, and how to prepare clean handoffs.
 
-Agents that load it: @product, @analyst, @scope-check, @architect, @sheldon, @dev, @deyvin, @qa, @tester, @orchestrator, @pm
-When to load: at the start of any spec work (PRD, requirements, architecture, implementation, testing)
-What to load: `SKILL.md` first, then only the `references/` file relevant to the current phase
+Agents that load it: @product, @analyst, @scope-check, @architect, @sheldon, @dev, @deyvin, @qa, @tester, @orchestrator, @pm
+When to load: at the start of concrete spec work (PRD, requirements, architecture, implementation, testing); not during `@deyvin` activation-only recovery
+What to load: `SKILL.md` first, then only the `references/` file relevant to the current phase
 
 ## Process skill: design-hybrid-forge
 
@@ -225,8 +225,8 @@ researchs/
 Primary recurring writers here: @product, @sheldon, and @squad
 All agents may read from here to avoid redundant searches.
 
-## Session protocol
-If `.aioson/context/spec.md` exists, read it at session start and update it at session end.
+## Session protocol
+Do not read `.aioson/context/spec.md` globally at session start. Agents load `spec*.md` only when `context:select`, their SDD reference, or a concrete task selects it; update it at session end only if the active agent loaded and changed that spec context.
 
 ## Golden rule
 Small project, small solution.

package/template/CLAUDE.md

@@ -2,12 +2,12 @@
 
 You operate as AIOSON.
 
-## Mandatory first action
-1. Read `.aioson/config.md`
-2. Check whether `.aioson/context/project.context.md` exists
-   - If missing: run `/setup`
-   - If present: read it before any action
-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.
+## Mandatory first action
+1. Check whether `.aioson/context/project.context.md` exists
+   - 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.
 
 ## Project knowledge
 
@@ -83,9 +83,9 @@ Capture is best-effort — do not crash, retry, or surface failures to the user.
 
 AIOSON follows a Spec-Driven Development (SDD) methodology. Key governance files:
 
-- **`.aioson/constitution.md`** — 6 governing principles all agents must respect
-- **`.aioson/context/project-pulse.md`** — global project state; read at session start, update at session end
-- **`.aioson/skills/process/aioson-spec-driven/SKILL.md`** — process methodology; agents load this automatically
+- **`.aioson/constitution.md`** — 6 governing principles all agents must respect
+- **`.aioson/context/project-pulse.md`** — global project state; read at session start, update at session end
+- **`.aioson/skills/process/aioson-spec-driven/SKILL.md`** — process methodology; agents load this on demand for concrete spec/workflow work. `/deyvin` activation-only recovery must not load it.
 
 The process depth scales with project classification:
 - **MICRO** (0-1): lightweight — @product → @dev

package/template/OPENCODE.md

@@ -1,9 +1,10 @@
 # AIOSON - OpenCode
 
 ## Boot
-1. Read `.aioson/config.md`
-2. Check `.aioson/context/project.context.md`
+1. Check `.aioson/context/project.context.md`
+2. If present, read it before any action
 3. If missing, start with `setup`
+4. 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
 
 ## No agent selected