VibeFlow Master Spec

Contents

One-sentence summary

A local-first npm CLI harness that opens AI-first Home and coordinates Claude Code, Codex CLI, GitHub Copilot CLI, OpenCode, and Antigravity CLI using shared project context, Anthropic-style skills, source/file readers, typed capability manifests, hooks, multi-agent planning, verification, and continuous skill evolution.

What the tool does

- Starts from npm/npx
- Opens AI-first Home; `vf init` handles repository intake in a TTY
- Keeps session search, queue editing, typed participant proposal/review/commit, quotes, reactions, and approvals in chat
- Collects repo, task, docs, and work management sources
- Finds source connector skills
- Finds file reader skills
- Reads and normalizes project context
- Generates CLAUDE.md, AGENTS.md, and Copilot instructions
- Creates Claude agents and Anthropic-style skills
- Dispatches Claude Code, Codex, Copilot CLI, OpenCode, or Antigravity CLI through the canonical owned async route
- Uses hooks and the typed capability fabric to control risky actions
- Verifies diff, tests, logs, and acceptance criteria
- Proposes skill updates from lessons learned

Key design principles

Main agent is the coordinator; the selected CLI remains the engine of record.
For coordinate routes, the coordinator is the sole authority and the executor is a different admitted engine that only performs the committed work. Typed add-participant proposals promote direct → coordinate through proposal/review/commit, and removing the last executor collapses the route back to direct. `coordination-coordinator` is read-only and `coordination-executor` is the writable executor role on a distinct ready engine. Claude and Codex currently advertise both native role-sandbox authority and authenticated structured coordination output. Copilot, OpenCode, and Antigravity stay on workflow transports and fail closed for this route until their adapters can prove both contracts. Claude coordinating Codex is the reference example, not a fixed binding.
Exact by-id resume is limited to Claude, Codex, and OpenCode.
An exact resume trusts the CLI's own history and sends only new user and peer-agent deltas.
Do not repeat a recipient's own prior output when native cursor proof is exact.
When supported native reconciliation detects compaction or exact proof is unavailable, revoke exact authority and replay bounded structured own public history; never omit it silently.
Keep incremental context bounded to the user and other agents in the route; never duplicate the receiving CLI's own native history.
Clarifications and corrections stay with the coordinator; it resolves ambiguity by checking the task spec, then conversation context, then repo evidence, then a safe default, and asks the user only as a last resort.
Do not rely on stale model memory for version-sensitive tasks.
Use verified skills when available.
Search trusted external docs/skills when needed.
Do not silently install or enable risky dependencies.
Confidence below threshold triggers bounded investigation, not infinite loops.
If confidence remains low, recommend the next best action with evidence.
Ask for approval only for side effects or high-risk actions.
No evidence, no conclusion.
No verification, no completion.
Generate the fewest files possible.
Everything a tool emits is AI-generated, not hand-maintained boilerplate.
Declare persisted/API/config vocabularies once as frozen `as const` authorities; never duplicate them as enums or raw UI/backend unions.

Conversation and owned-process contract

  • vf / vf ui open AI-first Home: searchable session rail, central conversation, queue-aware composer, participant details, and inline typed actions.
  • Sends made during agent work enter durable FIFO order. ArrowUp edits only the latest queued human message; a race preserves the draft for explicit send-as-new. Only transport-ambiguous requests or typed retryable: true + recovery_action: retry admission failures may replay the exact idempotency-bound request. Typed failures wait for an explicit retry; an in-flight admission interrupted by browser offline stays Reconciling and replays the exact request automatically only after authoritative refresh. Non-retryable collisions retain their exact payload as Needs action for typed recovery or confirmed dismissal and never auto-resend.
  • Add/remove agent actions happen in chat. Typed add-participant requests create a proposal that can promote a direct route into coordinate through proposal/review/commit, and removing the last executor collapses it back to direct. Quotes may reference one through eight visible cross-source messages; reactions use the bounded typed emoji set and agent anti-spam cap.
  • Public delivery is canonical VF-TURN/1 JSON. Exact native resume sends only new user and peer response/reaction deltas; when supported native reconciliation detects compaction or exact proof is unavailable, full/unproved delivery adds up to eight recipient responses, capped at 2 KiB UTF-8 each with provenance/digest/counts, and may add content-addressed VF-HANDOFF/1.
  • Private ranges use one-shot VF-PRIVATE-FILE-RANGES/1 JSON. A Copilot prompt file is an argv transport fallback, not session history or memory.
  • Owned async launches persist supervisor/CLI PID plus exact start identity and release only after quiescence plus streams-drained.
  • Executors work in linked git worktrees, must commit their result, and the host only promotes a clean, quiescent HEAD by fast-forward after verification. Removing the last executor collapses the route back to direct. Failures and divergence remain preserved for recovery.
  • Windows uses a kill-on-close Job Object with kernel-contained proof. Linux/macOS use an isolated process group with cooperative-lineage proof. Live/unprovable recovery fails closed. Injected tests and the native windows-latest smoke both cover PID identity, Job Object containment, release, and orphan recovery. Release is fail-closed on that live proof: release-please waits for the main-push aggregate, npm publish waits for the release-workflow aggregate, and both Windows jobs check out the exact github.sha they authorize.

Minimal-footprint and AI-generated output

VibeFlow must keep the number of files it creates in a target repo as small as possible, and every file it does create must be produced by the AI at runtime from canonical context — not copied from static, hand-maintained template files.

- Generate the minimum set of files needed for the selected engine and task.
- Do not scaffold files the current run does not use (lazy, on-demand generation).
- Prefer one canonical source plus on-demand projections over many persisted copies.
- No static template files checked into the tool as the source of generated output;
  the orchestrator composes each file from canonical context with the AI.
- Generated files are disposable and reproducible: deleting them and re-running
  must reproduce equivalent output from the same canonical context.
- Collapse optional/empty artifacts: only emit per-area files (e.g.
  .github/instructions/*.instructions.md, .claude/agents/*) that the task actually needs.

This principle takes precedence over the illustrative “full” file lists elsewhere in these specs (for example in GENERATED_FILES.md and ARCHITECTURE.md): those lists describe the maximum surface VibeFlow may generate, not a set it must always create.

Engine support

Claude Code:
- CLAUDE.md
- .claude/agents
- .claude/skills
- .claude/settings.json

Codex CLI:
- AGENTS.md
- .codex/config.toml
- prompt-injected selected skills

GitHub Copilot CLI:
- AGENTS.md
- .github/copilot-instructions.md
- .github/instructions/*.instructions.md
- prompt-injected selected skills

OpenCode:
- AGENTS.md
- opencode.json
- .opencode/plugins/vf-guard.ts
- .opencode/skills

Antigravity CLI (`agy`):
- AGENTS.md
- .agents/agents
- .agents/skills
- .agents/mcp_config.json
- .agents/hooks.json

Skill system

External skills = baseline knowledge from trusted sources
Internal skills = verified project/team lessons

Every skill:

- has SKILL.md
- has metadata in SKILL.md YAML frontmatter
- declares capabilities
- declares permissions
- has status: draft / experimental / verified / deprecated
- has changelog when updated

Hook system

Hooks use a universal protocol:

pre-command
post-command
pre-write
post-write
skill-compliance
final-verify

Decisions:

allow
warn
require_approval
block

Security posture

Local-first
Read-only by default
No public tunnel by default
No silent install
No source upload by default
No auto-push
No auto-merge
No auto-deploy

Engine readiness

presence   → binary on PATH (or `which`)
auth       → whoami / login status, no live run
quota      → parse claude / codex / copilot quota output (src/engine-quota.ts)

Engine readiness results are cached in-process (src/probe-cache.ts): stable results live 60 s, transient probe-failed results live 5 s. vf doctor --refresh discards the cache and re-probes immediately. The preflight gate (src/preflight-delegate.ts) layers presence → auth → quota in that order and auto-falls-back to the next ready engine when the chosen one is exhausted, returns 429 / 403, or fails auth.

Pre-flight quota gate

exhausted  → engine reports 0% quota remaining       → fall back to next ready engine
429        → rate-limited response                    → fall back to next ready engine
403        → forbidden / unauthorised billing region  → fall back to next ready engine
auth       → CLI present but no valid credentials     → fall back to next ready engine
no engine  → no engine passes all three layers        → block dispatch + surface reason

The gate is evaluated before every dispatch (vf run / vf orchestrate) and short-circuits cheaply on the cache; on miss it parses a single JSON output per engine. See WORK_UNIT_ORCHESTRATION.md for how the gate plugs into the work-unit lifecycle.

Naming decision

The recommended public product name is VibeFlow and the short CLI command is vf.

Recommended package:

npx @magicpro97/vibeflow

Memory recall

VibeFlow ships a built-in recall layer (MemoryProvider seam, two providers):

  • builtin (default opt-in): bun:sqlite FTS5 over .vibeflow/knowledge/decisions.md; zero deps; lazy-indexed on mtime.
  • claude-mem (external opt-in): shells claude-mem search; requires separate install.

Recall injects a Relevant past decisions: block into dispatchPrompt (between Skills and Constraints) and buildPlanPrompt (beside §2 Non-negotiables). Off by default; enable via vf config memory builtin.

Updated skill provider decision

The Context7 HTTP API should be the primary external skill and documentation resolver. It is queried over HTTP (https://context7.com/api/v2) via the runtime fetch — no external ctx7 binary is required — with an optional CONTEXT7_API_KEY for higher rate limits. Vercel find-skills remains a supported secondary provider.

Default priority:

1. Local verified skills
2. Context7 HTTP API (skills and docs)
3. Anthropic official skills/plugins
4. Vercel find-skills
5. Official vendor docs
6. Trusted MCP registries
7. Community skills after review
8. npm packages after security verification

Related: Architecture · Security Model Edit this page on GitHub