All commands

Incremental mode (default): re-analyzes only what changed since the last run, detected via git. A run is also due when only a test file, the CI configuration, or the test runner's configuration changed.

Full rebuild from scratch. Ignores existing .vibeflow/, re-analyzes everything.

Deep-dive into a specific module or directory (80%+ of files). Enriches global patterns with module-specific examples.

Adds a review checkpoint: presents patterns found, asks about false positives and missing patterns before saving.

Analyzes an external dependency repo (design system, shared lib). Clones it, detects what your main repo uses, merges relevant patterns.

Runs the full-suite command and the affected-tests command once each and records their times and the date. Without it, analyze records the test commands without running them.

index.md gains a Tests and Pitfalls block: the full-suite command, the narrowest affected-tests command with its measured time or unmeasured, and the pitfalls with their source.

Imported pattern protection: incremental mode skips patterns that have imported versions (from teach --from). External source of truth takes precedence.

Quick round: if your first response has total clarity (concrete problem, defined audience, closable scope), skips to 1–2 rounds then generates PRD.

Complete flow: 3–5 discovery rounds with strategic questioning. Explores problem, audience, success criteria, scope, and trade-offs.

The dialogue's decisive questions and their answers go under ## Clarifications in the PRD, and gen-spec carries them into the spec.

From PRD: pass a path to .vibeflow/prds/<slug>.md and it uses the PRD as basis for the spec.

From description: describe the feature directly and it generates the spec from scratch.

PRD validation gate: when input is a PRD (file or >3 lines), runs 5 sanity checks (concrete problem, audience, closable scope, .vibeflow/ conflicts, stack viability). Asks up to 2 questions if issues found. Short descriptions skip the gate.

Auto-split: if spec exceeds limits (>7 DoD checks or exceeds budget), automatically splits into numbered parts with dependency tracking.

What the spec cannot decide becomes a [NEEDS CLARIFICATION: <question>] marker, aiming at 3 open at most. Before saving, it checks its own draft (binary checks, a test or Scenarios: on each functional check where the project has a test runner, the marker count) and can ask up to 2 questions in one round; markers still open stay in the saved spec and are named in the reply.

Records the questions asked and their answers in ## Clarifications, at most 5 per session, plus the ones a PRD carries.

A functional DoD check can carry Scenarios: lines in the EARS form (WHEN <condition> THE SYSTEM SHALL <behavior>), and a check can be a property that names its oracle. They are fields of a check: the DoD stays 3 to 7 checks.

Ends ## Risks with a Risk code: list of the paths or functions the change touches in money and totals, credentials and permissions, deleting or overwriting data, and date and time boundaries (Risk code: none when there are none). That is where the audit sabotages.

With no one to answer (claude -p, a pipeline), it can end on its questions with no spec saved.

## Clarifications, Scenarios:, Risk code:, [NEEDS CLARIFICATION: …] and the EARS keywords stay in English in a spec or PRD written in any language, because other commands match them byte for byte.

Find & validate spec: locates spec, validates required sections, checks multi-part dependencies.

Extract guardrails: DoD, scope, anti-scope, budget, and technical decisions become hard rules.

Load context: reads conventions, applicable patterns, index.md. Uses Pattern Resolution for smart matching.

Plan: identifies target files, verifies budget, maps DoD to implementation steps.

Implement: executes following patterns exactly. Minimum change principle. No refactoring outside scope.

Run tests: auto-detects test runner (npm test, pytest, cargo test, etc.). Max 2 fix attempts.

Refine (simplify in scope): cleans the diff it wrote (reuse, names, dead code) on a green baseline and re-runs the tests; reverts if they break.

Self-verify DoD: checks each DoD item with evidence. Reports overall status.

Finish: summarizes DoD, budget, and tests, and suggests /vibeflow:audit as the next step.

Phases 0 to 3 run as above; in place of phases 4 to 8, the session becomes the orchestrator of the execution loop: an executor implements in a fresh session and the independent audit runs in another.

In the front matter of .vibeflow/loop/config.md, turns the loop on for the project.

Turns the loop off for one run, even with the config on.

Without the kit, or without Node.js 18 or newer, the loop stops before phase 0, says what to install, and reminds you that implement without --loop still runs.

Agent-agnostic: works with Codex, Copilot, Cursor, Claude Code, Hermes Agent, or any coding agent.

Embedded patterns: includes real code examples from your .vibeflow/patterns/ so the agent follows your conventions.

Validation: rejects specs with >7 DoD checks or exceeding budget. Requires splitting first.

The audit reads the change from one file, so the review and the Critical Gate judge the same diff. --package <path> reads that package; without it, the audit builds one in .vibeflow/reviews/<feature-slug>-round-0.md from --base <ref> when given, or else from the merge-base with the default branch (or from HEAD, for uncommitted work on the default branch). The diff runs from there to the working tree, so a branch's commits and its uncommitted work are judged together. With --package, --base or --reaudit given, or in a loop part, an empty package ends in FAIL ("nothing to audit"). In an audit run by hand with no diff to package, or with no kit or no Node.js 18+, there is no package and the report records Review package: none (<reason>).

Checks one fix round against its own diff: runs the suite and the audit's probes, closes or keeps each open finding, and looks for new defects in the fix diff only.

Writes behavior probes as tests under <test dir>/audit/ and sabotages risk code, each sabotage undone from a copy checked by hash. By hand, probes and sabotage run only with this flag; without it, the report lists the probe cases as code and records Sabotage: skipped.

Every finding has a severity (defect, risk-gap, low), a cause, and a confidence. An open defect or risk-gap holds the verdict below PASS whatever its confidence, so expect PARTIAL where 1.15 gave PASS. A low finding goes to ### Follow-ups without blocking.

PASS: all DoD checks pass, patterns followed, tests pass, gate clean, and no open defect or risk-gap.

PARTIAL: some checks pass, gaps identified with specific details.

FAIL: DoD not met, tests failing, an unjustified CRITICAL/HIGH Critical Gate finding, or an empty package where a change was expected. Tests fail = automatic FAIL regardless of other checks.

On PARTIAL or FAIL, generates an incremental prompt pack covering only the gaps, so you can fix without re-reading the full spec.

Targets .vibeflow/hotfixes/ instead of a spec: re-runs each doc's DoD checks and regression test against the current code and classifies it as still-holds, promote, or regressed. No PASS/PARTIAL/FAIL verdict.

≤4 files budget: tighter than the standard ≤6. If the task needs more, it warns you to use the full pipeline.

Ephemeral spec: generated in memory only (not saved to disk). Goes straight to prompt pack.

Use for small planned tasks with clear requirements. An observed defect with evidence goes to hotfix, regardless of size. Skip if the idea is vague or architecturally significant.

Short doc in .vibeflow/hotfixes/, written in 2 moments: symptom, hypothesis, and properties to preserve before any code; root cause, DoD, and regression after the fix.

The regression test enters the suite before the fix and must fail on the current code, for the reason the hypothesis names. Written after, it could only agree with the fix.

Two outcomes: done, or a named HALT from a closed set of 6 (e.g., cannot-reproduce, exceeds-hotfix-budget). Every HALT saves the doc with the human's next step; resume by passing the doc path.

verified requires all 4: real reproduction, regression test red→green, project suite green, and a clean Critical Gate. Anything less becomes partial, with the reason visible in the doc.

Later, audit --consolidate-hotfixes reclassifies the trace docs against the current code.

Use when an observed defect has reproducible evidence, even a small one. A planned task with no defect goes to quick; a vague idea goes to discover.

Pattern correction: updates an existing pattern doc with your correction. Survives incremental updates.

New convention: adds to conventions.md (e.g., "we always use named exports").

Architectural decision: adds to decisions.md with context and discarded alternatives.

New pattern: creates a new .vibeflow/patterns/<name>.md file with standard structure.

--from <url|path>: imports patterns and conventions from an external reference repo (e.g., shared coding guidelines, architecture docs). Interactive review lets you pick what to import. Saves to .vibeflow/patterns/external-<name>/.

Conflict detection: when importing or creating patterns, detects name collisions with existing local or imported patterns. Asks which version to keep, with no silent overwrites.

Verdicts breakdown (PASS/PARTIAL/FAIL percentages), DoD pass rate, top 3 most failing checks, top 3 most violated patterns.

Quality trend: improving, stable, or degrading (requires ≥3 audits).

When .vibeflow/loop/ holds ledgers (its .md files other than config.md), the report gains a ### Loop section with the numbers from the kit's loop-stats.mjs (parts, first-audit PASS rate, average fix rounds, median time from dispatch to PASS) and the findings by severity and cause, counted from the audit reports. Without ledgers, the report is unchanged.

A report with Verdict: pending is an audit in progress or interrupted: stats counts it apart ("N audits in progress or interrupted") and leaves it out of every other count.