@jaimevalasek/aioson 1.22.0 → 1.23.1

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
 

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

@@ -28,10 +28,11 @@ Allowed machine-readable exceptions:
 | Project configuration | `.aioson/config.md` |
 | Conformance schema | `.aioson/context/conformance-{slug}.yaml` ← machine-readable exception |
 | Security findings | `.aioson/context/security-findings-{slug}.json` ← machine-readable exception |
-| Workflow handoff/runtime state | `.aioson/context/workflow.state.json`, `.aioson/context/handoff-protocol.json`, `.aioson/context/last-handoff.json` |
-| Parallel coordination machine files | `.aioson/context/parallel/*.json` |
-| Simple implementation plans | `.aioson/context/simple-plans/{slug}.md` |
-| Squad definitions | `.aioson/squads/{slug}/` |
+| Workflow handoff/runtime state | `.aioson/context/workflow.state.json`, `.aioson/context/handoff-protocol.json`, `.aioson/context/last-handoff.json` |
+| Parallel coordination machine files | `.aioson/context/parallel/*.json` |
+| Simple implementation plans | `.aioson/context/simple-plans/{slug}.md` |
+| Retrospective dossier | `.aioson/context/retro/{slug}.md` (or `window-last-{N}.md`) ← harness:retro |
+| Squad definitions | `.aioson/squads/{slug}/` |
 | Skill manifests | `.aioson/skills/{category}/{slug}/SKILL.md` |
 | Feature artifacts | `.aioson/context/{artifact}-{slug}.md` |
 | Project artifacts | `.aioson/context/{artifact}.md` |
@@ -43,13 +44,14 @@ 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
-simple-plans/{slug}.md       ← dev / deyvin
-features.md                   ← product / pm
-project-pulse.md              ← all agents (update at session end)
+implementation-plan-{slug}.md ← pm
+simple-plans/{slug}.md       ← dev / deyvin
+retro/{slug}.md               ← harness:retro (retrospective dossier; window-last-{N}.md for windows)
+features.md                   ← product / pm
+project-pulse.md              ← all agents (update at session end)
 conformance-{slug}.yaml       ← conformance machine-readable exception
 security-findings-{slug}.json ← pentester/qa security findings exception
 workflow.state.json           ← workflow runtime exception

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/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/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

@@ -102,7 +102,7 @@ When running Codex directly (without `aioson workflow:next`), these rules apply:
 - For implementation requests (code changes, feature build, refactor, bugfix), default to workflow routing and execute via the next workflow stage agent (typically `@dev` after required upstream stages).
 - Exception: if the user explicitly activates `@deyvin` (or the compatibility alias `@pair`), it may work directly only as a continuity / pair-programming agent for existing known context and a small validated slice. If the request is a new project, greenfield build, new feature, broad redesign, vague or contradictory, or mixes product + UX + implementation scope, `@deyvin` must hand off immediately and must not code first.
 - Official workflow agents (`@setup`, `@product`, `@analyst`, `@scope-check`, `@architect`, `@ux-ui`, `@pm`, `@orchestrator`, `@dev`, `@qa`) must stay inside the workflow. Do not answer requests outside the current agent's scope.
-- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work. Single exception: when `auto_handoff: true` is set in `project.context.md`, the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping — never past the `@dev` handoff.
+- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work. Single exception: when `auto_handoff: true` is set in `project.context.md`, the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping. That chain stops before the first `@dev` activation (the human clears context and starts implementation) and resumes through the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their `@qa` triggers fire → `@validator`); it never auto-runs `feature:close`/publish — those require explicit human approval.
 - If `project.context.md` is inconsistent, stale, or partially invalid, repair it inside the workflow when the correct value is objectively inferable from the active context and artifacts.
 - If a context field is still uncertain, route back to `@setup` inside the workflow instead of offering direct execution as a workaround.
 - Never silently bypass workflow after `@setup` or after collecting requirements.

package/template/CLAUDE.md

@@ -103,7 +103,7 @@ When running Claude Code directly (without `aioson workflow:next`), these rules
 **Hard constraints — no exceptions:**
 - You MUST NEVER implement code, produce UI specs, write PRDs, or answer technical tasks outside an activated agent.
 - If the user explicitly activates `/deyvin` or `/pair`, it may act directly only for continuity on existing known context and a small validated slice. If the request is a new project, greenfield build, new feature, broad redesign, vague or contradictory, or mixes product + UX + implementation scope, `/deyvin` must hand off immediately and must not code first.
-- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work. Single exception: when `auto_handoff: true` is set in `project.context.md`, the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping — never past the `@dev` handoff.
+- Between agent handoffs, your ONLY valid output is: which agent is next and why. Do not continue into that agent's work. Single exception: when `auto_handoff: true` is set in `project.context.md`, the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping. That chain stops before the first `@dev` activation (the human clears context and starts implementation) and resumes through the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their `@qa` triggers fire → `@validator`); it never auto-runs `feature:close`/publish — those require explicit human approval.
 - If the user sends an implementation request before setup is complete: do not implement. Tell them to activate `/setup` first.
 - If the user insists on bypassing an agent stage: refuse and redirect. Urgency or complexity do not override this rule.