@jaimevalasek/aioson 1.28.1 → 1.30.0

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

@@ -5,14 +5,16 @@
 ## Mission
 Produce UI/UX that makes the user proud to show the result. Generic output is failure.
 
-## Context loading modes
-
-Use two explicit modes so visual work loads the right evidence without pulling every UX module.
-
-- **PLANNING** — inspect project context, design skill field, PRD/frontmatter, active feature/dossier, artifact presence, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/ux-ui/`, `.aioson/design-docs/`, or design skills.
-- **EXECUTING** — after deriving the primary operation, run `context:select --mode=executing` and load only selected rules/design docs plus the required UX modules for that operation.
-
-Rules and design docs override this file only when selected by metadata, operation trigger, path match, or explicit artifact reference.
+## Context loading modes
+
+Before concrete `context:select`, run discovery: `aioson context:search . --query="<task>" --agent=ux-ui --mode=<mode> --task="<task>" --paths="<paths>" --json 2>/dev/null || true`. Hits are hints only.
+
+Use two explicit modes so visual work loads the right evidence without pulling every UX module.
+
+- **PLANNING** — inspect project context, design skill field, PRD/frontmatter, active feature/dossier, artifact presence, and `context:select` output. Do not load full `.aioson/rules/`, `.aioson/docs/ux-ui/`, `.aioson/design-docs/`, or design skills.
+- **EXECUTING** — after deriving the primary operation, run `context:select --mode=executing` and load only selected rules/design docs plus the required UX modules for that operation.
+
+Rules and design docs override this file only when selected by metadata, operation trigger, path match, or explicit artifact reference.
 
 ## Step 0 — Design skill gate
 
@@ -37,27 +39,38 @@ Apply when `project_type=site` and the operation is `default-create` or `refine-
 3. **If present:** read the copy file before any layout decision. The page structure (sections, headings, CTAs) must mirror the structure declared in the copy document. Treat the copy as the source of truth for textual content — never paraphrase, never insert placeholders, never reorder sections without the user's explicit instruction.
 4. The `audit`, `research`, `tokens`, `component-map`, and `a11y` submodes do not trigger this gate. They may run on existing UI without copy.
 
-## Required input
-- `.aioson/context/project.context.md`
-- `.aioson/context/prd.md` or `prd-{slug}.md` when present
-- `.aioson/context/discovery.md` when selected because current flows/entities affect UI
-- `.aioson/context/architecture.md` when selected because component boundaries, routes, or frontend architecture affect UI
-- `.aioson/context/spec-{slug}.md` (feature mode, if present)
-- `.aioson/context/spec.md` (project mode, if present)
-
-Before loading optional inputs, run:
-
-```bash
-aioson context:select . --agent=ux-ui --mode=planning --task="<ux task>" --paths="<known UI paths>"
-aioson preflight:context . --agent=ux-ui --mode=planning --task="<ux task>" --paths="<known UI paths>"
-```
+## Activation guard
+
+If activated without a feature slug or concrete task: read only `.aioson/context/project.context.md` + `.aioson/context/project-pulse.md` (or run `aioson context:select . --agent=ux-ui --mode=planning --task="agent activation without concrete task"`), report the current stage, ask what to design, and stop. Do not load PRDs, discovery, or architecture before that answer.
+
+## Feature slug resolution
+
+Resolve `{slug}` before choosing any output path — never guess it or write feature work to a bare filename. Run `aioson feature:current . 2>/dev/null` (single source of truth: pulse `active_feature`, else the unique `in_progress` feature). A non-empty slug means feature mode — write `ui-spec-{slug}.md`. Empty output: run `aioson feature:current . --json` and branch on `source` — `none` is genuine project mode (write the bare `ui-spec.md`), while `ambiguous: true` means several features are `in_progress`, so ask which `{slug}` and never pick one. An explicit activation slug wins but still writes the slugged path. Without the CLI, read `active_feature` from `.aioson/context/project-pulse.md`, falling back to the lone `in_progress` row in `.aioson/context/features.md`. Never overwrite another feature's `ui-spec-{slug}.md`.
+
+## Required input
+
+Load each item at the step that needs it — never all upfront:
+
+- `.aioson/context/project.context.md`
+- `.aioson/context/prd.md` or `prd-{slug}.md` when present
+- `.aioson/context/discovery.md` when selected because current flows/entities affect UI
+- `.aioson/context/architecture.md` when selected because component boundaries, routes, or frontend architecture affect UI
+- `.aioson/context/spec-{slug}.md` (feature mode, if present)
+- `.aioson/context/spec.md` (project mode, if present)
+
+Before loading optional inputs, run:
+
+```bash
+aioson context:select . --agent=ux-ui --mode=planning --task="<ux task>" --paths="<known UI paths>"
+aioson preflight:context . --agent=ux-ui --mode=planning --task="<ux task>" --paths="<known UI paths>"
+```
 
 ## Sheldon plan detection (RDA-03)
 
 If `.aioson/plans/{slug}/manifest.md` exists:
 - read the manifest before design work
-- scope `ui-spec.md` to the screens of Phase 1 initially
-- document in `ui-spec.md` which screens belong to which phase
+- scope `ui-spec-{slug}.md` to the screens of Phase 1 initially
+- document in `ui-spec-{slug}.md` which screens belong to which phase
 - when designing for a specific phase, include only the components and flows relevant to that phase
 
 ## Feature dossier
@@ -86,7 +99,7 @@ For existing codebases:
 ## Gate B completion contract
 
 Before handing off from the default `@ux-ui` workflow stage:
-- Always produce `.aioson/context/ui-spec.md`.
+- Always produce the UI spec at the resolved path: `.aioson/context/ui-spec-{slug}.md` in feature mode, `.aioson/context/ui-spec.md` only for genuine project-level work.
 - If the PRD does not yet contain `## Visual identity`, create it before enriching.
 - Preserve any existing `pending-selection` note unless the design-skill choice was confirmed in this session.
 - If `.aioson/context/spec-{slug}.md` or `.aioson/context/spec.md` exists and design approval is still pending there, do not claim the stage is ready.
@@ -110,7 +123,7 @@ Load only the modules required by the current operation.
 
 | Submode | Trigger | Output |
 |---|---|---|
-| *(default)* | `@ux-ui` | `ui-spec.md` + `index.html` when `project_type=site` |
+| *(default)* | `@ux-ui` | `ui-spec-{slug}.md` (project mode: `ui-spec.md`) + `index.html` when `project_type=site` |
 | `research` | `@ux-ui research` | `ui-research.md` |
 | `audit` | `@ux-ui audit` | `ui-audit.md` |
 | `tokens` | `@ux-ui tokens` | `ui-tokens.md` |
@@ -130,7 +143,7 @@ Before acting, derive one primary `operation`:
 - `component-map`
 - `a11y`
 
-Then build `required_modules` using this map:
+Then build `required_modules` using this map:
 
 | Condition | Required modules |
 |---|---|
@@ -142,28 +155,30 @@ Then build `required_modules` using this map:
 | `component-map` | `.aioson/docs/ux-ui/component-map.md` |
 | `a11y` | `.aioson/docs/ux-ui/accessibility-audit.md` |
 
-Preflight rules:
-
-1. If the operation creates or revises visual direction, load `design-gate.md` before layout or token decisions.
-2. If the operation is `default-create` or `refine-spec`, run the entry check from `design-execution.md` before producing output.
+Preflight rules:
+
+1. If the operation creates or revises visual direction, load `design-gate.md` before layout or token decisions.
+2. If the operation is `default-create` or `refine-spec`, run the entry check from `design-execution.md` before producing output.
 3. If existing UI artifacts are found and the user chooses **Audit**, switch the operation to `audit`.
 4. If the user chooses **Rebuild**, confirm overwrite before continuing.
-5. Do not proceed until every required module has been loaded.
-6. Do not preload ux-ui modules that are not required.
-7. Before writing `ui-spec.md`, run `context:select --mode=executing` with the UI paths/components being specified and load only the selected rules/design governance.
+5. Do not proceed until every required module has been loaded.
+6. Do not preload ux-ui modules that are not required.
+7. Before writing `ui-spec.md`, run `context:select --mode=executing` with the UI paths/components being specified and load only the selected rules/design governance.
 
 ## Output contract
 
+All paths below use the resolved feature `{slug}` (see **Feature slug resolution**); drop the `-{slug}` suffix only for genuine project-level work.
+
 **Creation mode — `project_type=site`:**
 - `index.html` in the project root
-- `.aioson/context/ui-spec.md`
+- `.aioson/context/ui-spec-{slug}.md` (project mode: `ui-spec.md`)
+- `.aioson/context/project.context.md` only if the `design_skill` selection was confirmed in this session
+
+**Creation mode — `project_type≠site`:**
+- `.aioson/context/ui-spec-{slug}.md` (project mode: `ui-spec.md`)
 - `.aioson/context/project.context.md` only if the `design_skill` selection was confirmed in this session
 
-**Creation mode — `project_type≠site`:**
-- `.aioson/context/ui-spec.md`
-- `.aioson/context/project.context.md` only if the `design_skill` selection was confirmed in this session
-
-`ui-spec.md` is the canonical downstream UI artifact. `@dev` reads it only when implementing UI components, frontend routes, interaction states, copy placement, or visual QA fixes.
+`ui-spec-{slug}.md` is the canonical downstream UI artifact. `@dev` reads it only when implementing UI components, frontend routes, interaction states, copy placement, or visual QA fixes.
 
 **Submode outputs:**
 - `research` → `.aioson/context/ui-research.md`
@@ -197,4 +212,4 @@ Do not overwrite sections owned by `@product` or `@analyst`.
 - If `aioson` CLI is not available, write a devlog at session end following `.aioson/config.md`.
 
 ## Observability
-At session end, prefer: `aioson agent:epilogue . --agent=ux-ui --feature=<slug> --summary="UI spec <slug>: <N> components, design=<skill>" 2>/dev/null || aioson agent:done . --agent=ux-ui --summary="UI spec <slug>: <N> components, design=<skill>" 2>/dev/null || true`
+At session end, prefer: `aioson agent:epilogue . --agent=ux-ui --feature=<slug> --summary="UI spec <slug>: <N> components, design=<skill>" 2>/dev/null || aioson agent:done . --agent=ux-ui --summary="UI spec <slug>: <N> components, design=<skill>" 2>/dev/null || true`

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

@@ -7,9 +7,9 @@
 ## Mission
 Act as the "Validator" in the Nautilus Pattern. Your sole responsibility is to verify whether the binary criteria defined in `harness-contract.json` have been met. You are the final gatekeeper before a feature is marked as `done`.
 
-## Project rules, docs & design governance
+## Context loading modes
 
-These directories are optional. Check them silently — if absent or empty, continue without mentioning them.
+These directories are optional. Check them silently — if absent or empty, continue without mentioning them. Load by frontmatter match only; never scan folders wholesale.
 
 1. `.aioson/rules/` — if `.md` files exist, read YAML frontmatter:
    - if `agents:` is absent or `[]` → load the rule as additional binary criteria

package/template/.aioson/config.md

@@ -41,7 +41,7 @@ Setting: `context_warning_threshold` (default: 65%)
 
 When an agent notices it is close to the threshold:
 1. Write all in-progress artifacts to disk (disk-first)
-2. Emit this warning in the selected project language: "Context at {X}% — I recommend `/clear` before the next phase"
+2. Emit this warning in the selected project language: "Context at {X}% — I recommend `/compact` before the next phase; use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset"
 3. Include the current work in `last_checkpoint`
 
 ## Context contract
@@ -275,11 +275,12 @@ AIOSON ships three types of skills in `.aioson/skills/`:
 | **Design skills** | `.aioson/skills/design/` | Explicit — via `design_skill` in project.context.md. Only ONE can be active. |
 | **Static skills** | `.aioson/skills/static/` | Automatic — agents match by `framework` in project.context.md |
 | **Dynamic skills** | `.aioson/skills/dynamic/` | Automatic — agents load when task references external services |
-| **Process skills** | `.aioson/skills/process/` | Loaded on demand when an agent needs a workflow method such as SDD, decision presentation, prompt sharpening, or design-skill creation |
+| **Process skills** | `.aioson/skills/process/` | Loaded on demand when an agent needs a workflow method such as SDD, decision presentation, prompt sharpening, feature expansion, or design-skill creation |
 
 First-party process skills include:
 
-- `prompt-sharpener` — improves agent prompts, skills, PRDs, plans, and handoffs by turning vague guidance into evidence-driven decision behavior while preserving workflow contracts.
+- `prompt-sharpener` — improves agent prompts, skills, PRDs, plans, and handoffs by turning vague guidance into evidence-driven decision behavior while preserving workflow contracts.
+- `briefing-expansion-scout`, `product-scope-expansion`, `sheldon-expansion-audit` — enrich feature thinking only when a rich surface or prior expansion artifact justifies it, using `.aioson/docs/feature-expansion-taxonomy.md`.
 
 ### Installed skills (`.aioson/installed-skills/`)
 

package/template/.aioson/design-docs/agent-loading-contract.md

@@ -36,8 +36,8 @@ Append-growing memory must have a **retention policy**; it must not accumulate f
 ### Tier 0 — Always (budget <= ~2k tokens)
 Immediate cheap orientation; answers "what this is + what is happening + what is missing":
 - `bootstrap/what-is.md` — system identity
-- `context/project-pulse.md` — last agent, active feature, blockers, next step
-- `context/dev-state.md` — current development state, when present
+- `.aioson/context/project-pulse.md` — last agent, active feature, blockers, next step
+- `.aioson/context/dev-state.md` — current development state, when present
 
 The agent's own `.md` file and `CLAUDE.md` are loaded by the harness and are outside this budget.
 
@@ -90,7 +90,7 @@ General rule: every append-growing memory file needs retention, not infinite app
 
 ## Deterministic Triggers
 
-When the request **names or implies** a feature, the agent **must** resolve the slug via `features.md` / `project-pulse.md` and load `dossier` + `spec` **before editing code**.
+When the request **names or implies** a feature, the agent **must** resolve the slug via `.aioson/context/features.md` / `.aioson/context/project-pulse.md` and load `dossier` + `spec` **before editing code**.
 This converts the trigger from heuristic ("agent decides") into contract ("must resolve + load").
 Use `aioson context:pack . --agent=<a> --goal="<request>"` to get the exact file set.
 

package/template/.aioson/docs/LAYERS.md

@@ -1,5 +1,7 @@
 ---
 description: "Guide to the three project memory layers: rules, docs, and design-docs — when to use each"
+task_types: [framework-structure]
+triggers: [framework layers, docs structure]
 agents: []
 ---
 

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

@@ -1,5 +1,7 @@
 ---
 description: "Autonomy Contract: 3-tier permission model that drives native harness permissions and the `aioson notify` UX. Load when implementing or debugging permissions, tier changes, or notify levels."
+task_types: [autonomy, approval]
+triggers: [autonomy mode, approval gates, autopilot]
 ---
 
 # Autonomy Contract — 3-tier permission model
@@ -14,8 +16,8 @@ Visual notifier: `aioson notify --level=info|warn|block`.
 
 | Tier | Intent | UX | Examples |
 |---|---|---|---|
-| `tier1_silent`   | Read-only and telemetry. Auto-execute, no notification.                | none           | `git status`, `aioson preflight`, `aioson context:health`, `agent:done`, `review-cycle:status` |
-| `tier2_notified` | Mutates AIOSON memory (`bootstrap/`, `features/`, `runtime/`). Auto-execute with **inline notify** (ℹ).         | `ℹ [topic] msg` | `memory:reflect-prepare`, `memory:reflect-commit`, `workflow:next`, `dossier:*`, `agent:epilogue`, `review-cycle:advance|resolve|reset` |
+| `tier1_silent`   | Read-only and telemetry. Auto-execute, no notification.                | none           | `git status`, `aioson preflight`, `aioson context:health`, `agent:done`, `review-cycle:status` |
+| `tier2_notified` | Mutates AIOSON memory (`bootstrap/`, `features/`, `runtime/`). Auto-execute with **inline notify** (ℹ).         | `ℹ [topic] msg` | `memory:reflect-prepare`, `memory:reflect-commit`, `workflow:next`, `dossier:*`, `agent:epilogue`, `review-cycle:advance|resolve|reset` |
 | `tier3_blocking` | Irreversible or external (publish, push, npm registry). **Never** auto-executed; the CLI returns exit 2 and waits for a human. | `⛔ [topic] msg` | `git push *`, `npm publish *`, `cloud:publish:*`, `genome:publish` |
 
 A tool opts into tiers via `derived_from_tiers`:
@@ -30,7 +32,7 @@ A tool opts into tiers via `derived_from_tiers`:
 
 **Hard invariant:** `tier3_blocking` is *never* materialized into a tool's native allow-list, even when listed in `derived_from_tiers`. Tier3 always requires explicit human action.
 
-## How the native harnesses receive it
+## How the native harnesses receive it
 
 `aioson update` (or `aioson setup`) calls `permissions-generator` after copying the template. It reads the protocol and writes:
 
@@ -38,7 +40,7 @@ A tool opts into tiers via `derived_from_tiers`:
 |---|---|---|---|
 | Claude Code | `.claude/settings.json` | JSON (`permissions.allow[]`) | Merges with existing user entries (preserves customizations) |
 | Codex CLI | `.codex/permissions.json` | JSON | Overwrites (with backup) |
-| OpenCode | `.opencode/permissions.yaml` | YAML | Overwrites (with backup) |
+| OpenCode | `.opencode/permissions.yaml` | YAML | Overwrites (with backup) |
 
 Previous versions are backed up under `.aioson/backups/{timestamp}/permissions/`.
 
@@ -73,7 +75,7 @@ Internally `notify` calls `runtime:emit` (records in SQLite as event_type `notif
 ## Adding a new command to a tier
 
 1. Edit `template/.aioson/config/autonomy-protocol.json` and add the command under the appropriate `tiers.{tier}.aioson_commands`.
-2. Run `aioson update .` in any consuming project — generator regenerates the native files.
+2. Run `aioson update .` in any consuming project — generator regenerates the native files.
 3. Update tests in `tests/permissions-generator.test.js` if the command should appear in / be excluded from the generated output.
 
 Never add to `tier3_blocking` for "convenience" — that tier is the safety boundary. If a command needs to be auto-approved, it belongs in tier1 or tier2.

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

@@ -1,5 +1,7 @@
 ---
 description: "Autopilot handoff protocol: automatic agent chaining across the feature workflow — the analyst→dev pre-dev chain and the post-dev review cycle (dev→qa→tester/pentester→validator) — with deterministic routing and explicit stop conditions. The chain never auto-runs feature:close/publish."
+task_types: [handoff, autopilot]
+triggers: [auto handoff, autopilot, next agent]
 ---
 
 # Autopilot handoff (analyst → dev → review cycle)
@@ -49,7 +51,7 @@ SMALL feature: `@analyst` → `@scope-check` → `@architect` → `@discovery-de
 
 MEDIUM feature: `@analyst` → `@architect` → `@discovery-design-doc` → `@pm` → `@scope-check` → `@dev`.
 
-The prompt-only fallback still stops before the FIRST `@dev` activation because `@dev` is a heavy phase and benefits from a fresh context window. Runtime agentic mode may cross this boundary only by starting a fresh `@dev` activation from the checkpoint/context package, not by carrying the upstream chat context forward. If the gateway cannot start that fresh activation, stop with the normal `/clear` + `/dev` recommendation.
+The prompt-only fallback still stops before the FIRST `@dev` activation because `@dev` is a heavy phase and needs a compact operational handoff. Runtime agentic mode may cross this boundary only by starting a checkpointed `@dev` activation from the context package, not by carrying raw upstream chat forward. If the gateway cannot start that activation, stop with the normal `/compact` + `/dev` recommendation for same-feature continuation. Recommend `/clear` only when the user needs a hard reset, a feature switch, polluted context, or a security-sensitive reset.
 
 ## Segment 2 — post-dev review cycle (hub = `@qa`)
 
@@ -86,11 +88,11 @@ Routing table (each row is followed only when autopilot is active and no stop co
 3. **Corrections cap reached** — review cycles are bounded by `agentic_policy.review_cycle` (default 3); when `review-cycle:advance` returns `stop_cycle_limit`, stop and escalate to the human.
 4. **Critical security finding** — the `@qa` corrections security gate (auth/secret/credential/session/password/token/PII/encryption keywords) blocks the auto-loop; stop and require human intervention.
 5. **Verdict not clean / gate or readiness blocked** — `@scope-check` not `approved`/`patched`, `@architect` Gate B blocked, `@discovery-design-doc` readiness `blocked`, `@pm` Gate C blocked, `@validator` FAIL with no safe corrections path: stop and route to the owner manually.
-6. **Context budget** — estimated usage ≥ `context_warning_threshold` (`.aioson/config.md`): write the compaction checkpoint to `.aioson/context/last-handoff.json`, stop, and recommend `/clear`. The workflow resumes from `workflow.state.json` — the next session re-enters autopilot automatically.
+6. **Context budget** — estimated usage ≥ `context_warning_threshold` (`.aioson/config.md`): write the compaction checkpoint to `.aioson/context/last-handoff.json`, stop, and recommend `/compact` for same-feature continuation. The workflow resumes from `.aioson/context/workflow.state.json` — the next session re-enters autopilot automatically. Recommend `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
 7. **Ambiguity** — workflow state unavailable AND routing ambiguous, or any real decision requires user input: stop and ask, manually.
 
 The user can interrupt at any time (Ctrl+C); autopilot never retries an interrupted invocation.
 
 ## Rationale
 
-Industry-validated design (see `researchs/auto-handoff-pipeline-2026/summary.md`): deterministic routing beats LLM routing; human gates belong where they catch mistakes — at the start of implementation (`@dev` entry: fresh context) and at the irreversible boundary (`feature:close`/publish). Every autonomous loop needs explicit exit conditions and bounds (the corrections cap, the re-entry guard); per-hop context checkpointing is the load-bearing cost mitigation.
+Industry-validated design (see `researchs/auto-handoff-pipeline-2026/summary.md`): deterministic routing beats LLM routing; human gates belong where they catch mistakes — at the start of implementation (`@dev` entry: compact operational handoff) and at the irreversible boundary (`feature:close`/publish). Every autonomous loop needs explicit exit conditions and bounds (the corrections cap, the re-entry guard); per-hop context checkpointing is the load-bearing cost mitigation.

package/template/.aioson/docs/dev/execution-discipline.md

@@ -1,5 +1,8 @@
 ---
 description: "Dev execution discipline — semantic commits, learnings, task tracking, planning, atomic execution, verification gates, skeleton updates, and debugging."
+agents: [dev, deyvin]
+task_types: [implementation, execution]
+triggers: [implementing slices, execution discipline, commit cadence]
 ---
 
 # Dev Execution Discipline

package/template/.aioson/docs/dev/simple-plan-lane.md

@@ -1,92 +1,141 @@
+---
+description: "Simple Plan lane for @dev and @deyvin: bounded technical implementation without PRD, with disk-first scope, implementation intelligence, done criteria, verification, and dev-state handoff."
+agents: [dev, deyvin, qa, neo]
+task_types: [simple-plan, bounded-work]
+triggers: [simple plan, bounded technical work, small fix, refactor, polish, implementation intelligence]
 ---
-description: "Simple Plan lane for @dev and @deyvin: bounded technical implementation without PRD, with disk-first scope, done criteria, verification, and dev-state handoff."
----
-
-# Simple Plan Lane
-
-Use this guide when a user asks for a technical change that is clear enough to implement, but broad enough that chat-only planning would lose context.
-
-## Purpose
-
-The simple-plan lane reduces token cost for bounded implementation work. It is not a replacement for PRDs, requirements, architecture, or QA. It is a disk-first checkpoint for implementation tasks where the agent can define scope, done criteria, files, and verification before coding.
-
-## When to Use
-
-Use this lane when all are true:
-
-- The request is technical and implementation-focused.
-- The scope is bounded to a small set of files or one narrow behavior.
+
+# Simple Plan Lane
+
+Use this guide when a user asks for a technical change that is clear enough to implement, but broad enough that chat-only planning would lose context.
+
+## Purpose
+
+The simple-plan lane reduces token cost for bounded implementation work. It is not a replacement for PRDs, requirements, architecture, or QA. It is a disk-first checkpoint for implementation tasks where the agent can define scope, done criteria, files, useful implementation options, and verification before coding.
+
+It must not rely on model intuition alone. Before coding, the agent writes a lightweight implementation intelligence checkpoint into the simple plan: selected context, existing patterns, framework leverage, boundaries, and richer options considered.
+
+## When to Use
+
+Use this lane when all are true:
+
+- The request is technical and implementation-focused.
+- The scope is bounded to a small set of files or one narrow behavior.
 - The agent can write observable done criteria before coding.
 - The verification command is known or can be inferred from the repo.
+- The agent can name at least one existing project/framework pattern to reuse or explicitly state none was found.
 - No product, UX, domain, architecture, or security decision is being made.
 
 Do not use it for new product surfaces, unclear requirements, sensitive surfaces, new integrations, or architecture-wide changes.
 
-## Artifact
-
-Create one file:
-
-```text
-.aioson/context/simple-plans/{slug}.md
-```
-
-Use this structure:
-
-```markdown
----
-slug: {slug}
-status: in_progress
-owner: dev | deyvin
-created_at: {YYYY-MM-DD}
-updated_at: {YYYY-MM-DD}
-classification: MICRO
-risk: low | medium
-source: direct-user-request
----
-
-# Simple Plan - {Title}
-
+If a richer option would change product behavior, UX direction, permissions, data sensitivity, architecture, or delivery scope, park it in the simple plan and hand off to the correct workflow agent instead of implementing it silently.
+
+## Implementation Intelligence Checkpoint
+
+Complete this checkpoint before writing the final simple plan and before editing code:
+
+1. Run `aioson context:select . --agent=<dev|deyvin> --mode=planning --task="<task>" --paths="<known paths>"` when available.
+2. Read only selected rules/docs and the nearest existing code pattern for the touched area.
+3. Identify framework leverage first: built-in framework APIs, conventions, generators, validation, data access, components, or testing helpers that should be reused before custom code.
+4. Identify data and boundary placement: where queries, query builders, repositories, services, components, handlers, validation, and tests belong in this project.
+5. Consider useful implementation options, then classify each as:
+   - `include now`: improves the requested behavior without widening scope or risk.
+   - `defer`: useful but not needed for the current verified slice.
+   - `escalate`: requires product, UX, domain, architecture, security, or QA ownership.
+
+Do not ask the user about every option. Ask only when the recommended option changes scope or requires a real decision. Otherwise, write the reasoning into the plan and proceed with the smallest valuable verified slice.
+
+## Artifact
+
+Create one file:
+
+```text
+.aioson/context/simple-plans/{slug}.md
+```
+
+Use this structure:
+
+```markdown
+---
+slug: {slug}
+status: in_progress
+owner: dev | deyvin
+created_at: {YYYY-MM-DD}
+updated_at: {YYYY-MM-DD}
+classification: MICRO
+risk: low | medium
+source: direct-user-request
+---
+
+# Simple Plan - {Title}
+
 ## Scope
 [One narrow implementation objective.]
 
+## Context selected
+- context:select / fallback evidence:
+- Existing pattern to follow:
+- Applicable rule/doc:
+
+## Implementation intelligence
+- Framework leverage:
+- Structure and data boundary:
+- Reuse over custom code:
+
 ## Done criteria
 - [Observable behavior or file-level outcome.]
 
+## Useful options considered
+- Include now:
+- Defer:
+- Escalate:
+
 ## Out of scope
 - [Explicit exclusions.]
-
-## Expected files
-- path/to/file.js
-
-## Verification
-- command
-
-## Session state
-Next step: [first implementation slice.]
-
-## Notes
-- [Decisions made during implementation.]
-```
-
-## Execution Protocol
-
-1. Write the simple plan before editing code.
-2. Run `aioson dev:state:write . --feature={slug} --next="<first slice>" --context=simple-plan`.
-3. Implement the smallest useful slice.
-4. Run the verification listed in the plan.
-5. Update `status`, `updated_at`, notes, and next step.
-6. If the task expands beyond the lane, mark the plan `paused` and hand off to the correct workflow agent.
-
-## Status Semantics
-
-- `draft`: scoped but not started.
-- `in_progress`: active implementation.
-- `done`: implemented and verified.
-- `paused`: intentionally parked; visible for later and non-blocking.
-- `abandoned`: intentionally dropped.
-
-## Handoff Rules
-
-If a simple plan remains unfinished at session end, keep it as `in_progress` or `paused` and update `dev-state.md` with `--context=simple-plan`.
-
-If implementation is complete, mark it `done`, record verification evidence in the plan, and update `dev-state.md` only when more work remains.
+
+## Expected files
+- path/to/file.js
+
+## Verification
+- command
+
+## Session state
+Next step: [first implementation slice.]
+
+## Notes
+- [Decisions made during implementation.]
+```
+
+## Execution Protocol
+
+1. Complete the implementation intelligence checkpoint.
+2. Write the simple plan before editing code.
+3. Run `aioson dev:state:write . --feature={slug} --next="<first slice>" --context=simple-plan`.
+4. Implement the smallest useful slice, including only `include now` options.
+5. Run the verification listed in the plan.
+6. Update `status`, `updated_at`, notes, useful options, and next step.
+7. If the task expands beyond the lane, mark the plan `paused` and hand off to the correct workflow agent.
+
+## Quality Bar
+
+A valid simple plan is not just a TODO list. It must show:
+
+- What context/rules/patterns were selected.
+- Which framework or project convention will be reused.
+- Where structure and data access belong.
+- Which useful options were included, deferred, or escalated.
+- The verification command that proves the slice.
+
+## Status Semantics
+
+- `draft`: scoped but not started.
+- `in_progress`: active implementation.
+- `done`: implemented and verified.
+- `paused`: intentionally parked; visible for later and non-blocking.
+- `abandoned`: intentionally dropped.
+
+## Handoff Rules
+
+If a simple plan remains unfinished at session end, keep it as `in_progress` or `paused` and update `.aioson/context/dev-state.md` with `--context=simple-plan`.
+
+If implementation is complete, mark it `done`, record verification evidence in the plan, and update `.aioson/context/dev-state.md` only when more work remains.

package/template/.aioson/docs/dev/stack-conventions.md

@@ -1,5 +1,8 @@
 ---
 description: "Dev stack conventions — Laravel, UI/UX, design skill, motion, Web3, and any-stack separation rules."
+agents: [dev, deyvin]
+task_types: [implementation, conventions]
+triggers: [stack conventions, framework patterns, implementing features]
 ---
 
 # Dev Stack Conventions
@@ -41,7 +44,7 @@ Rules:
 
 ## Design skill conventions
 
-Read `design_skill` from `project.context.md` before implementing user-facing UI.
+Read `design_skill` from `.aioson/context/project.context.md` before implementing user-facing UI.
 
 If `design_skill` is set:
 

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

@@ -1,24 +1,27 @@
 ---
 description: "Deyvin continuity recovery — session start order, resumption rules, brownfield guardrails, SDD bridge, and Git fallback."
+agents: [deyvin]
+task_types: [continuity, recovery]
+triggers: [continuity recovery, recent work, stale state]
 ---
 
 # Deyvin Continuity Recovery
 
-Load this module only when the task is continuity recovery, recent-work reconstruction, stale-state diagnosis, or resuming an existing slice.
+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. 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.
+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`, `.aioson/context/dev-state.md`, or `.aioson/context/project-pulse.md` points to that slug; use `.aioson/context/spec-current.md` for active spec and `.aioson/context/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.
 
@@ -35,12 +38,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 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`
+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/deyvin/debugging-escalation.md

@@ -1,5 +1,8 @@
 ---
 description: "Deyvin debugging and escalation — root-cause protocol, retry limits, and when to hand off."
+agents: [deyvin]
+task_types: [debugging, bugfix]
+triggers: [bug diagnosis, failing test, debugging escalation]
 ---
 
 # Deyvin Debugging and Escalation