§ 06 · FAQ FIG. 06 · DWG VC-006

The questions strangers ask first.

This page exists so the framework can explain itself without forcing people to reverse-engineer the repo, the shell helpers, or the license before they know whether the system fits.

"The installer, docs, and command deck should all promise the same thing."

Read Quick Start Back to Overview

Installation 4 items

01 Why does 𝚅𝚒𝚋𝚎𝚌𝚛𝚊𝚏𝚝𝚎𝚍. install into $VIBECRAFTED_ROOT/.vibecrafted/ instead of $HOME/.agents/?

$VIBECRAFTED_ROOT/.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.

02 Can I install 𝚅𝚒𝚋𝚎𝚌𝚛𝚊𝚏𝚝𝚎𝚍. 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.

03 What does make doctor actually check?

The doctor verifies the central store, helper availability, symlink health, required foundations (loctree-mcp and aicx-mcp), evidence tools such as prview and ScreenScribe, plus whether your shell environment is quiet enough for agent tooling.

04 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 5 items

05 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.

06 Why not just use ChatGPT, Copilot, or a single giant prompt?

Because 𝚅𝚒𝚋𝚎𝚌𝚛𝚊𝚏𝚝𝚎𝚍. 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.

07 Are loctree and aicx required?

Not honestly. loctree and aicx are required foundations: one gives the agent structural perception, the other restores prior decisions and intent. If either is missing, fix the foundation layer before trusting the workflow.

08 How do I get screenscribe review past early model validation?

Treat it as runtime truth, not folklore. Keep the CLI reachable on PATH, keep ~/.config/screenscribe/config.env aligned with the Libraxis defaults, use ai-suggestions for the model aliases, set SCREENSCRIBE_VISION=false as operator intent, and remember that the current CLI still overrides that stored flag during review, so the launcher surface must inject --no-vision for plain review runs on the current Libraxis path. The repo-local source of truth is the ScreenScribe Review Gate doc.

09 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 4 items

10 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.

11 Can I run 𝚅𝚒𝚋𝚎𝚌𝚛𝚊𝚏𝚝𝚎𝚍. 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.

12 What lives in $VIBECRAFTED_ROOT/.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.

13 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 3 items

14 Is 𝚅𝚒𝚋𝚎𝚌𝚛𝚊𝚏𝚝𝚎𝚍. 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.

15 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.

16 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.