| name | vibeloom |
| description | Contract-driven governance for long-lived AI-coded projects. Use when the user wants to bootstrap, import, generate, review, reconcile, or approve artifacts in a project governed by the VibeLoom methodology (modes: vibe, pm, dev, expert). |
VibeLoom
VibeLoom governs long-lived AI-coded projects by generating a tiered contract of specifications (intent-specs → product-specs → system-specs), deriving execution context from it, and generating code from the approved stack. The user retains approval authority; subagents do the scoped work in parallel waves.
When to use this skill
Invoke on any $vibeloom or /vibeloom command, or when the user mentions VibeLoom, contract-driven governance, or asks to run any of the methodology operations (init, import, generate, eval, review, reconcile, approve, status).
Authoritative sources
Always consult these before making decisions:
- vibeloom-methodology.md — WHAT and WHY (entities, tiers, modes, operations, approval model, derivation DAG). If this skill file conflicts with the methodology, the methodology wins.
- vibeloom-implementation.md — HOW (artifact layout, metadata shape, ID schema, runtime loop, subagent dispatch, load sets).
Runtime references (load on demand)
- references/operations.md — per-operation quick reference (purpose, parameters, preconditions, postconditions).
- references/modes.md — per-mode behavior (
vibe, pm, dev, expert): tier ownership, auto-advance, public surface.
- references/runtime.md — dispatch mechanics: runtime loop, waves, load sets, late-fetch, validation.
- references/artifacts.md — artifact layout, frontmatter shapes, ID schema, derivation rules.
- references/eval.md — semantic-eval dimensions, finding schema, severity classification (what the agent checks on top of the engine's structural eval).
- references/troubleshooting.md — failure modes and recovery (cache corruption, direct edits, breaking changes, partial wave failure).
Templates
The 17 artifact templates live under assets/:
intent-specs/: intent.md, vibe-intent.md, defaults.mdproduct-specs/: prd.md, usm.md, dm.mdsystem-specs/: system.md, vibe-system.md, containers.md, container.md, component.mdcontext/: pdr.md, adr.md, bdd.md, root-config.md, container-config.md, component-config.md
Load one template at a time for the artifact being generated.
Engine
The engine/ directory contains the Python package that implements the deterministic substrate described in vibeloom-implementation.md. Zero install, zero dependencies — Python 3.10+ is the only requirement. Invoke the engine via python -m with PYTHONPATH pointing at engine/:
PYTHONPATH=<skill-root>/engine python3 -m vibeloom_engine <command> --repo <target-repo>
<skill-root> is the directory containing this SKILL.md. Available commands:
| Engine command | Purpose |
|---|
python3 -m vibeloom_engine parse --repo <path> | Parse all artifacts; emit JSON inventory |
python3 -m vibeloom_engine graph --repo <path> | Build + persist .vibeloom/state/context-graph.json |
python3 -m vibeloom_engine eval --repo <path> [--target <tier>] | Run structural eval; non-zero exit on blocking findings |
python3 -m vibeloom_engine affected --repo <path> --ids <IDs...> | Compute the affected set from changed item IDs |
python3 -m vibeloom_engine staleness --repo <path> | Detect stale artifacts (approved-basis mismatch) |
python3 -m vibeloom_engine status --repo <path> | Emit a status snapshot; persist .vibeloom/state/status.json |
python3 -m vibeloom_engine detect-edits --repo <path> | Detect direct edits on approved contract artifacts (mtime fast-path, per-item hash confirmation) |
All engine commands emit JSON on stdout. The engine makes no semantic judgments — it parses, validates structure, computes the graph, and reports. Semantic judgment and user interaction remain with the skill.
Optional: pip install -e engine puts a shorter vibeloom-engine command on PATH. Not required for skill operation.
Command routing
On any operation invocation, load references/operations.md first for parameters and preconditions, then load the subset of references/ relevant to the operation:
| Operation | First load | Then |
|---|
init, import | operations.md, modes.md | template for intent (init) or reconstruction prompts (import) |
generate <target> | operations.md, runtime.md | target-tier templates + graph cache |
eval <target>, review <target> | operations.md, runtime.md, eval.md | target artifacts + methodology eval checks |
reconcile <target> | operations.md, runtime.md, eval.md | downstream artifacts + graph |
approve <target> | operations.md, modes.md, eval.md | target artifacts |
status | artifacts.md | graph cache + status snapshot |
Getting started
If the repo has no VibeLoom governance yet, the user typically starts with init --mode <vibe|pm|dev|expert> (new project) or import --mode <mode> (existing codebase). Consult references/modes.md to help the user pick a mode.
Guardrails
- Never bypass an approval gate. When a contract tier is a user stop in the current mode, halt and surface findings rather than advancing.
- Treat the methodology as authoritative. If this file or a reference disagrees with the methodology, follow the methodology and flag the drift.
- Do not invent entity types, ID prefixes, or derivation edges. The valid set is defined by the methodology's Derivation DAG.
- Subagents receive scoped load sets only. They never load the skill or the methodology docs.
- Late-fetch is bounded: one re-invocation per task; exceed means a finding and task exit.
reconcile is always user-initiated. Never auto-invoke it.
Response shape
Keep responses tight. For operations that pause for user input, use a four-section structure:
- Scope — what tier/scope this operation touched
- Decision — what the skill did or is asking the user to decide
- Affected — item IDs, artifacts, and scopes changed or surfaced
- Next — the suggested next command
