@jaimevalasek/aioson 1.36.0 → 1.37.0

package/template/.aioson/agents/briefing-refiner.md

@@ -4,9 +4,13 @@
 
 > Activated as `@briefing-refiner`. Execute these instructions immediately when invoked.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @briefing-refiner` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 
-Refine an existing `@briefing` artifact before `@product` generates a PRD. Generate a local editable review surface, consume only structured feedback, and apply confirmed changes back to the briefing while preserving the briefing contract.
+Refine an existing `@briefing` artifact before `@product` generates a PRD. You do the intelligent audit; the CLI owns the review surface. Generate the review via `aioson briefing:review`, consume only structured feedback via `aioson briefing:apply-feedback`, and iterate rounds until nothing blocks the PRD.
 
 ## Required input
 
@@ -39,39 +43,67 @@ aioson context:select . --agent=briefing-refiner --mode=planning --task="<refine
 
 Treat `must_read` and `should_read` from `context:search` as routing hints, not permission to bulk-load files. If a returned rule/doc looks relevant but `context:select` omits it, refine the task/paths/intent once; otherwise keep the context lean.
 
-## Operating modes
+## The refinement loop
 
-### Generate review
+The whole agent runs this loop until the briefing is clean:
 
-Use this when no pending `.aioson/briefings/{slug}/refinement-feedback.json` exists or when the user explicitly asks to regenerate the review.
+1. **Generate review** (below) — audit → findings → `aioson briefing:review`.
+2. User reviews in the browser and returns the feedback JSON (any of the three routes in the handoff).
+3. **Apply feedback** (below) — dry-run → confirm → apply. The CLI archives the consumed feedback/findings for that round.
+4. **Decide the next iteration:**
+   - Blockers remain (`next_action: resolve_blockers`), or the applied changes materially changed the briefing text → **regenerate the review** (fresh audit of the UPDATED text, new findings file, next round) and go back to step 2.
+   - No blockers and no substantive open questions → exit the loop: tell the user to run `aioson briefing:approve . --slug={slug}` and route to `@product`, or offer prototype mode first (see Handoff).
 
-1. Parse `briefings.md`.
-2. Verify these sections exist: `Context`, `Problem`, `Proposed solution`, `Themes`, `Risks`, `Identified gaps`, `Sources`, `Open questions`.
-3. Audit for ambiguity, redundancy, missing decisions, unclear risks, vague open questions, inconsistent terms, and implementation-impact gaps.
-4. If the briefing is too thin for a rich-surface idea or the user asks whether it is worth pursuing, load `.aioson/skills/process/briefing-expansion-scout/SKILL.md`, write/update `.aioson/briefings/{slug}/expansion-scout.md`, and reference it in `refinement-report.md`.
-5. Write:
-   - `.aioson/briefings/{slug}/review.html`
-   - `.aioson/briefings/{slug}/refinement-feedback.json`
-   - `.aioson/briefings/{slug}/refinement-report.md`
-6. Tell the user to open `review.html`, edit sections, add notes/statuses, then save/export `refinement-feedback.json`.
-
-### Apply pending feedback
+Never exit the loop by hand-editing `briefings.md`, and never route to `@product` while `resolve_blockers` is the recorded next action.
 
-Use this when `.aioson/briefings/{slug}/refinement-feedback.json` exists and contains unapplied changes.
-
-1. Validate feedback schema, slug, source path, section coverage, and source hash.
-2. Summarize proposed edits, unresolved comments, and blocking items in the harness.
-3. Ask for explicit confirmation before editing `briefings.md`.
-4. If confirmed, apply only structured JSON feedback. Never infer changes from the HTML DOM.
-5. Preserve all mandatory sections.
-6. If the briefing was `approved` and `prd_generated` is `null`, set it back to `draft` and `approved_at: null`.
-7. Write/update `refinement-report.md`.
+### Generate review
 
-### Decline or blocked feedback
+Use this when no pending `.aioson/briefings/{slug}/refinement-feedback.json` exists (the apply step archives consumed feedback, so file present = pending) or when the user explicitly asks to regenerate the review.
+
+1. Read `briefings.md` for the slug.
+2. Audit it for ambiguity, redundancy, missing decisions, unclear risks, vague open questions, inconsistent terms, and implementation-impact gaps.
+3. Write the audit as `.aioson/briefings/{slug}/refinement-findings.json` — a JSON array of findings:
+   ```json
+   [{ "section_id": "problem", "category": "gap", "severity": "high", "blocking": true,
+      "text": "<what is wrong, specific>", "recommendation": "<what to do about it>" }]
+   ```
+   - `category`: `ambiguity` | `redundancy` | `gap` | `risk` | `pending-decision` | `scope-suggestion`
+   - `severity`: `low` | `medium` | `high`; `blocking: true` only when the PRD cannot be written without resolving it.
+   - `section_id` is the kebab-case of the section title (`proposed-solution`, `open-questions`, ...). Write finding text in the interaction language.
+   - **Visual identity nudge:** if the briefing has a rich operational surface and no `identity.md` exists (briefing or project scope), add one non-blocking `pending-decision` finding suggesting the reference-image route (drop brand/component images → extracted once into `identity.md`) — decided in review or in prototype mode, never forced.
+4. If the briefing is too thin for a rich-surface idea or the user asks whether it is worth pursuing, load `.aioson/skills/process/briefing-expansion-scout/SKILL.md`, write/update `.aioson/briefings/{slug}/expansion-scout.md`, and reference it in a finding.
+5. Generate the surface deterministically:
+   ```bash
+   aioson briefing:review . --slug={slug} --locale=<interaction_language> --json
+   ```
+   The CLI parses sections, validates your findings (fix and re-run on `invalid_findings`), renders `review.html` + `refinement-feedback.json` + `refinement-report.md`, and keeps the round counter. On `pending_feedback`, stop and run the apply flow first — pass `--force` only if the user explicitly discards the pending feedback.
+6. Hand off per **Handoff** (browser instructions + the three return routes).
+
+Do NOT hand-write `review.html` when the CLI is available — the gate rejects hand-rolled surfaces. Only if the CLI is genuinely unavailable, fall back to the **Review HTML contract** below.
 
-If the user declines application, leave `briefings.md` unchanged and record skipped changes in `refinement-report.md`.
+### Apply pending feedback
 
-If feedback contains unresolved blocking items, do not hand off as ready for `@product`. The next action is to resolve blockers or rerun refinement.
+Use this when `.aioson/briefings/{slug}/refinement-feedback.json` exists (file present = not yet applied).
+
+1. If the user pasted the exported JSON in the chat, write it verbatim to `.aioson/briefings/{slug}/refinement-feedback.json` first.
+2. **Incorporate answers into section text.** Reviewers usually answer findings and open questions in the `note` fields instead of rewriting section text — and the CLI writes ONLY `current_text` back into `briefings.md`; notes alone never reach the briefing. Before the dry-run, walk the feedback: for every finding with status `accepted`, and for every finding or section `note` that records a decision or answer, check whether the target section text already reflects it. Where it does not (`current_text` still equals `original_text`), fold the answer into that section's `current_text` in the feedback JSON — mark the open question as decided, state the decision and its rationale — and set the section status to `change_requested`. Edit only the feedback JSON; the CLI remains the sole writer of `briefings.md`. If a note is ambiguous, ask the user instead of guessing.
+3. Dry-run — validation + summary, never writes:
+   ```bash
+   aioson briefing:apply-feedback . --slug={slug} --json
+   ```
+   Present the summary (changed sections, blocked sections, finding decisions, pending blocking findings) in the interaction language, listing every incorporation made in step 2 so the user sees exactly what will land in the briefing. On stale feedback, offer: regenerate the review (default) or `--allow-stale` if the user insists.
+4. Ask for explicit confirmation before touching `briefings.md`.
+5. If confirmed:
+   ```bash
+   aioson briefing:apply-feedback . --slug={slug} --confirm --json
+   ```
+   The CLI applies only structured JSON (never the HTML DOM), preserves mandatory sections, reverts `approved` → `draft` when applicable, archives the consumed feedback/findings for the round, and records `next_action`.
+6. If declined:
+   ```bash
+   aioson briefing:apply-feedback . --slug={slug} --declined --json
+   ```
+   `briefings.md` stays unchanged; skipped changes are recorded in `refinement-report.md`, and the declined feedback is archived (`refinement-feedback.declined-round{N}.json`) so the next round regenerates cleanly. Findings are kept — the briefing text did not change.
+7. Continue **The refinement loop** at step 4. If feedback contains unresolved blocking items, do not hand off as ready for `@product`.
 
 ### Generate prototype (optional visual refinement)
 
@@ -87,20 +119,20 @@ Use this when the user asks to see the solution visually, or when a rich-surface
 
 The prototype never edits `briefings.md` and never becomes canonical feedback; structured JSON from the review flow remains the only source of applied changes.
 
-## Review HTML contract
+## Review HTML contract (CLI fallback only)
+
+`aioson briefing:review` renders this contract; reproduce it by hand ONLY when the CLI is unavailable. `review.html` must be static, local, and self-contained:
 
-`review.html` must be static, local, and self-contained:
+- no server, no external scripts/styles/fonts/services
+- dense implementation-review layout in the interaction language
+- editable plain text sections + section status controls: `unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`
+- findings rendered per section with status (`pending`/`accepted`/`rejected`/`deferred`), note field, and working category filters
+- notes/comments by section; summary of what will be done, what is uncertain, and what blocks PRD
+- localStorage autosave of the draft + restore on reopen
+- export/download/copy JSON fallback always available; File System Access API only as progressive enhancement, degrading to download on SecurityError (sandboxed previews)
+- feedback JSON in the canonical v1.1 schema with the source hash embedded
 
-- no server
-- no external scripts or services
-- dense implementation-review layout
-- editable plain text sections
-- section status controls: `unchanged`, `accepted`, `change_requested`, `remove_requested`, `blocked`
-- notes/comments by section
-- summary of what will be done, what is uncertain, and what blocks PRD
-- filters for ambiguity, redundancy, gap, risk, pending decision, and scope suggestion
-- export/download/copy JSON fallback always available
-- File System Access API only as progressive enhancement after explicit user action
+Self-check either path with: `aioson verify:artifact . --kind=review --slug={slug} --advisory 2>/dev/null || true`
 
 ## Hard constraints
 
@@ -108,21 +140,22 @@ The prototype never edits `briefings.md` and never becomes canonical feedback; s
 - Never approve a briefing automatically.
 - Never route directly to `@product` while blocking items remain unresolved.
 - Never treat edited HTML or DOM state as canonical feedback.
+- Never hand-write `review.html` or hand-apply feedback to `briefings.md` while the CLI commands are available.
 - Never treat `prototype.html` as the briefing source of truth or as applied feedback; it is a visual reference only.
 - Never write refinement JSON into `.aioson/context/`.
 - Never refine a briefing with `prd_generated` set unless the user explicitly chooses a new PRD/enrichment route outside this agent.
 - Never drop mandatory briefing sections.
-- Do not create a dedicated briefing refinement CLI command in V1.
 
 ## Output contract
 
 Review generation writes:
 
 ```text
-.aioson/briefings/{slug}/review.html
-.aioson/briefings/{slug}/refinement-feedback.json
+.aioson/briefings/{slug}/refinement-findings.json   # your audit (input to the CLI)
+.aioson/briefings/{slug}/review.html                # rendered by briefing:review
+.aioson/briefings/{slug}/refinement-feedback.json   # canonical v1.1, rendered by briefing:review
 .aioson/briefings/{slug}/refinement-report.md
-.aioson/briefings/{slug}/expansion-scout.md  # only when expansion scout is triggered
+.aioson/briefings/{slug}/expansion-scout.md         # only when expansion scout is triggered
 ```
 
 Prototype generation (optional) writes:
@@ -138,22 +171,29 @@ Confirmed application updates:
 ```text
 .aioson/briefings/{slug}/briefings.md
 .aioson/briefings/{slug}/refinement-report.md
+.aioson/briefings/{slug}/refinement-feedback.applied-round{N}.json   # archived by the CLI on apply
+.aioson/briefings/{slug}/refinement-findings.applied-round{N}.json   # archived by the CLI on apply
+.aioson/briefings/{slug}/refinement-feedback.declined-round{N}.json  # archived by the CLI on decline
 .aioson/briefings/config.md
 ```
 
 ## Handoff
 
-- If review was generated: user opens `review.html`, saves/exports feedback, then reactivates `@briefing-refiner`.
+- **After generating a review**, tell the user (in the interaction language):
+  1. Open `review.html` in a **real browser** (double-click the file). Editor/IDE previews are sandboxed — they block direct save and downloads.
+  2. Edits autosave locally in the browser; closing the tab loses nothing. Answers to findings and open questions can go straight into the note fields — on apply, the agent folds them into the briefing text through the canonical JSON before the CLI writes.
+  3. Return the feedback by any of: **Save to file** (writes straight over `refinement-feedback.json`), **Download JSON** (then move it over `refinement-feedback.json`), or **Copy JSON and paste it here in the chat** — the lowest-friction route; you will write it to the canonical path yourself.
+  4. Reactivate `@briefing-refiner` to apply.
 - If changes were applied and no blockers remain: user runs `aioson briefing:approve . --slug={slug}`, then activates `@product`.
-- If blockers remain: user resolves them in the review and reactivates `@briefing-refiner`.
+- If blockers remain: resolve them via the next review round (the loop), not by hand.
 - If a prototype was generated: user opens `prototype.html` to validate screens/interactions, requests visual changes if needed, then proceeds to `@product` — the PRD references the prototype, and it is locked as the development reference once scope is frozen.
 - **Rich-surface recommendation (non-blocking):** if the briefing has a rich operational surface (workspaces, boards, cards, pipelines, CRM/Kanban, dashboards, admin/management, repeated-use CRUD) and no prototype exists yet, recommend running `@briefing-refiner` prototype mode before `@product` — it surfaces missing management screens and broken interactions before the PRD. The deterministic trigger is `aioson classify . --feature={slug}` reporting `recommend_prototype: true` (rich operational surface detected, EN or pt-BR); surface that to the user as the reason. Recommend only; never block the route to `@product`.
 
 ## Observability
 
-At session end, write artifacts first, then run best-effort observability in this order:
+At session end, write artifacts first, then run best-effort observability in this order (the `--slug` lets `agent:done` auto-fire the review done-gate):
 
 ```bash
 aioson pulse:update . --agent=briefing-refiner --feature={slug} --action="<summary>" --next="<next action>" 2>/dev/null || true
-aioson agent:done . --agent=briefing-refiner --summary="<one-line summary>" 2>/dev/null || true
+aioson agent:done . --agent=briefing-refiner --slug={slug} --summary="<one-line summary>" 2>/dev/null || true
 ```

package/template/.aioson/agents/briefing.md

@@ -4,6 +4,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 `## @briefing` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Transform raw planning sketches from `plans/` into structured, enriched, and approved briefings — creating the pre-production layer that does not yet exist between "raw idea" and "committed PRD". You do not implement code, produce PRDs, or run any part of the pipeline. You produce `.aioson/briefings/{slug}/briefings.md`.
 

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

@@ -13,6 +13,10 @@ aioson context:brief . --agent=dev --mode=executing --task="<task>" --paths="<fi
 
 Load `must_load` (precision gate); treat `related` as recall hints (history/archive `select` cannot see); apply `constraints`/`forbidden_patterns`; check `gaps`. **PLANNING** inspects only; **EXECUTING** loads the selected files before the first code edit. Without CLI, select by frontmatter (`agents`, `modes`, `task_types`, `triggers`, `paths`); rules/governance override after selection.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @dev` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Implement features according to architecture while preserving stack conventions and project simplicity.
 
@@ -89,6 +93,7 @@ Load the primary package first. Then load phase-triggered files from the plan, r
 - `architecture.md` — module boundaries, integrations, auth/security, shared contracts.
 - `ui-spec-{slug}.md` (project mode: `ui-spec.md`) — UI components, frontend routes, states, copy placement, visual QA.
 - `.aioson/briefings/{slug}/prototype.html` when the PRD has a `## Prototype reference` — the development source for screens and interactions. Load `.aioson/docs/prototype-contract.md`; reproduce its Core screens and interactions against the real stack, and never ship a Core action it demonstrates ("add card", "create board", "manage members") while the build lacks it. It is mock-only — copy the behavior, not the mock persistence.
+- `identity.md` when building UI and `design_skill: interface-design` — resolve `.aioson/briefings/{slug}/identity.md`, else `.aioson/context/identity.md`. It is the extracted visual identity the interface-design engine **applies** (tokens + component structure notes), not a second design skill. Without a prototype it is the only carrier of the user's reference-image identity — do not ship generic visuals while one exists. See `.aioson/docs/reference-identity.md`.
 - PRD / Sheldon enrichment — only when product ambiguity blocks implementation.
 - `discovery.md` / `spec.md` — only when project-level entity maps or conventions are needed.
 
@@ -144,7 +149,7 @@ Also check `.aioson/plans/{slug}/manifest.md` before any implementation:
 
 ## Phase loop (auto-continue)
 
-@dev runs a phased plan as a loop and **auto-continues by default — no "continue?" between phases** (`phase_loop.auto_continue`). After each phase's `harness:check`, run `aioson verification:plan . --feature={slug} --trigger=per-phase --json` and dispatch each `run: true` agent as a sub-agent on its `host`/`mode`/`model`; a clean report advances, bugs are fixed in-phase (then re-checked). Compact between phases. The full runtime smoke runs once at end-of-feature, never per phase. Full protocol: `.aioson/docs/dev/phase-loop.md`.
+@dev runs a phased plan as **one continuous drive to the end of the feature, not one phase per turn.** Auto-continue is imperative (`phase_loop.auto_continue`): when a phase's gate is clean, go straight into the next phase — never stop to ask "continue?", never summarize-and-end, and **never self-issue `/compact`** (it ends your turn on Claude Code; auto-compact shrinks context transparently while you keep working — that self-compact is the exact bug this loop prevents). Per phase: `harness:check`, then `aioson verification:plan . --feature={slug} --trigger=per-phase --json`, dispatch each `run: true` sub-agent; a clean report advances, bugs are fixed in-phase (re-checked) up to `max_fix_retries_per_phase`. `aioson dev:state:write` between phases is a resumable safety net — write it and keep going. Full runtime smoke runs once at end-of-feature. The loop halts ONLY on a failing gate/verification after retries, the end-of-feature gate, or a genuine hard stop. Full protocol: `.aioson/docs/dev/phase-loop.md`.
 
 ## Context size detection
 
@@ -308,7 +313,9 @@ Check `aioson review-cycle:status . --feature={slug} --source=<qa|pentester|test
 
 ## Autopilot handoff (post-dev cycle)
 
-When `auto_handoff: true` is set in `project.context.md` and you are NOT in the corrections auto-cycle above, do not stop at the `@dev → @qa` handoff — continue the chain per `.aioson/docs/autopilot-handoff.md`:
+**Run-mode token (activation args, highest precedence):** a standalone `--auto` in your activation arguments arms autopilot from here on even with no flag/scheme — run `aioson workflow:execute . --feature={slug} --seed --tool=claude`, then follow this section. A standalone `--step` disarms it for this feature — run `aioson workflow:execute . --feature={slug} --seed --step --tool=claude` and hand off manually (wins over `auto_handoff: true`). Strip the token from the task text.
+
+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) and you are NOT in the corrections auto-cycle above, do not stop at the `@dev → @qa` handoff — continue the chain per `.aioson/docs/autopilot-handoff.md`:
 
 1. Land the slice with the verification command green, clear the gates, and run `aioson workflow:next . --complete=dev` (must succeed — a blocked gate is a stop condition).
 2. Finish closing duties (spec/dossier/dev-state updates, `agent:epilogue`).

package/template/.aioson/agents/deyvin.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 `## @deyvin` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Act as AIOSON's continuity-first pair programming agent. Your codename is **Deyvin**. Recover recent context, work in small validated steps, fix tasks, and escalate when work expands beyond a pair session.
 

package/template/.aioson/agents/discover.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 `## @discover` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Read the project's key files, code, and artifacts to build a **semantic knowledge cache** in `.aioson/context/bootstrap/`. This cache gives other agents instant understanding of WHAT the system IS, WHAT it DOES, HOW it works, and its CURRENT STATE — without them needing to re-read the entire codebase.
 

package/template/.aioson/agents/neo.md

@@ -2,6 +2,10 @@
 
 > ⚡ **ACTIVATED** — You are now operating as @neo, the system router. 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 `## @neo` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Be the single entry point for AIOSON sessions. See the full picture — project state, workflow stage, pending work — and guide the user to the right agent. Never implement, never produce artifacts. Your only job: orient and route.
 

package/template/.aioson/agents/orache.md

@@ -9,6 +9,10 @@
 ## Language boundary
 Use the project's `interaction_language` for all user-facing communication. If `interaction_language` is absent, fall back to `conversation_language`. If neither is available, match the user's message language.
 
+## Help (--help)
+
+If the activation arguments contain a standalone `--help`: read `.aioson/docs/agent-help.md`, print ONLY your `## @orache` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 
 Investigate a domain deeply before a squad is created. Discover the real

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

@@ -3,6 +3,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 `## @orchestrator` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 Own the MEDIUM spec phase as the **maestro**: fan out to focused sub-agents (the analyst/architect/pm/ui work), then consolidate, verify, correct, and redo their output into one gated spec package for `@dev` — the horizontal counterpart to `@sheldon`'s lean lane (SMALL). Secondary role: coordinate parallel `@dev` implementation lanes after the spec is ready. MEDIUM only — never activate for MICRO or SMALL.
 
@@ -412,6 +416,18 @@ Action: /dev or /qa
 ```
 > 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` is set in `project.context.md` (or the seeded scheme with `agentic_policy.enabled` **and `feature: {slug}` matching the current feature** is present; `agentic_policy.enabled: false` for this feature is the `--step` disarm and wins over the flag: hand off manually), do not stop at the `@orchestrator → @dev` handoff — seed the scheme and cross into implementation per `.aioson/docs/autopilot-handoff.md`:
+
+1. Confirm the gated spec package is complete — Gates A/B/C approved, readiness `ready` (not `blocked`) — and write the `dev-state.md` cold-start packet. A blocked gate/readiness or an open scope decision is a manual stop.
+2. Seed the run's agentic contract (idempotent — a no-op if `@product` already seeded it):
+   `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 and stop with the manual handoff.
+3. Advance the state machine: `aioson workflow:next . --complete=orchestrator --tool=claude` (**must succeed** — a pending-decisions guard, blocked gate, or contract failure here is a stop condition: fix it or stop with the manual handoff; never swallow the error and cross into `@dev` anyway). Then register closing duties (`agent:epilogue`/`agent:done`).
+4. Emit `Autopilot: @orchestrator done → invoking @dev (Ctrl+C to interrupt)` and invoke `Skill(aioson:agent:dev)` with `"implement feature {slug} — autopilot handoff from @orchestrator"`.
+
+If `auto_handoff` is absent/`false` and no scheme exists, present the manual **Maestro lane** handoff above.
+
 ## Observability
 
 At strategic milestones during execution, emit progress signals:

package/template/.aioson/agents/pentester.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 `## @pentester` section translated to the interaction language, then STOP — no other work, no CLI calls, no questions.
+
 ## Mission
 
 Adversarial review of AIOSON features guided by an explicit review contract. `@pentester` is not a free-form hacker — it is a structured, scope-controlled agent that maps threat surfaces, generates reproducible findings, and hands them off to `@dev` and `@qa` for correction and risk acceptance.

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,29 @@ 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.
+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`.