@jaimevalasek/aioson 1.18.0 → 1.20.0

package/src/constants.js

@@ -190,6 +190,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'setup',
     displayName: 'Setup',
+    description: 'Project onboarding and context setup',
     command: '@setup',
     path: '.aioson/agents/setup.md',
     dependsOn: [],
@@ -198,6 +199,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'discovery-design-doc',
     displayName: 'Discovery/Design Doc',
+    description: 'Discovery and design doc generation',
     command: '@discovery-design-doc',
     path: '.aioson/agents/discovery-design-doc.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -206,6 +208,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'discover',
     displayName: 'Discover',
+    description: 'Semantic knowledge discovery and bootstrap cache generation',
     command: '@discover',
     path: '.aioson/agents/discover.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -214,6 +217,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'product',
     displayName: 'Product',
+    description: 'Product vision, PRD and feature scoping',
     command: '@product',
     path: '.aioson/agents/product.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -222,6 +226,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'deyvin',
     displayName: 'Deyvin',
+    description: 'Pair programming partner for continuity sessions',
     command: '@deyvin',
     path: '.aioson/agents/deyvin.md',
     aliases: ['pair'],
@@ -231,6 +236,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'analyst',
     displayName: 'Analyst',
+    description: 'Domain discovery and entity mapping (SMALL/MEDIUM)',
     command: '@analyst',
     path: '.aioson/agents/analyst.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -239,6 +245,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'architect',
     displayName: 'Architect',
+    description: 'Project structure and technical decisions (SMALL/MEDIUM)',
     command: '@architect',
     path: '.aioson/agents/architect.md',
     dependsOn: [
@@ -250,6 +257,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'ux-ui',
     displayName: 'UI/UX',
+    description: 'UI/UX design system and component spec (SMALL/MEDIUM)',
     command: '@ux-ui',
     path: '.aioson/agents/ux-ui.md',
     dependsOn: [
@@ -263,6 +271,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'pm',
     displayName: 'PM',
+    description: 'Backlog and user stories (MEDIUM only)',
     command: '@pm',
     path: '.aioson/agents/pm.md',
     dependsOn: [
@@ -277,6 +286,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'dev',
     displayName: 'Dev',
+    description: 'Feature implementation (any stack)',
     command: '@dev',
     path: '.aioson/agents/dev.md',
     dependsOn: [
@@ -289,8 +299,14 @@ const AGENT_DEFINITIONS = [
   {
     id: 'pentester',
     displayName: 'Pentester',
+    description: 'Adversarial security review and threat-surface mapping',
     command: '@pentester',
     path: '.aioson/agents/pentester.md',
+    flags: [
+      { name: 'mode', value: 'framework_target|app_target', description: 'Target mode for security review' },
+      { name: 'feature', value: '<slug>', description: 'Feature slug (required for app_target)' },
+      { name: 'scope', value: '<scope>', description: 'Target scope (required for app_target)' }
+    ],
     dependsOn: [
       '.aioson/context/project.context.md',
       '.aioson/context/spec-{slug}.md (active feature)'
@@ -300,6 +316,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'qa',
     displayName: 'QA',
+    description: 'Risk-first review and test generation (SMALL/MEDIUM)',
     command: '@qa',
     path: '.aioson/agents/qa.md',
     dependsOn: ['.aioson/context/discovery.md'],
@@ -308,6 +325,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'validator',
     displayName: 'Validator',
+    description: 'Technical validation against success contract',
     command: '@validator',
     path: '.aioson/agents/validator.md',
     dependsOn: [
@@ -319,6 +337,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'tester',
     displayName: 'Tester',
+    description: 'Systematic test engineering for implemented apps (all sizes)',
     command: '@tester',
     path: '.aioson/agents/tester.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -327,6 +346,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'orchestrator',
     displayName: 'Orchestrator',
+    description: 'Session protocol and parallel execution (MEDIUM)',
     command: '@orchestrator',
     path: '.aioson/agents/orchestrator.md',
     dependsOn: [
@@ -342,6 +362,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'squad',
     displayName: 'Squad',
+    description: 'Squad assembly and management',
     command: '@squad',
     path: '.aioson/agents/squad.md',
     dependsOn: [],
@@ -351,6 +372,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'orache',
     displayName: 'Orache',
+    description: 'Domain investigation and strategic research',
     command: '@orache',
     path: '.aioson/agents/orache.md',
     dependsOn: [],
@@ -359,6 +381,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'genome',
     displayName: 'Genome',
+    description: 'Domain genome creation and application',
     command: '@genome',
     path: '.aioson/agents/genome.md',
     dependsOn: [],
@@ -367,6 +390,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'design-hybrid-forge',
     displayName: 'Design Hybrid Forge',
+    description: 'Generate hybrid design skill from two visual parents',
     command: '@design-hybrid-forge',
     path: '.aioson/agents/design-hybrid-forge.md',
     dependsOn: ['.aioson/context/project.context.md'],
@@ -375,14 +399,61 @@ const AGENT_DEFINITIONS = [
   {
     id: 'site-forge',
     displayName: 'Site Forge',
+    description: 'Clone, extract, and forge sites and design skills from any URL',
     command: '@site-forge',
     path: '.aioson/agents/site-forge.md',
     dependsOn: ['.aioson/context/project.context.md'],
     output: 'src/components/*.tsx + src/app/page.tsx + docs/research/{hostname}/ + public/images/{hostname}/'
   },
+  {
+    id: 'neo',
+    displayName: 'Neo',
+    description: 'System router: see the full picture, get guided to the right agent',
+    command: '@neo',
+    path: '.aioson/agents/neo.md',
+    dependsOn: ['.aioson/context/project.context.md'],
+    output: 'routing decision + agent handoff'
+  },
+  {
+    id: 'sheldon',
+    displayName: 'Sheldon',
+    description: 'Deep technical analysis and architecture review',
+    command: '@sheldon',
+    path: '.aioson/agents/sheldon.md',
+    dependsOn: ['.aioson/context/project.context.md'],
+    output: 'enriched PRD or architecture review'
+  },
+  {
+    id: 'committer',
+    displayName: 'Committer',
+    description: 'Professional Git commit generation from changes and context',
+    command: '@committer',
+    path: '.aioson/agents/committer.md',
+    dependsOn: [],
+    output: 'git commit(s)'
+  },
+  {
+    id: 'copywriter',
+    displayName: 'Copywriter',
+    description: 'Conversion-focused marketing copy',
+    command: '@copywriter',
+    path: '.aioson/agents/copywriter.md',
+    dependsOn: [],
+    output: 'marketing copy + content assets'
+  },
+  {
+    id: 'briefing',
+    displayName: 'Briefing',
+    description: 'Pre-production briefings and planning',
+    command: '@briefing',
+    path: '.aioson/agents/briefing.md',
+    dependsOn: ['.aioson/context/project.context.md'],
+    output: '.aioson/briefings/{slug}/'
+  },
   {
     id: 'profiler-researcher',
     displayName: 'Profiler Researcher',
+    description: 'Clone profiler: research phase',
     command: '@profiler-researcher',
     path: '.aioson/agents/profiler-researcher.md',
     dependsOn: [],
@@ -391,6 +462,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'profiler-enricher',
     displayName: 'Profiler Enricher',
+    description: 'Clone profiler: enrichment phase',
     command: '@profiler-enricher',
     path: '.aioson/agents/profiler-enricher.md',
     dependsOn: ['.aioson/profiler-reports/{person-slug}/research-report.md'],
@@ -399,6 +471,7 @@ const AGENT_DEFINITIONS = [
   {
     id: 'profiler-forge',
     displayName: 'Profiler Forge',
+    description: 'Clone profiler: forge and validate',
     command: '@profiler-forge',
     path: '.aioson/agents/profiler-forge.md',
     dependsOn: ['.aioson/profiler-reports/{person-slug}/enriched-profile.md'],

package/src/i18n/messages/en.js

@@ -19,6 +19,8 @@ module.exports = {
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=en]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|opencode] [--lang=<bcp47-tag>] [--locale=en]',
+    help_agent_help:
+      'aioson agent:help [agent] [--json]',
     help_agent_invoke:
       'aioson agent:invoke <agent> [path] [--tool=codex|claude|gemini|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=en]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=en]',
@@ -219,7 +221,7 @@ module.exports = {
     help_runtime_emit:
       'aioson runtime:emit [path] --agent=<name> [--type=<event>] [--summary=<text>] [--title=<text>] [--refs=<file[,file2]>] [--plan-step=<id>] [--meta=<json>] [--json] [--locale=en]',
     help_live_start:
-      'aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<name> [--tool-bin=<binary>] [--permission-mode=default|yolo] [--tool-args=<args>] [--title=<text>] [--goal=<text>] [--plan=<file>] [--session=<key>] [--message=<text>] [--attach] [--no-launch] [--tmux] [--json] [--locale=en]',
+      'aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<name> [--tool-bin=<binary>] [--permission-mode=default|yolo] [--tool-args=<args>] [--title=<text>] [--goal=<text>] [--plan=<file>] [--session=<key>] [--message=<text>] [--attach] [--no-launch] [--tmux] [--json] [--locale=en]',
     help_live_status:
       'aioson live:status [path] [--agent=<name>] [--limit=8] [--watch=2] [--format=compact|tmux-bar] [--json] [--locale=en]',
     help_live_handoff:
@@ -505,7 +507,22 @@ module.exports = {
       'Pentester app_target requires --feature=<slug> (or --slug=<slug>).',
     prompt_missing_scope_for_app_target:
       'Pentester app_target requires --scope=<area>.',
-    prompt_title: 'Prompt for agent "{agent}" on tool "{tool}" (locale: {locale}):'
+    prompt_title: 'Prompt for agent "{agent}" on tool "{tool}" (locale: {locale}):',
+    help_available: 'Available agents:',
+    help_run_detail: 'Run "aioson agent:help <name>" for details on a specific agent.',
+    help_usage: 'Usage:',
+    help_claude_code: '(Claude Code)',
+    help_common_options: 'Common options:',
+    help_opt_tool: 'Target tool (codex|claude|gemini|opencode)',
+    help_opt_language: 'Interaction language (e.g., pt-BR, en)',
+    help_opt_headless: 'Output prompt only, no runtime tracking',
+    help_opt_output: 'Save headless prompt to file',
+    help_opt_json: 'JSON output mode',
+    help_agent_options: 'Agent-specific options ({command}):',
+    help_requires: 'Requires:',
+    help_produces: 'Produces:',
+    help_instruction_file: 'Instruction file:',
+    help_unknown_agent: 'Unknown agent: {agent}'
   },
   context_validate: {
     missing_file: 'Context file not found: {path}',
@@ -1090,11 +1107,11 @@ module.exports = {
     plan_not_found: 'Plan file not found: {plan}',
     no_active_session: 'No active live session found for {agent}.',
     session_not_active: 'Live session for {agent} is not active.',
-    json_requires_no_launch: '--json requires --no-launch for live:start because foreground launch is interactive.',
-    tool_binary_not_found: 'Tool binary not found in PATH: {binary}',
-    tool_mismatch: 'Active session uses tool "{existing}" but --tool={requested} was given. Close the session first or use the same tool.',
-    tool_mismatch_auto_closed: 'Previous live session used "{existing}" and was auto-closed. Starting a new session with "{requested}".',
-    micro_task_already_open: 'A live micro-task is already open for {agent}. Emit task_completed before task_started again.',
+    json_requires_no_launch: '--json requires --no-launch for live:start because foreground launch is interactive.',
+    tool_binary_not_found: 'Tool binary not found in PATH: {binary}',
+    tool_mismatch: 'Active session uses tool "{existing}" but --tool={requested} was given. Close the session first or use the same tool.',
+    tool_mismatch_auto_closed: 'Previous live session used "{existing}" and was auto-closed. Starting a new session with "{requested}".',
+    micro_task_already_open: 'A live micro-task is already open for {agent}. Emit task_completed before task_started again.',
     handoff_same_agent: 'live:handoff requires different --agent and --to values.',
     handoff_agent_mismatch: 'No active live session found for {agent}.',
     watch_json_conflict: '--watch cannot be combined with --json.',

package/src/i18n/messages/es.js

@@ -20,6 +20,8 @@ module.exports = {
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=es]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|opencode] [--lang=<bcp47-tag>] [--locale=es]',
+    help_agent_help:
+      'aioson agent:help [agent] [--json]',
     help_agent_invoke:
       'aioson agent:invoke <agent> [path] [--tool=codex|claude|gemini|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=es]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=es]',
@@ -383,7 +385,22 @@ module.exports = {
       'Pentester app_target requiere --feature=<slug> (o --slug=<slug>).',
     prompt_missing_scope_for_app_target:
       'Pentester app_target requiere --scope=<area>.',
-    prompt_title: 'Prompt para el agente "{agent}" en la herramienta "{tool}" (locale: {locale}):'
+    prompt_title: 'Prompt para el agente "{agent}" en la herramienta "{tool}" (locale: {locale}):',
+    help_available: 'Agentes disponibles:',
+    help_run_detail: 'Ejecute "aioson agent:help <nombre>" para detalles de un agente específico.',
+    help_usage: 'Uso:',
+    help_claude_code: '(Claude Code)',
+    help_common_options: 'Opciones comunes:',
+    help_opt_tool: 'Herramienta destino (codex|claude|gemini|opencode)',
+    help_opt_language: 'Idioma de interacción (ej: pt-BR, en)',
+    help_opt_headless: 'Solo salida del prompt, sin rastreo de runtime',
+    help_opt_output: 'Guardar prompt headless en archivo',
+    help_opt_json: 'Modo de salida JSON',
+    help_agent_options: 'Opciones específicas del agente ({command}):',
+    help_requires: 'Requiere:',
+    help_produces: 'Produce:',
+    help_instruction_file: 'Archivo de instrucción:',
+    help_unknown_agent: 'Agente desconocido: {agent}'
   },
   context_validate: {
     missing_file: 'Archivo de contexto no encontrado: {path}',

package/src/i18n/messages/fr.js

@@ -20,6 +20,8 @@ module.exports = {
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=fr]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|opencode] [--lang=<bcp47-tag>] [--locale=fr]',
+    help_agent_help:
+      'aioson agent:help [agent] [--json]',
     help_agent_invoke:
       'aioson agent:invoke <agent> [path] [--tool=codex|claude|gemini|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=fr]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=fr]',
@@ -382,7 +384,22 @@ module.exports = {
       'Pentester app_target exige --feature=<slug> (ou --slug=<slug>).',
     prompt_missing_scope_for_app_target:
       'Pentester app_target exige --scope=<area>.',
-    prompt_title: 'Prompt pour l agent "{agent}" sur l outil "{tool}" (locale : {locale}) :'
+    prompt_title: 'Prompt pour l agent "{agent}" sur l outil "{tool}" (locale : {locale}) :',
+    help_available: 'Agents disponibles :',
+    help_run_detail: 'Exécutez "aioson agent:help <nom>" pour les détails d un agent spécifique.',
+    help_usage: 'Utilisation :',
+    help_claude_code: '(Claude Code)',
+    help_common_options: 'Options communes :',
+    help_opt_tool: 'Outil cible (codex|claude|gemini|opencode)',
+    help_opt_language: 'Langue d interaction (ex : pt-BR, en)',
+    help_opt_headless: 'Sortie du prompt uniquement, sans suivi runtime',
+    help_opt_output: 'Enregistrer le prompt headless dans un fichier',
+    help_opt_json: 'Mode de sortie JSON',
+    help_agent_options: 'Options spécifiques de l agent ({command}) :',
+    help_requires: 'Requiert :',
+    help_produces: 'Produit :',
+    help_instruction_file: 'Fichier d instruction :',
+    help_unknown_agent: 'Agent inconnu : {agent}'
   },
   context_validate: {
     missing_file: 'Fichier de contexte introuvable : {path}',

package/src/i18n/messages/pt-BR.js

@@ -20,6 +20,8 @@ module.exports = {
     help_agents: 'aioson agents [path] [--lang=<bcp47-tag>] [--locale=pt-BR]',
     help_agent_prompt:
       'aioson agent:prompt <agent> [path] [--tool=codex|claude|gemini|opencode] [--lang=<bcp47-tag>] [--locale=pt-BR]',
+    help_agent_help:
+      'aioson agent:help [agent] [--json]',
     help_agent_invoke:
       'aioson agent:invoke <agent> [path] [--tool=codex|claude|gemini|opencode] [--mode=framework_target|app_target] [--feature=<slug>] [--scope=<area>] [--lang=<bcp47-tag>] [--locale=pt-BR]',
     help_context_validate: 'aioson context:validate [path] [--json] [--locale=pt-BR]',
@@ -217,7 +219,7 @@ module.exports = {
     help_runtime_emit:
       'aioson runtime:emit [path] --agent=<nome> [--type=<evento>] [--summary=<texto>] [--title=<texto>] [--refs=<arquivo[,arquivo2]>] [--plan-step=<id>] [--meta=<json>] [--json] [--locale=pt-BR]',
     help_live_start:
-      'aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<nome> [--tool-bin=<binario>] [--permission-mode=default|yolo] [--tool-args=<args>] [--title=<texto>] [--goal=<texto>] [--plan=<arquivo>] [--session=<chave>] [--message=<texto>] [--attach] [--no-launch] [--tmux] [--json] [--locale=pt-BR]',
+      'aioson live:start [path] --tool=codex|claude|gemini|opencode --agent=<nome> [--tool-bin=<binario>] [--permission-mode=default|yolo] [--tool-args=<args>] [--title=<texto>] [--goal=<texto>] [--plan=<arquivo>] [--session=<chave>] [--message=<texto>] [--attach] [--no-launch] [--tmux] [--json] [--locale=pt-BR]',
     help_live_status:
       'aioson live:status [path] [--agent=<nome>] [--limit=8] [--watch=2] [--format=compact|tmux-bar] [--json] [--locale=pt-BR]',
     help_live_handoff:
@@ -477,7 +479,22 @@ module.exports = {
       'Pentester app_target exige --feature=<slug> (ou --slug=<slug>).',
     prompt_missing_scope_for_app_target:
       'Pentester app_target exige --scope=<area>.',
-    prompt_title: 'Prompt para o agente "{agent}" na ferramenta "{tool}" (locale: {locale}):'
+    prompt_title: 'Prompt para o agente "{agent}" na ferramenta "{tool}" (locale: {locale}):',
+    help_available: 'Agentes disponíveis:',
+    help_run_detail: 'Execute "aioson agent:help <nome>" para detalhes de um agente específico.',
+    help_usage: 'Uso:',
+    help_claude_code: '(Claude Code)',
+    help_common_options: 'Opções comuns:',
+    help_opt_tool: 'Ferramenta alvo (codex|claude|gemini|opencode)',
+    help_opt_language: 'Idioma de interação (ex: pt-BR, en)',
+    help_opt_headless: 'Saída apenas do prompt, sem rastreamento de runtime',
+    help_opt_output: 'Salvar prompt headless em arquivo',
+    help_opt_json: 'Modo de saída JSON',
+    help_agent_options: 'Opções específicas do agente ({command}):',
+    help_requires: 'Requer:',
+    help_produces: 'Produz:',
+    help_instruction_file: 'Arquivo de instrução:',
+    help_unknown_agent: 'Agente desconhecido: {agent}'
   },
   context_validate: {
     missing_file: 'Arquivo de contexto nao encontrado: {path}',
@@ -1116,11 +1133,11 @@ module.exports = {
     plan_not_found: 'Arquivo de plano nao encontrado: {plan}',
     no_active_session: 'Nenhuma sessao live ativa encontrada para {agent}.',
     session_not_active: 'A sessao live de {agent} nao esta ativa.',
-    json_requires_no_launch: '--json requer --no-launch para live:start porque o lancamento em primeiro plano e interativo.',
-    tool_binary_not_found: 'Binario da ferramenta nao encontrado no PATH: {binary}',
-    tool_mismatch: 'A sessao ativa usa a ferramenta "{existing}" mas --tool={requested} foi informado. Encerre a sessao primeiro ou use a mesma ferramenta.',
-    tool_mismatch_auto_closed: 'A sessao live anterior usava "{existing}" e foi fechada automaticamente. Iniciando nova sessao com "{requested}".',
-    micro_task_already_open: 'Uma micro-tarefa live ja esta aberta para {agent}. Emita task_completed antes de task_started novamente.',
+    json_requires_no_launch: '--json requer --no-launch para live:start porque o lancamento em primeiro plano e interativo.',
+    tool_binary_not_found: 'Binario da ferramenta nao encontrado no PATH: {binary}',
+    tool_mismatch: 'A sessao ativa usa a ferramenta "{existing}" mas --tool={requested} foi informado. Encerre a sessao primeiro ou use a mesma ferramenta.',
+    tool_mismatch_auto_closed: 'A sessao live anterior usava "{existing}" e foi fechada automaticamente. Iniciando nova sessao com "{requested}".',
+    micro_task_already_open: 'Uma micro-tarefa live ja esta aberta para {agent}. Emita task_completed antes de task_started novamente.',
     handoff_same_agent: 'live:handoff requer valores diferentes para --agent e --to.',
     handoff_agent_mismatch: 'Nenhuma sessao live ativa encontrada para {agent}.',
     watch_json_conflict: '--watch nao pode ser combinado com --json.',

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

@@ -228,6 +228,8 @@ Before the first code change, decide which dev docs must be loaded:
 
 Do not preload these docs if the current slice does not need them.
 
+Before touching code, if `aioson` is available, run `aioson feature:sweep . --dry-run --json` to detect done features not yet archived. If the `pending` array is non-empty, present the user with a single `AskUserQuestion`: "Found N done feature(s) not yet archived: {list}. Archive now?" with options "(Recomendado) Sim, arquivar agora" and "Não, seguir sem arquivar". If yes, run `aioson feature:sweep .` and report the result. This step is advisory — never block session start.
+
 ## Execution invariants
 
 These rules apply even if no extra dev doc was loaded:

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

@@ -90,6 +90,7 @@ Run this after the immediate scope gate and before touching code:
 6. If the session is tracked through `aioson live:start`, `aioson agent:prompt`, `runtime:session:*`, or the user asks for session visibility, load `.aioson/docs/deyvin/runtime-handoffs.md`
 7. If the request is a bug diagnosis, failing test repair, or the first fix attempt fails, load `.aioson/docs/deyvin/debugging-escalation.md`
 8. Do not touch code until all required modules have been loaded
+9. If `aioson` is available, run `aioson feature:sweep . --dry-run --json` to detect done features not yet archived. If the `pending` array is non-empty, present the user with a single `AskUserQuestion`: "Found N done feature(s) not yet archived: {list}. Archive now?" with options "(Recomendado) Sim, arquivar agora" and "Não, seguir sem arquivar". If yes, run `aioson feature:sweep .` and report the result. This step is advisory — never block session start.
 
 ## Working kernel
 

package/template/.claude/commands/aioson/agent/analyst.md

@@ -1,5 +1,16 @@
----
-description: "AIOSON — Domain discovery and entity mapping (SMALL/MEDIUM)"
----
-
-Read `.aioson/agents/analyst.md` and follow all instructions. $ARGUMENTS
+---
+description: "AIOSON — Domain discovery and entity mapping (SMALL/MEDIUM)"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@analyst — Domain discovery and entity mapping (SMALL/MEDIUM)
+Usage: /aioson:agent:analyst [task description]
+Requires:
+  .aioson/context/project.context.md
+Produces: .aioson/context/discovery.md
+Instruction file: .aioson/agents/analyst.md
+CLI help: aioson agent:help analyst
+
+Otherwise: Read `.aioson/agents/analyst.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/architect.md

@@ -1,5 +1,17 @@
----
-description: "AIOSON — Project structure and technical decisions (SMALL/MEDIUM)"
----
-
-Read `.aioson/agents/architect.md` and follow all instructions. $ARGUMENTS
+---
+description: "AIOSON — Project structure and technical decisions (SMALL/MEDIUM)"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@architect — Project structure and technical decisions (SMALL/MEDIUM)
+Usage: /aioson:agent:architect [task description]
+Requires:
+  .aioson/context/project.context.md
+  .aioson/context/discovery.md
+Produces: .aioson/context/architecture.md
+Instruction file: .aioson/agents/architect.md
+CLI help: aioson agent:help architect
+
+Otherwise: Read `.aioson/agents/architect.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/briefing.md

@@ -1,5 +1,16 @@
----
-description: "AIOSON — Pre-production briefings and planning"
----
-
-Read `.aioson/agents/briefing.md` and follow all instructions. $ARGUMENTS
+---
+description: "AIOSON — Pre-production briefings and planning"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@briefing — Pre-production briefings and planning
+Usage: /aioson:agent:briefing [task description]
+Requires:
+  .aioson/context/project.context.md
+Produces: .aioson/briefings/{slug}/
+Instruction file: .aioson/agents/briefing.md
+CLI help: aioson agent:help briefing
+
+Otherwise: Read `.aioson/agents/briefing.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/committer.md

@@ -1,5 +1,16 @@
----
-description: "AIOSON — Professional Git commit generation from changes and context"
----
-
-Read `.aioson/agents/committer.md` and follow all instructions. $ARGUMENTS
+---
+description: "AIOSON — Professional Git commit generation from changes and context"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@committer — Professional Git commit generation from changes and context
+Usage: /aioson:agent:committer [task description]
+Requires:
+  (none)
+Produces: git commit(s)
+Instruction file: .aioson/agents/committer.md
+CLI help: aioson agent:help committer
+
+Otherwise: Read `.aioson/agents/committer.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/copywriter.md

@@ -1,5 +1,16 @@
----
-description: "AIOSON — Conversion-focused marketing copy"
----
-
-Read `.aioson/agents/copywriter.md` and follow all instructions. $ARGUMENTS
+---
+description: "AIOSON — Conversion-focused marketing copy"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@copywriter — Conversion-focused marketing copy
+Usage: /aioson:agent:copywriter [task description]
+Requires:
+  (none)
+Produces: marketing copy + content assets
+Instruction file: .aioson/agents/copywriter.md
+CLI help: aioson agent:help copywriter
+
+Otherwise: Read `.aioson/agents/copywriter.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/design-hybrid-forge.md

@@ -1,5 +1,16 @@
----
-description: "AIOSON — Generate a hybrid design skill from two visual parents"
----
-
-Read `.aioson/agents/design-hybrid-forge.md` and follow all instructions. $ARGUMENTS
+---
+description: "AIOSON — Generate hybrid design skill from two visual parents"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@design-hybrid-forge — Generate hybrid design skill from two visual parents
+Usage: /aioson:agent:design-hybrid-forge [task description]
+Requires:
+  .aioson/context/project.context.md
+Produces: .aioson/installed-skills/{hybrid-slug}/SKILL.md + .aioson/installed-skills/{hybrid-slug}/references/ + .aioson/installed-skills/{hybrid-slug}/previews/ + .aioson/installed-skills/{hybrid-slug}/.skill-meta.json
+Instruction file: .aioson/agents/design-hybrid-forge.md
+CLI help: aioson agent:help design-hybrid-forge
+
+Otherwise: Read `.aioson/agents/design-hybrid-forge.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/dev.md

@@ -1,5 +1,18 @@
----
-description: "AIOSON — Feature implementation (any stack)"
----
-
-Read `.aioson/agents/dev.md` and follow all instructions. $ARGUMENTS
+---
+description: "AIOSON — Feature implementation (any stack)"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@dev — Feature implementation (any stack)
+Usage: /aioson:agent:dev [task description]
+Requires:
+  .aioson/context/project.context.md
+  .aioson/context/discovery.md
+  .aioson/context/architecture.md
+Produces: code changes
+Instruction file: .aioson/agents/dev.md
+CLI help: aioson agent:help dev
+
+Otherwise: Read `.aioson/agents/dev.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/deyvin.md

@@ -1,5 +1,16 @@
----
-description: "AIOSON — Pair programming partner (alias: pair)"
----
-
-Read `.aioson/agents/deyvin.md` and follow all instructions. $ARGUMENTS
+---
+description: "AIOSON — Pair programming partner for continuity sessions"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@deyvin — Pair programming partner for continuity sessions (aliases: pair)
+Usage: /aioson:agent:deyvin [task description]
+Requires:
+  .aioson/context/project.context.md
+Produces: small code changes + continuity notes in spec.md + runtime logs/tasks
+Instruction file: .aioson/agents/deyvin.md
+CLI help: aioson agent:help deyvin
+
+Otherwise: Read `.aioson/agents/deyvin.md` and follow all instructions. $ARGUMENTS

package/template/.claude/commands/aioson/agent/discover.md

@@ -1,5 +1,16 @@
----
-description: "AIOSON — Semantic knowledge discovery: scan project and generate .aioson/context/bootstrap cache"
----
-
-Read `.aioson/agents/discover.md` and follow all instructions. $ARGUMENTS
+---
+description: "AIOSON — Semantic knowledge discovery and bootstrap cache generation"
+---
+
+If $ARGUMENTS is exactly "--help" or starts with "--help":
+Do NOT activate the agent. Instead, display this help and stop:
+
+@discover — Semantic knowledge discovery and bootstrap cache generation
+Usage: /aioson:agent:discover [task description]
+Requires:
+  .aioson/context/project.context.md
+Produces: .aioson/context/bootstrap/what-is.md + .aioson/context/bootstrap/how-it-works.md + .aioson/context/bootstrap/what-it-does.md + .aioson/context/bootstrap/current-state.md
+Instruction file: .aioson/agents/discover.md
+CLI help: aioson agent:help discover
+
+Otherwise: Read `.aioson/agents/discover.md` and follow all instructions. $ARGUMENTS