@jaimevalasek/aioson 1.22.0 → 1.23.1

package/template/.aioson/agents/dev.md

@@ -2,19 +2,21 @@
 
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
-## Project rules, docs & design governance
-
-These directories are optional. Check them silently — if absent or empty, continue without mentioning them.
-
-1. `.aioson/rules/` — if `.md` files exist, read YAML frontmatter:
-   - if `agents:` is absent or `[]` → load the rule
-   - if `agents:` includes `dev` → load the rule
-   - otherwise skip it
-2. `.aioson/docs/` — load only docs whose `description` is relevant to the current implementation task, or that are referenced by a loaded rule.
-3. `.aioson/context/design-doc*.md` — load when `scope`, `description`, or `agents:` matches the current feature or implementation task.
-4. `.aioson/design-docs/*.md` — load only when implementation implies module boundaries, file creation, naming, reuse, or componentization. Treat loaded governance docs as constraints during implementation.
-
-Loaded rules and governance override the default conventions in this file. This fallback applies even when the `aioson` CLI is unavailable.
+## Context loading modes
+
+Use two modes and do not blur them:
+
+- **PLANNING** — inspect status, frontmatter, indexes, and `aioson context:select`; do not load full rules/docs/design governance.
+- **EXECUTING** — before the first code edit, load only the files selected for the concrete task and paths.
+
+If `aioson` is available, select context with:
+
+```bash
+aioson context:select . --agent=dev --mode=planning --task="<task>" --paths="<known paths>"
+aioson context:select . --agent=dev --mode=executing --task="<task>" --paths="<files to touch>"
+```
+
+If the CLI is unavailable, read YAML frontmatter only and apply the same rule: `agents`, `modes`, `task_types`, `triggers`, and `paths` decide what to load. Rules and governance override this file only after they are selected by mode/task/path.
 
 ## Mission
 Implement features according to architecture while preserving stack conventions and project simplicity.
@@ -24,13 +26,14 @@ Implement features according to architecture while preserving stack conventions
 **Step 0 — Tool-first preflight (before reading any file):**
 If `aioson` is available:
 ```bash
-aioson workflow:status .
-aioson context:validate .
-aioson preflight . --agent=dev --feature={slug}
-aioson preflight:context . --agent=dev
-aioson memory:status .
-```
-Use output to orient; load listed `rules`/`design_governance` before structural code changes. If CLI unavailable, proceed to Step 1.
+aioson workflow:status .
+aioson context:validate .
+aioson preflight . --agent=dev --feature={slug}
+aioson context:select . --agent=dev --mode=planning --task="<task>" --paths="<known paths>"
+aioson preflight:context . --agent=dev --mode=planning --task="<task>" --paths="<known paths>"
+aioson memory:status .
+```
+Use output to orient. Do not load full `rules`, `.aioson/docs/`, or `.aioson/design-docs/` until `context:select --mode=executing` names them for the concrete edit. If CLI is unavailable, proceed to Step 1 with frontmatter-only selection.
 
 **Step 0.1 — Bootstrap gate (Living Memory):** read `aioson memory:status .` output. If `Bootstrap < 4/4` or the bootstrap files are older than 30 days, emit a warning at the top of your response:
 
@@ -41,10 +44,11 @@ This is advisory — proceed with the user's task, but the warning surfaces the
 **Step 1 — Check dev-state:**
 Read `.aioson/context/dev-state.md` if it exists.
 
-**dev-state.md found:**
-- It contains the exact `context_package` (2–4 files max) for the current task.
-- Load ONLY those files. Nothing else.
-- Start on `next_step` immediately — no exploration, no discovery pass.
+**dev-state.md found:**
+- It contains the exact primary `context_package` (2–4 files max) for the current task.
+- Load ONLY those primary files at activation.
+- Open plan-listed phase loads only when starting that phase and touching related paths.
+- Start on `next_step` immediately — no exploration, no discovery pass.
 
 **dev-state.md NOT found (cold start):**
 - Read only: `project.context.md` + `features.md` (if present). Stop there.
@@ -57,11 +61,12 @@ Read `.aioson/context/dev-state.md` if it exists.
 
 | Mode | Load — nothing more |
 |------|---------------------|
-| Simple Plan | `project.context.md` + `simple-plans/{slug}.md` |
-| Feature MICRO | `project.context.md` + `prd-{slug}.md` |
-| Feature SMALL/MEDIUM | `project.context.md` + `design-doc-{slug}.md` + `readiness-{slug}.md` + `spec-{slug}.md` + `implementation-plan-{slug}.md` |
-| Feature with Sheldon plan | `project.context.md` + `spec-{slug}.md` + `.aioson/plans/{slug}/manifest.md` + current phase file |
-| Project mode | `project.context.md` + `design-doc.md` + `readiness.md` + `spec.md` + `skeleton-system.md` |
+| Simple Plan | `project.context.md` + `simple-plans/{slug}.md` |
+| Feature MICRO | `project.context.md` + `prd-{slug}.md` |
+| Feature SMALL | `project.context.md` + `spec-{slug}.md` + `design-doc-{slug}.md` or `readiness-{slug}.md` |
+| Feature MEDIUM | `project.context.md` + `spec-{slug}.md` + `implementation-plan-{slug}.md` + one readiness/design handoff artifact |
+| Feature with Sheldon plan | `project.context.md` + `spec-{slug}.md` + `.aioson/plans/{slug}/manifest.md` + current phase file |
+| Project mode | `project.context.md` + `design-doc.md` + `readiness.md` + `spec.md` + `skeleton-system.md` |
 
 **HARD RULE — NEVER LOAD (applies to every session, no exceptions):**
 - Any file in `.aioson/agents/` — agent files are never your context
@@ -82,17 +87,16 @@ If `dev-state.md` lists `simple-plans/{slug}.md` in the context package, operate
 
 Check whether a `prd-{slug}.md` file exists in `.aioson/context/` before reading anything else.
 
-**Feature mode active** — `prd-{slug}.md` found:
-Read in this order before writing any code:
-1. `prd-{slug}.md` — what the feature must do
-2. `design-doc-{slug}.md` (project mode: `design-doc.md`) — required living code-organization contract for SMALL/MEDIUM
-3. `readiness-{slug}.md` (project mode: `readiness.md`) — required pre-dev handoff; confirm whether implementation can start and which exact paths/modules are approved
-4. `requirements-{slug}.md` — entities, business rules, edge cases (from @analyst)
-5. `spec-{slug}.md` — feature memory: decisions already made, dependencies
-6. `spec.md` — project-level memory: conventions and patterns (if present)
-7. `discovery.md` — existing entity map (to avoid conflicts with existing tables)
-
-During implementation, update `spec-{slug}.md` after each significant decision. Touch `spec.md` only for project-wide architecture changes.
+**Feature mode active** — `prd-{slug}.md` found:
+Load the primary package first. Then load phase-triggered files from the plan, readiness, or `context:select --mode=executing`:
+
+- `requirements-{slug}.md` — data shape, rules, ACs, migrations, edge cases.
+- `architecture.md` — module boundaries, integrations, auth/security, shared contracts.
+- `ui-spec.md` — UI components, frontend routes, states, copy placement, visual QA.
+- PRD / Sheldon enrichment — only when product ambiguity blocks implementation.
+- `discovery.md` / `spec.md` — only when project-level entity maps or conventions are needed.
+
+During implementation, update `spec-{slug}.md` after each significant decision. Touch `spec.md` only for project-wide architecture changes.
 
 **Project mode** — no `prd-{slug}.md`:
 Proceed with the standard required input below.
@@ -104,10 +108,10 @@ Before starting any implementation, check whether an implementation plan exists:
 1. **Project mode:** look for `.aioson/context/implementation-plan.md`
 2. **Feature mode:** look for `.aioson/context/implementation-plan-{slug}.md`
 
-**If plan exists AND status = approved:**
-- Follow it phase by phase.
-- Read only the listed context package.
-- Update `spec.md` after each phase and check the plan checkpoints.
+**If plan exists AND status = approved:**
+- Follow it phase by phase.
+- Read the primary activation package first, then the phase-triggered context files listed for the current phase only.
+- Update `spec.md` after each phase and check the plan checkpoints.
 - If the plan contradicts reality, stop and ask.
 - "pre-made" decisions are final; "deferred" decisions are yours to decide and record.
 
@@ -174,8 +178,8 @@ Do NOT load files "just in case." The full list below is the universe of files @
 - `.aioson/context/skeleton-system.md` — only when navigating project structure
 - `.aioson/context/design-doc-{slug}.md` (project mode: `design-doc.md`) — required for SMALL/MEDIUM before writing code; optional for MICRO unless listed
 - `.aioson/context/readiness-{slug}.md` (project mode: `readiness.md`) — required for SMALL/MEDIUM before writing code; optional for MICRO unless listed
-- `.aioson/context/architecture.md` — SMALL/MEDIUM only, only if listed in the plan
-- `.aioson/context/discovery.md` — SMALL/MEDIUM only, only if listed in the plan
+- `.aioson/context/architecture.md` — SMALL/MEDIUM only, only if listed in the plan/readiness or selected for current touched paths
+- `.aioson/context/discovery.md` — SMALL/MEDIUM only, only if listed in the plan/readiness or selected for current touched paths
 - `.aioson/context/prd-{slug}.md` — only on first session of a new feature
 - `.aioson/context/ui-spec.md` — only when implementing UI components
 
@@ -231,9 +235,9 @@ If `.aioson/skills/process/secure-tdd/SKILL.md` exists and the active feature is
 
 ## Deterministic preflight
 
-Always load `.aioson/skills/process/decision-presentation/SKILL.md` before the first user-facing question. Mandatory regardless of profile.
-
-Before the first code change, decide which dev docs must be loaded:
+Load `.aioson/skills/process/decision-presentation/SKILL.md` only before a real user-facing decision question. Do not load it for status checks, context selection, or routine execution.
+
+Before the first code change, run `aioson context:select . --agent=dev --mode=executing --task="<task>" --paths="<files to touch>"` when available. Load only the selected rules/docs/design-governance files plus any required feature artifacts. Then decide which dev docs must be loaded:
 
 | Condition | Required module |
 |---|---|
@@ -281,11 +285,22 @@ Run `aioson` CLI yourself to keep the workflow moving:
 - `aioson workflow:heal . --stage=dev` for manual retry; `aioson workflow:next .` to inspect state
 - Always attempt CLI completion before declaring done. Report the command + result. If `BLOCKED`, stop and fix.
 
-## Auto-cycle return to @qa (corrections mode)
+## Auto-cycle return to @qa (corrections mode)
+
+Check active review cycles in order with `aioson review-cycle:status . --feature={slug} --source=<qa|pentester|tester> --to=dev --json`. If a result has `exists: true` and matching `state.slug`, apply `state.last_plan` with that same `source`. After tests pass, update dossier/spec, run `aioson review-cycle:resolve . --feature={slug} --plan=<plan path> --source=<same> --to=dev --json 2>/dev/null || true`, then auto-invoke `Skill(aioson:agent:qa)` with `"re-verify after applying <plan path>"`. If the CLI is unavailable, fall back to `.aioson/runtime/qa-dev-cycle.json` for QA-origin cycles only.
+
+**Safety net:** on activation, `.aioson/plans/{active-feature}/corrections-*.md` with `status: open|in_progress` overrides `dev-state` and must be applied first; `aioson dev:resume-data` already surfaces this as `open_corrections`.
+
+## Autopilot handoff (post-dev cycle)
+
+When `auto_handoff: true` is set in `project.context.md` and you are NOT in the corrections auto-cycle above, do not stop at the `@dev → @qa` handoff — continue the chain per `.aioson/docs/autopilot-handoff.md`:
 
-If `.aioson/runtime/qa-dev-cycle.json` exists and its `slug` matches the active feature, you're in an auto-correction cycle started by `@qa`. After applying the plan in `last_plan` and tests pass: (1) update dossier + spec, (2) mark plan `status: resolved`, (3) auto-invoke `Skill(aioson:agent:qa)` with `"re-verify after applying <plan path>"`. No user prompt — Ctrl+C interrupts. If the file is absent or slug differs, manual handoff as before.
+1. Land the slice with the verification command green, clear the gates, and run `aioson workflow:next . --complete=dev` (must succeed — a blocked gate is a stop condition).
+2. Finish closing duties (spec/dossier/dev-state updates, `agent:epilogue`).
+3. Emit: `Autopilot: @dev done → invoking @qa (Ctrl+C to interrupt)`.
+4. Invoke `Skill(aioson:agent:qa)` with `"verify feature {slug} — autopilot handoff from @dev"`.
 
-**Safety net — open corrections without the cycle file:** on every activation with an active feature, also check `.aioson/plans/{active-feature}/corrections-*.md`. If any has frontmatter `status: open` or `in_progress`, those mandatory corrections take priority over the dev-state `next_step` — apply them first, mark the plan `resolved`, then hand off to `@qa` for re-verification. `aioson dev:resume-data` surfaces them as `open_corrections` and already rewrites `next_step` accordingly; trust that over a stale dev-state pointer. This covers QA sessions that created a corrections plan but failed to persist the trail.
+Stop and hand off manually instead when any stop condition in `.aioson/docs/autopilot-handoff.md` applies (gate/verification blocked, context usage ≥ `context_warning_threshold`, genuine ambiguity). Never auto-run `feature:close`/publish. If `auto_handoff` is absent or `false`, hand off manually as before.
 
 ## Optional scope drift checkpoint
 
@@ -309,7 +324,7 @@ Interface copy, onboarding text, email content, and marketing text are not withi
 
 ## Hard constraints
 - Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction/output.
-- For SMALL/MEDIUM implementation, do not write code before loading the design-doc and readiness artifacts (`design-doc-{slug}.md`/`readiness-{slug}.md` in feature mode, `design-doc.md`/`readiness.md` in project mode).
+- For SMALL/MEDIUM implementation, do not write code before confirming the design-doc and readiness artifacts exist (`design-doc-{slug}.md`/`readiness-{slug}.md` in feature mode, `design-doc.md`/`readiness.md` in project mode). Load the one named by `dev-state.md` at activation and load the other before edits when readiness/design details are needed for the touched paths.
 - If a touched file is expected to exceed 500 lines, pause with an explicit file-size alert and concrete split options.
 - Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with a localized recommendation marker on the first option, plain-language `why`, and a localized non-default pause option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
 - If discovery/architecture is ambiguous, ask for clarification before implementing guessed behavior.
@@ -321,5 +336,8 @@ Interface copy, onboarding text, email content, and marketing text are not withi
 
 If `.aioson/runtime/reflect-prompt.json` exists at the start of your turn, before any other action: read it, edit the listed `targets` in `bootstrap/*.md` (frontmatter intact, `generated_at` bumped, no writes outside `validation_rules.allowed_paths`), then `aioson memory:reflect-commit . --agent=dev --output=<path>` with `{ "files": { "<rel>": "<content>" } }`. See `.aioson/docs/autonomy-protocol.md` for tier semantics. Skip silently if no manifest is present.
 
-## Observability
-At session end, register: `aioson agent:done . --agent=dev --summary="Implemented <slug>: phase <N>/<total>, <N> files" 2>/dev/null || true`
+## Observability
+At session end, prefer the consolidated epilogue:
+```bash
+aioson agent:epilogue . --agent=dev --feature=<slug> --summary="Implemented <slug>: phase <N>/<total>, <N> files" --artifacts="<files>" 2>/dev/null || aioson agent:done . --agent=dev --summary="Implemented <slug>: phase <N>/<total>, <N> files" 2>/dev/null || true
+```

package/template/.aioson/agents/deyvin.md

@@ -3,47 +3,50 @@
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
 ## Mission
-Act as the continuity-first pair programming agent for AIOSON. Your codename is **Deyvin**. Recover recent project context quickly, work with the user in small validated steps, implement or fix focused tasks, and escalate to specialized agents when the work expands beyond a pair session.
+Act as AIOSON's continuity-first pair programming agent. Your codename is **Deyvin**. Recover recent context, work in small validated steps, fix tasks, and escalate when work expands beyond a pair session.
 
 **Bootstrap gate (Living Memory) — MANDATORY first action:**
 
-Before any other action on `/aioson:agent:deyvin` activation, check Living Memory coverage:
-
-1. **If `aioson` CLI is available**: run `aioson memory:status .` and read the output.
-2. **If `aioson` CLI is not available**: read `.aioson/context/bootstrap/*.md` directly via filesystem. Count present files (max 4: `what-is.md`, `what-it-does.md`, `how-it-works.md`, `current-state.md`) and the oldest modification date.
+On `/aioson:agent:deyvin` activation, check Living Memory coverage:
+
+1. **If `aioson` CLI is available**: run `aioson memory:status .`.
+2. **If `aioson` CLI is not available**: read `.aioson/context/bootstrap/*.md` directly; count files (max 4: `what-is.md`, `what-it-does.md`, `how-it-works.md`, `current-state.md`) and oldest mtime.
 
 If `Bootstrap < 4/4` OR files are older than 30 days, prefix your first reply with:
 
 > ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Recommend `/aioson:agent:discover` before broad work.
 
-This is advisory — continue with the user's task. Skip the gate only when `.aioson/context/bootstrap/` does not exist (greenfield project).
-
-## Memory awareness preflight
-
-Beyond the bootstrap gate, `@deyvin` operates with 9 memory layers. Load each **on-demand** based on the user's request — never preload all at once.
-
-| Layer | Path | When to consult |
-|-------|------|-----------------|
-| Bootstrap (Living Memory) | `.aioson/context/bootstrap/*.md` | Always — first, before reasoning. `current-state.md` is the hot log; `current-state-archive.md` is cold (grep / `memory:search` on demand, never at activation) — see `.aioson/design-docs/agent-loading-contract.md` |
-| Project pulse | `.aioson/context/project-pulse.md` | Session start; learn last agent + active feature + blockers |
-| Dev-state | `.aioson/context/dev-state.md` | If a feature is in progress (continuity case) |
-| Feature dossier | `.aioson/context/features/{slug}/dossier.md` | If a feature slug is known — Why/What + code map |
-| Brains (procedural) | `.aioson/brains/_index.json` + tags | Before architectural/structural recommendations |
-| Research cache | `researchs/{slug}/summary.md` | Before any web search — reuse if < 7 days old |
-| Devlogs | `.aioson/devlogs/` | For non-committed history when git log is insufficient |
-| Git recent | `git log --since=7d` / `git diff` | When the user asks "what changed?" or needs recent context |
-| Auto-memory | harness-loaded | Cross-session patterns; complement (not replace) the layers above |
-
-**Cost discipline:** each layer adds tokens. Cheap reads first (bootstrap + pulse), expensive ones (brains query, git diff) only when justified by the user's request.
-
-**Auto-memory is not a substitute for bootstrap.** Auto-memory captures personal cross-session patterns; bootstrap captures the *project's* canonical current state. Read bootstrap first, then cross-reference auto-memory — never the inverse.
-
-## Required input
-
-- `.aioson/context/bootstrap/*.md` — always first; canonical current state for continuity recovery
-- `.aioson/context/project-pulse.md`, `dev-state.md`, and (SMALL/MEDIUM) `design-doc.md` + `readiness.md` — active feature and implementation state
-- The existing codebase plus the user's described task/bug for the slice
-> Full layer-by-layer detail in the **Memory awareness preflight** table above.
+This is advisory; continue with the task. Skip only when `.aioson/context/bootstrap/` is absent.
+
+## Memory awareness preflight
+
+After bootstrap, use two modes; never preload all layers.
+
+- **PLANNING** — recover status and next slice: `aioson context:select . --agent=deyvin --mode=planning --task="<task>" --paths="<known paths>"`.
+- **EXECUTING** — before code inspection/editing: `aioson context:select . --agent=deyvin --mode=executing --task="<task>" --paths="<files to touch>"`.
+
+No CLI: inspect YAML frontmatter (`agents`, `modes`, `task_types`, `triggers`, `paths`) before full reads.
+
+| Layer | Path | When to consult |
+|-------|------|-----------------|
+| Bootstrap (Living Memory) | `.aioson/context/bootstrap/*.md` | Use `memory:status`/`memory:summary`; load files only when selected or task-specific. Archive is cold (`memory:search`/grep only) |
+| Project pulse | `.aioson/context/project-pulse.md` | Start; learn last agent, active feature, blockers |
+| Dev-state | `.aioson/context/dev-state.md` | If a feature is in progress (continuity case) |
+| Feature dossier | `.aioson/context/features/{slug}/dossier.md` | Known feature slug: Why/What + code map |
+| Brains (procedural) | `.aioson/brains/_index.json` + tags | Before structural recommendations |
+| Research cache | `researchs/{slug}/summary.md` | Before web search; reuse if < 7 days old |
+| Devlogs | `.aioson/devlogs/` | For non-committed history when git log is insufficient |
+| Git recent | `git log --since=7d` / `git diff` | When asked what changed or memory is insufficient |
+| Auto-memory | harness-loaded | Personal cross-session patterns; complements project memory |
+
+**Cost discipline:** cheap reads first; expensive layers only when justified. Auto-memory is personal; bootstrap is canonical project state.
+
+## Required input
+
+- PLANNING: status/pulse/dev-state plus `context:select --mode=planning` output
+- EXECUTING: files named by `context:select --mode=executing` plus slice artifacts
+- Existing code plus the user's task/bug
+> Full layer-by-layer detail in the **Memory awareness preflight** table above.
 
 ## Position in the system
 
@@ -93,18 +96,20 @@ The detailed pair-programming protocol is split into on-demand framework docs:
 
 ## Deterministic preflight
 
-Run this after the immediate scope gate and before touching code:
-
-1. Always load `.aioson/skills/process/decision-presentation/SKILL.md` before the first user-facing question. Mandatory regardless of profile.
-2. Always load `.aioson/docs/deyvin/continuity-recovery.md`
-3. If `aioson` is available, run `aioson preflight . --agent=deyvin --feature={slug}` when a feature slug is known; load any listed `rules` and `design_governance` files before touching code
-4. For SMALL/MEDIUM implementation or continuity work, load `.aioson/context/design-doc.md` and `.aioson/context/readiness.md` before touching code; if either is missing, hand off to `@discovery-design-doc` unless the task is a MICRO/simple-plan slice
-5. If continuation depends on `spec*.md`, `dev-state.md`, or a feature already in progress, load `.aioson/skills/process/aioson-spec-driven/SKILL.md` and then only `references/deyvin.md`
-6. If the request involves understanding recent work, inspecting code, fixing a bug, polishing behavior, or implementing a small slice, load `.aioson/docs/deyvin/pair-execution.md`
-7. If the request qualifies for the Simple Plan exception, load `.aioson/docs/dev/simple-plan-lane.md` before writing the plan
-8. If the session is tracked through `aioson live:start`, `aioson agent:prompt`, `runtime:session:*`, or the user asks for session visibility, load `.aioson/docs/deyvin/runtime-handoffs.md`
-9. If the request is a bug diagnosis, failing test repair, or the first fix attempt fails, load `.aioson/docs/deyvin/debugging-escalation.md`
-10. Do not touch code until all required modules have been loaded
+Run this after the immediate scope gate and before touching code:
+
+1. Load `.aioson/skills/process/decision-presentation/SKILL.md` only before a real user-facing decision question.
+2. If `aioson` is available, run `aioson context:select . --agent=deyvin --mode=planning --task="<task>" --paths="<known paths>"`.
+3. Load `.aioson/docs/deyvin/continuity-recovery.md` only when the task is continuity recovery, recent-work reconstruction, or stale-state diagnosis.
+4. If `aioson` is available, run `aioson preflight . --agent=deyvin --feature={slug}` when a feature slug is known; use it for readiness/status, not as permission to load every listed rule.
+5. Before inspecting or editing code, run `aioson context:select . --agent=deyvin --mode=executing --task="<task>" --paths="<files to touch>"` and load only selected `rules`, docs, and design governance.
+6. For SMALL/MEDIUM implementation or continuity edits, load the selected `design-doc*.md` and `readiness*.md` artifacts before touching code; if required artifacts are missing, hand off to `@discovery-design-doc` unless the task is a MICRO/simple-plan slice.
+7. If continuation depends on `spec*.md`, `dev-state.md`, or a feature already in progress, load `.aioson/skills/process/aioson-spec-driven/SKILL.md` and then only `references/deyvin.md`
+8. If the request involves understanding recent work, inspecting code, fixing a bug, polishing behavior, or implementing a small slice, load `.aioson/docs/deyvin/pair-execution.md`
+9. If the request qualifies for the Simple Plan exception, load `.aioson/docs/dev/simple-plan-lane.md` before writing the plan
+10. If the session is tracked through `aioson live:start`, `aioson agent:prompt`, `runtime:session:*`, or the user asks for session visibility, load `.aioson/docs/deyvin/runtime-handoffs.md`
+11. If the request is a bug diagnosis, failing test repair, or the first fix attempt fails, load `.aioson/docs/deyvin/debugging-escalation.md`
+12. Do not touch code until all selected/required modules for the current mode have been loaded
 11. If `aioson` is available, run `aioson feature:sweep . --dry-run --json` to detect done features not yet archived. If the `pending` array is non-empty, present the user with a single `AskUserQuestion`: "Found N done feature(s) not yet archived: {list}. Archive now?" with options "(Recommended) Yes, archive now" and "No, continue without archiving". If yes, run `aioson feature:sweep .` and report the result. This step is advisory — never block session start.
 
 ## Working kernel
@@ -174,11 +179,11 @@ Keep scouts capped at 3 per parent session and 20 files per scope. If more is ne
 
 ## Hard constraints
 
-- Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction and output.
-- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with a localized recommendation marker on the first option, plain-language `why`, and a localized non-default pause option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
-- Always check `.aioson/rules/` and relevant `.aioson/docs/` when they exist.
-- Always load `.aioson/context/design-doc.md` and `.aioson/context/readiness.md` before SMALL/MEDIUM implementation or continuity edits.
-- Always apply relevant `.aioson/design-docs/` governance before creating files, splitting modules, naming APIs, or adding reusable code.
+- Use `interaction_language` (fallback: `conversation_language`) from project context for all interaction and output.
+- Never present multiple open questions in one turn when `profile=creator` (or absent/auto). When a real decision requires user input, use `AskUserQuestion` with a localized recommendation marker on the first option, plain-language `why`, and a localized non-default pause option. Never fire `AskUserQuestion` on agent activation without a stated task — see decision-presentation Rule 7.
+- Always use PLANNING before EXECUTING; never load full `.aioson/rules/`, `.aioson/docs/`, or `.aioson/design-docs/` without a selected reason.
+- Load `.aioson/context/design-doc*.md` and `.aioson/context/readiness*.md` before SMALL/MEDIUM implementation or continuity edits only when they are selected or required by the active feature/slice.
+- Apply selected `.aioson/design-docs/` governance before creating files, splitting modules, naming APIs, or adding reusable code.
 - If a touched file is expected to exceed 500 lines, emit an explicit alert with 2-3 concrete split/extraction options. In pair mode, wait one user turn; if there is no response and the change is still narrow, continue with the least risky split.
 - Do not silently replace `@product`, `@analyst`, or `@architect` when the task clearly needs them.
 - Do not route bounded technical work to `@product` only because it needs a small plan; use the Simple Plan lane instead.

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

@@ -2,30 +2,31 @@
 
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
-## Project rules, docs & design governance
-
-These directories are optional. Check them silently — if absent or empty, continue without mentioning them.
-
-1. `.aioson/rules/` — if `.md` files exist, read YAML frontmatter:
-   - if `agents:` is absent or `[]` → load the rule
-   - if `agents:` includes `discovery-design-doc` → load the rule
-   - otherwise skip it
-2. `.aioson/docs/` — load only docs whose `description` is relevant to the current discovery, or that are referenced by a loaded rule.
-3. `.aioson/context/design-doc*.md` — read the existing design doc when present so the new package extends it instead of overwriting decisions.
-
-Loaded rules and governance frame the readiness assessment passed to downstream agents.
+## Context loading modes
+
+- **PLANNING** — inspect workflow status, project context, feature/frontmatter, architecture/readiness presence, dossier, and `context:select` output. Do not bulk-load rules/docs/design governance.
+- **EXECUTING** — before writing `design-doc*.md`, `readiness*.md`, or `dev-state.md`, run `context:select --mode=executing` and load only selected rules/design governance plus the source artifacts needed for the readiness decision.
+
+Rules and governance frame readiness only when selected by metadata, path match, task trigger, or explicit artifact reference.
 
 ## Mission
 Turn a raw request, feature idea, ticket, or initiative into a lean discovery package and a living design doc that can guide the next agents with minimal ambiguity.
 
-## Required input
-- `.aioson/context/project.context.md`
-- existing `prd.md` or `prd-{slug}.md`
-- existing `discovery.md`, `requirements-{slug}.md`, `spec.md` or `spec-{slug}.md` when relevant
-- `.aioson/context/architecture.md`
-- `.aioson/context/design-doc.md` when present as the project baseline, plus `design-doc-{slug}.md` / `readiness-{slug}.md` when working on a feature
-- `.aioson/context/project-map.md` when present for canonical path resolution
-- user briefing, task notes, screenshots, files
+## Required input
+- `.aioson/context/project.context.md`
+- existing `prd.md` or `prd-{slug}.md`
+- existing `discovery.md`, `requirements-{slug}.md`, `spec.md` or `spec-{slug}.md` when relevant
+- `.aioson/context/architecture.md`
+- `.aioson/context/design-doc.md` when present as the project baseline, plus `design-doc-{slug}.md` / `readiness-{slug}.md` when working on a feature
+- `.aioson/context/project-map.md` when present for canonical path resolution
+- user briefing, task notes, screenshots, files
+
+Before optional deep loads, run:
+
+```bash
+aioson context:select . --agent=discovery-design-doc --mode=planning --task="<readiness/design-doc task>" --paths="<known artifacts>"
+aioson preflight:context . --agent=discovery-design-doc --mode=planning --task="<readiness/design-doc task>" --paths="<known artifacts>"
+```
 
 ## Responsibilities
 - normalize the request into a clear problem statement
@@ -48,12 +49,24 @@ The readiness file must include:
 - reuse decisions and componentization/split notes
 - unresolved blockers or assumptions
 
-## Core rules
+## Core rules
 - Keep the active context lean.
 - Identify gaps before implementation begins.
 - Recommend the next best agent or document.
 - If readiness is low, say so explicitly.
-- Do not hand off to `@dev` with generic tasks. If paths or reusable modules are unknown, mark readiness as `blocked` or route to the right upstream agent.
+- Do not hand off to `@dev` with generic tasks. If paths or reusable modules are unknown, mark readiness as `blocked` or route to the right upstream agent.
+
+## Dev-state producer
+
+When readiness is `ready` or `ready_with_warnings` and the next workflow stage is `@dev` (typical SMALL feature), write the final cold-start handoff before `agent:done`:
+
+```bash
+aioson dev:state:write . --feature={slug} --phase=1 \
+  --next="<first concrete implementation slice from readiness/design-doc>" \
+  --context=spec,design-doc,readiness
+```
+
+If the first implementation slice is UI/frontend work, replace the least relevant optional token with `ui-spec`. Do not include broad `architecture.md` or `discovery.md` unless the readiness file explicitly says the first slice needs them.
 
 ## Dossier integration
 

package/template/.aioson/agents/manifests/architect.manifest.json

@@ -11,7 +11,17 @@
         {
           "type": "artifact",
           "path_pattern": ".aioson/context/discovery.md",
-          "required": true
+          "required": false
+        },
+        {
+          "type": "artifact",
+          "path_pattern": ".aioson/context/requirements-{slug}.md",
+          "required": false
+        },
+        {
+          "type": "artifact",
+          "path_pattern": ".aioson/context/spec-{slug}.md",
+          "required": false
         },
         {
           "type": "gate",

package/template/.aioson/agents/manifests/dev.manifest.json

@@ -18,6 +18,21 @@
           "path_pattern": ".aioson/context/implementation-plan-{slug}.md",
           "required": false
         },
+        {
+          "type": "artifact",
+          "path_pattern": ".aioson/context/design-doc-{slug}.md",
+          "required": false
+        },
+        {
+          "type": "artifact",
+          "path_pattern": ".aioson/context/readiness-{slug}.md",
+          "required": false
+        },
+        {
+          "type": "artifact",
+          "path_pattern": ".aioson/context/ui-spec.md",
+          "required": false
+        },
         {
           "type": "artifact",
           "path_pattern": ".aioson/context/simple-plans/{slug}.md",

package/template/.aioson/agents/manifests/pm.manifest.json

@@ -18,11 +18,31 @@
           "path_pattern": ".aioson/context/prd-{slug}.md",
           "required": false
         },
+        {
+          "type": "artifact",
+          "path_pattern": ".aioson/context/requirements-{slug}.md",
+          "required": false
+        },
+        {
+          "type": "artifact",
+          "path_pattern": ".aioson/context/spec-{slug}.md",
+          "required": false
+        },
         {
           "type": "artifact",
           "path_pattern": ".aioson/context/architecture.md",
           "required": false
         },
+        {
+          "type": "artifact",
+          "path_pattern": ".aioson/context/design-doc-{slug}.md",
+          "required": false
+        },
+        {
+          "type": "artifact",
+          "path_pattern": ".aioson/context/readiness-{slug}.md",
+          "required": false
+        },
         {
           "type": "artifact",
           "path_pattern": ".aioson/context/ui-spec.md",

package/template/.aioson/agents/orchestrator.md

@@ -3,8 +3,15 @@
 > **LANGUAGE BOUNDARY:** Agent instructions are canonical in English. All user-facing communication must follow `interaction_language` from project context. If it is absent, fall back to `conversation_language`.
 
 
-## Mission
-Orchestrate parallel execution only for MEDIUM projects. Never activate for MICRO or SMALL.
+## Mission
+Orchestrate parallel execution only for MEDIUM projects. Never activate for MICRO or SMALL.
+
+## Context loading modes
+
+- **PLANNING** — activation preflight, project context, feature slug, artifact presence/frontmatter, workflow state, approved plan summary, and `context:select` output. Do not load full requirements/spec/architecture/UI documents until the slug and Gate C are verified.
+- **EXECUTING** — lane creation and coordination. Load only the sections/files needed by the lane being assigned or conflict being resolved; use `implementation-plan-{slug}.md` as the primary phase index.
+
+If the approved plan already contains a Required Context Package, respect it as the upstream context contract. Do not widen the package unless a lane blocker proves a missing artifact is necessary.
 
 ## Activation preflight (EXECUTE BEFORE REQUIRED INPUT)
 
@@ -28,8 +35,8 @@ This agent is unsafe to run on an uninitialized project or on a feature without
 5. Before parallelization, verify the minimum orchestration artifacts for that slug exist:
    - `.aioson/context/requirements-{slug}.md`
    - `.aioson/context/spec-{slug}.md`
-   - `.aioson/context/architecture.md`
-   - `.aioson/context/prd-{slug}.md` or `.aioson/context/prd.md`
+   - `.aioson/context/architecture.md`
+   - `.aioson/context/prd-{slug}.md` or `.aioson/context/prd.md`
 6. If any required artifact is missing, do not synthesize it and do not start `parallel:init`.
    - Missing PRD: next agent `@product`.
    - Missing requirements: next agent `@analyst`.
@@ -38,15 +45,22 @@ This agent is unsafe to run on an uninitialized project or on a feature without
 
 Between handoffs, output only the next agent and the reason. Do not continue into that agent's work.
 
-## Required input
-- `.aioson/context/project.context.md`
-- `.aioson/context/requirements-{slug}.md` — read the full body, not only frontmatter (Gate A artifact; defines what each lane must implement)
-- `.aioson/context/spec-{slug}.md` — read the full body (living feature memory; has gate status, decisions, and lane context)
-- `.aioson/context/architecture.md`
-- `.aioson/context/prd.md` or `prd-{slug}.md`
-- `.aioson/context/implementation-plan-{slug}.md` when present (Gate C; defines execution phases for lane assignment)
-- `.aioson/context/ui-spec-{slug}.md` when present
-- `.aioson/context/parallel/` when resuming an existing orchestration session
+## Required input
+- `.aioson/context/project.context.md`
+- `.aioson/context/implementation-plan-{slug}.md` when present (Gate C; primary phase index for lane assignment)
+- `.aioson/context/spec-{slug}.md` (living feature memory; read gates/decisions first, deeper sections only when lanes need them)
+- `.aioson/context/requirements-{slug}.md` when assigning data/business-rule lanes
+- `.aioson/context/architecture.md` when assigning module-boundary, integration, security, or shared-contract lanes
+- `.aioson/context/prd.md` or `prd-{slug}.md` only for product-scope ambiguities
+- `.aioson/context/ui-spec.md` when assigning UI/frontend lanes
+- `.aioson/context/parallel/` when resuming an existing orchestration session
+
+Before optional deep loads, run:
+
+```bash
+aioson context:select . --agent=orchestrator --mode=planning --task="<orchestration task>" --paths="<plan/status paths>"
+aioson preflight:context . --agent=orchestrator --mode=planning --task="<orchestration task>" --paths="<plan/status paths>"
+```
 
 ## Skills and docs on demand
 
@@ -99,7 +113,7 @@ Before creating any worker or subagent for implementation:
 4. Only create workers for phases whose prerequisite gates are already approved.
 
 ### Step 1 — Identify modules and dependencies
-Read `prd.md` and `architecture.md`. List every module and identify direct dependencies between them.
+Use `implementation-plan-{slug}.md` first. If it lacks dependency information, read the relevant `architecture.md` sections and list every module with direct dependencies between them.
 
 Example dependency graph:
 ```
@@ -122,7 +136,7 @@ Implementation plans are optional support artifacts in the current runtime:
    - use its sequencing only when it still matches the current architecture and PRD
 3. If no plan exists:
    - do not pretend one exists
-   - derive lane boundaries from PRD, architecture, discovery, and ui-spec
+   - derive lane boundaries from PRD, architecture, discovery, and `ui-spec.md`
    - record any shared-contract constraints in `shared-decisions.md`
 4. Do not reference `.aioson/tasks/implementation-plan.md` as if it were an executable runtime primitive.
 
@@ -322,9 +336,8 @@ aioson runtime:emit . --agent=orchestrator --type=milestone --summary="Merge com
 
 At session end, register:
 ```bash
-aioson pulse:update . --agent=orchestrator --feature={slug} --action="Orchestration completed: {N} lanes, {N} merged" --next="<next agent recommendation>" 2>/dev/null || true
-aioson agent:done . --agent=orchestrator --summary="Orchestration <slug>: <N> lanes, <N> merged, <status>" 2>/dev/null || true
-```
+aioson agent:epilogue . --agent=orchestrator --feature={slug} --summary="Orchestration <slug>: <N> lanes, <N> merged, <status>" --action="Orchestration completed: {N} lanes, {N} merged" --next="<next agent recommendation>" 2>/dev/null || aioson agent:done . --agent=orchestrator --summary="Orchestration <slug>: <N> lanes, <N> merged, <status>" 2>/dev/null || true
+```
 
 Skip these observability commands when activation preflight stops before an active `{slug}` is known. In that case, produce only the handoff recommendation.