Driving work through VibeFlow (vf)

VibeFlow is a local-first orchestrator for AI coding agents (Claude Code, Codex, Copilot CLI). The golden rule: drive the task through vf, do not free-hand it. vf already encodes the confidence gate (nothing is "done" < 1.0 with evidence), the guardrail hooks, the skills store, and the parallel work-unit orchestrator. Re-implementing those by hand (manual codex exec, hand-rolled review, gh pr create loops) is the anti-pattern this skill exists to stop.

This SKILL.md is the slim index. Load a reference file only when the task needs it (progressive disclosure) — do not carry the full detail in every turn.

When to use

Use when a task involves VibeFlow workflow setup, orchestration, agent dispatch, or gated verification.

When not to use

Do not use this skill to bypass the SPEC-FIRST gate or replace evidence with a self-reported completion claim.

Steps

1. Apply the SPEC-FIRST gate, choose the matching flow, load only needed references, then run the flow.

Verification

• vf verify exits 0 after typecheck, lint, tests, evidence, scope, and normative gates pass.
• vf skills validate passes for canonical project skills.

0. SPEC-FIRST GATE (before any writing/dispatching command)

vf init, vf run --yes, and vf orchestrate --yes all WRITE or DISPATCH. Never run them blind. First reflect the task back as a short spec and get confirmation. Ask only the questions whose answers you don't already have:

0.1 Spec questions

1. Goal — one sentence: what does "done" look like? (becomes the workflow goal)
2. Scope — which files/dirs may change? what is off-limits? (drives per-unit scope)
3. Engine — claude, codex, or copilot? (default: copilot). Cheap mechanical work → codex.
4. Risk class — docs | simple-code | feature | architecture | security | deploy (sets the confidence band; default 1.0 for code).
5. Parallel? — one concern → a single unit; several independent slices → one work unit each. Overlapping file scopes are serialised automatically.
6. Real run or preview? — default everything to a DRY run first, confirm, then --yes.

State the spec back in 3-5 lines, ask the open questions, WAIT for the answer, THEN act. Skip the gate only for read-only commands (vf doctor, vf units status, vf verify, vf skills list, any --dry-run).

1. Pick the flow

Always start with vf doctor --probe if you have not confirmed an engine is ready this session — a dispatch against a cold engine fails the creation gate.

Bare /vf — grill first

If the user typed /vf with NO task, do not guess and dispatch. Load references/grill.md: read the recent chat context (last messages, open files, errors), infer 2-3 likely intents, then relentlessly grill the user through the SPEC-FIRST questions until the spec is concrete — then map it to a Flow above. (Interview technique credited to mattpocock/grill-me.)

2. References (load on demand)

• references/flows.md — full Flow A-D playbooks (init / spec→task / workflow / verify-and-ship), every flag explained.
• references/grill.md — bare /vf context-grill protocol: infer intents, interview to a spec, route to a Flow.
• references/hooks.md — guardrail hooks: arming, the live PreToolUse gate, per-engine block-vs-detect semantics.
• references/pitfalls.md — the anti-patterns learned the hard way; read before improvising.

3. Skills and external docs (before inventing steps)

• vf skills list / vf skills search <task> — find a verified skill before hand-rolling.
• vf skills resolve — report which skill needs are satisfied locally vs. on demand.
• vf discover docs <lib> --yes — pull external library docs via Context7 (network needs --yes).
• vf discover skills "<task>" --yes — find an external skill to import.
• vf skills validate — validate the skill store against the Anthropic format.
• vf skills sync --engine <name> — mirror .vibeflow/skills into an engine's skill dir.

4. Verification (prove it worked)

• After init: vf doctor (engine ready + hooks armed) and the generated files exist.
• After a dispatch/workflow: vf verify exits 0 (all gates green) and vf units status shows the units done at confidence 1.0 with recorded evidence.
• When the work edited repo code directly (not via a vf dispatch): the repo's own gate checklist still applies in full — bun run fix, bun run check, bun run build, e2e on UI diffs, refresh-normative-proofs, and pre-push review evidence. Load .vibeflow/skills/bun-typescript-conventions §Verification; on this repo bun run check IS the CI check job, so skipping it is how "every change fails CI" happens.
• Validate this skill itself: vf skills validate.

See references/flows.md §Flow D and references/pitfalls.md for the full verify loop.

Powered by VibeFlow.