Ralph Vault

Ralph Vault

Lifecycle tool for a knowledge vault: a tiered deepwiki that documents the intent, interfaces and structure of one or more code repositories, kept faithful and current so agents (especially ralph loops) have a reliable knowledge source. Project-agnostic — the documented repos live in a per-vault config registry, nothing is hardcoded.

How it is split

• Deterministic work → scripts/gv.py (a single stdlib CLI): scaffolding, the repo registry, status, validation, and emitting ralph plan files. Run it directly; it needs no context loaded.
• Content generation → FIXED prompts in assets/prompts/ driven by an agent / ralph loop: writing the actual documentation from source.

Run gv.py from the project that owns the vault. Default vault path is vault/; override with --vault <path>.

Action router

Load the matching reference file only for the action at hand (progressive disclosure). Do not preload all of them.

Shared contracts (load when authoring or validating content, not for routine CLI calls):

• references/vault-structure.md — the tier layout, load tiers, and frontmatter contract.
• references/config.md — the .ralphvault/config.json registry schema.

Quick start

gv=scripts/gv.py                      # path to this skill's CLI
python3 $gv --vault vault init --project myproj
python3 $gv --vault vault add --name my-svc --path ../my-svc --stack auto
python3 $gv --vault vault plan --needs-work        # → plan/plan.md + plan/task/NN.md (only affected entries)
ralph-loop.sh 30 plan/plan.md                     # drive generation (any ralph runner)
python3 $gv --vault vault validate                # gate before committing
python3 $gv --vault vault check                   # status overview (path-aware staleness)

Hard rules

• Phase separation (agent vs loop): the agent only runs the deterministic CLI actions (init, add, delete, plan, validate, check, mark-synced, mark-reconciled) and never authors vault content itself. All content generation (update/bootstrap/sync, relations, dependencies, components) is delegated to a ralph loop. After plan, the agent's turn is done: return the ralph-loop.sh <N> plan/plan.md command and stop — do not open subagents or write into repos/, relations/, infrastructure/, technologies/, components/ yourself. Generate content directly only if the user explicitly asks for it.
• Never copy source code into the vault. Extract intent, interfaces, structure, named entities only.
• Aggressive progressive disclosure: load the minimum context for the current single task. Start from tier-1 cards (agent-context/repo-cards/*); descend into deeper tiers or read source only when the task cannot be completed otherwise. Never preload whole repos, all docs, or unrelated tiers.
• Always stamp frontmatter + provenance (commit, last_sync) on repo-derived docs — see references/vault-structure.md.
• Validate before done: any generation task (run by the loop, or by the agent only when the user explicitly asked) is not finished until gv.py validate reports zero errors for the touched files. For the agent, a plan handoff is "done" once the plan files are emitted and the command is returned.
• One repo per ralph iteration: keep generation tasks atomic so a fresh-context loop stays deterministic.
• Incremental & path-aware: staleness and sync scope are computed from the last commit touching each entry's source (so a subdir is not flagged on unrelated monorepo commits), and from each doc's source_globs (so a sync regenerates only the changed modules). Close every generation via gv.py mark-synced (advances last_sync_commit + logs commit→docs to meta/changelog.md); never hand-edit config.json.
• Nothing project-specific lives in the skill: repos, URLs, stacks and budgets come from the vault's config, never from edits to these files.