@jaimevalasek/aioson 1.36.0 → 1.37.0

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

@@ -4,28 +4,38 @@ task_types: [handoff, autopilot]
 triggers: [auto handoff, autopilot, next agent]
 ---
 
-# Autopilot handoff (pre-dev detours → dev → review cycle)
+# Autopilot handoff (feature start → dev → review cycle)
 
-Opt-in protocol that removes manual handoff confirmations in the deterministic segments of the feature workflow. Two segments:
+Opt-in protocol that removes the **mechanical** handoff confirmations across the whole feature workflow — the "type /sheldon", "type /dev", "run phase 2", "run qa" stops. Genuine human decisions (product scope, sizing/enrichment) still happen interactively inside their agents; autopilot only removes the mechanical "run the next thing" step once an agent's own work is settled. Two segments:
 
-1. **Pre-dev chain (opt-in detours → `@dev`):** by default the MEDIUM lane routes `@product → @orchestrator → @dev` and the SMALL lean lane routes `@product → @sheldon → @dev`, so there is no pre-dev auto-chain — `@orchestrator` (maestro) and `@sheldon` (lean) own the spec solo and hand off manually. `@analyst`, `@architect`, `@pm`, `@scope-check`, and `@discovery-design-doc` chain automatically only when an opt-in detour adds them to the active sequence. Upstream agents (`@briefing`, `@product`, `@sheldon`, `@orchestrator`) always stay manual — they end on genuine human decisions.
-2. **Post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` → `@validator`):** once a human starts `@dev`, the implementation and review agents chain automatically until the feature is ready to close. `@qa` is the hub: it owns the routing to the specialized agents and the corrections loop.
+1. **Spec → dev chain (`@product → @sheldon`/`@orchestrator` → `@dev`):** when autopilot is on, each spec agent — once its own decisions are resolved (no open `AskUserQuestion`, the gates it owns approved) — seeds the agentic scheme and auto-invokes the next stage instead of stopping. It crosses the pre-dev boundary via the `dev-state.md` cold-start packet, not by carrying raw upstream chat forward. `@analyst`, `@architect`, `@pm`, `@scope-check`, and `@discovery-design-doc` chain automatically only when an opt-in detour adds them to the active sequence.
+2. **Post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` → `@validator`):** the implementation and review agents chain automatically until the feature is ready to close. `@qa` is the hub: it owns the routing to the specialized agents and the corrections loop.
+
+Both segments stop only at the human close/publish gate (`feature:close`) and at the hard stop conditions below. Historically Segment 1 stayed manual (upstream agents end on human decisions); autopilot now crosses it too, but only mechanically — a real product/sizing decision still pauses for the human before any auto-invoke.
 
 ## Activation
 
-Autopilot is active only when ALL are true:
+Autopilot is active when BOTH of the first two hold, gated by the third:
+
+1. Either `project.context.md` frontmatter has `auto_handoff: true`, OR `.aioson/context/workflow-execute.json` exists with `agentic_policy.enabled: true` **and `feature` matching the current slug** (the seeded scheme — a scheme left by a different/closed feature does NOT count, for any agent in the chain). **Per-feature disarm wins over the flag:** a scheme for the current slug with `agentic_policy.enabled: false` (written by `aioson workflow:execute . --feature={slug} --seed --step`) turns autopilot OFF for that feature even when `auto_handoff: true` — an explicit per-feature choice always beats the project default.
+
+**Inline run-mode tokens (highest precedence, human entry points only):** a standalone `--auto` or `--step` in the activation arguments of `@product` (kickoff) or `@dev` (late entry/override) IS the run-mode decision — the agent strips it from the task text and never asks. `--auto` seeds the scheme (arming the whole chain from that point); `--step` writes the disarmed scheme. Downstream agents (`@qa`/`@tester`/`@pentester`/`@validator`) do not parse tokens — they read the flag/scheme. Absent both, the run mode is not yet chosen: **`@product` asks it on screen at feature kickoff** (Autopilot / Step by step / Always autopilot — see product.md "Run mode"). Picking Autopilot seeds the scheme (activating this segment); "Always autopilot" also writes `auto_handoff: true`; Step by step leaves both unset = manual handoffs. Only `@product` asks — downstream agents read the flag/scheme and never re-prompt.
+2. A feature workflow is active (feature slug known).
+3. The current agent's own gate/verdict passed AND no genuine human decision is open (see stop conditions).
 
-1. `project.context.md` frontmatter has `auto_handoff: true` (absent or `false` = manual handoffs, current behavior).
-2. A feature workflow is active (feature slug known, classification SMALL or MEDIUM).
-3. The current agent's own gate/verdict passed (see stop conditions).
+## Seeding the agentic scheme
 
-Preferred runtime entrypoint:
+The first spec agent to finish under autopilot seeds the run's contract — this is the "scheme" the whole chain follows, and it is what makes a feature built the normal way (`@product → @sheldon`/`@orchestrator` → …) run to `feature:close` without the user launching anything:
 
 ```bash
-aioson workflow:execute . --feature={slug} --tool=<tool> --agentic
+aioson workflow:execute . --feature={slug} --seed --tool=<tool>
 ```
 
-`workflow:execute --agentic` is the central orchestration contract. It writes `.aioson/context/workflow-execute.json` with `agentic_policy`, including the review-loop caps, sidecar/scout policy, lane guard, current checkpoint, and resumable command. Prompt-level `Skill(aioson:agent:<next>)` chaining remains a compatibility fallback for clients that cannot let the gateway consume this checkpoint.
+`--seed` writes `.aioson/context/workflow-execute.json` (with `agentic_policy.enabled: true` — review-loop caps, `feature_close: human_gate`, and the stop conditions) plus `.aioson/context/workflow.state.json`. It is **seed-only**: it records the policy the interactive agents follow but does NOT drive stage transitions itself (the agents do, via `Skill(aioson:agent:<next>)` + `aioson workflow:next . --complete=<agent>`). Re-seeding the same slug is idempotent, and a stale `workflow.state.json` left by a feature that is no longer active in `features.md` is discarded and reseeded. Once the scheme exists with `agentic_policy.enabled`, autopilot is on for the whole feature even if `auto_handoff` was never written to frontmatter.
+
+**Seed failure is a stop condition.** The seeding agent must check the command result: a `different_active_feature` failure means another feature is genuinely active in `workflow.state.json` — surface it to the user (close/pause it, or `aioson feature:sweep .`) and stop with the manual handoff. Never continue the chain as if autopilot were armed when the seed failed.
+
+The headless/tracked runner `aioson workflow:execute . --feature={slug} --tool=<tool> --agentic` (without `--seed`) is the same contract but also advances checkpoints from the CLI — use it for non-interactive runs. Prompt-level `Skill(...)` chaining is how interactive Claude Code / codex sessions consume the scheme.
 
 ## Routing — deterministic, never LLM-chosen
 
@@ -45,13 +55,13 @@ When autopilot is active and no stop condition applies:
 3. If no runtime gateway is available, emit a one-line transition notice: `Autopilot: @<current> done → invoking @<next> (Ctrl+C to interrupt)`.
 4. Invoke `Skill(aioson:agent:<next>)` with the task `"continue feature {slug} — autopilot handoff from @<current>"`. No user prompt — Ctrl+C interrupts.
 
-## Segment 1 — pre-dev chain (opt-in detours → `@dev`)
+## Segment 1 — spec → dev chain
 
-SMALL feature (lean default): `@product` → `@sheldon` → `@dev` — `@product`/`@sheldon` hand off manually, so there is no pre-dev auto-chain; autopilot resumes in the post-dev review cycle (Segment 2). The full-merged SMALL detour auto-chains `@analyst` → `@architect` → `@dev` when opted in (with `@scope-check`/`@discovery-design-doc` only if the sequence adds them).
+SMALL feature (lean default): `@product` → `@sheldon` → `@dev`. Under autopilot: `@product`, once the PRD is settled, seeds the scheme and invokes `@sheldon`; `@sheldon`, once sizing/enrichment is confirmed and its lean-lane artifacts + `dev-state.md` are written, completes its own stage (`aioson workflow:next . --complete=sheldon`) and invokes `@dev`. The full-merged SMALL detour auto-chains `@analyst` → `@architect` → `@dev` when opted in (with `@scope-check`/`@discovery-design-doc` only if the sequence adds them).
 
-MEDIUM feature (maestro default): `@product` → `@orchestrator` → `@dev` — `@product`/`@orchestrator` hand off manually too, so there is likewise no pre-dev auto-chain (the `@orchestrator` maestro fans out to `@analyst`/`@architect`/`@pm` as sub-agents, not as workflow stages). `@analyst` → `@architect` → `@pm` → `@dev` auto-chains only when an opt-in full-chain detour adds those stages to the sequence (`@discovery-design-doc` and `@scope-check` chain only if the sequence adds them).
+MEDIUM feature (maestro default): `@product` → `@orchestrator` → `@dev`. Under autopilot: `@product` seeds + invokes `@orchestrator`; `@orchestrator`, once its gated spec package (Gates A/B/C approved, readiness ready) + `dev-state.md` are written, invokes `@dev`. The maestro fans out to `@analyst`/`@architect`/`@pm` as sub-agents, not as workflow stages; those chain as stages only under an opt-in full-chain detour.
 
-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.
+Crossing into `@dev` goes through the `dev-state.md` cold-start packet the spec agent writes — `@dev`'s session-start protocol loads only that minimal package, so `@dev` does not inherit the heavy upstream chat; transparent auto-compact trims the rest. That is why the crossing is safe without a manual `/compact`. The spec agent still stops with the normal manual `/dev` recommendation if it has an open product/scope/sizing decision or a gate it owns is not approved. 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`)
 
@@ -84,7 +94,7 @@ Routing table (each row is followed only when autopilot is active and no stop co
 ## Stop conditions — break the chain and emit the normal manual handoff
 
 1. **`feature:close` / publish** — ALWAYS the human gate. When `@qa` (PASS, nothing pending) or `@validator` (PASS) is the last clean step, STOP and recommend `aioson feature:close . --feature={slug}`. Never auto-run `feature:close`, `feature:archive`, `npm publish`, or any publish/close action.
-2. **First `@dev` entry without runtime gateway** — prompt-only clients stop here (Segment 1). Runtime agentic mode may continue only through a fresh checkpointed `@dev` activation.
+2. **Genuine human decision open** — a spec agent with an unresolved product/scope/sizing question (an open `AskUserQuestion`, or a gate it owns not yet approved) finishes that decision with the human before any auto-invoke, and stops with the normal manual handoff. Autopilot removes mechanical stops, never real decisions. (This replaces the old "always stop before the first `@dev`" rule: the crossing is now automatic once the spec agent's own decisions are settled and `dev-state.md` is written.)
 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** — the `@orchestrator` maestro spec package not gate-approved (Gates A/B/C) or its readiness `blocked`, `@validator` FAIL with no safe corrections path (and, when present as detours, `@architect` Gate B / merged-mode readiness `blocked`, `@pm` Gate C blocked, `@scope-check` not `approved`/`patched`, or `@discovery-design-doc` readiness `blocked`): stop and route to the owner manually.

package/template/.aioson/docs/dev/phase-loop.md

@@ -11,7 +11,7 @@ On-demand detail for @dev's `## Phase loop` kernel section. Applies when a phase
 
 ## The loop
 
-**Auto-continue is the default — do NOT stop to ask "continue?" between phases** (`phase_loop.auto_continue` in `.aioson/config/verification.json`). The per-phase verification report replaces that human checkpoint: a clean report means proceed; a failing one stops the loop. Set `auto_continue: false` to pause for confirmation between phases.
+**Auto-continue is the default and it is imperative — a phased plan runs to the END OF THE FEATURE in one continuous drive, not one phase per turn** (`phase_loop.auto_continue` in `.aioson/config/verification.json`). After a phase's gate is clean you will feel the pull to stop and report "Phase N done — continue?"; that pull is the exact bug this loop exists to defeat. Do NOT stop, do NOT ask, do NOT summarize-and-end between phases — proceed straight into the next phase. The per-phase verification report is the checkpoint that replaces the human "continue?": a clean report advances automatically; a failing one (after in-phase fix retries) is the only thing that halts the loop mid-feature. The run otherwise halts only at the end-of-feature gate or at a genuine hard stop (real ambiguity, a blocked gate, or a context ceiling on a host without transparent auto-compact). Set `auto_continue: false` only if you deliberately want to pause for confirmation between phases.
 
 After finishing each phase:
 
@@ -21,15 +21,18 @@ After finishing each phase:
    ```bash
    aioson verification:plan . --feature={slug} --trigger=per-phase --json
    ```
-   For every agent with `run: true`, dispatch it as a sub-agent on the returned `host` / `mode` / `model`, scoped to this phase's changed files:
+   For every agent with `run: true`, dispatch it as a sub-agent on the plan's top-level `host` plus that agent's `mode` / `model`, scoped to this phase's changed files:
    - `mode: native` → an in-harness sub-agent. On Claude Code use the Task tool with that `model` tier (e.g. `sonnet-4.6`); on codex/opencode use their own configured model. The sub-agent writes its `report` file (e.g. `qa-report-{slug}.md`) and returns it to @dev.
    - `mode: external` → only the explicitly configured cross-vendor auditor (`cross_check`); never spawn one otherwise.
    Read the report: **PASS** → continue. **Bugs** → fix them within this phase, re-run `harness:check`, and re-dispatch — up to `phase_loop.max_fix_retries_per_phase` times, then stop and surface the failure instead of advancing.
-4. **Compact between phases** (when `phase_loop.compact_between_phases` is true and phases remain). Write the cold-start packet:
+4. **Checkpoint, then keep going — do NOT end the turn.** Write the cold-start packet as a crash/interrupt safety net:
    ```bash
    aioson dev:state:write   # slug, completed phase, next phase, manifest path, required context, decisions
    ```
-   then shed context — `/compact` on Claude Code, or open a fresh context and reload via `aioson dev:resume-data .` on codex/opencode — and resume on the next phase. Each phase gets a clean context with no manual chat hand-off.
+   Then continue **immediately** into the next phase in the SAME turn. Context management is the host's job, never a reason to stop:
+   - **Claude Code (and any host with transparent auto-compact):** never self-issue `/compact` and never end your turn between phases. Auto-compact shrinks context in place when it fills — you just keep implementing. With `compact_between_phases: true`, "compact" means *write the checkpoint above*, NOT *stop for a manual compaction*.
+   - **codex / opencode (no transparent auto-compact):** the host wrapper re-enters on a fresh context and reloads via `aioson dev:resume-data .`. Only these hosts break the turn, and only their wrapper — never a bare prompt — restarts the loop.
+   The checkpoint exists so an interrupted run resumes cheaply, not so you pause. A phase boundary with a clean gate is a checkpoint, never a stopping point.
 5. **End-of-feature gate (after the last phase only).** Hand off to `@qa`, which runs the full runtime smoke (build + migrate + boot + Core happy-path) plus `@tester`/`@pentester`/`@validator` per:
    ```bash
    aioson verification:plan . --feature={slug} --trigger=end-of-feature
@@ -40,7 +43,7 @@ After finishing each phase:
 - The per-phase check is **light**: one cheap-tier sub-agent, changed-files scope, capped by `budget.max_subagents_per_phase`.
 - It is **suppressed on MICRO** (`budget.skip_on_micro`) — MICRO phases just auto-continue with no sub-agent.
 - The **expensive full runtime smoke runs once**, at end-of-feature only (`budget.full_smoke = end-of-feature-only`) — never per phase.
-- Compaction between phases keeps each phase's context small, which is cheaper than carrying one accumulating context across a long feature.
+- Context stays small without stopping: on Claude Code transparent auto-compact shrinks it in place as it fills, and the between-phase `dev:state:write` checkpoint lets any compaction (auto or a host-driven fresh context) resume the next phase cheaply. You get the small-context savings without ever ending the turn.
 
 ## Configuration
 

package/template/.aioson/docs/play/llm-data-and-bindings.md

@@ -29,14 +29,56 @@ Play manages global LLM connections in Settings:
 
 Apps should not store Play LLM secrets in repository files or frontend code.
 
+Env vars Play injects at spawn (one per configured connection, since 2026-07-02):
+
+| Play LLM connection | Injected env var |
+|---|---|
+| OpenAI | `OPENAI_API_KEY` |
+| Claude (Anthropic) | `ANTHROPIC_API_KEY` |
+| OpenRouter | `OPENROUTER_API_KEY` |
+| Google Gemini | `GEMINI_API_KEY` |
+| DeepSeek | `DEEPSEEK_API_KEY` |
+| xAI | `XAI_API_KEY` |
+
+Alongside the keys, Play injects **`AIOSON_LLM_CHAIN`** (since 2026-07-02): a
+JSON string WITHOUT keys carrying the validated model per operation and the
+fallback order the user arranged in Play Settings:
+
+```json
+{
+  "exportedAt": "2026-07-02T18:00:00.000Z",
+  "appScope": null,
+  "configs": [
+    {
+      "provider": "openrouter",
+      "operation": "text_generation",
+      "model": "deepseek/deepseek-chat",
+      "baseUrl": "https://openrouter.ai/api/v1",
+      "priority": 1
+    }
+  ]
+}
+```
+
 Expected app behavior:
 
 - Prefer app-local explicit config only when the app intentionally lets the user override provider settings.
-- Otherwise read provider API keys injected by Play during spawn, such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENROUTER_API_KEY`.
+- Otherwise read the provider API keys injected by Play during spawn (table above).
+- **Do not hardcode models.** For each operation the app needs (`text_generation`, `image_understanding`, `speech_to_text`, ...), pick the first `configs[]` entry for that operation (sorted by `priority`) whose provider has its `*_API_KEY` present, and use that entry's `model` and `baseUrl`. Fall back to app defaults only when `AIOSON_LLM_CHAIN` is absent or has no entry for the operation.
+- Gemini, DeepSeek and xAI are OpenAI-compatible — reuse an OpenAI-compatible client pointed at the entry's `baseUrl`.
 - Lazy-initialize LLM clients. Do not instantiate SDK clients at module load, because missing keys can crash the backend before the app can render a degraded state.
-- Treat `llm-chain.json` as metadata/order only when present. It must not contain API keys.
+- Treat `AIOSON_LLM_CHAIN` as metadata/order only. It never contains API keys.
 - Treat `aioson-models.json` or `llm-chain.json` in the app cwd as optional/legacy for installed apps, not the primary credential contract.
 
+Injection lifecycle — env vars only exist at spawn time:
+
+- Play injects on UI-driven spawn of an installed app AND on draft preview (`spawn_draft`), so an app under development tests with the same contract it will have once installed.
+- Supervisor auto-respawn preserves the keys from the original spawn.
+- A process that is already running does NOT pick up a key configured afterwards. After adding or changing a Play LLM connection, stop and reopen the app (or the draft preview).
+- A backend started by hand outside Play (`npm run dev` in a terminal or agent session) receives nothing — set the key in that shell env or use app-local config for that scenario.
+
+Troubleshooting "provider not configured" in the app UI while the Play connection exists: (1) the app process started before the key was configured — close and reopen the app; (2) the backend is running outside Play; (3) the app expects a provider the user did not configure — Play injects only the keys that exist, one env var per provider.
+
 Recommended lazy pattern:
 
 ```ts
@@ -178,7 +220,9 @@ await fetch(`${PLAY_BASE}/api/bindings/${APP_SLUG}`, {
 
 ## Executing connectors
 
-After binding, execute through ProductBridge by alias:
+After binding, execute through ProductBridge by alias. The SAME endpoint runs
+all three connector types (`mcpi`, `api`, `mcp`) — Play routes by the
+connector's type (since 2026-07-02):
 
 ```http
 POST http://localhost:5180/api/mcp/execute
@@ -188,14 +232,33 @@ Content-Type: application/json
   "alias": "busca-produtos",
   "params": {
     "search": "dipirona"
-  }
+  },
+  "tool": "tool-name"
 }
 ```
 
-The alias must match both:
+`tool` is optional and only used for `mcp` connectors that expose more than
+one tool (a server with exactly one tool needs no `tool` field).
+
+Response shape is the same for all types:
+`{ "data": <json>, "error": null | "message", "duration_ms": <n> }`.
+
+What each type does:
+
+- `mcpi` — runs the query template on the TARGET database of the Play
+  Database Connection (credentials from Play's keyring), `{{param}}` becomes a
+  prepared-statement bind. Drivers: postgresql, mysql, sqlite.
+- `api` — HTTP request to the connector URL: `{{param}}` interpolated into the
+  URL (percent-encoded); leftover params become query string (GET/DELETE) or a
+  JSON body (POST/PUT); auth headers from Play's keyring are applied.
+- `mcp` — LOCAL stdio MCP server: Play spawns the connector command, performs
+  the JSON-RPC handshake (initialize → tools/list → tools/call) and returns
+  the tool result. Spawn per call, 60s timeout.
 
-- `data_bindings[].id`
-- the active binding alias
+MCP scope today: local stdio servers only (auth via the command's own
+env/args — no OAuth involved). REMOTE MCP servers over HTTP, which use OAuth
+2.1 per the MCP spec, are NOT supported yet — do not fake them with manual
+headers; treat that binding as unavailable and degrade.
 
 ## Degraded state
 

package/template/.aioson/skills/design/interface-design/SKILL.md

@@ -28,6 +28,23 @@ It helps the agent make strong decisions when the user wants a deliberate, high-
 - Do not combine it with any other design skill.
 - Use it when the user wants strong design craft but has not asked for a very specific visual system.
 
+## Identity resolution (run FIRST, before any visual decision)
+
+Resolve an `identity.md` in this order: `.aioson/briefings/{slug}/identity.md` (feature scope) →
+`.aioson/context/identity.md` (project brand) → none.
+
+- **If one exists, it is the identity source of truth this engine APPLIES**: take palette,
+  typography, spacing/layout, radius & depth, motion, design pillars, and signature moves from it as
+  the token layer, and feed its `## Component structure notes` into component/screen decisions. It is
+  extracted **data** (from the user's reference images via `reference-identity-extract`) that
+  parameterizes this one engine — never a second design skill, and never a license to skip the
+  quality gates below.
+- **If none exists**, run intent-first: choose the surface type, domain palette, and signature move
+  yourself per the references. Do not fabricate an `identity.md`.
+
+Every consumer of this package (ux-ui, prototype-forge, dev builds) inherits this step by loading
+this SKILL — see `.aioson/docs/reference-identity.md`.
+
 ## Loading guide
 
 | Task | Load |

package/template/AGENTS.md

@@ -7,15 +7,15 @@ You operate as AIOSON — an AI development squad with specialized agents.
    - If missing: activate @setup agent immediately
    - If present: read it before any action
 2. Read `.aioson/config.md` only if project context is missing/invalid, setup/routing policy is needed, or the active agent explicitly asks for config details.
-3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — concrete code/review agents use `context:brief` for precision selection, broad recall, and constraints. Load `must_load`, treat `related` as recall hints, and keep `context:select` as the underlying selector/fallback when the CLI or agent contract asks for it. Do not alarm if the directory is absent or empty.
+3. If `.aioson/rules/` contains `.md` files, note silently that project rules are active — concrete code/review agents use `context:brief` for precision selection, broad recall, and constraints. Load `must_load`, treat `related` as recall hints, and keep `context:select` as the underlying selector/fallback when the CLI or agent contract asks for it. Do not alarm if the directory is absent or empty.
 
-## Project knowledge
-
-Read `.aioson/learnings/INDEX.md` if it exists. Each line is a project gotcha or recipe with its file path and a one-line summary. Lazy-load individual files only when title/scope matches your current task or files being touched.
-
-## Canonical context paths
-
-When instructions mention context artifacts by bare filename — `project.context.md`, `project-pulse.md`, `features.md`, `dev-state.md`, `workflow.state.json`, `last-handoff.json`, or `handoff-protocol.json` — resolve them to `.aioson/context/<filename>`. Never probe the project root or `.aioson/` root for these files.
+## Project knowledge
+
+Read `.aioson/learnings/INDEX.md` if it exists. Each line is a project gotcha or recipe with its file path and a one-line summary. Lazy-load individual files only when title/scope matches your current task or files being touched.
+
+## Canonical context paths
+
+When instructions mention context artifacts by bare filename — `project.context.md`, `project-pulse.md`, `features.md`, `dev-state.md`, `workflow.state.json`, `last-handoff.json`, or `handoff-protocol.json` — resolve them to `.aioson/context/<filename>`. Never probe the project root or `.aioson/` root for these files.
 
 ## No agent selected
 
@@ -107,8 +107,8 @@ 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 `.aioson/context/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 `.aioson/context/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.
+- 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 `.aioson/context/project.context.md` (or a seeded `.aioson/context/workflow-execute.json` with `agentic_policy.enabled` is present), the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping. That chain runs the whole feature — the spec authority (`@sheldon`/`@orchestrator`) seeds the agentic scheme and crosses into `@dev` via the `dev-state.md` cold-start packet, `@dev` runs all phases in one continuous drive, and the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their `@qa` triggers fire → `@validator`) follows automatically. It stops only for a genuine human decision (product scope/sizing still open) and never auto-runs `feature:close`/publish — those require explicit human approval.
+- If `.aioson/context/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.
 
@@ -161,7 +161,7 @@ AIOSON uses the `aioson-spec-driven` process skill to enforce specification-firs
 
 ### Core artifacts
 - `constitution.md` — governs all agents with 6 articles
-- `.aioson/context/project-pulse.md` — global heartbeat, max 30 lines, updated by every agent at session end
+- `.aioson/context/project-pulse.md` — global heartbeat, max 30 lines, updated by every agent at session end
 - `spec-{slug}.md` — feature memory with `phase_gates`, `spec_version`, and `last_checkpoint`
 - `conformance-{slug}.yaml` — machine-readable AC definitions (MEDIUM projects only)
 
@@ -177,7 +177,7 @@ Gates are blocking in MEDIUM, informational in MICRO/SMALL.
 For concrete spec/workflow work, the active agent checks for `aioson-spec-driven` in `.aioson/installed-skills/` or `.aioson/skills/process/` and loads only its role-specific reference file (e.g., `references/dev.md`, `references/qa.md`). A bare `@deyvin` activation is not spec work: follow Deyvin's activation-only fast path and do not open this skill.
 
 ### Project pulse convention
-Every agent updates `.aioson/context/project-pulse.md` at session end with: last_agent, last_gate, active features, blockers, and next recommended action. This enables crash recovery — any agent can read `.aioson/context/project-pulse.md` and know where to resume.
+Every agent updates `.aioson/context/project-pulse.md` at session end with: last_agent, last_gate, active features, blockers, and next recommended action. This enables crash recovery — any agent can read `.aioson/context/project-pulse.md` and know where to resume.
 
 ## Process skill: aioson-spec-driven
 
@@ -199,29 +199,29 @@ Activated by: @design-hybrid-forge
 Default output: `.aioson/installed-skills/{hybrid-name}/`
 What to load: `SKILL.md` first, then only the `references/` file relevant to the current phase
 
-## Process skill: prompt-sharpener
-
-Located at: `.aioson/skills/process/prompt-sharpener/SKILL.md`
-
-This is a first-party process skill for improving agents, skills, PRDs, plans, handoffs, and instruction-heavy markdown by turning vague guidance into evidence-driven decision behavior.
-
-Use when: improving AIOSON prompts/skills, reducing dead context without losing contracts, or sharpening artifacts before downstream handoff.
-What to load: `SKILL.md` first; load `references/prompt-diagnostics.md` only for multi-prompt audits or adoption planning.
-
-## Process skills: feature expansion
-
-Located at:
-- `.aioson/skills/process/briefing-expansion-scout/SKILL.md`
-- `.aioson/skills/process/product-scope-expansion/SKILL.md`
-- `.aioson/skills/process/sheldon-expansion-audit/SKILL.md`
-
-These are first-party process skills for richer feature thinking without uncontrolled MVP inflation.
-
-Agents that load them: @briefing, @briefing-refiner, @product, @sheldon
-When to load: only when the active idea/PRD has a rich surface, a prior expansion artifact exists, or the user asks for richer options.
-Shared taxonomy: `.aioson/docs/feature-expansion-taxonomy.md`
-
-## Shared research cache: researchs/
+## Process skill: prompt-sharpener
+
+Located at: `.aioson/skills/process/prompt-sharpener/SKILL.md`
+
+This is a first-party process skill for improving agents, skills, PRDs, plans, handoffs, and instruction-heavy markdown by turning vague guidance into evidence-driven decision behavior.
+
+Use when: improving AIOSON prompts/skills, reducing dead context without losing contracts, or sharpening artifacts before downstream handoff.
+What to load: `SKILL.md` first; load `references/prompt-diagnostics.md` only for multi-prompt audits or adoption planning.
+
+## Process skills: feature expansion
+
+Located at:
+- `.aioson/skills/process/briefing-expansion-scout/SKILL.md`
+- `.aioson/skills/process/product-scope-expansion/SKILL.md`
+- `.aioson/skills/process/sheldon-expansion-audit/SKILL.md`
+
+These are first-party process skills for richer feature thinking without uncontrolled MVP inflation.
+
+Agents that load them: @briefing, @briefing-refiner, @product, @sheldon
+When to load: only when the active idea/PRD has a rich surface, a prior expansion artifact exists, or the user asks for richer options.
+Shared taxonomy: `.aioson/docs/feature-expansion-taxonomy.md`
+
+## Shared research cache: researchs/
 
 Located at: `researchs/` (project root)
 
@@ -245,7 +245,7 @@ Primary recurring writers here: @product, @sheldon, and @squad
 All agents may read from here to avoid redundant searches.
 
 ## Session protocol
-Do not read `.aioson/context/spec.md` globally at session start. Agents load `spec*.md` only when `context:brief`/`context:select`, their SDD reference, or a concrete task selects it; update it at session end only if the active agent loaded and changed that spec context.
+Do not read `.aioson/context/spec.md` globally at session start. Agents load `spec*.md` only when `context:brief`/`context:select`, their SDD reference, or a concrete task selects it; update it at session end only if the active agent loaded and changed that spec context.
 
 ## Golden rule
 Small project, small solution.

package/template/CLAUDE.md

@@ -112,7 +112,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 `.aioson/context/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.
+- 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 `.aioson/context/project.context.md` (or a seeded `.aioson/context/workflow-execute.json` with `agentic_policy.enabled` is present), the agents covered by `.aioson/docs/autopilot-handoff.md` auto-invoke the next agent's skill instead of stopping. That chain runs the whole feature — the spec authority (`@sheldon`/`@orchestrator`) seeds the agentic scheme and crosses into `@dev` via the `dev-state.md` cold-start packet, `@dev` runs all phases in one continuous drive, and the post-dev review cycle (`@dev` → `@qa` → `@tester`/`@pentester` when their `@qa` triggers fire → `@validator`) follows automatically. It stops only for a genuine human decision (product scope/sizing still open) and 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.