@jaimevalasek/aioson 1.17.2 → 1.17.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaimevalasek/aioson",
-  "version": "1.17.2",
+  "version": "1.17.3",
   "description": "AI operating framework for hyper-personalized software.",
   "keywords": [
     "ai",
@@ -46,6 +46,8 @@
     "ci": "npm run lint && npm test"
   },
   "dependencies": {
-    "better-sqlite3": "^12.6.2"
+    "archiver": "^8.0.0",
+    "better-sqlite3": "^12.6.2",
+    "terser": "^5.48.0"
   }
 }

package/src/commands/store-system.js

@@ -6,6 +6,33 @@ const { exists, ensureDir } = require('../utils');
 const { readConfig } = require('./config');
 const { readWorkspace, findProjectRoot } = require('./workspace');
 
+let _terser = null;
+function getTerser() {
+  if (!_terser) _terser = require('terser');
+  return _terser;
+}
+
+async function createZipBuffer(files) {
+  const archiver = require('archiver');
+  const { PassThrough } = require('stream');
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    const stream = new PassThrough();
+    stream.on('data', (chunk) => chunks.push(chunk));
+    stream.on('end', () => resolve(Buffer.concat(chunks)));
+    stream.on('error', reject);
+
+    const archive = archiver('zip', { zlib: { level: 9 } });
+    archive.on('error', reject);
+    archive.pipe(stream);
+
+    for (const [relPath, content] of Object.entries(files)) {
+      archive.append(content, { name: relPath });
+    }
+    archive.finalize();
+  });
+}
+
 const DEFAULT_BASE_URL = 'https://aioson.com';
 const SYSTEM_PACKAGES_DIR = '.aioson/system-packages';
 const BACKUPS_DIR = '.aioson/.backups';
@@ -25,6 +52,17 @@ const SYSTEM_ALLOWED_EXTS = new Set([
   '.gitignore',
 ]);
 
+const SYSTEM_BUILD_ALLOWED_EXTS = new Set([
+  '.js', '.jsx', '.mjs', '.cjs',
+  '.json', '.jsonc',
+  '.css',
+  '.html',
+  '.svg', '.ico',
+  '.sql',
+  '.yaml', '.yml',
+  '.prisma',
+]);
+
 // Dirs/files to skip when collecting sources
 const SKIP_DIRS = new Set([
   'node_modules', '.git', 'dist', 'build', '.turbo', '.next',
@@ -33,13 +71,21 @@ const SKIP_DIRS = new Set([
   '.aioson', '.claude', '.gemini', '.codex', 'researchs',
 ]);
 
+const SKIP_DIRS_BUILD = new Set([
+  'node_modules', '.git', '.turbo', '.next',
+  '.cache', 'coverage', '.nyc_output',
+  'src', 'dashboard/src',
+  '.aioson', '.claude', '.gemini', '.codex', 'researchs',
+]);
+
 const SKIP_FILES = new Set([
   'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml',
   'bun.lockb',
 ]);
 
-const MAX_FILE_BYTES = 512 * 1024;        // 512 KB per file
-const MAX_PACKAGE_BYTES = 20 * 1024 * 1024; // 20 MB total
+const MAX_FILE_BYTES = 512 * 1024;             // 512 KB per file (source)
+const MAX_FILE_BYTES_BUILD = 2 * 1024 * 1024;  // 2 MB per file (compiled bundles)
+const MAX_PACKAGE_BYTES = 20 * 1024 * 1024;    // 20 MB total
 
 /**
  * Parseia lista de emails autorizados a partir de:
@@ -114,15 +160,18 @@ async function storeGet(url, token) {
  * Collect all eligible source files under `dir`.
  * Returns { relativePath: content } — only text files with allowed extensions.
  */
-async function collectSystemFiles(dir) {
+async function collectSystemFiles(dir, { buildMode = false } = {}) {
   const files = {};
   let totalBytes = 0;
   const errors = [];
+  const skipDirs = buildMode ? SKIP_DIRS_BUILD : SKIP_DIRS;
+  const allowedExts = buildMode ? SYSTEM_BUILD_ALLOWED_EXTS : SYSTEM_ALLOWED_EXTS;
 
   async function walk(current, rel) {
     const entries = await fs.readdir(current, { withFileTypes: true });
     for (const entry of entries) {
-      if (SKIP_DIRS.has(entry.name)) continue;
+      if (skipDirs.has(entry.name)) continue;
+      if (rel && skipDirs.has(`${rel}/${entry.name}`)) continue;
       if (SKIP_FILES.has(entry.name)) continue;
 
       const fullPath = path.join(current, entry.name);
@@ -137,12 +186,12 @@ async function collectSystemFiles(dir) {
         ? `.${entry.name.split('.').pop().toLowerCase()}`
         : '';
 
-      // Allow dotfiles with no extension (like .gitignore) that match skip list check
-      if (!SYSTEM_ALLOWED_EXTS.has(ext) && ext !== '') continue;
+      if (!allowedExts.has(ext) && ext !== '') continue;
 
       try {
         const stat = await fs.stat(fullPath);
-        if (stat.size > MAX_FILE_BYTES) {
+        const maxBytes = buildMode ? MAX_FILE_BYTES_BUILD : MAX_FILE_BYTES;
+        if (stat.size > maxBytes) {
           errors.push(`File too large (skipped): "${relPath}" (${(stat.size / 1024).toFixed(0)} KB)`);
           continue;
         }
@@ -151,7 +200,25 @@ async function collectSystemFiles(dir) {
           errors.push(`Package exceeds ${MAX_PACKAGE_BYTES / 1024 / 1024} MB limit — stop collecting.`);
           return;
         }
-        const content = await fs.readFile(fullPath, 'utf8');
+        let content = await fs.readFile(fullPath, 'utf8');
+
+        if (buildMode && (ext === '.js' || ext === '.mjs' || ext === '.cjs')) {
+          try {
+            const terser = getTerser();
+            const result = await terser.minify(content, {
+              compress: { passes: 2, drop_console: false },
+              mangle: {
+                toplevel: true,
+                properties: { regex: /^_/ },
+              },
+              format: { comments: false },
+            });
+            if (result.code) content = result.code;
+          } catch {
+            // terser failed on this file — keep original compiled JS
+          }
+        }
+
         files[relPath] = content;
       } catch {
         // binary or unreadable — skip silently
@@ -231,13 +298,27 @@ async function runSystemPublish({ args, options, logger, t }) {
   const config = await readConfig();
   const token = requireToken(config, t);
   const dir = path.resolve(process.cwd(), args[0] || '.');
+  const buildMode = Boolean(options.build);
 
   logger.log(t('system.publish_reading_manifest'));
   const manifest = await readSystemJson(dir, t);
   logger.log(t('system.package_manifest_ok', { slug: manifest.slug, version: manifest.version, name: manifest.name }));
 
-  logger.log(t('system.package_collecting_files'));
-  const { files, totalBytes, errors } = await collectSystemFiles(dir);
+  if (buildMode) {
+    const buildCmd = manifest.build_command || 'npm run build';
+    logger.log(`Building: ${buildCmd}`);
+    const { execSync } = require('child_process');
+    try {
+      execSync(buildCmd, { cwd: dir, stdio: 'inherit', timeout: 300_000 });
+    } catch (e) {
+      throw new Error(`Build failed: ${e.message}`);
+    }
+    logger.log('Build complete. Collecting compiled output (source excluded)...');
+  } else {
+    logger.log(t('system.package_collecting_files'));
+  }
+
+  const { files, totalBytes, errors } = await collectSystemFiles(dir, { buildMode });
 
   if (errors.length > 0) {
     for (const e of errors) logger.log(`  [WARN] ${e}`);
@@ -268,13 +349,20 @@ async function runSystemPublish({ args, options, logger, t }) {
     return { ok: true, dryRun: true, manifest, fileCount, totalBytes, visibility, authorizedEmails };
   }
 
+  logger.log('Creating ZIP package...');
+  const zipBuffer = await createZipBuffer(files);
+  const zipBase64 = zipBuffer.toString('base64');
+  const zipKb = (zipBuffer.length / 1024).toFixed(1);
+  logger.log(`ZIP: ${zipKb} KB (${fileCount} files)`);
+
   logger.log(t('system.publish_sending'));
   const baseUrl = resolveBaseUrl(config);
   const response = await storePost(`${baseUrl}/api/store/systems/publish`, {
     kind: 'aioson.store.system',
     slug: manifest.slug,
     version: manifest.version,
-    files,
+    zipBase64,
+    files: buildMode ? undefined : files,
     manifest,
     visibility,
     paid,
@@ -283,7 +371,7 @@ async function runSystemPublish({ args, options, logger, t }) {
   }, token);
 
   logger.log(t('system.publish_done', { slug: manifest.slug, url: `${baseUrl}/store/systems/${manifest.slug}` }));
-  logger.log(t('system.publish_summary', { files: fileCount, kb: (totalBytes / 1024).toFixed(1) }));
+  logger.log(t('system.publish_summary', { files: fileCount, kb: zipKb }));
   return { ok: true, manifest, fileCount, totalBytes, visibility, paid, response };
 }
 

package/template/.aioson/agents/analyst.md

@@ -331,7 +331,7 @@ Generate `.aioson/context/discovery.md` with the following sections:
 
 ## Dev handoff producer
 
-Before the final `agent:done` call, when the next agent in the workflow is `@dev`, produce `dev-state.md` so the next `/dev` session auto-resumes on cold start instead of pinging the user for context:
+Before the final `agent:done` call, when the next agent in the workflow is `@dev`, produce `dev-state.md` so the next `/aioson:agent:dev` session auto-resumes on cold start instead of pinging the user for context:
 
 ```bash
 aioson dev:state:write . --feature={slug} --phase=1 \

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

@@ -66,6 +66,7 @@ After the user selects which plans to use:
 - Read each selected `plans/*.md` file fully.
 - Read `project.context.md` for project context.
 - Scan `.aioson/context/` for existing PRDs (`prd*.md`) — load titles/summaries only to avoid duplicating committed work.
+- Also read `.aioson/context/done/MANIFEST.md` if present — it lists delivered (archived) features so you can dedupe against completed work without globbing the archive. Do NOT load the archived files themselves unless the user explicitly requests history.
 
 **2. Enrich**
 
@@ -229,6 +230,7 @@ Always register additional files with a note at the bottom of `briefings.md`:
 - **Never approve a briefing automatically** — approval requires explicit user action via CLI.
 - **Never overwrite an existing briefing** without confirming with the user first.
 - **Slug must be confirmed** by the user before any file is written.
+- **Never recommend `@sheldon` (or any post-PRD agent) as the next step.** The only handoff from `@briefing` is `@product`. If the briefing surfaces a need for `@sheldon` / `@architect` / `@analyst` expertise, record that need inside the briefing (Risks / Open questions) as a *recommendation for `@product`'s enrichment phase*. `@product` decides when to invoke specialists after the PRD exists. See `briefing-craft.md` §1 "Mitigating weak markers" for examples.
 - Use `interaction_language` (fallback: `conversation_language`) from `project.context.md` for all interaction and output.
 
 ## Responsibility boundary
@@ -259,6 +261,6 @@ Always register additional files with a note at the bottom of `briefings.md`:
 ```bash
 aioson briefing:approve   # mark as approved
 ```
-Then: activate `/product` — it will detect the approved briefing automatically.
+Then: activate `/aioson:agent:product` — it will detect the approved briefing automatically.
 > Recommended: `/clear` first — fresh context window
 ---

package/template/.aioson/agents/copywriter.md

@@ -25,7 +25,7 @@ understood, eliminates objections, and drives one clear action.
 ## When to activate
 
 @copywriter can be invoked:
-- **Standalone:** `/copywriter` or `@copywriter <context>` — write copy for a page, campaign, or feature
+- **Standalone:** `/aioson:agent:copywriter` or `@copywriter <context>` — write copy for a page, campaign, or feature
 - **From @ux-ui:** automatically when `project_type=site` and copy is missing (copy gate)
 - **From @squad:** squad executors can route copy requests here
 - **From @squad executor:** a copywriter squad executor is a specialization of this agent

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

@@ -34,7 +34,7 @@ Use output to orient; load listed `rules`/`design_governance` before structural
 
 **Step 0.1 — Bootstrap gate (Living Memory):** read `aioson memory:status .` output. If `Bootstrap < 4/4` or the bootstrap files are older than 30 days, emit a warning at the top of your response:
 
-> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Run `/discover` (or `aioson memory:refresh`) before continuing on broad work.
+> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Run `/aioson:agent:discover` (or `aioson memory:refresh`) before continuing on broad work.
 
 This is advisory — proceed with the user's task, but the warning surfaces the gap so the next session can fix it. Skip when bootstrap/ does not exist (greenfield).
 
@@ -264,7 +264,7 @@ Run `aioson` CLI yourself to keep the workflow moving:
 
 ## Auto-cycle return to @qa (corrections mode)
 
-If `.aioson/runtime/qa-dev-cycle.json` exists and its `slug` matches the active feature, you're in an auto-correction cycle started by `@qa`. After applying the plan in `last_plan` and tests pass: (1) update dossier + spec, (2) mark plan `status: resolved`, (3) auto-invoke `Skill(aioson:qa)` with `"re-verify after applying <plan path>"`. No user prompt — Ctrl+C interrupts. If the file is absent or slug differs, manual handoff as before.
+If `.aioson/runtime/qa-dev-cycle.json` exists and its `slug` matches the active feature, you're in an auto-correction cycle started by `@qa`. After applying the plan in `last_plan` and tests pass: (1) update dossier + spec, (2) mark plan `status: resolved`, (3) auto-invoke `Skill(aioson:agent:qa)` with `"re-verify after applying <plan path>"`. No user prompt — Ctrl+C interrupts. If the file is absent or slug differs, manual handoff as before.
 
 ## Security findings consumption
 

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

@@ -7,14 +7,14 @@ Act as the continuity-first pair programming agent for AIOSON. Your codename is
 
 **Bootstrap gate (Living Memory) — MANDATORY first action:**
 
-Before any other action on `/deyvin` activation, check Living Memory coverage:
+Before any other action on `/aioson:agent:deyvin` activation, check Living Memory coverage:
 
 1. **If `aioson` CLI is available**: run `aioson memory:status .` and read the output.
 2. **If `aioson` CLI is not available**: read `.aioson/context/bootstrap/*.md` directly via filesystem. Count present files (max 4: `what-is.md`, `what-it-does.md`, `how-it-works.md`, `current-state.md`) and the oldest modification date.
 
 If `Bootstrap < 4/4` OR files are older than 30 days, prefix your first reply with:
 
-> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Recommend `/discover` (or `aioson memory:refresh`) before broad work.
+> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Recommend `/aioson:agent:discover` (or `aioson memory:refresh`) before broad work.
 
 This is advisory — continue with the user's task. Skip the gate only when `.aioson/context/bootstrap/` does not exist (greenfield project).
 
@@ -110,14 +110,14 @@ Apply this table deterministically after reading the user's request and consulti
 | Small slice of well-bounded code change; code already partially understood | Handle here (pair execution) |
 | Bug fix with failing test attached, or clear error message + reproducer | Handle here via `debugging-escalation.md` |
 | Diagnosis ambiguous; needs survey of >5 files or tracing a runtime flow | **Spawn sub-task scout** via `aioson scout:prep` (or CLI-less fallback — see "Sub-task scout invocation" below) |
-| New feature, new module, or cross-product surface | Handoff `/product` |
-| Decision affects multiple modules / system-wide architecture | Handoff `/architect` |
-| Missing domain rules, entities, or brownfield knowledge gap | Handoff `/analyst` |
-| PRD exists for the feature but is thin / sized wrong | Handoff `/sheldon` |
-| Visual direction unclear or UI system not defined | Handoff `/ux-ui` |
-| Vague scope, unclear readiness, contradictions | Handoff `/discovery-design-doc` |
-| Larger structured implementation batch that no longer fits pair conversation | Handoff `/dev` |
-| Formal QA / risk review or test pass requested | Handoff `/qa` |
+| New feature, new module, or cross-product surface | Handoff `/aioson:agent:product` |
+| Decision affects multiple modules / system-wide architecture | Handoff `/aioson:agent:architect` |
+| Missing domain rules, entities, or brownfield knowledge gap | Handoff `/aioson:agent:analyst` |
+| PRD exists for the feature but is thin / sized wrong | Handoff `/aioson:agent:sheldon` |
+| Visual direction unclear or UI system not defined | Handoff `/aioson:agent:ux-ui` |
+| Vague scope, unclear readiness, contradictions | Handoff `/aioson:agent:discovery-design-doc` |
+| Larger structured implementation batch that no longer fits pair conversation | Handoff `/aioson:agent:dev` |
+| Formal QA / risk review or test pass requested | Handoff `/aioson:agent:qa` |
 
 **Tie-breakers when two rows apply:**
 1. If the request is ambiguous, escalate (handoff) instead of handling.
@@ -136,7 +136,7 @@ When the rubric routes here ("Diagnosis ambiguous; needs survey of >5 files or t
    - **Claude Code**: Agent tool with `tools: [Read, Grep]`, `disallowedTools: [Bash, Edit, Write]`, `prompt = <returned string>`. Sub-agent writes JSON to the returned `output_path`.
    - **Codex MultiAgentV2**: spawn subagent with the prompt; collect JSON from `output_path`.
    - **Other harnesses lacking isolated sub-agent**: use the CLI-less fallback below.
-4. `aioson scout:validate . --json --input=<output_path>`. On `schema_invalid`, re-prompt the sub-agent with `error.details`. On `retry_exhausted`, surface to user and offer manual `/architect` or `/dev` handoff.
+4. `aioson scout:validate . --json --input=<output_path>`. On `schema_invalid`, re-prompt the sub-agent with `error.details`. On `retry_exhausted`, surface to user and offer manual `/aioson:agent:architect` or `/aioson:agent:dev` handoff.
 5. `aioson scout:commit . --json --input=<output_path>` — telemetry emitted, cap counter decremented.
 6. Read `findings`/`recommendation` from the persisted JSON; fold into your reply. Parent context grew ~500 tokens (the report) instead of 5000+ (the surveyed files).
 
@@ -172,7 +172,7 @@ Dispatch via harness sub-agent with the tool whitelist `[Read, Grep]`. Read the
 
 ### Cap discipline (both paths)
 
-- Default: max **3 scouts per parent session**. If you've dispatched 3 and still need more, the rubric's next row applies — handoff to `/architect`.
+- Default: max **3 scouts per parent session**. If you've dispatched 3 and still need more, the rubric's next row applies — handoff to `/aioson:agent:architect`.
 - Default: max **20 files per scout scope**. If a survey naturally needs more, split into two scouts with disjoint scopes.
 - Defaults are tunable in `.aioson/config/scout-engine.json`.
 

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

@@ -77,7 +77,7 @@ Check these in order. Stop at the first failure:
 | Features archived | `.aioson/context/done/MANIFEST.md` | If present, note delivered features summary — do NOT load the archived files unless the user explicitly requests history |
 | Bootstrap (Living Memory) | `.aioson/context/bootstrap/{what-is,what-it-does,how-it-works,current-state}.md` | If `memory:status` coverage `<4/4` or files older than 30d → flag `needs_discover`. Read `what-is.md` to enrich the project identity line. |
 | Feature dossier | `.aioson/context/features/{slug}/dossier.md` per active feature | Read Why/What + Agent Trail tail. If absent for SMALL/MEDIUM → flag `needs_dossier_init`. |
-| Harness contract | `.aioson/plans/{slug}/{harness-contract,progress}.json` per active feature | Check `progress.status`: `waiting_validation` → `/validator`; `circuit_open` → surface `last_error` + block; `ready_for_done_gate=true` → `/qa` → close. |
+| Harness contract | `.aioson/plans/{slug}/{harness-contract,progress}.json` per active feature | Check `progress.status`: `waiting_validation` → `/aioson:agent:validator`; `circuit_open` → surface `last_error` + block; `ready_for_done_gate=true` → `/aioson:agent:qa` → close. |
 | Brains (procedural) | `.aioson/brains/_index.json` | Confirm presence + count + tags. Loaded by `@dev`/`@sheldon` themselves — `@neo` only signals existence. |
 | Design doc | `.aioson/context/design-doc*.md` | Note presence |
 | Copy exists | `.aioson/context/copy-*.md` | Only relevant when `project_type=site`. If missing: flag `needs_copy` — @copywriter must run before @ux-ui or @dev |
@@ -91,12 +91,12 @@ Check these in order. Stop at the first failure:
 Glob `.aioson/context/noises/*.md`. For each file, count body lines matching `^- \[ \]` (unchecked) versus `^- \[x\]` (checked). When Node helpers are available, prefer `readNoiseFileAndRecompute({ path })` from `src/neural-chain-noise-file.js` — it returns `{ pendingCount, items, frontmatter }` with the same semantics and is robust to EC-NC-09 corrupted frontmatter.
 
 **If any noise file has `pendingCount > 0`:**
-- This is a BLOCKER, not info — routing to any other agent (`/dev`, `/deyvin`, `/qa`, etc.) is paused.
+- This is a BLOCKER, not info — routing to any other agent (`/aioson:agent:dev`, `/aioson:agent:deyvin`, `/aioson:agent:qa`, etc.) is paused.
 - Surface in the dashboard under the ⛔ section, one block per file:
   - Path (relative to project root)
   - `{pendingCount}/{totalCount}` resolved
   - Each pending item: `target_path — {motivo}` (the `motivo` already includes `edge_type` and `confidence` from BR-NC-06)
-- Recommended next action becomes: "Resolve the noise items above (mark `- [x]` once verified or fixed), OR explicitly say *skip noises* and re-activate `/neo` to confirm intent. Routing stays paused until one of those happens."
+- Recommended next action becomes: "Resolve the noise items above (mark `- [x]` once verified or fixed), OR explicitly say *skip noises* and re-activate `/aioson:agent:neo` to confirm intent. Routing stays paused until one of those happens."
 - Set `confidence: low` and `clarification` in the routing block; do NOT recommend a downstream agent until the user resolves or explicitly skips.
 
 **If `pendingCount === 0` across every noise file:** noise files are stale — the next `runChainHookOnAgentDone` invocation (or `chain:audit` call) will `maybeDeleteNoiseFile` them automatically (EC-NC-10 idempotent). Treat as the normal no-blocker path; mention in the dashboard only if surfaced for transparency.
@@ -121,16 +121,16 @@ Based on Step 1 results, classify the project into one of these stages:
 |---|---|---|
 | **Chain audit pending** | `chain_noises_pending` flagged in Step 1.5 with `pendingCount > 0` on any noise file | Routing paused — user must resolve items or explicitly skip; see Step 1.5 |
 | **Not initialized** | config.md missing | Manual: user needs to run `aioson init` |
-| **Needs setup** | `needs_setup` or `needs_setup_repair` | `/setup` |
-| **Needs product definition** | Context valid, no PRD | `/product` |
-| **Needs analysis** | PRD exists, no discovery | `/analyst` |
-| **Needs architecture** | Discovery exists, no architecture | `/architect` |
-| **Needs copy** | `project_type=site`, no `copy-{slug}.md` in `.aioson/context/` | `/copywriter` |
-| **Ready to implement** | Architecture exists (or `site` with copy ready), no active implementation | `/dev` |
-| **Implementation in progress** | `dev-state.md` exists with `status: in_progress` — strongest signal; or spec exists with open items, or feature branch active | `/deyvin` (continuity) or `/dev` (new batch) |
-| **Needs QA** | Implementation looks complete, no QA pass recorded | `/qa` |
+| **Needs setup** | `needs_setup` or `needs_setup_repair` | `/aioson:agent:setup` |
+| **Needs product definition** | Context valid, no PRD | `/aioson:agent:product` |
+| **Needs analysis** | PRD exists, no discovery | `/aioson:agent:analyst` |
+| **Needs architecture** | Discovery exists, no architecture | `/aioson:agent:architect` |
+| **Needs copy** | `project_type=site`, no `copy-{slug}.md` in `.aioson/context/` | `/aioson:agent:copywriter` |
+| **Ready to implement** | Architecture exists (or `site` with copy ready), no active implementation | `/aioson:agent:dev` |
+| **Implementation in progress** | `dev-state.md` exists with `status: in_progress` — strongest signal; or spec exists with open items, or feature branch active | `/aioson:agent:deyvin` (continuity) or `/aioson:agent:dev` (new batch) |
+| **Needs QA** | Implementation looks complete, no QA pass recorded | `/aioson:agent:qa` |
 | **Feature flow** | `prd-{slug}.md` in progress | Detect which stage the feature is in using the same logic |
-| **Parallel execution** | MEDIUM project with implementation plan | `/orchestrator` |
+| **Parallel execution** | MEDIUM project with implementation plan | `/aioson:agent:orchestrator` |
 
 ### Step 4 — Present the dashboard
 
@@ -161,7 +161,7 @@ After presenting the dashboard, ask exactly one question:
 
 - If the stage is clear: "Ready to proceed with `/agent`?"
 - If ambiguous: "What would you like to focus on?" with 2-3 numbered options
-- If everything is done: "Project looks complete. Want to start a new feature, run QA, or do a continuity session with `/deyvin`?"
+- If everything is done: "Project looks complete. Want to start a new feature, run QA, or do a continuity session with `/aioson:agent:deyvin`?"
 
 Then **HALT**. Wait for user input.
 
@@ -172,32 +172,32 @@ Based on the user's answer:
 1. **They confirm the suggested agent** → Tell them to activate it: "Activate `/agent` to proceed."
 2. **They pick a different path** → Validate it makes sense. If it does, confirm. If it skips a critical stage, warn once: "That agent needs {artifact} first. Want to run `/agent` to create it?"
 3. **They describe a task in natural language** → Map it to the right agent:
-   - "I want to build X" → `/product` (if no PRD) or `/dev` (if PRD exists)
-   - "Fix the bug in Y" → `/deyvin`
-   - "Review the code" → `/qa`
-   - "Set up the project" → `/setup`
-   - "I need a new feature" → `/product`
-   - "What changed?" → `/deyvin`
-   - "Run things in parallel" → `/orchestrator`
-   - "Create a squad" → `/squad`
-   - "Research this domain" / "investigate this market" / "competitor scan" → `/orache`
-   - "Write the copy / text for the page" → `/copywriter`
-   - "Create a landing page / sales page" → `/product` (if no PRD) or `/copywriter` (if PRD exists but no copy) or `/ux-ui` (if copy exists)
-   - "Add tests" / "improve coverage" / "no tests" / "shipped without tests" / "test gaps" → `/tester`
-   - "Audit security" / "find security flaws" / "pentest" / "is this secure?" / "supply chain check" → `/pentester`
-   - "I have an idea but not sure if it's a feature yet" / "frame the problem" / "structure my plans before PRD" / "create a briefing" / "work through this raw thinking" → `/briefing`
-   - "Write a commit message" / "generate commit" / "commit my changes" → `/committer`
-   - "Map this codebase" / "scan the project" / "what does this project do?" / "bootstrap context" → `/discover`
-   - "Deep technical analysis of an existing PRD" / "is this a phased plan?" / "size the PRD" / "enrich requirements" → `/sheldon` (PRD-only; never for code archaeology or runtime state)
-   - "Diagnose existing code" / "is this a bug or a missing feature?" / "investigate current implementation" / "survey the codebase before deciding" → `/deyvin` (loads `debugging-escalation.md`; escalates to `/product` if it turns out to be a new feature, never to `/sheldon`)
-   - "Architectural review of an implemented system" / "structural impact of a change" → `/architect`
-   - "Write a discovery / design doc" / "I need a design doc" → `/discovery-design-doc`
-   - "Refine the backlog" / "break PRD into stories" → `/pm`
-   - "Validate against the contract" / "check if it meets the spec" → `/validator`
-   - "Generate a domain genome" / "extract domain knowledge" → `/genome`
-   - "Profile this person" / "build a clone profiler" / "DNA mental" → `/profiler-researcher` (research) → `/profiler-enricher` (enrich) → `/profiler-forge` (advisor)
-   - "Clone this site" / "extract this site's design" / "fork visual style from URL" → `/site-forge`
-   - "Hybrid design from two skills" / "merge two design systems" → `/design-hybrid-forge`
+   - "I want to build X" → `/aioson:agent:product` (if no PRD) or `/aioson:agent:dev` (if PRD exists)
+   - "Fix the bug in Y" → `/aioson:agent:deyvin`
+   - "Review the code" → `/aioson:agent:qa`
+   - "Set up the project" → `/aioson:agent:setup`
+   - "I need a new feature" → `/aioson:agent:product`
+   - "What changed?" → `/aioson:agent:deyvin`
+   - "Run things in parallel" → `/aioson:agent:orchestrator`
+   - "Create a squad" → `/aioson:agent:squad`
+   - "Research this domain" / "investigate this market" / "competitor scan" → `/aioson:agent:orache`
+   - "Write the copy / text for the page" → `/aioson:agent:copywriter`
+   - "Create a landing page / sales page" → `/aioson:agent:product` (if no PRD) or `/aioson:agent:copywriter` (if PRD exists but no copy) or `/aioson:agent:ux-ui` (if copy exists)
+   - "Add tests" / "improve coverage" / "no tests" / "shipped without tests" / "test gaps" → `/aioson:agent:tester`
+   - "Audit security" / "find security flaws" / "pentest" / "is this secure?" / "supply chain check" → `/aioson:agent:pentester`
+   - "I have an idea but not sure if it's a feature yet" / "frame the problem" / "structure my plans before PRD" / "create a briefing" / "work through this raw thinking" → `/aioson:agent:briefing`
+   - "Write a commit message" / "generate commit" / "commit my changes" → `/aioson:agent:committer`
+   - "Map this codebase" / "scan the project" / "what does this project do?" / "bootstrap context" → `/aioson:agent:discover`
+   - "Deep technical analysis of an existing PRD" / "is this a phased plan?" / "size the PRD" / "enrich requirements" → `/aioson:agent:sheldon` (PRD-only; never for code archaeology or runtime state)
+   - "Diagnose existing code" / "is this a bug or a missing feature?" / "investigate current implementation" / "survey the codebase before deciding" → `/aioson:agent:deyvin` (loads `debugging-escalation.md`; escalates to `/aioson:agent:product` if it turns out to be a new feature, never to `/aioson:agent:sheldon`)
+   - "Architectural review of an implemented system" / "structural impact of a change" → `/aioson:agent:architect`
+   - "Write a discovery / design doc" / "I need a design doc" → `/aioson:agent:discovery-design-doc`
+   - "Refine the backlog" / "break PRD into stories" → `/aioson:agent:pm`
+   - "Validate against the contract" / "check if it meets the spec" → `/aioson:agent:validator`
+   - "Generate a domain genome" / "extract domain knowledge" → `/aioson:agent:genome`
+   - "Profile this person" / "build a clone profiler" / "DNA mental" → `/aioson:agent:profiler-researcher` (research) → `/aioson:agent:profiler-enricher` (enrich) → `/aioson:agent:profiler-forge` (advisor)
+   - "Clone this site" / "extract this site's design" / "fork visual style from URL" → `/aioson:agent:site-forge`
+   - "Hybrid design from two skills" / "merge two design systems" → `/aioson:agent:design-hybrid-forge`
    - "What agents exist?" / "show me the menu" / "list the agents" / "agent catalog" / "que agentes existem?" → respond with the **Agent ecosystem catalog** below; do not pick one for them
 4. **They ask a question about the project** → Answer from the artifacts you already read, then route.
 
@@ -208,62 +208,62 @@ AIOSON has 30 official agents grouped by purpose. The default workflow chain use
 ### Workflow chain (default for any feature)
 | Agent | Use when |
 |---|---|
-| `/setup` | Project not initialized or context invalid |
-| `/product` | New feature/product surface needs PRD |
-| `/analyst` | Need entity map, business rules, edge cases |
-| `/architect` | Structural / system-level decisions before implementation |
-| `/ux-ui` | Visual system, component spec, design skill |
-| `/pm` | Refine backlog, break PRD into stories (MEDIUM only) |
-| `/orchestrator` | Run multiple agents in parallel on a MEDIUM feature |
-| `/dev` | Implement a structured slice with PRD/spec already defined |
-| `/qa` | Risk-first review, gate decisions, test coverage check |
-| `/validator` | Validate implementation against the success contract |
+| `/aioson:agent:setup` | Project not initialized or context invalid |
+| `/aioson:agent:product` | New feature/product surface needs PRD |
+| `/aioson:agent:analyst` | Need entity map, business rules, edge cases |
+| `/aioson:agent:architect` | Structural / system-level decisions before implementation |
+| `/aioson:agent:ux-ui` | Visual system, component spec, design skill |
+| `/aioson:agent:pm` | Refine backlog, break PRD into stories (MEDIUM only) |
+| `/aioson:agent:orchestrator` | Run multiple agents in parallel on a MEDIUM feature |
+| `/aioson:agent:dev` | Implement a structured slice with PRD/spec already defined |
+| `/aioson:agent:qa` | Risk-first review, gate decisions, test coverage check |
+| `/aioson:agent:validator` | Validate implementation against the success contract |
 
 ### Continuity & routing
 | Agent | Use when |
 |---|---|
-| `/deyvin` (alias `/pair`) | Pair-programming continuity, small validated slices, "fix bug Y" |
-| `/neo` | (you are here) — orient and route, don't implement |
+| `/aioson:agent:deyvin` (alias `/aioson:agent:pair`) | Pair-programming continuity, small validated slices, "fix bug Y" |
+| `/aioson:agent:neo` | (you are here) — orient and route, don't implement |
 
 ### Quality & risk
 | Agent | Use when |
 |---|---|
-| `/tester` | Coverage gaps, mutation testing, property-based, smell audit on critical paths |
-| `/pentester` | Adversarial review for app or framework — auth, secrets, supply chain, LLM injection |
+| `/aioson:agent:tester` | Coverage gaps, mutation testing, property-based, smell audit on critical paths |
+| `/aioson:agent:pentester` | Adversarial review for app or framework — auth, secrets, supply chain, LLM injection |
 
 ### Discovery & research
 | Agent | Use when |
 |---|---|
-| `/briefing` | Raw plans → structured pre-PRD briefing; problem framing with JTBD/Cagan |
-| `/orache` | Domain investigation, market & competitor research |
-| `/sheldon` | **PRD-only.** Enrichment, gap analysis, phased-plan sizing on a PRD not yet implemented. Never code archaeology or runtime diagnosis. |
-| `/discovery-design-doc` | Living design doc bridging discovery to implementation |
-| `/discover` | Semantic knowledge cache (`bootstrap/`) for instant project understanding |
+| `/aioson:agent:briefing` | Raw plans → structured pre-PRD briefing; problem framing with JTBD/Cagan |
+| `/aioson:agent:orache` | Domain investigation, market & competitor research |
+| `/aioson:agent:sheldon` | **PRD-only.** Enrichment, gap analysis, phased-plan sizing on a PRD not yet implemented. Never code archaeology or runtime diagnosis. |
+| `/aioson:agent:discovery-design-doc` | Living design doc bridging discovery to implementation |
+| `/aioson:agent:discover` | Semantic knowledge cache (`bootstrap/`) for instant project understanding |
 
 ### Content
 | Agent | Use when |
 |---|---|
-| `/copywriter` | Conversion copy, landing pages, marketing text, VSL scripts |
+| `/aioson:agent:copywriter` | Conversion copy, landing pages, marketing text, VSL scripts |
 
 ### Operations
 | Agent | Use when |
 |---|---|
-| `/committer` | Generate semantic commit messages from staged changes |
-| `/squad` | Assemble and manage a parallel squad on a multi-track feature |
-| `/genome` | Extract / apply a domain genome (canonical knowledge) |
+| `/aioson:agent:committer` | Generate semantic commit messages from staged changes |
+| `/aioson:agent:squad` | Assemble and manage a parallel squad on a multi-track feature |
+| `/aioson:agent:genome` | Extract / apply a domain genome (canonical knowledge) |
 
 ### Profiling & cloning (specialized pipelines)
 | Agent | Use when |
 |---|---|
-| `/profiler-researcher` | Phase 1 — research a person/persona for clone-profiler genome |
-| `/profiler-enricher` | Phase 2 — enrich the profile with cognitive structure |
-| `/profiler-forge` | Phase 3 — forge the advisor agent from the genome |
+| `/aioson:agent:profiler-researcher` | Phase 1 — research a person/persona for clone-profiler genome |
+| `/aioson:agent:profiler-enricher` | Phase 2 — enrich the profile with cognitive structure |
+| `/aioson:agent:profiler-forge` | Phase 3 — forge the advisor agent from the genome |
 
 ### Design & site forging
 | Agent | Use when |
 |---|---|
-| `/design-hybrid-forge` | Generate a hybrid design skill from two visual parents |
-| `/site-forge` | Clone, extract, and forge sites or design skills from any URL |
+| `/aioson:agent:design-hybrid-forge` | Generate a hybrid design skill from two visual parents |
+| `/aioson:agent:site-forge` | Clone, extract, and forge sites or design skills from any URL |
 
 ### Routing rules for the catalog
 
@@ -275,18 +275,18 @@ AIOSON has 30 official agents grouped by purpose. The default workflow chain use
 
 `@tester`, `@pentester`, and `@briefing` are official AIOSON agents that sit off the default workflow chain. They're often forgotten — surface them when their triggers match.
 
-**Route to `/tester`** when:
+**Route to `/aioson:agent:tester`** when:
 - The user mentions test gaps, weak coverage, brownfield without baseline tests, shipped-without-tests, "no tests", or coverage below the critical-path target (≥ 90% line / ≥ 80% branch on auth/money/ownership)
 - `@qa` flagged a coverage gap and recommended `@tester`
 - 3+ modules have zero/partial coverage
 
-**Route to `/pentester`** when:
+**Route to `/aioson:agent:pentester`** when:
 - The user wants a security audit, pentest, threat review, or asks "is this secure?"
 - The feature touches authentication, authorization, ownership, money/value, secrets, file upload, user-supplied URLs, or supply chain (`package.json`, lockfiles, GitHub Actions)
 - The feature is LLM-aware (prompts, RAG, agent loops, tool invocation)
 - `@qa` flagged a sensitive surface and recommended `@pentester`
 
-**Route to `/briefing`** when:
+**Route to `/aioson:agent:briefing`** when:
 - The user has raw plans (`plans/*.md`) they want to structure before opening a PRD
 - The user says "I have an idea but I'm not sure if it's a feature yet" or describes something fuzzy that needs problem framing
 - The conversation is generating feature-shaped descriptions and needs JTBD reframing
@@ -302,21 +302,21 @@ For MEDIUM features with sensitive surface, prefer the tracked invocation: `aios
 - Never runs as a persistent session — route and get out of the way
 - Never replaces another agent's judgment
 - Never makes architectural or product decisions
-- Never bypasses the workflow (e.g., routing to `/dev` when no PRD exists)
+- Never bypasses the workflow (e.g., routing to `/aioson:agent:dev` when no PRD exists)
 
 ## Handling edge cases
 
 **User insists on skipping stages:**
-> "I understand the urgency, but `/dev` needs {artifact} to work well. Running `/agent` first takes {estimate}. Want to do that, or use `/deyvin` for a quick focused slice?"
+> "I understand the urgency, but `/aioson:agent:dev` needs {artifact} to work well. Running `/agent` first takes {estimate}. Want to do that, or use `/aioson:agent:deyvin` for a quick focused slice?"
 
 **Multiple features in progress:**
 List them with their stages. Ask which one to continue.
 
 **Brownfield project without discovery:**
-> "This is an existing project but there's no `discovery.md` yet. I recommend `/analyst` to map what exists before making changes."
+> "This is an existing project but there's no `discovery.md` yet. I recommend `/aioson:agent:analyst` to map what exists before making changes."
 
 **User just wants to chat:**
-> "I'm the router — I see the state and point the way. For a working conversation, `/deyvin` is your pair. Want me to route you there?"
+> "I'm the router — I see the state and point the way. For a working conversation, `/aioson:agent:deyvin` is your pair. Want me to route you there?"
 
 ## Output contract
 

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

@@ -351,7 +351,7 @@ If a question is outside product scope, acknowledge it briefly and redirect: "Th
 
 ## Dev handoff producer
 
-When the PRD classification is **MICRO** (next agent will be `@dev` directly without intermediate stages), produce `dev-state.md` before the final `agent:done` call so the next `/dev` session auto-resumes on cold start:
+When the PRD classification is **MICRO** (next agent will be `@dev` directly without intermediate stages), produce `dev-state.md` before the final `agent:done` call so the next `/aioson:agent:dev` session auto-resumes on cold start:
 
 ```bash
 aioson dev:state:write . --feature={slug} \

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

@@ -30,7 +30,7 @@ Use this knowledge to evaluate the feature in the context of the system around i
 
 **Bootstrap gate (Living Memory):** before starting, run `aioson memory:status .` if available. If `Bootstrap < 4/4` or the files are older than 30 days, surface a warning at the top of your QA report:
 
-> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Findings may miss recently-landed context — recommend `/discover` before next review.
+> ⚠ [bootstrap] coverage <N>/4 (or stale <D>d). Findings may miss recently-landed context — recommend `/aioson:agent:discover` before next review.
 
 This is advisory; continue with the review. Skip when bootstrap/ does not exist.
 
@@ -112,7 +112,7 @@ State file: `.aioson/runtime/qa-dev-cycle.json` — `{slug, cycle, started_at, l
 Sequence:
 - Read the file. If absent or `slug` differs → start fresh (`cycle = 0`).
 - **Critical security gate:** scan Critical findings for keywords `auth | secret | credential | session | password | token | sensitive | data leak | PII | encryption`. If any match → DO NOT auto-loop. Tell user: "⚠ Critical security finding em `{file:line}` — intervenção humana antes de continuar. Plano em `{plan path}`." Stop.
-- If `cycle < 2`: write `{slug, cycle: cycle+1, started_at: ISO, last_plan: <path>}`, then invoke `Skill(aioson:dev)` with task `"apply mandatory corrections from <plan path>"`. User can Ctrl+C anytime.
+- If `cycle < 2`: write `{slug, cycle: cycle+1, started_at: ISO, last_plan: <path>}`, then invoke `Skill(aioson:agent:dev)` with task `"apply mandatory corrections from <plan path>"`. User can Ctrl+C anytime.
 - If `cycle >= 2`: delete the file. Tell user: "Auto-cycle de QA→Dev esgotado (2 rounds). Findings remanescentes em `{plan path}`. Intervenção humana necessária."
 
 **Reset:** delete `qa-dev-cycle.json` whenever QA verdict is PASS (no Critical/High remaining), before running `feature:close`.
@@ -159,7 +159,7 @@ Both `@tester` and `@pentester` are official AIOSON agents. Surface them explici
 **Recommend `@validator`** in the report when:
 - `.aioson/plans/{slug}/harness-contract.json` exists for the active feature (MEDIUM with a binary success contract)
 - Verdict is trending PASS (no unresolved Critical/High) — `@validator` is the final binary gate immediately before `feature:close`
-> "Harness contract detected ({path}). Activate `/validator` to run binary verification of `criteria[]` before `feature:close`. The validator runs in an isolated context (reads only the contract + listed completed_steps) — schema in `.aioson/docs/sheldon/harness-contract.md`."
+> "Harness contract detected ({path}). Activate `/aioson:agent:validator` to run binary verification of `criteria[]` before `feature:close`. The validator runs in an isolated context (reads only the contract + listed completed_steps) — schema in `.aioson/docs/sheldon/harness-contract.md`."
 
 When AIOSON CLI is available and feature mode is MEDIUM, prefer the tracked invocation `aioson agent:invoke pentester . --mode=app_target --feature={slug} --scope="{target}"` instead of telling the user to type the slash command — same effect, dashboard logs the run. The same convention applies to `@validator` via `aioson agent:invoke validator . --feature={slug}`.
 

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

@@ -13,9 +13,9 @@ PRD quality guardian. Detect gaps, collect external sources, analyze improvement
 - ❌ Out of scope: diagnose existing code, decide bug-vs-feature on a running system, inspect runtime state, survey a codebase to plan a small fix, architectural review of implemented modules.
 
 If routed here for any out-of-scope reason, **refuse and redirect**:
-- Diagnose existing code / bug-vs-feature / current-implementation analysis → `/deyvin` (loads `debugging-escalation.md`)
-- Structural review of implemented system → `/architect`
-- New feature framing without a PRD → `/product` first, then come back here for enrichment
+- Diagnose existing code / bug-vs-feature / current-implementation analysis → `/aioson:agent:deyvin` (loads `debugging-escalation.md`)
+- Structural review of implemented system → `/aioson:agent:architect`
+- New feature framing without a PRD → `/aioson:agent:product` first, then come back here for enrichment
 
 ## Project rules, docs & design docs
 

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

@@ -517,7 +517,7 @@ Register: `aioson agent:done . --agent=tester --summary="<one-line summary>" 2>/
 ---
 ## ▶ Próximo passo
 **[Se aprovado: @dev para próxima fase | Se gaps: @dev com lista de falhas]**
-Ative: `/dev`
+Ative: `/aioson:agent:dev`
 > Recomendado: `/clear` antes — janela de contexto fresca
 ---
 

package/template/.aioson/docs/briefing/briefing-craft.md

@@ -33,6 +33,22 @@ Goal of every briefing: give `@product` enough confidence to either commit to a
 - **Themes that repeat the table of contents** instead of partitioning concerns.
 - **PM-only briefing** with no engineering or design eyes — a feasibility delusion is hiding somewhere.
 
+### Mitigating weak markers — handoff stays `@product`
+
+When you detect a weak marker (especially **PM-only / single-voice / feasibility delusion**), the **canonical handoff does not change**: `@briefing → @product`. The mitigation is recorded *inside* the briefing, not in the handoff.
+
+- **Acknowledge the marker explicitly** in `## Risks` or `## Open questions` (e.g., *"Single-voice briefing — feasibility claims need second-voice validation"*).
+- **Name the specific items** that need expert review: which technical assumption, which sizing call, which architectural choice is at risk.
+- **Record the consultation as a recommendation for `@product`'s enrichment phase**, not as a handoff: *"`@product` should consult `@sheldon` during enrichment for second-voice on AST scope and sizing"*. The PRD is the input `@sheldon` needs to run.
+
+**Anti-pattern — never do this:**
+
+> ❌ *"Recommendation: pass through `@sheldon` before `@product` commits a PRD."*
+
+`@sheldon` operates **exclusively on PRDs not yet implemented** (see `sheldon.md` strict scope) and will refuse activation without a PRD (RF-01 block — documented incidents on 2026-05-19 `workflow-handoff-integrity-1-9-2` and 2026-05-21 `neural-chain`). Skipping `@product` breaks the chain.
+
+**Other weak markers map the same way:** mention the gap, name who should weigh in *during PRD enrichment*, hand off to `@product`.
+
 ## 2. Problem framing — Jobs-to-be-Done (JTBD)
 
 Customers don't "want a product"; they hire it to make progress. The job is the *progress*, not the surface task.

package/template/.aioson/docs/deyvin/runtime-handoffs.md

@@ -39,4 +39,4 @@ Plain natural-language agent activation in an external client does not create ru
 
 The runtime helpers above cover same-session handoffs (`live:handoff`, `runtime:session:finish`). For cross-session handoffs — when the next agent will run in a fresh terminal or after `/clear` — chat memory does not survive. Before suggesting `/clear`, persist the diagnostic to `plans/{slug}.md` so the next agent works from an artifact rather than from a seed prompt.
 
-Load `.aioson/docs/handoff-persistence.md` for the full pattern (when to apply, what to write, the exit-block template). Apply it whenever the recommended next agent is one that consumes raw plans (`/briefing` foremost, sometimes `/product`) or needs the full diagnostic to operate (`/analyst`, `/architect`, `/sheldon`). Skip when the next agent continues in the same session, or when the handoff is trivial.
+Load `.aioson/docs/handoff-persistence.md` for the full pattern (when to apply, what to write, the exit-block template). Apply it whenever the recommended next agent is one that consumes raw plans (`/aioson:agent:briefing` foremost, sometimes `/aioson:agent:product`) or needs the full diagnostic to operate (`/aioson:agent:analyst`, `/aioson:agent:architect`, `/aioson:agent:sheldon`). Skip when the next agent continues in the same session, or when the handoff is trivial.

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

@@ -25,21 +25,21 @@ Before suggesting `/clear` to the user, persist the actionable diagnostic to `pl
 2. /clear is safe — the next agent reads plans/{slug}.md
 ```
 
-`plans/` is the canonical input directory for `/briefing` (and a useful seed for `/product` too). The directory may not exist yet — create it.
+`plans/` is the canonical input directory for `/aioson:agent:briefing` (and a useful seed for `/aioson:agent:product` too). The directory may not exist yet — create it.
 
 ## When to apply
 
 | Situation | Persist? |
 |---|---|
-| Handoff routes to an agent that takes raw plans (`/briefing` first and foremost, sometimes `/product`) | Yes |
-| Handoff routes to an agent that needs a discovery pass (`/analyst`, `/architect`, `/sheldon`) | Yes — they read context from `.aioson/context/` AND from raw plans |
-| Same-session continuation (`/dev` keeps going, `/qa` reviews implementation just done) | No — context is in chat |
+| Handoff routes to an agent that takes raw plans (`/aioson:agent:briefing` first and foremost, sometimes `/aioson:agent:product`) | Yes |
+| Handoff routes to an agent that needs a discovery pass (`/aioson:agent:analyst`, `/aioson:agent:architect`, `/aioson:agent:sheldon`) | Yes — they read context from `.aioson/context/` AND from raw plans |
+| Same-session continuation (`/aioson:agent:dev` keeps going, `/aioson:agent:qa` reviews implementation just done) | No — context is in chat |
 | Handoff happens via tracked live session (`aioson live:handoff`) | No — telemetry already carries the trail |
-| Trivial routing ("you want `/setup` first") with no diagnostic to preserve | No |
+| Trivial routing ("you want `/aioson:agent:setup` first") with no diagnostic to preserve | No |
 
 ## What to write
 
-Structure of `plans/{slug}.md` (lightweight — `/briefing` will enrich it):
+Structure of `plans/{slug}.md` (lightweight — `/aioson:agent:briefing` will enrich it):
 
 ```md
 # {Short title} — raw plan
@@ -89,6 +89,6 @@ Session artifacts written:
 ## Anti-patterns
 
 - **Inlining 2 KB of diagnostic as a "seed prompt" in the routing message.** The user shouldn't have to copy-paste a wall of text. Persist it.
-- **Persisting trivial routings.** A user who asks "what does `/setup` do" doesn't need a `plans/` file written. Apply the table above.
+- **Persisting trivial routings.** A user who asks "what does `/aioson:agent:setup` do" doesn't need a `plans/` file written. Apply the table above.
 - **Persisting code archaeology.** Code lives in code; reading recommendations live in the artifact only when they would otherwise be lost across `/clear`.
 - **Forgetting to mention the file.** If you wrote `plans/{slug}.md` but the handoff message doesn't reference it, the user won't know to read it (or to let the next agent read it).