pantheon-opencode 1.0.0

package/bin/pantheon-init.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { homedir, platform } from 'os';
+import { execSync } from 'child_process';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+const CFG = path.join(homedir(), '.config', 'opencode');
+
+function printUsage() {
+  console.log('Pantheon Orchestrator — Multi-agent orchestration platform');
+  console.log('');
+  console.log('Usage:');
+  console.log('  npx pantheon-orchestrator init              # Install globally');
+  console.log('  npx pantheon-orchestrator init --project    # Install in project');
+  console.log('  npx pantheon-orchestrator init --dry-run    # Preview only');
+  console.log('  npx pantheon-orchestrator init --no-mcp     # Skip MCP + venv');
+  console.log('  npx pantheon-orchestrator init --force      # Overwrite + recreate venv');
+  console.log('  npx pantheon-orchestrator --help            # Show this help');
+}
+
+function getPkgVersion() {
+  try {
+    const p = path.join(ROOT, 'package.json');
+    return JSON.parse(fs.readFileSync(p, 'utf8')).version || '?';
+  } catch { return '?'; }
+}
+
+function getAgentList() {
+  const agentsDir = path.resolve(ROOT, 'src', 'agents');
+  if (!fs.existsSync(agentsDir)) return [];
+  return fs.readdirSync(agentsDir)
+    .filter(f => f.endsWith('.md') && f !== 'README.md')
+    .map(f => f.replace('.md', ''));
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (args.includes('--help')) { printUsage(); process.exit(0); }
+
+  if (command === 'init' || !command) {
+    const isProject = args.includes('--project');
+    const isDryRun = args.includes('--dry-run');
+    const skipMCP = args.includes('--no-mcp');
+    const forceReinstall = args.includes('--force');
+    const base = isProject
+      ? path.join(process.cwd(), '.opencode')
+      : CFG;
+
+    const version = getPkgVersion();
+    console.log(`Pantheon Orchestrator v${version} — ${isDryRun ? 'DRY RUN' : 'Installing...'}`);
+    if (forceReinstall && !isDryRun) console.log('  🔄 Force mode — overwriting existing files + recreating venv');
+    console.log(`Target: ${base}${isProject ? ' (project-local)' : ' (global)'}`);
+    console.log('');
+
+    // Force: delete old venv to force clean install
+    if (forceReinstall && !isDryRun) {
+      const venvPath = path.join(base, '.venv');
+      if (fs.existsSync(venvPath)) {
+        fs.rmSync(venvPath, { recursive: true, force: true });
+      }
+    }
+
+    // 1. Agents
+    console.log('  Agents:');
+    const agentList = getAgentList();
+    let count = 0;
+    for (const agent of agentList) {
+      const s = path.join(ROOT, 'src', 'agents', `${agent}.md`);
+      const d = path.join(base, 'agents', `${agent}.md`);
+      if (fs.existsSync(s)) {
+        if (!isDryRun) {
+          fs.mkdirSync(path.join(base, 'agents'), { recursive: true });
+          fs.copyFileSync(s, d);
+        }
+        count++;
+      }
+    }
+    console.log(`    ${count} agent files → ${isDryRun ? '(preview)' : `${base}/agents/`}`);
+
+    // 2. Skills
+    console.log('  Skills:');
+    const skillsSrc = path.resolve(ROOT, 'src', 'skills');
+    if (fs.existsSync(skillsSrc)) {
+      const skills = fs.readdirSync(skillsSrc).filter(f => fs.statSync(path.join(skillsSrc, f)).isDirectory());
+      if (!isDryRun) {
+        for (const skill of skills) {
+          const s = path.join(skillsSrc, skill);
+          const d = path.join(base, 'skills', skill);
+          fs.cpSync(s, d, { recursive: true, force: true });
+        }
+      }
+      console.log(`    ${skills.length} skills → ${isDryRun ? '(preview)' : `${base}/skills/`}`);
+    }
+
+    // 3. Instructions
+    console.log('  Instructions:');
+    const instrSrc = path.resolve(ROOT, 'src', 'instructions');
+    if (fs.existsSync(instrSrc)) {
+      const instrs = fs.readdirSync(instrSrc).filter(f => f.endsWith('.instructions.md'));
+      if (!isDryRun) {
+        fs.mkdirSync(path.join(base, 'instructions'), { recursive: true });
+        for (const f of instrs) {
+          fs.copyFileSync(path.join(instrSrc, f), path.join(base, 'instructions', f));
+        }
+      }
+      console.log(`    ${instrs.length} files → ${isDryRun ? '(preview)' : `${base}/instructions/`}`);
+    }
+
+    // 4. Commands
+    console.log('  Commands:');
+    const cmdSrc = path.resolve(ROOT, 'commands');
+    if (fs.existsSync(cmdSrc)) {
+      const cmds = fs.readdirSync(cmdSrc).filter(f => f.endsWith('.md'));
+      if (!isDryRun) {
+        fs.mkdirSync(path.join(base, 'commands'), { recursive: true });
+        for (const f of cmds) {
+          fs.copyFileSync(path.join(cmdSrc, f), path.join(base, 'commands', f));
+        }
+      }
+      console.log(`    ${cmds.length} commands → ${isDryRun ? '(preview)' : `${base}/commands/`}`);
+    }
+
+    // 5. TUI plugin
+    console.log('  TUI Plugin:');
+    const tuiSrc = path.resolve(ROOT, 'src', 'plugins', 'tui');
+    if (fs.existsSync(tuiSrc)) {
+      if (!isDryRun) {
+        fs.cpSync(tuiSrc, path.join(base, 'plugins', 'pantheon-tui'), { recursive: true, force: true });
+        const tuiJson = path.join(base, 'tui.json');
+        const tuiConfig = { $schema: 'https://opencode.ai/tui.json', plugin: ['plugins/pantheon-tui'] };
+        fs.writeFileSync(tuiJson, JSON.stringify(tuiConfig, null, 2));
+      }
+      console.log(`    Plugin → ${isDryRun ? '(preview)' : `${base}/plugins/pantheon-tui/`}`);
+      console.log(`    tui.json → ${isDryRun ? '(preview)' : `${base}/tui.json`}`);
+    }
+
+    // 6. AGENTS.md
+    const agentsMd = path.resolve(ROOT, 'AGENTS.md');
+    if (fs.existsSync(agentsMd) && !isDryRun) {
+      fs.copyFileSync(agentsMd, path.join(base, 'AGENTS.md'));
+    }
+
+    // 7. .venv + MCP servers (skip if --no-mcp)
+    if (!skipMCP && !isDryRun) {
+      console.log('');
+      console.log('  MCP Servers + .venv...');
+      const installScript = path.resolve(ROOT, 'scripts', 'install.mjs');
+      if (fs.existsSync(installScript)) {
+        try {
+          execSync(`node "${installScript}" "${base}"`, { stdio: 'inherit', cwd: ROOT });
+        } catch (e) {
+          console.log('  ⚠️  MCP install issue (non-fatal):', e.message.split('\n')[0]);
+        }
+      }
+    }
+
+    // 8. Done
+    console.log('');
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log(`  ✅ Pantheon Orchestrator v${version} installed!`);
+    console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+    console.log('');
+    console.log('  Next steps:');
+    console.log('  1. Enable background subagents:');
+    console.log('     echo \'export OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true\' >> ~/.zshrc');
+    console.log('  2. Launch OpenCode:');
+    console.log('     source ~/.zshrc && opencode');
+    console.log('  3. Test background delegation:');
+    console.log('     @zeus, dispatch 2 apollo in parallel to research');
+    console.log('');
+    return;
+  }
+
+  printUsage();
+  process.exit(1);
+}
+
+main().catch(err => { console.error('Error:', err.message); process.exit(1); });

package/commands/pantheon-audit.md

@@ -0,0 +1,25 @@
+---
+description: "Audit: heuristic scan (zero LLM) + Themis review. Usage: /pantheon-audit [--light|--full|--plan]"
+agent: "themis"
+---
+# /pantheon-audit — Quality & Security Audit
+
+**What:** Layer 1 heuristic scan (zero tokens, <2s). If BLOCKING, returns score. If APPROVED, Themis deep review.
+
+**Usage:**
+- `/pantheon-audit` — Full audit (Layer 1 → 2 → 3)
+- `/pantheon-audit --light` — Layer 1 only (quick scan)
+- `/pantheon-audit --full` — Force full review
+- `/pantheon-audit --plan` — Verification planning only
+
+## Layers
+
+### Layer 1 — Heuristic Scan
+`python3 scripts/themis_heuristic_scan.py [--path=<dir>]`
+Zero tokens, <2s. Checks: ruff, biome, anti-pattern slop, anti-overengineering (YAGNI), hash-anchored edits. Returns score 0-100 + APPROVED/BLOCKING.
+
+### Layer 2 — Themis Deep Review
+~500 tokens. Confidence scoring, regression prediction, OWASP Top 10.
+
+### Layer 3 — Verification Planning
+For N>5 file changes. Sugere plano de verificação antes de implementar.

package/commands/pantheon-bg.md

@@ -0,0 +1,10 @@
+---
+description: "List background tasks and their status"
+agent: zeus
+---
+
+List all active background subagent tasks:
+
+1. Query `task_status()` for any running task IDs
+2. Show task_id, agent type, timestamp, and state
+3. Keep the user informed of progress

package/commands/pantheon-consolidate.md

@@ -0,0 +1,11 @@
+---
+description: "Merge and consolidate memory entries"
+agent: zeus
+---
+
+Merge related memory entries and consolidate duplicates:
+
+1. Search for related memories via memory_search
+2. Merge overlapping entries
+3. Remove duplicates via memory_forget
+4. Store consolidated entry via memory_store

package/commands/pantheon-deepwork.md

@@ -0,0 +1,128 @@
+---
+description: "Start a heavy multi-phase task with persisted checkpoints, phased specialist dispatch, and Themis review gates. Progress saved to .pantheon/deepwork/ for resumability. Usage: /pantheon-deepwork"
+agent: "zeus"
+---
+# /pantheon-deepwork — Heavy Task Workflow
+
+**What:** Starts a structured, checkpointed workflow for complex multi-step tasks. Progress is persisted to `.pantheon/deepwork/<task-slug>/` so work can resume if interrupted. Each phase is gated by Themis review.
+
+## When to Use
+
+- Tasks expected to take 10+ turns
+- Multi-agent orchestration with dependencies
+- Work that spans multiple sessions
+- Anything where losing context mid-way would be costly
+
+## When NOT to Use
+
+- Simple fixes (use @talos)
+- Single-file changes (use /subtask)
+- Tasks completable in < 5 turns (use normal delegation)
+
+## Workflow
+
+```
+Phase 0: SCOPING
+  └─ Zeus + Athena define task scope, phases, and acceptance criteria
+  └─ Output: .pantheon/deepwork/<slug>/PLAN.md
+
+Phase 1: DISCOVERY
+  └─ @apollo maps relevant codebase areas
+  └─ Output: .pantheon/deepwork/<slug>/DISCOVERY.md
+
+Phase 2-N: IMPLEMENTATION (parallel per phase)
+  └─ @hermes / @aphrodite / @demeter implement phase scope
+  └─ Output: .pantheon/deepwork/<slug>/phase-<N>-<agent>.md
+
+GATE after each phase:
+  └─ @themis reviews phase output
+  └─ FAIL → fix and re-submit
+  └─ PASS → continue to next phase
+
+Phase FINAL: VERIFICATION
+  └─ @themis full integration review
+  └─ All tests pass, coverage >80%
+  └─ Output: .pantheon/deepwork/<slug>/REVIEW.md
+```
+
+## Checkpoint System
+
+Each phase writes a checkpoint file. If work is interrupted:
+
+```
+/pantheon-deepwork --resume <slug>    # Resume from last checkpoint
+/pantheon-deepwork --status <slug>    # Show current progress
+/pantheon-deepwork --list             # List all deepwork tasks
+```
+
+Checkpoint files:
+
+```
+.pantheon/deepwork/<slug>/
+├── PLAN.md                  # Scope and phase plan
+├── DISCOVERY.md             # Codebase map
+├── phase-1-hermes.md        # Phase 1 backend work
+├── phase-1-aphrodite.md     # Phase 1 frontend work
+├── phase-1-review.md        # Phase 1 Themis review
+├── phase-2-*.md             # Subsequent phases
+├── REVIEW.md                # Final Themis review
+└── STATUS.md                # Current state (phase, progress, blockers)
+```
+
+## ⚡ Full-Auto Mode (`--full-auto`)
+
+> ⚠️ **WARNING:** This bypasses human review gates. Only for experienced operators. Tier 1 gates (plan, commit, deploy) still require human approval.
+
+New in v4.0 — **Ultrawork-style execution**. When `--full-auto` is passed:
+
+- **All gates auto-approve** — no waiting for Themis approval between phases
+- Only stops if Themis returns a **BLOCKING** verdict
+- Equivalent to the "ultrawork" paradigm from OMO (one-minute-optimization)
+- Checkpoints still saved at every phase boundary
+- Use for: high-confidence tasks, batch processing, experienced operators
+
+```
+/pantheon-deepwork --full-auto "Refactor auth service to use JWT"   # Full auto mode
+/pantheon-deepwork --full-auto --resume auth-jwt                     # Resume in full-auto
+```
+
+## Anti-Stall Integration
+
+Deepwork automatically applies:
+
+- **Stall Detection Protocol** — 3 turns no progress → escalate
+- **Phase Reminder** — after each dispatch, continue only independent work
+- **Progress Checkpoint** — every 5 turns, summarize completed vs remaining
+- **Delegate Retry** — delegation failures retried once with rephrased prompt
+
+If a phase stalls:
+
+1. Checkpoint current progress
+2. Report to user: "Phase [N] stalled. Progress saved. Options: (a) retry with different approach, (b) simplify scope, (c) skip phase and revisit."
+
+## Usage
+
+```
+/pantheon-deepwork "Add user authentication with OAuth2"         # Start new deepwork session
+/pantheon-deepwork --resume auth-oauth2                           # Resume interrupted session
+/pantheon-deepwork --status auth-oauth2                           # Show progress
+/pantheon-deepwork --list                                         # List all tasks
+/pantheon-deepwork --archive auth-oauth2                          # Archive completed task
+/pantheon-deepwork --full-auto "Refactor auth service"            # Full auto (ultrawork mode)
+/pantheon-deepwork --full-auto --resume auth-refactor             # Resume full-auto session
+```
+
+## Safety
+
+- All progress persisted — work is never lost
+- Each phase gated by Themis — quality enforced at every step
+- Explicit resume required — won't auto-continue without user intent (unless `--full-auto`)
+- `.pantheon/deepwork/` is gitignored — no accidental commits
+
+---
+
+## Related: `/pantheon-praxis` (merged)
+
+`/pantheon-praxis` was merged into `/pantheon-deepwork` in v4.0. Use `/pantheon-deepwork` for all multi-phase execution.
+
+For ad-hoc single-phase execution, use normal agent delegation (`@hermes`, `@aphrodite`, etc.) directly.

package/commands/pantheon-doc.md

@@ -0,0 +1,10 @@
+---
+description: "Generate or update project documentation"
+agent: zeus
+---
+
+Generate or update project documentation:
+
+1. Check ADRs in `.pantheon/memory-bank/`
+2. Update INSTALLATION.md, README.md, CHANGELOG.md
+3. Use @mnemosyne for memory bank documentation

package/commands/pantheon-focus.md

@@ -0,0 +1,9 @@
+---
+description: "Pin a session goal to prevent scope creep. Usage: /pantheon-focus"
+agent: "zeus"
+---
+# /pantheon-focus — Session Goal
+
+**What:** Pins a session objective. When active, all agents verify every action against the pinned goal. Off-topic work is flagged and blocked.
+**Usage:** `/pantheon-focus <short objective>`
+**Commands:** `/pantheon-focus list` — show all active goals, `/pantheon-focus clear` — remove all

package/commands/pantheon-forget.md

@@ -0,0 +1,58 @@
+---
+description: "Compress old memory entries into summarized form. /pantheon-forget lists entries older than N days, then replaces them with a compressed summary. --auto applies without confirmation. Usage: /pantheon-forget"
+agent: "zeus"
+---
+# /pantheon-forget — Memory Range Compression
+
+**What:** Applies range compression to old memory entries — groups entries by time period and namespace, generates a concise summary via fast LLM, replaces N raw entries with 1 summary. Companion to memory_consolidate (merge) vs memory_forget (compress).
+
+## Usage
+
+```
+/pantheon-forget                                    → Lista candidatas (7+ dias, modo interativo)
+/pantheon-forget --days=30                          → Só entradas com 30+ dias
+/pantheon-forget --namespace=sessions               → Namespace específico
+/pantheon-forget --namespace=sessions --days=14     Combinado
+/pantheon-forget --auto                             → Comprime sem confirmação
+/pantheon-forget --auto --days=30 --compress         → Agressivo: 30+ dias + comprimir em 1 arquivo
+/pantheon-forget --dry-run                          → Preview sem modificar
+```
+
+## Flags
+
+| Flag | Default | Descrição |
+|------|---------|-----------|
+| `--days=<N>` | `7` | Idade mínima em dias |
+| `--namespace=<ns>` | `all` | Namespace específico |
+| `--auto` | off | Comprimir sem confirmação |
+| `--dry-run` | off | Preview sem modificar |
+| `--compress` | off | Comprimir tudo em 1 único entry (modo agressivo) |
+
+## How It Works
+
+1. `memory_list()` → obtém entradas, filtra por idade
+2. Agrupa por namespace + mês
+3. Cada grupo: envia para LLM fast com prompt:
+   ```
+   Summarize these N memory entries into 2-3 sentences:
+   [entries...]
+   ```
+4. Substitui grupo por entry único com key `compressed:<namespace>:<YYYY-MM>`
+5. Entradas originais são deletadas via `memory_forget()`
+
+## Output
+
+```
+🗜️ Memory Range Compression
+
+Group: sessions · 2026-06 (15 entries · 1.2K tokens)
+  → "Sessões de junho focadas em migração FastAPI, ajustes de rota e correção de testes."
+  → Compressed: 15 → 1 entry ✅
+
+Group: decisions · 2026-05 (8 entries · 640 tokens)
+  → "Decisões de maio sobre arquitetura: monorepo mantido, SQLAlchemy 2.0 como padrão."
+  → Compressed: 8 → 1 entry ✅
+
+Summary: 2 groups compressed, 23 entries → 2 entries (-91%)
+Tokens saved: ~1.8K
+```

package/commands/pantheon-hash.md

@@ -0,0 +1,11 @@
+---
+description: "Track file changes via content hashing"
+agent: zeus
+---
+
+Track file modifications using SHA-256 hashes:
+
+1. Hash all files before edits: kv_store("hash:<path>", sha256(content))
+2. After edits, compare: kv_get("hash:<path>") vs new hash
+3. Report which files changed and by how much
+4. Useful for audit trail and change detection

package/commands/pantheon-optimize.md

@@ -0,0 +1,79 @@
+---
+description: "Scan, clean, cache, and archive Pantheon project files. Scans for bloat, archives completed deepwork, migrates flat files to MCP memory, and reports optimization opportunities. Usage: /pantheon-optimize"
+agent: "zeus"
+---
+# /pantheon-optimize — Pantheon Project Optimizer
+
+**What:** Multi-mode optimization: scans for documentation bloat, archives completed deepwork, migrates memory-bank flat files to MCP memory (ChromaDB), and reports token savings.
+
+## Usage
+
+```
+/pantheon-optimize                          → Full scan + compress (default)
+/pantheon-optimize --dry-run                → Preview only, no changes
+/pantheon-optimize --archive                → Archive completed deepwork sessions
+/pantheon-optimize --cache                  → Migrate memory-bank to MCP memory
+/pantheon-optimize --path=<dir>             → Limit scan to directory
+/pantheon-optimize --all                    → Run all modes (default)
+```
+
+## Modes
+
+### `--archive` — Deepwork Archiving
+Archives completed deepwork sessions from `.pantheon/deepwork/<slug>/` to `.pantheon/deepwork/archive/<slug>/`.
+
+**Criteria:** A session is "completed" if it has a `REVIEW.md` containing "APPROVED".
+
+```
+/pantheon-optimize archive                          → Interactive (ask per slug)
+/pantheon-optimize archive --dry-run                → Preview only
+/pantheon-optimize archive --auto                   → Archive all completed
+/pantheon-optimize archive --auto --keep=2           → Keep only PLAN.md + REVIEW.md
+/pantheon-optimize archive --auto --compress         → Single .md per slug
+```
+
+### `--cache` — Memory Bank Migration
+Scans `.pantheon/memory-bank/` for flat `.md` files and migrates them to the MCP memory server (ChromaDB).
+
+**What it does:**
+1. Reads all `.md` files in `.pantheon/memory-bank/`
+2. Chunks by heading (## sections)
+3. Calls `memory_store()` for each chunk with appropriate namespace
+4. Optionally archives the original files after successful migration
+
+```
+/pantheon-optimize cache                     → Preview candidates, ask confirm
+/pantheon-optimize cache --dry-run           → Show what would migrate
+/pantheon-optimize cache --auto              → Migrate + archive originals
+```
+
+### `--dry-run` (global flag)
+Prevents any destructive action. Shows what WOULD be done.
+
+### Default mode (no flags)
+Runs bloat scan on all `.md` and `.json` files + compression report.
+
+## Output
+
+```
+🧹 Pantheon Optimize Report
+
+📦 Bloat Scan: 47 .md + 12 .json files
+   → 3 oversized files found
+   → ~2.4K tokens recoverable
+
+📁 Deepwork Archive: 15 candidates
+   → 12 completed (REVIEW.md APPROVED)
+   → 3 in progress (skipped)
+   → Run with --archive --auto to archive 12 sessions
+
+🗄️  Memory Cache: 24 files in memory-bank/
+   → 18 already in MCP memory (dedup)
+   → 6 candidates for migration (~3.2K tokens)
+   → Run with --cache to migrate
+
+📊 Summary:
+   ⚡ 15 files optimizable → ~5.6K tokens
+   🗑️  12 deepworks archivable → ~320 files cleanup
+   🗄️  6 memory files → MCP migration ready
+```

package/commands/pantheon-remember.md

@@ -0,0 +1,44 @@
+---
+description: "Store or recall a memory interactively. /pantheon-remember <text> → stores it. /pantheon-remember recall <key> → retrieves it. Omitting args starts interactive mode. Usage: /pantheon-remember"
+agent: "zeus"
+---
+# /pantheon-remember — Memory Store & Recall
+
+**What:** Stores a memory entry via `memory_store()` or recalls via `memory_recall()`. Interactive mode if no arguments.
+
+## Usage
+
+```
+/pantheon-remember "Decisão: usar FastAPI em vez de Flask"         → Store (namespace: default)
+/pantheon-remember "Decisão: ..." --namespace=decisions             → Store em namespace específico
+/pantheon-remember recall "FastAPI decision"                        → Recall por key
+/pantheon-remember recall "FastAPI decision" --namespace=decisions   → Recall em namespace
+/pantheon-remember                                                   → Modo interativo (pergunta→store→pergunta recall)
+```
+
+## Behavior
+
+### Store mode (default)
+1. Chama `memory_store()` com o texto fornecido
+2. Metadata: preenche `agent`, `type`, `timestamp` automaticamente
+3. Pergunta: "Quer buscar algo relacionado? (y/n)"
+   - `y` → `memory_recall()` com extração automática de keywords
+   - `n` → fim
+
+### Recall mode
+1. Chama `memory_recall()` com a key fornecida
+2. Se não achar, tenta `memory_search()` como fallback
+
+### Interactive mode (no args)
+1. "O que você quer armazenar?"
+2. Recebe texto → `memory_store()`
+3. "Quer buscar algo relacionado?"
+4. Opcional: "Qual namespace?" (default: "default")
+
+## Output
+
+```
+✅ Stored — id: 42 | namespace: decisions | key: auto-generated
+📎 Related entries (memory_recall):
+  - #1: "Decisão: usar FastAPI..." (score: 0.92)
+```

package/commands/pantheon-search.md

@@ -0,0 +1,48 @@
+---
+description: "Search memories by text with optional namespace filter, category, and result limit. /pantheon-search <query> --namespace=<ns> --top=<N> --stats. Usage: /pantheon-search"
+agent: "zeus"
+---
+# /pantheon-search — Memory Search
+
+**What:** Searches memory entries via `memory_search()` with hybrid vector + keyword (RRF fusion). Supports namespace filter, result limit, and stats view.
+
+## Usage
+
+```
+/pantheon-search "FastAPI performance"                             → Busca em todos os namespaces
+/pantheon-search "FastAPI" --namespace=decisions                    → Busca só em decisions
+/pantheon-search "bug pattern" --namespace=sessions --top=10        → 10 resultados
+/pantheon-search --stats                                            → memory_stats() completo
+/pantheon-search --stats --namespace=decisions                       → Stats por namespace
+```
+
+## Flags
+
+| Flag | Default | Descrição |
+|------|---------|-----------|
+| `--namespace=<ns>` | `all` | Filtrar por namespace específico |
+| `--top=<N>` | `5` | Número de resultados (max 50) |
+| `--stats` | off | Mostrar estatísticas em vez de buscar |
+
+## Output (search)
+
+```
+🔍 Memory Search: "FastAPI performance"
+
+Results (namespace: all):
+  #1 │ decisions │ "Decisão: usar FastAPI..." │ score: 0.89 │ 2026-07-20
+  #2 │ repo      │ "FastAPI async patterns"  │ score: 0.74 │ 2026-07-18
+  #3 │ sessions  │ "FastAPI migration done"  │ score: 0.61 │ 2026-07-15
+
+Found 3 results in 2 namespaces (0.23s)
+```
+
+## Output (stats)
+
+```
+📊 Memory Stats
+Total entries: 142
+Namespaces: decisions (58), sessions (44), repo (28), default (12)
+Vector entries: 142
+DB size: 1.2 MB
+```