xavier

name: xavier description: AI Agent Orchestrator & Knowledge System. Use when user says "/xavier setup", "/xavier review", "/xavier grill", "/xavier add-dep", "/xavier remove-dep", "/xavier deps-update", "/xavier uninstall", or any "/xavier" command.

Xavier — AI Agent Orchestrator

Xavier is an AI agent orchestrator that manages code reviews with diverse personas, dependency-skill knowledge, and a personal knowledge vault.

Command Routing

Parse the user's input to determine the subcommand. The argument after /xavier determines which skill to load and execute.

If no subcommand is provided, list available commands by scanning <XAVIER_HOME>/skills/ for directories containing SKILL.md. Read each skill's YAML frontmatter and display a table with columns Command and Description.

Router Lifecycle

Follow these steps exactly for every /xavier <command> invocation:

0. Resolve XAVIER_HOME: before doing anything else, determine the vault location:

• Run echo "$XAVIER_HOME" via Bash.
• If the variable is set and non-empty, use that value as the vault root.
• If unset or empty, default to ~/.xavier/.
• Store the resolved path. All ~/.xavier/ references below mean this resolved vault root.

1. Parse sub-command: extract the first argument after /xavier. Any remaining arguments are passed through to the skill.

2. Resolve skill file: look for <XAVIER_HOME>/skills/<command>/SKILL.md.

3. Unknown command gate: if the skill file does not exist, show an error:

Skill not found. Run /xavier setup to install skills.

4. Read frontmatter: parse the skill file's YAML frontmatter to get the requires list.

5. Vault gate: if requires is non-empty (not []), check that <XAVIER_HOME>/config.md exists. If it does not exist, tell the user:

Xavier vault not found. Run /xavier setup first.

Then stop — do not execute the skill.

6. Resolve requires:

6a. Auto-load config: Read and parse <XAVIER_HOME>/config.md. Make the config context available for all subsequent resolution steps. Validate that the following fields exist: name, teams, git-strategy, adapter. Warn (do not fail) on any missing fields.

6b. Resolve adapter (if adapter is in the requires list): Read the adapter name from the config's adapter field. Load the adapter from <XAVIER_HOME>/references/adapters/<adapter-name>/adapter.md. This is a sub-step of config resolution — the adapter key depends on the config being loaded first.

6c. Resolve remaining keys: For each other key in the requires list (excluding config and adapter, which are already resolved), load the corresponding context using the Requires Vocabulary below. Make all resolved context available for the skill's execution.

7. Execute inline: read the skill body (everything after the frontmatter) and follow its instructions directly in the current conversation, with all resolved context available.

7a. Interactive gates are hard stops: when executing a skill inline, any instruction to ask, prompt, confirm, quiz, wait for the user, use AskUserQuestion, or get feedback is a command boundary. Ask the user exactly what the skill requests, then stop executing that skill until the user replies. Do not infer the answer, pick defaults, choose filenames, continue to later steps, or invoke another Xavier command while waiting.

7b. Terminal handoff gate: when a skill reaches its final output, the current Xavier command is complete. You may show suggested next commands, but you MUST NOT execute them unless the user's newest message explicitly asks for that command. In particular, do not automatically move from grill to prd, from prd to tasks, from tasks to loop, or from any skill into code edits.

8. Vault commit: after the skill completes successfully, dispatch a vault commit if the vault exists. Read the git strategy from <XAVIER_HOME>/config.md:

• auto-commit or batch-commit: cd <XAVIER_HOME> && git add -A && git commit -m "<command>: <short context>"
• batch-commit + auto-push: same as above, then git push
• user-driven: skip — the user commits manually

Skills never mention or execute vault commits — the router owns this exclusively.

Requires Vocabulary

Path note: All paths below are relative to the resolved XAVIER_HOME (see step 0 of the Router Lifecycle). When you see <vault>/, substitute the resolved vault root (e.g., ~/.xavier/ by default, or whatever $XAVIER_HOME resolved to).

The following 15 keys are the only valid values in a skill's requires list:

Annotations: required vs optional

Requires keys support :required and :optional annotations to signal how the router should handle empty resolution:

requires: [config, personas:required, recurring-patterns:optional]

• Bare keys (no annotation) default to :required.
• :required — the router warns when this key resolves to empty context (e.g., directory has no files). The skill still executes, but the user sees a diagnostic.
• :optional — the router silently provides an empty result when the key resolves to nothing. No warning.

Rule: declare all vault-path reads

Skills MUST NOT read vault paths that are not covered by their requires list. Every vault directory a skill reads from must have a corresponding requires key declared in the frontmatter. Skills that only WRITE to a vault path (e.g., writing a new file to tasks/) do not need the corresponding index key — only skills that READ or LIST from those paths do.

If a requires key cannot be resolved (e.g., directory is empty or doesn't exist), provide an empty result for that key — do not fail. The skill decides how to handle missing context.

Choice-list count hint

When a skill (or the router itself, when listing PRDs / tasks for the user to pick from) presents a choice list backed by prd-index or tasks-index, append a count hint that surfaces how many archived items exist alongside the active ones. Use this exact format:

(N active, M archived — /xavier mark to revive)

• N — number of top-level .md files (active items returned by the index)
• M — number of .md files inside the corresponding done/ subdirectory. The done/ directory holds both status: done and status: superseded items, so the count is "archived" rather than "done" specifically — the label "done" would overstate completion once users start superseding items.
• The /xavier mark to revive tail is literal — it tells the user how to bring an archived item back into the active list

This hint is informational and never gates the choice list — archived items remain hidden until the user explicitly revives them.

Reference Files

Shared references used across multiple skills live in <vault>/references/:

• <vault>/references/patterns/shark.md — Shark orchestration protocol (delegates, never implements; backpressure is truth; remora spawning rules)
• <vault>/references/formats/zettelkasten.md — Base Zettelkasten frontmatter schema for vault notes
• <vault>/references/personas/ — Default reviewer personas (correctness, security, performance)
• <vault>/references/adapters/ — Runtime adapter contracts and implementations