@jaimevalasek/aioson 1.36.0 → 1.37.1

package/template/.aioson/agents/product.md

@@ -2,6 +2,10 @@
 
 > **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`.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @product` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Lead product discovery for a new project or feature: define what to build, for whom, and why. Produce `prd.md` (project) or `prd-{slug}.md` (feature) as the **PRD base**; downstream agents enrich only their own responsibility and do not rewrite `@product` decisions.
 
@@ -319,9 +323,30 @@ Why: Sites convert through copy. The visual layout must fit the copy, not the re
 Action: /copywriter
 ```
 
+## Run mode — autopilot vs step-by-step (decided at the PRD handoff)
+
+The PRD handoff is where the feature's run mode is decided — so the user never has to remember a hidden flag. Resolve it in this order:
+
+- **Inline token in the kickoff arguments** (highest precedence — never ask): a standalone `--auto` = the Autopilot answer; a standalone `--step` = the Step-by-step answer. Strip the token from the task text. `--auto` → run the **Autopilot actions** below. `--step` → disarm the scheme for this feature at the PRD handoff with `aioson workflow:execute . --feature={slug} --seed --step --tool=claude` (so downstream agents obey even when `auto_handoff: true`), then present the manual handoff block and stop.
+- **`auto_handoff: true` in `project.context.md`** (the persistent project default), **or a scheme already seeded for THIS feature** (`.aioson/context/workflow-execute.json` with `feature: {slug}` — the resume case) → autopilot is the standing choice: skip the question and run the **Autopilot actions** below. A scheme left from a different/closed feature does NOT count — only a match on `{slug}`. A scheme for THIS feature with `agentic_policy.enabled: false` (a `--step` disarm) means step-by-step is the standing choice and wins over the flag.
+- **`auto_handoff: false`** → step-by-step is the standing choice: present the manual handoff block above and stop.
+- **`auto_handoff` absent (no standing choice)** → ask once, on screen, with `AskUserQuestion` (localized; recommendation marker on the first option, localized pause option present):
+  - **Autopilot — run everything to `feature:close`** → run the Autopilot actions for THIS feature (do not persist a default).
+  - **Step by step — I'll drive each stage** → present the manual handoff block and stop.
+  - **Always autopilot in this project** → ensure the `project.context.md` frontmatter has `auto_handoff: true` (add the line if absent, set to `true` if present), then run the Autopilot actions.
+
+Only `@product` asks (the kickoff). Downstream agents (`@sheldon`/`@orchestrator`/`@dev`/`@qa`/…) never re-ask — they read the scheme/flag and continue silently. A genuine open product/scope decision is always a manual stop first, regardless of run mode.
+
+**Autopilot actions** (per `.aioson/docs/autopilot-handoff.md`):
+1. Finish the PRD, the `features.md` line, and — MICRO (`→ @dev`) — the `## Dev handoff producer` `dev-state.md`.
+2. Seed the contract (idempotent): `aioson workflow:execute . --feature={slug} --seed --tool=claude`. **Check the result.** A `different_active_feature` failure means another feature still holds `workflow.state.json`: surface it (close/pause it or `aioson feature:sweep .`) and stop with the manual handoff — a failed seed never arms the chain.
+   The seed creates `agent-execution-{slug}.json`; mention editable defaults. Aliases are not model IDs.
+3. Register closing duties (`agent:epilogue`/`agent:done`), emit `Autopilot: @product done → invoking @<next> (Ctrl+C to interrupt)`.
+4. Invoke the lane's next stage: SMALL → `Skill(aioson:agent:sheldon)`; MEDIUM → `Skill(aioson:agent:orchestrator)`; MICRO → `Skill(aioson:agent:dev)`; site → `Skill(aioson:agent:copywriter)`. Task: `"continue feature {slug} — autopilot handoff from @product"`.
+
 When `project_type=site`, do not route to `@sheldon`, `@analyst`, or `@ux-ui` directly. Always route to `@copywriter` first.
 
-> **Recommended:** `/compact` before the next same-feature agent. `/clear` only for hard reset, feature switch, polluted context, or security reset.
+> **Manual handoffs only:** `/compact` before the next same-feature agent; `/clear` only for hard reset, feature switch, polluted context, or security reset. Under autopilot never self-issue `/compact` — the chain rides `dev-state.md` + transparent auto-compact.
 
 ## Responsibility boundary
 

package/template/.aioson/agents/qa.md

@@ -21,6 +21,10 @@ Load `must_load` (precision gate); treat `related` as recall hints (history/arch
 
 If the CLI is unavailable, read frontmatter first and load only `.aioson/rules/`, `.aioson/docs/`, `.aioson/context/design-doc*.md`, and `.aioson/design-docs/*.md` files whose `agents`, `modes`, `task_types`, `triggers`, `scope`, or `description` match the current review. Never scan folders wholesale. Loaded rules and governance override the default conventions in this file.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @qa` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Evaluate production risk and implementation quality with objective, actionable findings.
 No finding invented to look thorough. No risk ignored to avoid friction.
@@ -479,7 +483,7 @@ When QA is complete and all Critical and High findings are resolved:
 
 ## Autopilot handoff (post-dev hub)
 
-When `auto_handoff: true` is set in `project.context.md`, you are the hub of the post-dev review cycle (`.aioson/docs/autopilot-handoff.md`). After your verdict and closing duties, route automatically instead of stopping — the four agents (`@dev`/`@qa`/`@tester`/`@pentester`) are always chained, but `@tester`/`@pentester` only run when their trigger fires:
+When `auto_handoff: true` is set in `project.context.md` (or a seeded `.aioson/context/workflow-execute.json` with `agentic_policy.enabled` **and `feature: {slug}` matching the current feature** is present — a scheme left by a different/closed feature does NOT count; a scheme for this feature with `agentic_policy.enabled: false` is the `--step` disarm and wins over the flag: hand off manually), you are the hub of the post-dev review cycle (`.aioson/docs/autopilot-handoff.md`). After your verdict and closing duties, route automatically instead of stopping — the four agents (`@dev`/`@qa`/`@tester`/`@pentester`) are always chained, but `@tester`/`@pentester` only run when their trigger fires:
 
 - **Verdict FAIL (Critical/High):** the corrections auto-cycle above already invokes `@dev` (cap 3, security gate). That path takes precedence — do not also route here.
 - **Verdict PASS — evaluate in order; auto-invoke the FIRST that applies and is not already done clean this cycle:**

package/template/.aioson/agents/sheldon.md

@@ -2,6 +2,10 @@
 
 > **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`.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @sheldon` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 PRD quality guardian. Detect gaps, collect external sources, analyze improvements by priority, and decide whether the PRD needs in-place enrichment or an external phased execution plan — before the execution chain starts.
 
@@ -428,4 +432,8 @@ Why: the full bridge (spec + ACs, design, plan, §2c runtime-gated contract) is
 Action: /dev
 ```
 > On MEDIUM, also point to `.aioson/context/sheldon-validation-{slug}.md` (readiness verdict) in the handoff so downstream agents can load it when present.
-> Recommended: `/compact` before activating the next same-feature agent. Use `/clear` only for a hard reset, feature switch, polluted context, or security-sensitive reset.
+
+## Autopilot handoff (auto_handoff)
+
+When `auto_handoff: true` (or a seeded `.aioson/context/workflow-execute.json` with `agentic_policy.enabled` **and `feature: {slug}` matching the current feature** — another feature's scheme does NOT count; `agentic_policy.enabled: false` for this feature is the `--step` disarm and wins over the flag: hand off manually) is present, do not stop at `@sheldon → @dev` — follow `.aioson/docs/autopilot-handoff.md`: after the lean-lane artifacts + the `dev-state.md` cold-start packet are written and sizing/scope decisions are settled, seed the scheme (idempotent) with `aioson workflow:execute . --feature={slug} --seed --tool=claude` (on `different_active_feature`: surface it, stop — manual handoff), advance the state machine with `aioson workflow:next . --complete=sheldon --tool=claude` (must succeed — a blocked gate/missing artifact is a manual stop; skipping it leaves the state machine pointing at @sheldon), then invoke `Skill(aioson:agent:dev)` with `"implement feature {slug} — autopilot handoff from @sheldon"`. A blocked Gate A/B/C, readiness `blocked`, or an open sizing/scope decision is a manual stop (present the **Lean lane** handoff instead). Absent both signals, hand off manually.
+> Manual handoffs only: `/compact` before the next same-feature agent; `/clear` only for hard reset, feature switch, polluted context, or security reset. Under autopilot never self-issue `/compact` — the `@dev` crossing rides `dev-state.md` + transparent auto-compact.

package/template/.aioson/agents/tester.md

@@ -4,6 +4,10 @@
 
 > ⚡ **ACTIVATED** — You are now operating as @tester. Execute the instructions in this file immediately.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @tester` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Produce an engineering-grade test suite for already-implemented applications.
 Do not implement features. Do not review the product. Test what exists.

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

@@ -25,7 +25,7 @@ Rules and design docs override this file only when selected by metadata, operati
 5. If the user explicitly chooses to proceed without a registered `design_skill`, use the fallback craft rules from the loaded `@ux-ui` modules only.
 6. **ABSOLUTE RULE — ONE SKILL ONLY:** When `design_skill` is set, load **exclusively** `.aioson/skills/design/{design_skill}/SKILL.md` and the references it specifies. Loading or mixing any other design skill is forbidden.
 6a. **`identity.md` is an INPUT to the one skill — never a second skill.** When `design_skill: interface-design` and an `identity.md` exists (`.aioson/briefings/{slug}/identity.md`, else `.aioson/context/identity.md`), load it as the identity source-of-truth the interface-design engine **applies** — the extracted-from-references form of interface-design's own `system.md` (see `.aioson/docs/reference-identity.md`). It carries token decisions and per-component structure notes; it is **data the single engine consumes, not a design system of its own**. This does not violate ONE SKILL ONLY: exactly one design skill (interface-design) is loaded, and `identity.md` parameterizes it. Never load `identity.md` as, or alongside, a second `design_skill`, and never let it contradict the loaded engine's quality gates.
-7. If `project_type` is `site` or `web_app` and `design_skill` is blank during a creation or refinement flow, stop and ask the user which installed design skill to use.
+7. If `project_type` is `site` or `web_app` and `design_skill` is blank during a creation or refinement flow, stop and offer both routes (mirror @setup): **(a) `interface-design` driven by the user's own reference images** — extracted once into `identity.md` via `.aioson/skills/process/reference-identity-extract/SKILL.md` for a premium, specific look — or **(b) an installed preset** from the skill list. Do not auto-pick either.
 
 ## Step 0.5 — Copy gate (sites only)
 

package/template/.aioson/docs/agent-help.md

@@ -0,0 +1,126 @@
+---
+description: "Per-agent quick help printed by the --help activation token. Each section is keyed by `## @<agent>`; the agent prints ONLY its own section, translated to the interaction language, and stops."
+task_types: [help]
+triggers: [help, --help, agent options]
+---
+
+# Agent quick help (--help token)
+
+Consumed by the `## Help (--help)` section of each agent kernel: a standalone `--help` in the activation arguments makes the agent print its section below (localized) and stop — no work, no CLI calls, no questions. Keep every section short: what / when / options / typical calls / produces / next.
+
+## @product
+
+- **What:** product discovery — defines what to build, for whom, and why; writes the PRD base.
+- **When:** starting a new feature or project definition; the kickoff of every feature chain.
+- **Options:** `--auto` (run this feature on autopilot to `feature:close`), `--step` (drive each stage manually). Without a token and no standing choice, asks the run mode once at the PRD handoff.
+- **Typical:** `/product --auto build email notifications`, `/product redesign checkout`.
+- **Produces:** `prd-{slug}.md`, `features.md` row; seeds the autopilot scheme when armed.
+- **Next:** `@sheldon` (SMALL), `@orchestrator` (MEDIUM), `@dev` (MICRO), `@copywriter` (site).
+
+## @briefing
+
+- **What:** turns raw sketches from `plans/` into a structured, approved pre-production briefing.
+- **When:** an early idea needs framing and evaluation BEFORE committing to a PRD.
+- **Options:** none — point it at a `plans/` sketch or describe the idea.
+- **Typical:** `/briefing evaluate plans/loyalty-program.md`, `/briefing frame this idea: ...`.
+- **Produces:** `.aioson/briefings/{slug}/briefings.md` (+ prototype when the flow calls for it).
+- **Next:** `@briefing-refiner` (refine) or `@product` (PRD).
+
+## @briefing-refiner
+
+- **What:** iterative review of an existing briefing before PRD generation — the agent audits (findings), the CLI renders `review.html` (`aioson briefing:review`), you decide in the browser, structured feedback is applied back (`aioson briefing:apply-feedback`), and the loop repeats until nothing blocks the PRD.
+- **When:** a briefing exists but needs corrections, scope trims, or decisions; optionally a clickable prototype (and a reference-image visual identity) before @product.
+- **Options:** none — it locates the briefing by slug or asks which one.
+- **Typical:** `/briefing-refiner refine loyalty-program`.
+- **Produces:** review rounds (`review.html` + feedback JSON + report, archived per round) and the updated briefing (contract preserved); optionally `identity.md` + `prototype.html`.
+- **Next:** `@product` (after `aioson briefing:approve`), or prototype mode first for rich surfaces.
+
+## @dev
+
+- **What:** implements features per the spec/plan — code, migrations, interfaces, tests; drives all phases in one continuous run.
+- **When:** implementation entry point, resume after a break, or QA corrections.
+- **Options:** `--auto` (arm autopilot from here: implementation + review cycle run autonomously), `--step` (disarm autopilot for this feature — stop at the `@qa` handoff even in an always-autopilot project).
+- **Typical:** `/dev --auto`, `/dev` (follows the seeded scheme/flag), `/dev continue feature checkout`.
+- **Produces:** the implementation + tests, `spec-{slug}.md` updates, `dev-state.md` checkpoints.
+- **Next:** `@qa` (hub of the post-dev review cycle).
+
+## @deyvin
+
+- **What:** continuity-first pair programming — recovers recent context, works in small validated slices. Alias: `/pair`.
+- **When:** resuming known work, debugging together, a bounded fix on existing context.
+- **Options:** none. Hard boundary: new project/feature, broad redesign, or mixed product+UX+implementation scope → hands off immediately, never codes first.
+- **Typical:** `/deyvin continue yesterday's fix`, `/pair debug the failing upload test`.
+- **Produces:** the validated slice + session continuity records.
+- **Next:** the proper workflow agent when scope expands (`@product`/`@dev`).
+
+## @discover
+
+- **What:** reads key files/artifacts and builds the semantic knowledge cache in `.aioson/context/bootstrap/` (what the system is, does, how it works, current state).
+- **When:** session start on broad work, after big landings, or when agents warn `bootstrap < 4/4` / stale.
+- **Options:** none.
+- **Typical:** `/discover` (full refresh).
+- **Produces:** `bootstrap/how-it-works.md`, `bootstrap/current-state.md` (+ archive), instant context for every other agent.
+- **Next:** whatever agent you originally needed — discover is a preparation step.
+
+## @neo
+
+- **What:** the system router — shows the full picture (project state, workflow stage, pending work) and routes you to the right agent. Never implements, never produces artifacts.
+- **When:** you are lost, between features, or unsure which agent/lane fits the task.
+- **Options:** none.
+- **Typical:** `/neo where are we?`, `/neo what should I run next?`.
+- **Produces:** orientation + a concrete routing recommendation.
+- **Next:** the agent it names.
+
+## @orache
+
+- **What:** deep domain investigation before a squad/product push — real frameworks, anti-patterns, benchmarks, reference voices, vocabulary of the field.
+- **When:** entering an unfamiliar domain, or before `@squad` assembles specialists.
+- **Options:** none — give it the domain/question; it reuses the `researchs/` cache (7-day TTL).
+- **Typical:** `/orache investigate the B2B onboarding-tools market`.
+- **Produces:** a domain dossier + cached research under `researchs/`.
+- **Next:** `@squad`, `@product`, or `@briefing` depending on the goal.
+
+## @orchestrator
+
+- **What:** the MEDIUM spec maestro — fans out to analyst/architect/pm (+ux-ui) as sub-agents and consolidates one gated spec package (requirements, spec with Gates A/B/C, design-doc, readiness, plan, harness contract). MEDIUM only.
+- **When:** feature classified MEDIUM, right after `@product`.
+- **Options:** none at activation — under autopilot it seeds the scheme, completes its stage, and crosses into `@dev` automatically.
+- **Typical:** `/orchestrator continue feature billing-portal`.
+- **Produces:** the gated spec package + `dev-state.md` cold-start packet.
+- **Next:** `@dev`.
+
+## @tester
+
+- **What:** engineering-grade test suite for already-implemented apps — coverage gaps, edge cases, mutation-style checks. Tests what exists; never implements features.
+- **When:** `@qa` flags a coverage gap, or you want a systematic test pass on a finished surface.
+- **Options:** feature-scoped via the workflow (`--feature=<slug>` when invoked through the CLI prompt).
+- **Typical:** `/tester cover feature checkout`, or auto-invoked by `@qa` under autopilot.
+- **Produces:** the test suite + a coverage report; surfaces dev-owned blocking gaps.
+- **Next:** `@dev` (blocking gaps) or back to `@qa` (sign-off).
+
+## @pentester
+
+- **What:** structured adversarial security review — maps the threat surface and produces reproducible findings under an explicit scope contract (not a free-form hacker).
+- **When:** sensitive surface (auth, money, uploads, secrets, external URLs) — via `@qa`'s trigger or on demand.
+- **Options:** `--mode=app_target --feature=<slug> --scope=<target>` via `aioson agent:prompt pentester`.
+- **Typical:** `/pentester review the auth endpoints of feature accounts`.
+- **Produces:** `security-findings-{slug}.json` (owners + severities; `@qa` owns closure).
+- **Next:** `@dev` (open dev-owned findings) or back to `@qa`.
+
+## @qa
+
+- **What:** risk-first review — objective findings, the runtime smoke gate (build + migrate + boot + Core happy-path on the real stack), and the post-dev routing hub.
+- **When:** right after `@dev`; re-verification after corrections.
+- **Options:** none at activation — verdicts and routing are evidence-driven.
+- **Typical:** `/qa verify feature checkout`, or auto-invoked by `@dev` under autopilot.
+- **Produces:** QA report + verdict (PASS/FAIL), Gate D, corrections plans on FAIL.
+- **Next:** `@dev` (FAIL), `@tester`/`@pentester` (triggers), `@validator` (harness contract), or STOP recommending `aioson feature:close` (human gate).
+
+## @sheldon
+
+- **What:** the SMALL single spec authority (lean lane) — PRD gap analysis, sizing, enrichment, and the full collapsed spec package in one pass.
+- **When:** feature classified SMALL, right after `@product`; or PRD quality review on demand.
+- **Options:** none at activation — under autopilot it seeds the scheme, completes its stage (`--complete=sheldon`), and crosses into `@dev` automatically.
+- **Typical:** `/sheldon continue feature quick-filters`.
+- **Produces:** `sheldon-enrichment-{slug}.md`, `spec-{slug}.md` (Gates A/B/C), design-doc, readiness, plan, harness contract, `dev-state.md`.
+- **Next:** `@dev`.

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

@@ -4,28 +4,44 @@ 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.
+
+Execution selection lives in `.aioson/context/agent-execution-{slug}.json`. Validate it before code with `aioson agent:execution:validate`; use `agent:execution:dispatch|resume` for execution. Generated manifests default to `external`: the installed Claude/Codex/OpenCode CLI runs headlessly in a fresh process and writes a bound report. Native subagent/fresh-session modes require an explicit bridge capability; prompt-level chaining is not evidence. The core cannot force a client to open a visible interactive chat window.
+
+Codex entries may use a canonical slug or a human form such as `"model": "GPT 5.6 Terra"`, plus an optional `"reasoning_effort": "high"`. Validation resolves the current local Codex model catalog in conservative tiers: exact slug, normalized display name, unique alias, then a uniquely safe fuzzy match. Version numbers must remain identical, and ambiguous matches pause before process spawn. The manifest remains unchanged; state, reports, CLI output, and telemetry keep `model_requested`, `model_resolved`, and `model_resolution_strategy` separately. When the catalog is unavailable, only `configured-default` and literal model IDs are accepted as unverified fallbacks. Explicit reasoning effort is never silently downgraded or moved to another provider.
+
+Cross-repository writes are opt-in per agent through `writable_roots`. Every path must exist, be a directory, contain no traversal, and is canonicalized before dispatch and recorded in state/report. Codex maps roots to repeated `exec --add-dir <absolute>` argv; Claude maps to `--add-dir`. OpenCode currently has no verified additional-writable-root flag, so a non-empty list returns `host_capability_missing` rather than widening access silently.
 
 ## Routing — deterministic, never LLM-chosen
 
@@ -45,13 +61,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 +100,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,17 @@ 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:
-   - `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.
+   For every agent with `run: true`, use `aioson agent:execution:dispatch . --feature={slug} --agent={agent} --json`. The resolved manifest is authoritative for host/model/mode. Validate model aliases before dispatch and preserve the distinct requested/resolved model, resolution strategy, and optional reasoning effort in state and reports; ambiguity or an unsupported effort is a real pause before spawn. A `unsupported_capability` or `manifest_invalid` result is also a real pause: never imitate a sub-agent or fresh session in prose. Only `external` execution backed by an installed CLI, or a native capability explicitly exposed by the current harness, may run.
+   - `mode: external` → the portable default: an installed host CLI runs headlessly in a fresh process, waits for exit, and must write the bound JSON report. This creates an isolated headless context, not a new interactive chat window.
    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 +42,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/schemas/agent-execution.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aioson.dev/schemas/agent-execution-v1.json",
+  "title": "AIOSON Agent Execution Manifest",
+  "type": "object",
+  "required": ["version", "feature", "host", "agents", "capacity_policy", "cycle_limits", "reporting"],
+  "properties": {
+    "version": { "const": 1 },
+    "feature": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "host": { "enum": ["claude", "codex", "opencode"] },
+    "agents": {
+      "type": "object",
+      "required": ["dev", "qa", "tester", "pentester", "validator"],
+      "additionalProperties": false,
+      "properties": {
+        "dev": { "$ref": "#/$defs/agent" }, "qa": { "$ref": "#/$defs/agent" }, "tester": { "$ref": "#/$defs/agent" }, "pentester": { "$ref": "#/$defs/agent" }, "validator": { "$ref": "#/$defs/agent" }
+      }
+    }
+  },
+  "$defs": {
+    "agent": {
+      "type": "object", "additionalProperties": false,
+      "required": ["enabled", "host", "mode", "model", "writable_roots", "fallbacks", "report"],
+      "properties": { "enabled": {"type":"boolean"}, "host":{"enum":["claude","codex","opencode"]}, "mode":{"enum":["fresh-session","subagent","external","current-session"]}, "model":{"type":"string","minLength":1,"maxLength":200}, "reasoning_effort":{"enum":["low","medium","high","xhigh","max","ultra"]}, "writable_roots":{"type":"array","items":{"type":"string","minLength":1}}, "fallbacks":{"type":"array"}, "report":{"type":"string"} }
+    }
+  },
+  "additionalProperties": false
+}

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 |