Installation
Why does VibeCrafted install into ~/.vibecrafted/ instead of
~/.agents/?
~/.vibecrafted/ is the central store and control plane. Agent-specific
directories are only views or symlink targets. The real source of truth, artifacts, and
helper state live in one place.
Can I install VibeCrafted without editing my shell config?
Yes. During the interactive path you can opt out of shell-helper installation. If you
still want helpers in the current session, source
${XDG_CONFIG_HOME:-$HOME/.config}/vetcoders/vc-skills.sh manually.
What does make doctor actually check?
The doctor verifies the central store, helper availability, symlink health, optional
foundations such as loctree/aicx/prview, and whether your shell environment is quiet
enough for agent tooling.
Which install path should I use in CI or automation?
Use make install for the direct non-interactive path, or call
python3 scripts/vetcoders_install.py install --source "$PWD" --non-interactive
when you want full CLI control.
Skills, Agents, Foundations
What is the difference between a skill and an agent?
An agent is the runtime, such as Codex, Claude, or Gemini. A skill is the instruction set
and workflow protocol that tells that runtime how to behave for a specific engineering
phase.
Why not just use ChatGPT, Copilot, or a single giant prompt?
Because VibeCrafted is trying to solve system-shaping, not just chat convenience. It
combines structural awareness, decision retrieval, convergence loops, and shipping
audits so the model sees the repo and the product surface instead of improvising blind.
Can I use VibeCrafted without loctree or aicx?
Technically yes, but you lose structural perception and session continuity. The framework
still runs, but the agent is operating with much weaker context.
What is the Marbles loop?
Marbles is the convergence engine. AI output is noisy, so the framework loops through
implementation, followup, measurement, and fixes until the important classes of findings
reach zero.
Workflow and Operations
When should I use vc-justdo instead of manual phases?
Use vc-justdo when the task is clear and you want the agent to take
ownership end-to-end. Use the phase skills separately when you want to supervise the
architectural decisions more closely.
Can I run VibeCrafted in CI/CD?
Yes. The direct install path is non-interactive, and skills like review, followup, and
release are explicitly shaped to work as repeatable quality or packaging gates.
What lives in ~/.vibecrafted/artifacts/?
Plans, reports, transcripts, and metadata from major runs. The artifact store exists so
agent work leaves durable evidence instead of disappearing into terminal scrollback.
What is Definition of Undone?
DoU is the audit that checks whether people can discover, understand, install, trust, and
adopt the thing. It measures product-surface truth, not only repo health.
Commercial posture
Is VibeCrafted open source?
The framework is distributed under Business Source License 1.1. The repo is visible and
usable, but it is not pure permissive open source.
Can small teams use it in production?
Yes. The Additional Use Grant allows individual developers and teams smaller than five
people to use the framework in production as long as they are not offering a competitive
hosted or embedded product.
What if I need a broader commercial arrangement?
The license points to VetCoders for alternative licensing arrangements. Read the repo
license for the exact terms and contact route before you commit to a broader rollout.
