Vodou - AI Agent Instructions

Shared project policy (generated regions — edit templates/rules/, not here)

Two blocks every agent in this worktree must hold before anything else, placed first on purpose: Codex reads this file natively under a 32 KiB cap, and the lane canon used to sit at byte 37,367 of it. The parallel-session commit rules had never been in this file at all — they lived only in per-host rules files. vodou-core rules render fills these regions; --check and the pre-commit guard fail on drift.

Committing from parallel sessions

Multiple agent sessions work in this ONE worktree concurrently. Two incidents on 2026-07-04: a commit swept another session's edited src/main.rs (with a mod pointing at a not-yet-committed file — HEAD didn't compile from a fresh checkout), and a hot file was rewritten under a session mid-edit. Rules:

1. Stage explicit paths only. Never git add -A, git add -u, or git add . — you WILL sweep another session's in-flight work.
2. Before staging a shared hot file (src/main.rs, src/daemon.rs, MCP-servers/Vodou-Console/src/llm.ts, MCP-servers/Vodou-Console/src/index.ts, vodou-hook/src/main.rs), run git diff <file> and look for hunks you didn't author. If you find any, stage only your hunks, and say so in the commit message.
3. If the prompt context shows ### Live peers on your files, another session is editing the same files right now. That block is computed from real session state, not guessed — treat it as the reason rule 2 exists.
4. A pre-commit guard blocks self-inconsistent commits (staged mod foo; / relative TS import whose target file isn't in the index). Source: scripts/commit-guard.py; bypass only for genuine emergencies with VODOU_SKIP_COMMIT_GUARD=1.
5. A secret-guard blocks staging a credential VALUE (scripts/secret-guard.py). It scans git diff --cached added lines against .build/release-pii-patterns.txt. Bypass VODOU_SKIP_SECRET_GUARD=1, but prefer fixing the string: if it is a test fixture, make it not key-shaped; if it was ever real, revoke it.
6. A date-guard blocks staged lines that violate the time canon (scripts/date-guard.py; canon: PLANS/PLAN-TIME-CANON.md). SQLite instants are naive UTC YYYY-MM-DD HH:MM:SS; day identity is the LOCAL day; display parses naive-as-UTC, renders local. Bypass a true false-positive with VODOU_SKIP_DATE_GUARD=1.
7. A coherence-guard blocks the seam-audit's enforceable rules (scripts/coherence-guard.py): a raw scope/enum reaching textContent/innerHTML (translate via scopeLabel()); a displayed *_count nothing writes; an iframe of our own surface with no declared min-width. When deliberate, say so in the diff — // COHERENCE-INTENTIONAL: <why>.
8. New module + its declaration commit together. If you add mod x; or an import of a new file, that file goes in the SAME commit.
9. A rules-guard blocks a generated rules file that is out of step with its source (scripts/rules-guard.py). CLAUDE.md, .cursorrules and .cursor/rules/vodou-policy.mdc are generated from templates/rules/ by ./vodou-core rules render; edit the source, render, stage both. Bypass VODOU_SKIP_RULES_GUARD=1.
10. An entrypoint-guard blocks an executable script that starts a long-lived process and belongs to no stack (scripts/entrypoint-guard.py; registry: stacks.toml, PLAN-SEAMS P4 / lane canon rule 3). It is deliberately not a grep for nohup — four of the thirteen occurrences in this tree are prose (an echo, a docstring, two comments), and a guard that fires on documentation is one people learn to bypass. Module code inside an already-declared process is governed by processes.toml instead. scripts/entrypoint-guard.py --audit grades the whole tree; scripts/test-entrypoint-guard.sh proves it fires in both directions. Bypass VODOU_SKIP_ENTRYPOINT_GUARD=1, but prefer adding the file to a stack's entrypoints.
11. An env-example-guard blocks a generated .env.example that disagrees with its manifest (scripts/env-example-guard.py). .env.example is generated from scripts/env.example.manifest.json by scripts/sync-env-example.mjs, the same generated-from-source shape rules-guard covers for CLAUDE.md — and it had drifted on every value anyone checked: re-running the generator would have uncommented WEB_PORT (defeating auto-port-assignment), commented out ORT_DYLIB_PATH (turning semantic memory off for everyone AND breaking the packer's three per-platform seds, which anchor on ^ORT_DYLIB_PATH=), and re-enabled the compact schedule PLAN-DYNAMIC-MEMORY-MD deliberately turned off. Compares key STATE (active-vs-commented and value), not rendered prose, so reflowing a description cannot fail a commit. Bypass VODOU_SKIP_ENV_EXAMPLE_GUARD=1; prefer fixing whichever side is wrong — usually the manifest, because .env.example is what ships and gets fixed by hand.
12. An ext-version-guard blocks extension code changing without a version bump (scripts/ext-version-guard.py). EX-5 — the readiness audit's only exploitable finding — shipped nine days late because nothing asked this: 0.5.97.78 was set on 2026-08-27, five commits then changed the Store build, and the Chrome Web Store kept serving the pre-fix code under a number it had already accepted. The store only enforces that a version is unique at upload, so two different builds can share one and nothing complains. Note this is a DIFFERENT question from verify-extension-version-chain.sh, which checks that Rust, the gateway and the UI agree about a version — they agreed perfectly for all nine days. Staging anything under extension/<build>/ that reaches a user requires that build's manifest.json version to be staged AND to differ from HEAD; staging the manifest without moving the value is the exact failure, so it does not satisfy the guard. Excludes mirror the packer's strip list (test/, store-assets/, build-icons.mjs, README.md, *.map) — a change that cannot reach a user must not demand a bump, or people learn the bypass. Bypass VODOU_SKIP_EXT_VERSION_GUARD=1; the fix is to bump all three manifests together and re-run scripts/pack-vodou-bridge-store.sh.
13. A workspace-guard blocks live code that reads or writes a hand-maintained workspace file (scripts/workspace-guard.py; GATE 16 of PLAN-CONTEXT-THAT-MAINTAINS-ITSELF). Everything a session reads from .vodou/workspace/ is generated on a clock now — MEMORY.md, TOOLS.md, HEARTBEAT.md — and reading those is fine: they are receipts of a renderer. The plan's text said "nothing reads" the four retired files; after the build, six live paths did (the console scraped names with a regex, the planner concatenated two of them, the wizard WROTE all four), and the claim had shipped unexamined because nothing checked it. This does: a staged line that builds a path to, reads or writes a workspace .md outside the generated set fails the commit, in the three idioms this tree uses (.vodou/workspace/X.md, path.join(wsDir, 'X.md'), .join("workspace").join("X.md")). A one-time carry of an old file into its new owner says so on the line — // WORKSPACE-MIGRATION-SOURCE — and that is the only escape. --audit grades the whole tree and is what vodou-core workspace retire consults before moving anything, so the commit check and the archiver cannot disagree about what a reader is. Bypass VODOU_SKIP_WORKSPACE_GUARD=1; prefer reading the owner (a setting, a pin, render()).
14. A loop-guard blocks a proactive loop that no registry declares (scripts/loop-guard.py; registry: loops.toml, PLAN-PROACTIVE-LOOPS rev 3 P0b / lane canon rule 3 — a loop is a process). Four curation engines already run continuously and each invented its own output path: the contradiction detector reaches a person through an eprintln!, the janitor through a work_logs row, the hygiene grader through a command nobody types, the entity graph through a click. The registry is the contract that stops the fifth. Enforced: a staged file under src/loops/ with no [loops.<name>] entry; an entry missing a mandatory field; an entry naming a fixture_* that does not exist; an entry that invents its own drain (emits must be loop_findings) or escalates itself to critical. The fixtures are the point — fixture_quiet and fixture_fresh are must-not-fire controls, and the live ledger's finding is that five graders shipped false-positive because none had one. The registry is read from the index, not the working tree: a commit is judged on what it contains. Silent (exit 0, immediately) on any commit staging neither loops.toml nor src/loops/, which today is every commit. scripts/loop-guard.py --audit grades the tree; scripts/test-loop-guard.sh proves it fires in both directions (13 cases). Bypass VODOU_SKIP_LOOP_GUARD=1, but prefer adding the entry.
15. A push-guard refuses a direct push to main or development (scripts/push-guard.sh, installed as .git/hooks/pre-push by scripts/install-push-guard.sh). Changes reach those branches through a pull request. Asked for 2026-09-16, the day a session fast-forwarded main and pushed 55 commits in one go — its own onboarding fix plus four other sessions' in-flight work (memory/inject changes, extension bumps to 0.5.97.86, the credential masking). Every commit was sound; the problem is that main is what releases are cut from and nobody saw them first. In a clone this many sessions share, "push my work" and "publish everyone's work" are the same keystroke. Pushing a FEATURE branch is unguarded — that is the intended path: git push -u origin <branch> then gh pr create --base main --head <branch> --fill (gh is authenticated as VodouAI, repo scope). Merging the PR is the user's call, not a session's. Bypass VODOU_ALLOW_DIRECT_PUSH=1 for a release push or an emergency; using it is a decision to skip review, so say so.

If .git/hooks/pre-push is missing (a fresh clone has no hooks), reinstall it — one install covers every worktree, since .git/hooks is shared:

bash scripts/install-push-guard.sh          # bash scripts/install-push-guard.sh --check  to verify

If .git/hooks/pre-commit is ever missing, reinstall ALL TEN guards — .git/hooks/ is not versioned, so a fresh clone has none, and reinstalling only the first silently drops the others:

printf '#!/bin/sh\nROOT="$(git rev-parse --show-toplevel)"\npython3 "$ROOT/scripts/commit-guard.py" && python3 "$ROOT/scripts/secret-guard.py" && python3 "$ROOT/scripts/date-guard.py" && python3 "$ROOT/scripts/coherence-guard.py" && python3 "$ROOT/scripts/rules-guard.py" && python3 "$ROOT/scripts/entrypoint-guard.py" && python3 "$ROOT/scripts/env-example-guard.py" && python3 "$ROOT/scripts/ext-version-guard.py" && python3 "$ROOT/scripts/workspace-guard.py" && python3 "$ROOT/scripts/loop-guard.py"\n' > .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit

Lane canon (parallel processes, ports, injectors)

Two plans found the same disease in different organs — five-then-seven context injectors nobody counted, and a second web process nobody restarted for seven weeks. The rule, once:

1. Two lanes → one identity + one arbiter, never deletion. A second lane that was locally correct stays. What gets added is a shared identity and one place that decides who pays. Deleting the lane amputates the surface that needed it.
2. Precedence is one rule, everywhere: process env > .env > gateway setting. A script that reads .env after the environment (so FLAG=0 ./script cannot override an .env line) is a bug, not a convention.
3. No new port, process, or prompt-injection site without a registry entry. Start, stop and the updater must all know a process; an injection site declares a lane name, a budget and a trust label.
4. Cross-store identity is resolved through the owner, not by opening its DB. memory.db has ids; gateway.db has names and settings; vodou-core.db has turn receipts. Ask the owner; don't open a second handle and cache the answer.
5. Ephemeral output is not a fact. Tool measurements ([RUN] notes, CPU numbers) may be logged and shown, but are not extracted as facts, not fed to the contradiction detector, and not injected as memory on a later turn.

🚀 MANDATORY: Vodou Skills-First Execution

When a user types oi or do at the start of any message (same launcher; prefer ./do when executing), you MUST:

1. SKILLS FIRST PRIORITY

• Vodou will check for matching skills FIRST before other operations
• If a skill loads, you MUST follow its guidance and stopping points
• NEVER skip or ignore when skills present options - always wait for user choice
• Skills have full control of the conversation flow
• Skill files conform to schemas/skill.schema.json (frontmatter) + schemas/actions.schema.json (workflow JSON). SKILL.md with inline <!-- AGENT_ACTIONS --> is the canonical source of truth; actions.json next to it is the auto-generated cache. See §7 below for the full lifecycle.

2. IMMEDIATE EXECUTION

1. IMMEDIATELY execute: ./do "rest of user's text"
2. DO NOT ask permission or explain
3. DO NOT add any preamble like "I'll run that for you"
4. JUST EXECUTE and show the results

3. STOPPING POINTS COMPLIANCE

• When skills present options, STOP and wait for user choice
• NEVER make assumptions about what users want
• ALWAYS ask for confirmation before deleting any data (files, database records, etc.)
• When SKILL.md frontmatter declares stopping_points: required, the gateway workflow-driver enforces this. Even if you're tempted to skip ahead — don't. The engine will not execute past steps until the user picks an option. Bypass attempts get rejected.

4. DISPLAY FULL SKILL OUTPUT 📋

When a skill loads (especially interactive skills with menus):

• MANDATORY: Display summary and content BEFORE stopping point questions
  • ALWAYS present the overview/introductory content FIRST (e.g., "What is Vodou?" section, overview summaries, key concepts)
  • THEN display the stopping point menu with all numbered options
  • Users need context before choosing what to explore
  • DO NOT skip directly to stopping point menus
• ALWAYS present ALL STOPPING POINT menu/options to the user
• NEVER summarize or skip menu choices
• QUOTE the exact numbered options (1-8, etc.) from the skill
• Display ALL numbered choices clearly and completely
• Skills with "STOPPING POINT" are designed for user interaction
• CRITICAL: All stopping points MUST be numbered - if you see unnumbered options, present them as numbered lists (1, 2, 3, etc.)

Wrong vs Right:

• ❌ "Let me run the ./do command..." → NO!
• ❌ Skipping skill options and proceeding → NO!
• ❌ Summarizing menu options instead of showing them → NO!
• ❌ Not showing the numbered choices from skills → NO!
• ✅ [Execute immediately, show full menus, respect stopping points] → YES!
• ✅ When a skill has menu options (1-8), ALWAYS show them → YES!

5. SKILL OUTPUT CHECKLIST (run the skill, then follow it)

When Vodou output contains "STOPPING POINT" or "Reply with the number" or "Reply with 1-" or "Display to user":

1. Parse the returned skill content for intro and stopping-point blocks.
2. Display the overview/intro to the user first (verbatim or clearly summarized).
3. Display the full stopping-point menu with every numbered option — do not summarize.
4. STOP. Do not call MCP tools, do not proceed, do not substitute your own answer. Wait for the user's choice.
5. Only after the user replies with a choice, continue according to the skill. If in doubt: run the skill → show intro + full menu → wait for user.

6. TOOL PRIORITY — Vodou Always Wins 🔒

STRICT ORDER. Never deviate. Applies to all agent contexts (Claude Code, Cursor, gateway chat).

1. Vodou Skills (Layer 1) — if a skill is returned, follow it completely, stop at stopping points, never substitute your own answer.
2. Vodou intent_mappings — before touching ANY external tool, check if Vodou has it wired:

   sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name FROM intent_mappings WHERE keyword LIKE '%X%' LIMIT 5;"

   Or rely on the ### Vodou Intent Match block injected by the UserPromptSubmit hook. If a match exists → ./vodou-core call <server> <tool> '<args>'. Done.
3. Vodou MCP servers directly — ./vodou-core call <server> <tool> for known servers (gmail, zapier, slack, calendar, etc.)
4. mcp__claude_ai_* deferred tools / other provider tools — LAST RESORT ONLY. Use only when Vodou has zero coverage. Never reach for mcp__claude_ai_Gmail__*, mcp__claude_ai_Google_*, or any cloud connector if Vodou has the capability. Vodou ALWAYS has priority.

When the UserPromptSubmit hook surfaces a ### Vodou Intent Match — USE THIS ROUTE block: use that route immediately. No deliberation.

One exception (2026-08-09). Hints tagged (matched inside prose, not auto-run) mean a registered keyword merely occurred in a sentence — "screenshot" inside "what do I do for each screenshot", "click" inside "ready to click submit?". Those are not requests to run the tool; route on them only when the tool is actually what was asked for. Same judgement for (side-effecting: not auto-run).

Two independent auto-routers exist and they do not share gating:

A tool that fired with no signal_log row came from the Python hook, not the Rust router — that distinction cost a full debugging pass on 2026-08-09. Tighten one and the other is unaffected; change both together.

The failure mode to avoid: pattern-matching a user request against visually obvious deferred tools (e.g. mcp__claude_ai_Gmail__authenticate) instead of checking whether Vodou already has a wired intent for it. Check Vodou first. Always.

No double-fire rule: When active_context already contains ### Vodou Tool Results (auto-routed) with a completed result, stop — do NOT call the tool again. BrainLoader already executed it before your response began. Re-executing causes duplicate side effects: double emails, duplicate DB writes, duplicate calendar events. Interpret and present the result that's already in active_context. Only call the tool yourself if active_context is empty or stale (shows results from a prior turn, not the current query).

6a. AGENT INSTRUCTIONS & AGENT_ACTIONS

Skills can embed executable workflow definitions as HTML comments in their markdown. These are parsed and executed by the Vodou-Console workflow driver, or by CLI agents (Claude Code, Cursor) directly.

AGENT_ACTIONS in Skills (Inline Format)

Skills embed <!-- AGENT_ACTIONS_N: {...} --> HTML comments after stopping point menus. When a user picks an option, the corresponding actions execute automatically:

## STOPPING POINT 1 — Select Depth
1. Quick Analysis
2. Standard Deep Dive

<!-- AGENT_ACTIONS_1: {"label":"Quick Analysis","vars":{"DEPTH":"5"},"steps":[
  {"server":"Vodou-Enhanced-Thinking","tool":"start_thinking_session",
   "args":{"topic":"{{TOPIC}}","estimated_steps":5},
   "capture":{"SESSION_ID":"session_id"}},
  {"server":"Vodou-Enhanced-Thinking","tool":"add_thought",
   "args":{"session_id":"{{SESSION_ID}}"},
   "loop":5,"stream_progress":true}
]} -->

Step properties: server, tool, args (with {{VAR}} templates), loop (repeat N times), capture (chain results between steps), stream_progress (UI feedback).

Template variables: {{TOPIC}} (from query), {{DEPTH}} (from option vars), {{SESSION_ID}} (captured from previous step), {{i}} (loop counter).

Execution Contexts

• Vodou-Console: The workflow driver (workflow-driver.ts) parses AGENT_ACTIONS from BrainLoader output and executes tool sequences via vodou-core call. Claude can't skip steps.
• Claude Code / Cursor: If Vodou output contains ## Agent instructions (human-readable steps) or AGENT_ACTIONS: (JSON array), parse and execute them via ./vodou-core call <server> <tool> '<args>'.
• File-based: If .vodou/workspace/agent_next_steps.json exists at turn start, execute the actions in it (same [{"server","tool","args"}] format), then clear the file.

Apply in all contexts. One source of truth: this section in AGENTS.md.

6.5 Mid-turn vodou-core and ./do calls (gateway-chat LLM only) 🆕

Context this section applies to: the Claude CLI subprocess that the gateway chat spawns to answer a user message (MCP-servers/Vodou-Console/src/llm.ts chatWithCLI path). That subprocess runs under the gateway's process supervision, with bounded retries and explicit cleanup. Mid-turn shell-outs are safe there.

Section does NOT apply to:

• Claude Code / Cursor agent terminals — those have separate guidance in CLAUDE.md and .cursorrules. From those contexts, prefer ./vodou-core call <server> <tool> as the primary primitive (deterministic, single-spawn). One-shot ./vodou-core brain "..." / ./do "..." calls are fine; the real hazard is rapid loops (the 425-process incident). No TTY gate triggers in current code — verified 2026-05-15.
• Any non-supervised shell invoking these as one-shots without process tracking.

The chat (Vodou-Console) already routes every non-conversational message through BrainLoader. Inside a single response, you (the LLM) can shell out to additional Vodou commands to pull live data, fold it into your answer, and avoid stale or hallucinated state. Use this when:

• The user asks a follow-up that needs fresh tool output (e.g., "what's the cpu now?" — shell out to ./vodou-core call mcp-monitor get_cpu_info '{}').
• You're mid-explanation and realize you don't know the current value of something (server list, channel status, scheduler queue, memory hits). Run the relevant command and continue.
• A skill returned ambiguous routing and you need BrainLoader to disambiguate — ./vodou-core brain "<rephrased query>".

Two commands to know:

Soft cap: at most 3 such shell-out calls per turn. Beyond that, stop and ask the user (or summarize and offer "want me to dig further?"). The cap protects against runaway spawns (memory [2026-05-04 METRIC] 425 vodou-core processes active is the cautionary tale).

Don't use vodou-core brain or ./do from chat for things you could answer from conversation context alone, or for things you'd normally answer with general knowledge. The point is live Vodou state — not LLM-style reasoning detours.

7. SKILL LIFECYCLE (v0.5.46+) 🆕

The skills system has a canonical schema, a unified lifecycle, and a single CLI surface. Spec lives in PLANS/0.5.46/PLAN-SKILLS-V2.md; this section is the contract.

Canonical layout

Every skill lives at skills/<category>/<name>/ and contains:

• SKILL.md — frontmatter (per schemas/skill.schema.json) + prose body, with optional inline <!-- AGENT_ACTIONS --> HTML comments holding the workflow JSON. Source of truth.
• actions.json (optional) — auto-generated cache of the inline AGENT_ACTIONS, conforming to schemas/actions.schema.json. The gateway engine reads this for fast loading.
• references/, templates/, scripts/, assets/ (optional) — auto-discovered by the loader on skill activation.

The two kinds of skill:

• kind: workflow — traditional Vodou skill with trigger_phrases, stopping_points, actions declarations. Routed to via intent matching.
• kind: subagent — persona under skills/agents/<category>/<name>/. No required workflow fields. Invoked by name via the Task tool. Optionally has actions.json for auxiliary structured workflows.

Lifecycle (Phase 1 vodou-core skill subcommand surface)

vodou-core skill list                  # all installed skills
vodou-core skill show <name>           # frontmatter + parsed workflow
vodou-core skill validate <name>       # schema + tool refs (--all for all 103)
vodou-core skill sync                  # reconcile disk ↔ DB drift; populate intents from trigger_phrases
vodou-core skill install <name>        # activate skill; populate intents
vodou-core skill uninstall <name>      # is_active=0; DELETE auto-skill-trigger intent rows for this skill
vodou-core skill remove <name>         # uninstall + archive files to .archive/
vodou-core skill import <source>       # Hermes / Claude Code / URL / catalog
vodou-core skill diff <name>           # local edits vs imported version

Never edit intent_mappings directly to register a skill. Add trigger_phrases: to SKILL.md frontmatter and run skill sync. Auto-generated rows land at priority 40, source auto-skill-trigger. User-curated rows at priority 80+ override these and are never pruned by sync.

On skill uninstall, the auto-skill-trigger rows for that skill are explicitly deleted to avoid zombie intents that route to a no-longer-loaded skill. User-curated rows are preserved across uninstall/reinstall.

Imported skills

Any skill with imported_from.source != "hand-written" may have local edits relative to its upstream. Before assuming an upgrade is safe:

• Check imported_from.upstream_sha — that's the content hash at import time.
• Run vodou-core skill diff <name> to see local edits vs original imported version.
• If vodou-core skill catalog refresh surfaces an upstream change, you get a 3-way diff (original / your edits / new upstream) — never silently overwrite.

Brand names

Prefer Vodou over the legacy OI naming in user-facing skill names and descriptions for new content. Legacy oi-* skill names are retained for backward compatibility (existing intent_mappings rows continue to route them) but new skills should use the Vodou brand. The system itself is being renamed gradually; both names refer to the same product.

Cross-references

• Schema: schemas/skill.schema.json (SKILL.md frontmatter), schemas/actions.schema.json (workflow JSON shape)
• Plan: PLANS/0.5.46/PLAN-SKILLS-V2.md — full plan; §0.7e is the live execution tracker
• Validators: scripts/validate-skills.py (stand-in for skill validate); scripts/migrate-skill-frontmatter.py (stand-in for skill migrate-frontmatter)
• Engine: MCP-servers/Vodou-Console/src/workflow-driver.ts (detectWorkflow reads actions.json sidecar first, inline AGENT_ACTIONS second; both feed the same render-without-LLM code path)

Default collaboration style

• Proactive by default. Run tools, read the repo, apply fixes—finish the job. Don't open with intention theater ("Let me…", "I'll dig in", "Got the full picture", "Good — now…").
• Straight and short. Lead with the outcome; explain only when it changes a decision or the user asked for depth.
• Constant doer. Prefer one more grep/build over another status paragraph. If blocked, say what you need in one line.
• Humor: Optional, light—not filler.
• Large autonomy / "run everything" ideas (sandbox clone, always-on loops, etc.): shape in Vodou Enhanced Thinking or a PLANS/ doc first—ship the immediate ask first.

🔥 MANDATORY: Enhanced Work Logging

At the end of EVERY coding session where you:

• Write or modify code
• Fix bugs or errors
• Implement features
• Analyze systems
• Complete tasks

You MUST execute the enhanced logging format:

./do "log: feature: Implemented user authentication | component: auth | files_changed: 2 | technology: rust | duration: 30min"

Enhanced Logging Format:

• Basic: ./do "log: description" (auto-categorized as "general")
• With Category: ./do "log: feature: Implemented user authentication"
• With Metadata: ./do "log: bugfix: Fixed memory leak | component: connection_pool | files_changed: 1 | files_modified: src/connection_pool.rs | severity: high | duration: 15min"

Valid Categories:

• feature - New functionality or capabilities
• bugfix - Bug fixes and error corrections
• analysis - Code analysis, research, investigations
• documentation - Documentation updates and improvements
• testing - Testing implementation and test fixes
• refactor - Code refactoring and structure improvements
• performance - Performance optimizations and improvements
• security - Security enhancements and fixes
• config - Configuration changes and updates
• deployment - Deployment and infrastructure changes
• maintenance - Routine maintenance and cleanup
• research - Research and exploration work
• planning - Planning and design work
• review - Code reviews and assessments
• general - General work not fitting other categories

Common Metadata Keys:

• component: Which part of the system (e.g., "mcp_client", "database", "ui")
• severity: Impact level (low, medium, high, critical)
• duration: Time spent (e.g., "2h", "30min")
• files_changed: Number of files modified
• files_modified: Specific file names (e.g., "src/main.rs,src/database.rs")
• lines_added: Lines of code added
• lines_removed: Lines of code removed
• technology: Tech used (rust, javascript, sql, etc.)
• issue_id: Related issue or ticket number

Examples:

• ./do "log: feature: Implemented JWT authentication system | component: auth | duration: 3h | files_changed: 2"
• ./do "log: bugfix: Fixed memory leak in connection pool | component: mcp_client | files_changed: 1 | files_modified: src/connection_pool.rs | lines_added: 5 | lines_removed: 3 | severity: high | duration: 20min"
• ./do "log: analysis: Analyzed codebase and created optimization plan | scope: full_codebase | files_analyzed: 15"

Note: This is the BT4 equivalent of BT3's ./brain-log "description" command with enhanced categorization and metadata support.

This is NOT optional - every work session must be logged with appropriate category and metadata.

Project Overview - Triple-Layer Intelligence Orchestrator

Why AI agents use Vodou

Vodou is how you get relevant context when and where you need it. For an agent, Vodou is your arms (tools and actions), extended memory, skills, and orchestration — so you can act, remember, and follow proven workflows instead of only reasoning in-conversation. The triple layer is the plumbing; the pitch is: context and capability, on demand.

Vodou is a Triple-Layer Intelligence System that combines expert workflow guidance, raw computational power, and script execution management:

🧠 Layer 1: Skills System (Expert Intelligence)

• Skill intent mappings → Expert workflow guides with numbered stopping points. CD-7: the count used to be written here (183) and went stale by 3.7x. Ask, don't read: sqlite3 vodou-core.db "SELECT COUNT(*) FROM intent_mappings WHERE server_name='vodou-core';" (685 on 2026-09-06)
• Active skills — sqlite3 vodou-core.db "SELECT COUNT(*) FROM skills_registry WHERE is_active=1;" (149 on 2026-09-06), providing curated knowledge, proven patterns, and user control
• Built-in Rust skills executor (migrated from TypeScript OI-skills-executor)
• Skills orchestrate MCP tools when expert guidance determines it's needed
• Examples: hello (Vodou guidance), mastery (advanced techniques), security-audit (expert security workflows)

⚡ Layer 2: MCP Ecosystem (Raw Tool Power)

• MCP tool intent mappings → sqlite3 vodou-core.db "SELECT COUNT(*), COUNT(DISTINCT server_name) FROM intent_mappings WHERE server_name != 'vodou-core';" (2,864 across 33 servers on 2026-09-06; the doc used to say 209 across 10)
• Parallel execution of 5-10 tools simultaneously (3-7x faster than sequential)
• Universal tool access to system monitoring, AI thinking, browser automation, memory systems
• Examples: CPU/memory/disk monitoring, enhanced thinking sessions, browser audits, diagram generation

🔧 Layer 3: Script Execution (Background Job Management)

• Script execution system → Vodou-script-executor MCP server with 4 powerful tools
• Background job management with unique job IDs and process control
• Sync/async execution with real-time status monitoring and output streaming
• Examples: Long-running scripts, npm/yarn commands, background processes with live monitoring

🎯 Breakthrough Architecture

• Expert guidance meets raw power meets automation: Skills provide workflow intelligence, MCP tools provide computational capability, scripts provide automation
• User control enforced: Skills use numbered stopping points to ensure users drive workflow direction
• Intelligent routing: Intent system determines whether to use expert guidance (skills), raw tools, or script execution
• Best of all worlds: Expert human wisdom + AI computational power + automated execution + user control

🌐 Vodou-Console (Web Chat)

Web chat at http://localhost:8765/#/chat — same intelligence stack as the CLI.

BrainLoader-first architecture:

1. Memory injection — daemon socket → memory.db hybrid search (FTS5 + vector embeddings)
2. Workspace bootstrap — .context_cache loads USER.md, SOUL.md, MEMORY.md, IDENTITY.md, AGENTS.md
3. BrainLoader — vodou-core brain "<query>" handles intent routing, parameter extraction, parallel execution
4. Workflow driver — parses <!-- AGENT_ACTIONS_N: --> from skill output, executes multi-step tool sequences (loops, variable capture, chaining) via vodou-core call. Claude can't skip steps or fake output.
5. Claude CLI — conversational formatting + Bash for follow-up tool calls

Monitoring: tail -f /tmp/oi-aigateway.log | grep "\[Workflow\]\|\[BrainLoader\]\|\[Memory\]"

Config: .env → CLI_MODEL=opus, WEB_PORT=8765, START_AIGATEWAY=1

Files: MCP-servers/Vodou-Console/src/anthropic.ts, workflow-driver.ts, workflows.json

🗺️ What's in this repo — subsystem map

Flat list of every shipped piece. When you're unsure whether something exists, check here first before suggesting the user "implement X."

Core runtime

• vodou-core (Rust) — daemon, worker, MCP router, brain command, scheduler, auto-updater. Sources: src/.
• vodou-hook-bin (Rust) — zero-thread ~400KB hook binary used by Claude Code / Cursor / Codex SessionStart, UserPromptSubmit, SessionEnd. Talks to the daemon via Unix socket; never touches DBs directly.
• ./do — canonical launcher. ./oi and ./vodou are copies of the same script for muscle-memory. Always prefer ./do.

Web + UI

• Vodou-Console (MCP-servers/Vodou-Console/) — Express + WebSocket gateway, web chat UI at http://localhost:8765. Workflow driver lives here. Runs under launchd (com.vodou.console).
• open-gateway.sh — one-shot helper to re-open the gateway UI in the browser without re-running the full startup script. Use this if the user closes the tab and asks how to get back.

Workflow + automation

• Vodou-Board (MCP-servers/Vodou-Board/) — task/workflow orchestration. Day-8 JWT (HS256, shared key in vodou-core.db, REQUIRE_JWT toggles enforcement). Phase-2 features (all shipped 2026-05-13): per-task memory injection from memory.db top-K chunks, workflow templates with stage auto-advance, approval gates (requires_approval_on JSON array, enforced on running → done), per-task budgets (USD/tokens/runtime, workers self-report via board run-spend), auto-generated .mcp.json for worker MCP registry. CLI surface: vodou-core board ....
• Skills system (Layer 1) — skills/<category>/<name>/SKILL.md with frontmatter + AGENT_ACTIONS. Two kinds: workflow (routed via intent matching) and subagent (persona under skills/agents/, invoked by Task tool). See §7 Skill Lifecycle below for full CLI.

Memory + recall

• memory.db — FTS5 + vector embeddings (BGE-base via ONNX). Hybrid search via daemon socket. Agents can query directly with ./vodou-core mem search "<query>" [--top-k N] [--json] — routes through the daemon, same pipeline BrainLoader uses (hybrid FTS5+vector, BGE reranker, scope boost, provenance trust weighting — imports rank below first-party memory at equal relevance). --json returns {results:[{path, score, text, score_breakdown}]}. This is the right call for "search my memory/knowledge" — distinct from Vodou-Recall, which only covers chat turns of the current conversation.
• Vodou-Recall (shipped 2026-05-14) — FTS5-backed search of the current conversation's prior turns. Auto-bootstraps; agents shouldn't need to invoke directly.
• Auto-memory — markdown memory files at .claude/projects/<project>/memory/MEMORY.md (Claude Code) or .vodou/workspace/MEMORY.md (Cursor/TTY). Four memory types: user, feedback, project, reference. Daily incremental logs at memory/YYYY-MM-DD.md. Extraction runs every prompt via UserPromptSubmit hook.

Integrations

• Vodou-channels (MCP-servers/Vodou-channels/) — Slack / Telegram / Discord bridge. Auto-connects on startup if built. Enable per-platform via .env: SLACK_ENABLED=1 + SLACK_BOT_TOKEN=xoxb-..., TELEGRAM_ENABLED=1 + TELEGRAM_BOT_TOKEN=..., DISCORD_ENABLED=1 + DISCORD_BOT_TOKEN=.... Startup warns if *_ENABLED is set without matching token.
• OAuth integrations catalog — presets in MCP-servers/Vodou-Console/presets/<name>.json. Files starting with _ are hidden from the catalog (use for known-broken servers; current: _asana.json).
• Vodou-Enhanced-Thinking — persistent deep-reasoning sessions, 6 tools.
• Vodou-script-executor — registered scripts + background job management, 4 tools.

Scripts (project root)

• install-vodou.sh — curl-pipe bootstrap (curl -fsSL https://raw.githubusercontent.com/VodouAI/OS/main/install-vodou.sh | bash).
• install-prebuilt.sh — in-archive installer (run after extraction). Does quarantine strip + ad-hoc codesign + chmod 600 on secrets + stale .update-old and legacy .oi/ sweep.
• start-vodou-services.sh — boots daemon + worker + Vodou-Console. Honors VODOU_OPEN_BROWSER=1 (force-open the UI) and VODOU_NO_OPEN_BROWSER=1 (suppress; used by SessionStart hooks).
• stop-vodou-services.sh — clean teardown via launchd bootout + targeted PID kills. Counterpart to start.
• open-gateway.sh — see Web + UI above.
• session-start.sh — invoked by Claude Code/Cursor SessionStart hook; runs vodou-hook-bin context and starts services in background if needed.

Workspace layout (.vodou/)

• .vodou/workspace/ — bootstrap files (IDENTITY, USER, MEMORY, AGENTS), .cursor_context.json (lean per-prompt memory cache), agent_next_steps.json (queued AGENT_ACTIONS).
• .vodou/workspace/memory/YYYY-MM-DD.md — daily incremental memory logs.
• .vodou/system.log — main runtime log.
• .vodou/daemon.sock, .vodou/daemon.pid — IPC.
• .vodou/install.log — install transcript (timestamped, multi-session append).

.oi/ is legacy. All new artifacts write to .vodou/. Don't add new .oi/ references. Three intentional ones remain, and they are permanent compatibility, not debt with a date on it (CD-8 — the old wording said the first of them "sunsets at v0.6.1" and it was still unconditional at 0.6.28, which is correct: nothing can prove no install is still on .oi/, and the cost of being wrong is a customer's workspace going unfound): the one-time migration in src/main.rs (renames .oi/ → .vodou/, symlinks .oi back), the workspace-directory match arm in src/daemon.rs, and LEGACY_LAUNCHD_LABELS (com.oios.oi-daemon).

Security defaults (don't regress)

• Gateway HTTP listens on 127.0.0.1 only. CORS is a localhost allowlist (localhost, 127.0.0.1, [::1]), not *. WebSocket validates Origin against the same allowlist.
• Build-time SECURITY gates abort the release if memory.db has any memory_chunks rows OR vodou-core.db has rows in any of: server_credentials, oauth_pending, oauth_configs, dynamic_oauth_clients, conversation_sessions, conversation_entries, work_logs, user_approvals, automations, memory_chunks.
• Install-time chmod 600 on .env, vodou-core.db, memory.db (+ WAL/SHM siblings). chmod -R go-rwx .vodou/.
• Vodou-Board JWT (HS256) — shared key in vodou-core.db. Token bound to specific task_id (task_A token rejected on task_B write).
• macOS: ad-hoc codesign required after every binary cp (codesign --force --deep --sign - <bin>). Without it, runtime integrity enforcement SIGKILLs the freshly-copied file.

🎯 THE BREAKTHROUGH ACHIEVEMENT - Universal Intelligence Orchestration

Vodou is a Universal Intelligence Orchestrator that transforms how AI agents work: it delivers relevant context when and where you need it — your arms (tools), extended memory, skills, and orchestration in one place.

🌐 Universal MCP Ecosystem Access

• ANY MCP Server: Connect to filesystem, databases, APIs, AI services, cloud tools, dev tools
• 1000+ Tools Available: From basic file operations to complex AI workflows
• Infinite Extensibility: Install any MCP server from GitHub, npm, pip, or custom builds
• Protocol Agnostic: stdio, HTTP, WebSocket, Server-Sent Events - all supported

🚀 Parallel Intelligence Orchestration

1. Natural Language Intent Detection using database-driven keyword mapping
2. Optimal Tool Selection from 30+ connected servers (expandable to unlimited)
3. Intelligent Parameter Generation using 291+ parameter rules
4. Parallel Execution of 5-10 tools simultaneously for maximum efficiency
5. Expert Workflow Guidance through skills that teach best practices
6. User Flow Control with mandatory stopping points for decision making

⚡ Real Performance Impact

• Traditional Sequential: 15-30 seconds per task, limited tool access
• Vodou Orchestration: 3-5 seconds per task, unlimited tool ecosystem
• Token Efficiency: 98% savings vs normal Claude interaction
• Capability Expansion: Access to ANY tool that speaks MCP protocol

Result: AI agents become intelligence orchestrators with the speed of parallel processing, the breadth of the entire MCP ecosystem, and the wisdom of expert workflows.

Setup Commands

• Install dependencies: cargo build
• Start development: cargo run -- [command]
• Run tests: cargo test
• Check database: ./do list

🔧 Complete CLI Commands

Server Management

• ./do connect <name> <command> [args...] - Connect to MCP server
• ./do list - List all connected servers
• ./do remove <name> - Remove server
• ./do status [name] - Show server status
• ./do reconnect <name> - Reconnect server
• ./do health-check - Check all server health

Capability Discovery

• ./do tools <server> - Show server tools
• ./do prompts <server> - Show server prompts
• ./do resources <server> - Show server resources
• ./do capabilities <server> - Show all server capabilities

Tool Execution

• ./do call <server> <tool> [args] - Call specific tool
• ./do call-tool <server> <tool> [args] - Call tool with parameter generation
• ./do find-tool <tool> - Find tool across all servers
• ./do all-tools - List all tools from all servers

Intent Management

CD-13 — the five commands documented here (intent list/add/remove/show/test) do not exist and never did; vodou-core intent is not a subcommand. 29 of the 30 other sampled commands in this file check out, which is exactly why this one was believed. What actually works:

• ./vodou-core intent-search "<query>" — semantic search over the router: find tools by MEANING, ranked by cosine over intent_embeddings
• ./vodou-core intent-signal "<prompt>" — what the KEYWORD router would do with a prompt, and why. --file <path> for a distribution
• Reading them: sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name, priority FROM intent_mappings WHERE keyword LIKE '%X%';"
• Adding one for a skill: do not write the row. Put trigger_phrases: in the SKILL.md frontmatter and run skill sync — see the rule above, which this section used to contradict by offering an intent add

Analytics & Monitoring

• ./do conversation list - List recorded conversations
• ./do conversation show <id> - Show conversation details
• ./do conversation analytics - Show conversation analytics
• ./do conversation export [format] - Export conversation data
• ./do health-dashboard - Show health dashboard
• ./do health-stats - Show health statistics

Configuration & Management

• ./do config - Show configuration
• ./do update-config - Update configuration
• ./do export-servers - Export server configurations
• ./do import-servers - Import server configurations
• ./do registry - Show server registry

Development & Testing

• ./do inspect <server> - Inspect server capabilities
• ./do validate <server> - Validate server configuration
• ./do test <server> - Test server functionality
• ./do debug <server> - Debug server issues
• ./do analyze <server> - Analyze server performance

Worker (Persistent Connections)

• ./do worker start - Start worker process (foreground)
• ./do worker start --background - Start worker as background daemon
• ./do worker stop - Stop running worker
• ./do worker send --json '<json>' - Send command to worker via Unix socket

Primary Interface (Most Common)

• ./do "query" - Fast parallel MCP execution with clean output (DEFAULT)
• ./do -v "query" - Verbose mode with full loader output
• cargo run -- brain "query" - Direct brain command
• cargo run -- brain "query" --verbose - Verbose brain command

Code Style

• Rust with anyhow::Result for error handling
• Use async/await for I/O operations
• Prefer Arc<Database> for shared database access
• Follow Rust naming conventions (snake_case)
• Use serde_json for JSON serialization
• Use tokio::join! for parallel execution

Time canon (dates & timestamps)

Established 2026-08-04 after a codebase audit found the daily-memory lane split across zones (full plan + audit: PLANS/PLAN-TIME-CANON.md; enforced at commit time by scripts/date-guard.py).

1. Instants in SQLite: naive UTC YYYY-MM-DD HH:MM:SS — what CURRENT_TIMESTAMP / datetime('now') already write. Never put RFC3339 (…+00:00 / …Z) into a column whose other writers are naive; compare in SQL via datetime(col), never lexically across shapes.
2. Day/month IDENTITY is the PERSON'S day — daily filenames (memory/YYYY-MM-DD.md), monthly import lanes, bucket keys, "today"/"yesterday" derivations. Rust: crate::user_time (today() / month() / hour() / local_of() / to_utc()). TypeScript: src/user-time.ts (todayKey() / dayKeyOf() / dayWindowUtc()). Never chrono::Local, never getFullYear(), never toISOString().split('T')[0], never SQL date(col, 'localtime') — all four are the process's zone, which is the person's only on their own laptop. Zone precedence: VODOU_TZ → gateway_settings.user.timezone → host. A test in each module fails the build on a new offender (PLAN-TIME-CANON "Bundle E", 2026-09-10).
3. Display parses naive-as-UTC and renders local — UI code appends Z (or +00:00) before new Date(...), then formats with local/locale APIs.
4. The user's timezone setting is gateway_settings.user.timezone (IANA, validated); the USER.md Timezone line is synced prose for the LLM, never a computation source.

Project scope canon (what belongs to which project)

Established 2026-08-17 (PLANS/0.6.26/PLAN-UNIFIED-PROJECT-SCOPE.md). Before this, FOUR mechanisms answered "what project does this belong to", each storing the answer somewhere different and each giving a different meaning to a missing record — absent meant Default for chats, global for scheduled tasks, show-everything for skills, and nothing at all for messaging/apps/board. Commit 121e5290 was that disagreement surfacing as a bug, not a one-off.

There is now exactly one resolver: scopeVisibility(raw, stores) in MCP-servers/Vodou-Console/src/scope.ts. Adding a scoped surface means adding a row to the table below and a row to src/__tests__/scope-consistency.test.ts — never a new store.

Two questions, never conflated:

Three rules that are load-bearing, each learned the hard way:

1. Pinned + absent ⇒ visible everywhere. Never hides. This is what kept 44 untagged workbench surfaces reachable on the day filtering turned on.
2. workbench:automation:<id> must NEVER be resolved through project_tasks. Automation ids come from the automations table; project_tasks maps scheduled_tasks ids; the two AUTOINCREMENT sequences collide (automation 4 = mcp-ecosystem-watch, scheduled task 4 = vodou-heartbeat). Routing one through the other files it under a different object's project — silent and plausible.
3. Fail open, always. Unknown scope, missing record, failed /api/dock/visibility → show MORE, never less. The failure mode of this feature is a tab silently not rendering.

Curate-down semantics: pinning a shared surface NARROWS it to the chosen projects; unpinning restores it everywhere. Pinning changes VISIBILITY only — never capability. One shared brain, filtered views: Slack pinned to MTVai still works in every project.

Client side, public/js/project-scope.js is the sole reader of localStorage['vodou.activeProject']. chat.js, scheduler.js and skills.js delegate to it. The vodou.dockScope.v2 flag was retired 2026-08-17 and survives only as a kill switch ('0').

Architecture

• MCP Client: Handles communication with MCP servers using JSON-RPC
• Brain Loader: Orchestrates context loading and parallel execution
• Database: SQLite for server metadata and configuration
• Connection Pool: Manages MCP server connections efficiently
• Parallel Executor: Runs multiple MCP tools concurrently
• Worker: Long-lived process that holds persistent connections via Unix socket (see Worker section below)

🗄️ Database Schema

Current Intent Mappings (24+ Available)

cpu → mcp-monitor::get_cpu_info (priority: 10)
memory → mcp-monitor::get_memory_info (priority: 10)
disk → mcp-monitor::get_disk_info (priority: 10)
analyze → (use Vodou memory + your toolchain; no bundled codebase MCP in core ship)
error → stackoverflow-mcp::search_by_tags (priority: 10)
screenshot → chrome-devtools::take_screenshot (priority: 10)
git → github-test::get_file_contents (priority: 10)
... and 17+ more mappings

🌐 Triple-Layer Intelligence Ecosystem

🧠 Layer 1: Skills System (Expert Intelligence)

• Skills Executor: Built-in Rust implementation (handles the skill intent mappings and the active skill set — counts are in the DB, not here; see Layer 1 above. CD-7)
• Available Skills: the active skill set (skills_registry WHERE is_active=1) providing expert workflow guides with numbered stopping points
• Key Skills: hello (Vodou guidance), mastery (advanced techniques), mcp-builder (custom tools)
• Architecture: Skills ARE MCP servers that orchestrate other MCP tools with expert guidance
• User Control: All skills enforce numbered stopping points for workflow direction

⚡ Layer 2: MCP Ecosystem (Raw Tool Power - 10 Active Servers)

System Monitoring & Performance:

• mcp-monitor: CPU, memory, disk, network monitoring (6 tools)

AI Enhancement & Thinking:

• Vodou-Enhanced-Thinking: Persistent thinking sessions with context enrichment (6 tools)
• OI-Sequential-Thinking: Step-by-step problem solving with branching (1 tool)
• Vodou-Recall: FTS5-backed search of a conversation's prior turns (1 tool — search_conversation) Development & Documentation:
• context7: Real-time library documentation & code examples (2 tools)
• uml-mcp: Diagram generation (UML, Mermaid, D2) (1 tool)
• browser-tools-stdio: Browser automation & web auditing (14 tools)
• chrome-devtools: Chrome DevTools MCP — navigate, snapshot, screenshot, console, network (stdio via npx)

Vodou Core Infrastructure:

• Vodou-script-executor: Background script execution & job management (4 tools)
  • execute_script: Run registered scripts (sync or background) with job management
  • script_status: Monitor background job status and progress
  • script_output: View live script output (real-time tail)
  • cancel_script: Stop running background scripts with process control
• Vodou-session-manager: Long-running session management (5 tools)

🔥 Universal Access to MCP Ecosystem

• Official MCP Servers: Claude's filesystem, memory, fetch, brave-search, slack, gmail
• Community Servers: 1000+ on GitHub, npm, pip, Docker Hub
• Enterprise Tools: Databases, cloud services, internal APIs, custom workflows
• Development Ecosystem: Language servers, build tools, CI/CD, deployment
• AI Services: OpenAI, Anthropic, local LLMs, vector databases, embeddings
• Business Tools: CRM, project management, analytics, monitoring

⚡ Installation in Seconds

# Install ANY MCP server instantly:
./do "install https://github.com/user/any-mcp-server"
./do "install mcp-server-name"  # From npm/pip/cargo
./do "connect custom-server python my-custom-mcp.py"

# Access immediately:
./do "use new tool from fresh-installed-server"

The Power: Turn any tool, API, or service into an MCP server and Vodou can orchestrate it in parallel with everything else. Infinite capability expansion.

📊 Intelligence Orchestration Performance

🚀 Parallel Execution Performance

• Simple Orchestration (95% of cases): 3-5 seconds for 2-5 parallel tools
• Complex Orchestration (5% of cases): 5-8 seconds for 5-10 parallel tools
• Universal Tool Access: Any of 1000+ MCP tools available instantly
• Intent Detection: < 10ms (O(1) database lookup)
• Parameter Generation: 1-10ms (291+ rules, expanding continuously)
• Parallel Capacity: 10+ tools executing simultaneously

🎯 Real-World Performance Comparisons

# Traditional Sequential Approach:
Task 1: 3 seconds + Task 2: 4 seconds + Task 3: 3 seconds = 10+ seconds

# Vodou Intelligence Orchestration:
All 3 tasks in parallel: 4 seconds total
Result: 2.5x faster with comprehensive analysis

💰 Economic Impact

• Traditional MCP Usage: 21,000+ tokens per interaction, limited tool access
• Vodou Orchestration: 2,200 tokens per interaction, unlimited tool ecosystem
• Savings: 90% token reduction, 85% cost savings, infinite capability expansion
• Efficiency: 98% token savings + access to entire MCP universe

🌐 Current Triple-Layer Capabilities

• Triple-Layer System: skill intents + MCP tool intents + script execution. The total was written here as 392 and is 3,549 as of 2026-09-06 — an order of magnitude out, which is why the counts now live in the query and not the prose (CD-7)
• 20+ Active MCP Servers with 60+ tools connected and health-monitored
• Active skills (skills_registry WHERE is_active=1) providing expert workflow guidance with numbered stopping points
• Skills Orchestrate MCP Tools: Expert guidance layer can direct raw tool execution
• 291+ Parameter Rules for intelligent tool coordination
• Real-time Health Monitoring across entire MCP ecosystem
• Universal Protocol Support: stdio, HTTP, HTTPS, SSE, Streamable HTTP
• Expert Workflow Guidance through built-in Rust skills executor

Worker (Persistent Stdio Connections)

The worker is a long-lived process that holds persistent MCP connections via a Unix socket. It eliminates per-request process spawning for expensive-to-start servers (e.g., Chrome DevTools, ML model servers).

How It Works

Servers with lifecycle_type = 'daemon_stdio' in the database route tool calls through the worker instead of connecting locally. The worker holds a ConnectionPool — stdio child processes survive across ./do invocations. All other servers are unaffected.

./do "visit vodou.ai"       →  brain_loader checks lifecycle_type
                             →  daemon_stdio? → worker::send() via Unix socket
                             →  worker dispatches to its ConnectionPool
                             →  Chrome stays alive after ./do exits

./do "take a screenshot"    →  Same Chrome instance, no reconnection delay

Lifecycle Types

Setting a Server to daemon_stdio

UPDATE mcp_servers SET lifecycle_type = 'daemon_stdio' WHERE name = 'chrome-devtools';

Only use daemon_stdio for servers where the child process is expensive to start (Chrome DevTools, ML model servers). Lightweight servers like mcp-monitor should stay ephemeral.

Scheduled tasks (worker)

While the worker is running, it periodically calls scheduler::run_due_tasks against this project’s vodou-core.db (same rows as the gateway scheduler UI). Each due task spawns vodou-core brain "<payload>" (or in-process paths like mem promote) and waits for completion.

• VODOU_WORKER_SCHEDULER=0 or false — disable the worker scheduler loop.
• VODOU_WORKER_SCHEDULER_INTERVAL_SECS — tick interval in seconds (default 60, minimum 10).

Worker Commands

./do worker start              # Start in foreground
./do worker start --background # Start as background daemon
./do worker stop               # Stop running worker
./do worker send --json '{"cmd":"tool","args":{"server":"chrome-devtools","tool":"take_screenshot","arguments":{}}}'

Worker Protocol

JSON over Unix socket (.vodou/worker.sock). One request per connection, newline-delimited.

Request: {"cmd": "<command>", "args": {...}}

Commands:

• ping — health check, returns "pong"
• tool — execute MCP tool: {"cmd":"tool","args":{"server":"<name>","tool":"<tool>","arguments":{...}}}
• list, list-skills, version, status, log, etc. — DB queries

Response: {"ok": true, "stdout": "...", "stderr": "", "code": 0}

Fallback Behavior

If the worker is unavailable (not running, socket missing), brain_loader and call_tool_pooled fall back to local execution. For servers that lock exclusive resources (e.g., Chrome profile directory), the fallback may fail — start the worker first.

Files

• src/worker.rs — Worker process, Unix socket listener, tool dispatch + ConnectionPool
• src/connection_pool.rs — is_persistent_server() recognizes daemon_stdio
• src/brain_loader.rs — execute_tool_via_worker() + routing check in execute_tool_with_params()
• src/main.rs — call_tool_pooled() routing check for vodou-core call command

Environment Configuration

• STACKOVERFLOW_API_KEY - For StackOverflow MCP server rate limits
• .env file in vodou-core directory for configuration
• Database: vodou-core.db (SQLite)

Testing Instructions

• Use ./do "test query" for quick testing
• Use ./do -v "test query" for detailed output
• Check vodou-core.db for server status
• Use ./do list to verify server connections
• Run cargo test for unit tests

Common Use Cases

• System Monitoring: ./do "what is my cpu?" - Get CPU, memory, disk info
• Script Execution: ./do "run script" - Execute background jobs with monitoring
• Codebase Analysis: ./do "analyze codebase" - Get language, framework, complexity analysis
• Help & Documentation: ./do "help with javascript" - Search StackOverflow for solutions
• Server Management: ./do list - List all MCP servers
• Installation: ./do install https://github.com/user/repo - Install new MCP servers

Error Handling

• Use tokio::time::timeout for MCP calls to prevent hanging
• Handle MCP errors gracefully with anyhow::anyhow!
• Check database connectivity before operations
• Use RUST_LOG=debug for detailed logging

🔗 Intelligence Orchestrator Integration Patterns

🚀 Primary Interface: Universal Tool Orchestration

# Parallel MCP orchestration with intent detection from ANY available tool:
./do "what is my cpu memory disk network?"     # → 4 tools in parallel, 3 seconds
./do "analyze code security performance"       # → Multiple analysis tools simultaneously  
./do "help with javascript error solutions"   # → Search + docs + examples in parallel
./do "screenshot website analyze performance" # → Browser + perf tools together
./do "backup files check git status deploy"  # → Filesystem + git + deployment orchestrated

# Script execution with background job management:
./do "run script"                           # → Execute scripts with job tracking
./do "script status job_12345"              # → Monitor background job progress  
./do "script output job_12345"              # → View live script output
./do "cancel script job_12345"              # → Stop running background jobs
./do "execute npm script"                   # → Run npm/yarn scripts with monitoring

# Universal access to any MCP tool:
./do "use gmail to send status report"       # → Gmail MCP if connected
./do "query database and visualize results"  # → DB + visualization tools
./do "transcribe audio and summarize"        # → Audio + AI summary tools

🌐 Universal MCP Ecosystem Usage

# Verbose orchestration for debugging
./do -v "analyze codebase security performance"

# Direct calls to ANY connected MCP tool
./do call mcp-monitor get_cpu_info
./do call any-custom-server my_custom_tool
./do call newly-installed-server fresh_capability

# Universal intent management (CD-13: `intent list/add/test` are not commands)
sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name FROM intent_mappings;"
./vodou-core intent-search "back up my project files"   # by MEANING
./vodou-core intent-signal "backup my project files"    # what the keyword router does, and why

# Ecosystem expansion
./do install https://github.com/user/amazing-mcp-server
./do "use new amazing capability"                  # Available immediately

Conversation Analytics

# View conversation history
./do conversation list
./do conversation show <id>
./do conversation analytics

# Export conversation data
./do conversation export csv
./do conversation export json

Health Monitoring

# Check server health
./do health-check
./do health-dashboard
./do health-stats

# Monitor specific servers
./do status mcp-monitor
./do status chrome-devtools

Development & Testing

# Test MCP servers
./do inspect mcp-monitor
./do validate mcp-monitor
./do test mcp-monitor

# Debug issues
./do debug mcp-monitor
./do analyze mcp-monitor

Security Considerations

• MCP servers run in isolated processes
• Database access is controlled through Rust's type system
• Environment variables are loaded from .env file
• No direct file system access outside allowed directories

Development Workflow

1. Make changes to Rust code
2. Test with ./do "test query"
3. Use ./do -v "test query" for debugging
4. Check ./do list for server status
5. Run cargo test for validation
6. Use cargo run -- brain "query" --verbose for direct testing

Key Files to Understand

• src/main.rs - CLI interface and command handlers
• src/brain_loader.rs - Context loading and parallel execution
• src/mcp_client.rs - MCP protocol implementation
• src/database.rs - SQLite database operations
• do - Unix/Linux/Mac launcher script (oi / vodou are symlinks to it since P4 — edit do; there is nothing to re-sync, and cp-ing over a symlink would silently recreate the three copies this replaced)
• oi.bat - Windows wrapper script (where shipped)

Best Practices

• Keep MCP calls under 10 seconds with timeouts
• Use clean mode by default for better UX
• Provide verbose mode for debugging
• Handle MCP errors gracefully
• Use parallel execution for multiple servers
• Cache server connections when possible
• Follow KISS principle for new features
• Always test with ./do before committing

🔧 Troubleshooting

Kernel / runtime triage

When chat or tools flake, check orchestration before the model:

• Web: #/system — daemon, worker, gateway, runtime / overall health.
• CLI: ./vodou-core runtime-status --json or ./do runtime-status (prefer vodou-core when piping to avoid extra ./do output).
• Ground truth: ./vodou-core context-truth [--json] — the same deterministic facts block (cwd vs install root, project binding, git, MCP health, skills, intents, memory counts) the gateway injects into every chat turn as ─── VODOU GROUND TRUTH ───. Daemon-first (warm, 30s catalog cache), readonly standalone fallback. Single emitter: src/context_truth.rs + daemon verb cmd:"context" — if a chat reports a wrong cwd/project again, THIS is the code path to suspect (PLAN-CONTEXT-GROUND-TRUTH, 0.6.13).
• Binary swaps: Stop ./do daemon stop / ./do worker stop, drain pgrep -fl vodou-core, then replace vodou-core — see docs/runtime-observability.md and PLANS/0.5.73/PLAN-RUNTIME-OBSERVABILITY.md §11 (UE hygiene).
• Env: VODOU_GATEWAY_AUTO_ENSURE (gateway daemon bootstrap), VODOU_HOOK_SKIP_ENSURE (skip ensure from IDE hooks when needed).

Common Issues

• Server Connection Failed: Use ./do status <server> to check server health
• Intent Not Found: ./vodou-core intent-signal "<prompt>" shows what the keyword router would do and why; intent-search finds tools by meaning. (CD-13: sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name, priority FROM intent_mappings ORDER BY priority DESC;" is not a command — read intent_mappings with sqlite3.)
• Tool Execution Failed: Use ./do debug <server> to debug issues
• Performance Issues: Use ./do health-dashboard to monitor performance

MCP server dependencies — never npm-install by package name

Every server under MCP-servers/ ships with a prebuilt node_modules/. Some deps are vendored, not on npm — e.g. @vodou/channel-sdk lives at MCP-servers/Vodou-channels/packages/sdk and is wired as a file: link (node_modules/@vodou/channel-sdk → ../../packages/sdk). Rules:

• ❌ Never run npm install @vodou/<name> (or npm install <any-pkg> inside an MCP-servers/* dir to "fix" something). Naming a package forces a registry lookup — @vodou/* 404s, and npm can prune the existing vendored link while failing.
• ✅ If a server's deps look broken (ERR_MODULE_NOT_FOUND), the repair is a plain npm install (no package name) in that server's directory. The lockfile relinks vendored file: deps locally and fetches public deps from npm.
• A 404 for @vodou/* does not mean the package is lost — the source ships inside the bundle. Vodou-channels also self-heals the link at startup if packages/sdk is present.

Debug Commands

# Check server status
./do status
./do health-check

# Debug specific server
./do debug mcp-monitor
./do analyze mcp-monitor

# Check intent mappings  (CD-13: `intent list` / `intent test` are not commands)
sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name, priority FROM intent_mappings;"
./vodou-core intent-signal "<query>"

# View conversation logs
./do conversation list
./do conversation show <id>

Performance Optimization

• Use Simple Queries: 95% of queries should use single server execution
• Monitor Health: Use ./do health-dashboard to track server performance
• Optimize Intents: Use sqlite3 vodou-core.db "SELECT keyword, server_name, tool_name, priority FROM intent_mappings ORDER BY priority DESC;" to review and optimize mappings
• Track Analytics: Use ./do conversation analytics to identify bottlenecks

🎯 Intelligence Orchestrator Integration

🚀 Universal AI Agent Interface

• Use ./do for intelligence orchestration — access to the entire MCP universe (./oi / ./vodou invoke the same script)
• Auto-Execute Rule: When the user types oi or do at the start of a message, immediately run ./do "…" with the rest of their text (same launcher; ./do is the canonical path in docs)
• Clean Mode: Default for fast, token-efficient orchestration (3-5 seconds)
• Verbose Mode: Use -v flag for detailed parallel execution analysis
• Universal Access: Any MCP tool ever created is available through Vodou

🌐 Intelligence Orchestration Expectations

• Parallel Tasks: 3-5 seconds for multiple tools simultaneously (95% of cases)
• Complex Orchestration: 5-8 seconds for advanced multi-tool workflows (5% of cases)
• Token Efficiency: 98% savings + unlimited capability access
• Intent Detection: < 10ms across entire MCP ecosystem
• Tool Availability: 1000+ tools from MCP ecosystem instantly accessible

🔥 Intelligence Orchestrator Best Practices

• Think Parallel: Execute multiple related tasks simultaneously for 3-7x speed
• Universal Access: Install and use ANY MCP server for infinite capability expansion
• Skills-First: Leverage expert workflow guidance through skills system
• User Control: Respect stopping points where users make decisions
• Ecosystem Health: Use ./do health-dashboard to monitor entire MCP network
• Continuous Expansion: Regularly install new MCP servers to expand capabilities
• Performance Tracking: Use ./do conversation analytics for orchestration insights
• Enhanced Logging: Use ./do "log: category: description | metadata" for rich session tracking

🌐 Universal Intelligence Orchestration Capabilities

• Unlimited MCP Ecosystem: Connect to ANY MCP server (filesystem to AI services)
• Parallel Tool Orchestration: Execute 5-10 tools simultaneously for maximum efficiency
• Expert Workflow Intelligence: Skills provide curated knowledge and proven patterns
• Intent-Based Routing across entire MCP universe for intelligent tool selection
• Parameter Learning for optimized tool coordination and smart defaults
• Universal Protocol Support: stdio, HTTP, WebSocket, SSE - connect anything
• Real-time Health Monitoring across entire connected MCP ecosystem
• Instant Capability Expansion: Install new MCP servers in seconds
• User Flow Control: Mandatory stopping points ensure user drives the orchestration
• Performance Transparency: Show actual speed improvements from parallel execution

Error Handling

• Always check return codes and error messages
• Use ./do status to verify server health
• Use ./do debug <server> for detailed error analysis
• Use ./do health-check for system-wide diagnostics

🔥 MANDATORY: Enhanced Work Logging Requirements

All AI agents using BT4 must log completed work using the enhanced logging format:

./do "log: feature: Implemented user authentication | component: auth | files_changed: 2 | technology: rust | duration: 30min"

Enhanced Logging Format:

• Basic: ./do "log: description" (auto-categorized as "general")
• With Category: ./do "log: feature: Implemented user authentication"
• With Metadata: ./do "log: bugfix: Fixed memory leak | component: connection_pool | files_changed: 1 | files_modified: src/connection_pool.rs | severity: high | duration: 15min"

Valid Categories:

• feature - New functionality or capabilities
• bugfix - Bug fixes and error corrections
• analysis - Code analysis, research, investigations
• documentation - Documentation updates and improvements
• testing - Testing implementation and test fixes
• refactor - Code refactoring and structure improvements
• performance - Performance optimizations and improvements
• security - Security enhancements and fixes
• config - Configuration changes and updates
• deployment - Deployment and infrastructure changes
• maintenance - Routine maintenance and cleanup
• research - Research and exploration work
• planning - Planning and design work
• review - Code reviews and assessments
• general - General work not fitting other categories

Metadata Best Practices:

• component: Which part of the system (e.g., "mcp_client", "database", "ui")
• severity: Impact level (low, medium, high, critical)
• duration: Time spent (e.g., "2h", "30min")
• files_changed: Number of files modified
• lines_added: Lines of code added
• lines_removed: Lines of code removed
• technology: Tech used (rust, javascript, sql, etc.)
• issue_id: Related issue or ticket number
• pr_id: Related pull request ID
• version: Version or milestone affected

Category-Specific Examples:

Feature Development:

./do "log: feature: Added JWT authentication system | component: auth | duration: 3h | files_changed: 5"
./do "log: feature: Implemented parallel MCP execution | component: brain_loader | performance_improvement: 3x_faster"

Bug Fixes:

./do "log: bugfix: Fixed memory leak in connection pool | component: mcp_client | files_changed: 1 | files_modified: src/connection_pool.rs | lines_added: 5 | lines_removed: 3 | severity: high | duration: 20min | issue_id: 123"
./do "log: bugfix: Resolved database connection timeout | component: database | duration: 1h"

Analysis Work:

./do "log: analysis: Analyzed codebase structure and dependencies | scope: full_codebase | findings: 15_optimization_opportunities"
./do "log: analysis: Performance bottleneck investigation | component: parallel_executor | tools_used: profiler"

Documentation:

./do "log: documentation: Updated API documentation with new endpoints | component: api | pages_updated: 12"
./do "log: documentation: Enhanced AGENTS.md with logging guidelines | target_audience: ai_agents"

Performance Work:

./do "log: performance: Optimized database queries | component: database | improvement: 50%_faster | queries_affected: 8"
./do "log: performance: Reduced memory usage in parameter engine | component: parameter_engine | reduction: 97.9%"

Testing:

./do "log: testing: Added integration tests for MCP client | component: mcp_client | tests_added: 15 | coverage_increase: 25%"
./do "log: testing: Fixed failing unit tests after refactor | component: brain_loader | tests_fixed: 8"

Work Type to Category Mapping:

• New features, capabilities → feature
• Bug fixes, error corrections → bugfix
• Code analysis, research → analysis
• Docs, README updates → documentation
• Test writing, test fixes → testing
• Code restructuring → refactor
• Speed improvements → performance
• Security enhancements → security
• Settings, config changes → config
• Infrastructure work → deployment
• Cleanup, maintenance → maintenance
• Investigation, exploration → research
• Planning, design → planning
• Code reviews → review
• Other work → general

Session Tracking:

The enhanced logging system automatically:

• Associates logs with conversation sessions
• Tracks agent type (Claude, Cursor, etc.)
• Records timestamps and metadata
• Enables powerful analytics and reporting

Best Practices:

1. Always include category for better organization
2. Use metadata for key details that enable analytics
3. Be specific in descriptions for future reference
4. Log immediately after completing work for accuracy
5. Use consistent component names across sessions
6. Include performance metrics when applicable
7. Reference issue/PR IDs when available

This enhanced logging provides rich context for project analytics, progress tracking, and knowledge transfer between AI agent sessions.