Vault best practices

The vault tier system is powerful and easy to misuse. These guidelines reflect patterns from 20+ Flexor deployments at alternative asset managers.

The promotion decision

Every skill, agent, or knowledge document starts somewhere. Knowing where to start it - and when to promote it - is the core vault management judgment.

Start at L4 or L3, promote when stable

New automations should start at L4 (project) or L3 (personal). This keeps experimental work isolated from shared infrastructure. Promote to L2 when:

1. The skill or agent has run for at least two weeks without a configuration change
2. At least two operators have reviewed the output and confirmed it is correct
3. The skill’s inputs and outputs are documented in the vault

Never put untested work directly into L2. A broken L2 skill affects all agents that reference it.

Distinguish rules from skills

Rules (compliance constraints, SLA thresholds, notification routing) belong in knowledge/ or rules/. They are readable documents that agents query. Skills are executable - they take inputs and produce outputs. Putting business logic in skills instead of rules makes it harder to audit and harder to change.

# Do this - threshold as a knowledge document
vaults/company/knowledge/sla-thresholds.md

# Not this - threshold hardcoded in a skill
sla_threshold: 30  # in a skill YAML

The knowledge-document approach lets a non-technical operator update an SLA threshold by editing a Markdown file. The hardcoded approach requires a skill edit, review, and sync.

L2 is shared infrastructure - treat it that way

Changes to L2 should go through a review process before sync. In most PLEXI deployments, the COO or data operations lead owns L2. They review skill and agent changes the same way they would review a change to a shared runbook.

A lightweight L2 change process:

1. Author makes the change in a local branch
2. One peer reviews the YAML (is the logic correct? are edge cases handled?)
3. Change is tested in a sandbox environment
4. COO approves promotion to production L2

Common mistakes

Mistake 1 - L2 sprawl

Promoting too many agents and skills to L2 before they are stable. The result: a cluttered L2 that operators do not trust because they have seen broken agents there before.

Fix: Keep L2 small. Only promote skills that are fully tested and actively used. Archive unused agents rather than leaving them in L2 indefinitely.

Mistake 2 - Configuration duplication

Defining the same data connection or notification webhook in multiple skills instead of once in vault.json.

Fix: All environment-specific values (data catalog URL, Slack webhook, API keys via env: references) belong in vault.json. Skills reference them via vault context variables, not as hardcoded values.

Mistake 3 - Project vault cleanup failure

L4 vaults from completed projects left in the active configuration. Old agents can trigger unexpectedly if their schedule is still active.

Fix: Archive L4 vaults at project close. flexor archive --vault <project-name> removes the vault from the active runtime while retaining it for audit purposes.

Mistake 4 - Sync skipped after changes

Editing vault files locally and running agents before syncing. The runtime sees the old state.

Fix: Add flexor sync to your deployment checklist. If you use CI, gate agent deployments on a successful sync step.

Tier assignment quick reference

Content type	Recommended tier	Rationale
Standard library skill invocations	L1 (read-only)	Use what PLEXI provides; don’t re-implement
Firm-wide monitoring agents	L2	Shared across all operators
Firm-wide SLA thresholds	L2 (knowledge/)	Readable by everyone; owned by COO
Fund-specific reporting agent	L2 or L4	L2 if multiple people run it; L4 if one project
Experimental skill under development	L3	Isolated to one operator until stable
Client deliverable automation	L4	Project-scoped; archived at project close
Personal notification preferences	L3	Operator-specific
Data dictionary	L2 (knowledge/)	Shared reference; updated by data team