AGENTS.md

⚡ VibeFlow v0.15.0 Active — local-first orchestrator for AI coding agents (https://github.com/magicpro97/vibeflow).

Project: vibeflow-hermes-execution · Goal: Complete Draft v7 brainstorming/debate end-to-end across runtime, CLI, policies, API/SSE, UI, and verification.

• For code navigation (definitions, references, callers, impact): prefer the language-server (LSP) MCP tools first; only fall back to grep/find/read if the others are unavailable.

VibeFlow commands (use these)

• vf doctor — check engine readiness before dispatching.
• vf init — regenerate context/engine files after editing .vibeflow/*.
• vf orchestrate — plan + dispatch work units in parallel under the confidence gate.
• vf verify — typecheck/lint/test + confidence/evidence/scope gates BEFORE claiming done.
• vf skills — list/resolve verified skills; prefer them over inventing steps.
• vf hooks emit --yes — ARM the guardrail (blocks destructive/free-handed actions; vf doctor shows ON/OFF). Working with vf — Confidence gate (MANDATORY): After ANY code edit, and BEFORE you claim a task is done, YOU MUST run vf verify and include its output as evidence. Nothing is "done" until vf verify passes at confidence 1.0 (command output, file path, or test result), within scope. No verification, no completion. Drive every task through vf — do not free-hand it. Arm the guardrail once with vf hooks emit --yes so this is enforced, not just advised. Learn from the run: capture a reusable procedure or worked-around mistake as a DRAFT skill (vf skills draft <name>), and record non-obvious decisions with vf decision add. vf orchestrate auto-crystallizes recurring patterns into a DRAFT for review. Full workflow guide: load the vf skill (or /vf in a CLI) — Flow A–D, pitfalls, and hooks live there. Powered by VibeFlow v0.15.0 — https://github.com/magicpro97/vibeflow

Bun and TypeScript conventions

• Read docs/CODING_CONVENTIONS.md before changing source, tests, protocols, subprocesses, or build configuration.
• Bun drives development and tests; shipped source must remain compatible with the Node-targeted ESM bundle.
• Do not add TypeScript enum or const enum. Shared closed vocabularies use one frozen as const runtime authority with inferred unions and total satisfies projections. Do not centralize genuinely local one-use literals.
• Keep strict TypeScript, portable argv-based process launches, deterministic cleanup, descriptive bun:test coverage, and the 400-line source cap.
• Run focused checks while iterating and the final vf verify confidence gate after any code edit.

Commit messages (Conventional Commits)

VibeFlow integrates release-please (see commit d88d061), so the commit message on main is the only signal that decides the next version bump. Write commits accordingly.

Bump mapping (release-please changelog sections in release-please-config.json):

Good examples (scope matches this repo's surface area):

• feat(cli): add --dry-run flag to vf orchestrate
• fix(ui): prevent dashboard re-render on tab switch
• ci: integrate release-please for auto-publish on main
• chore(deps): bump biome to 1.9.5
• feat(workflow): support parallel work units with overlapping scopes

Anti-patterns — reword before merging to main:

• update stuff -> fix(cli): handle empty work unit list gracefully
• WIP: trying things -> refactor(workflow): split orchestrator into plan + dispatch phases (or squash/reword — never merge WIP to main)
• Feature: add X -> feat: add X (lowercase, exact spec)

Escape hatch: commits with chore: / docs: / refactor: (or other non-bumping types) do not trigger a release. To ship a new version, land at least one feat: / fix: / perf: / BREAKING CHANGE: commit on main since the last release.

See release-please-config.json for the full changelog-sections mapping.

Release-please setup (first run)

VibeFlow uses release-please (commit d88d061). The bot opens/updates a Release PR on every push to main and publishes npm when merged. For the bot to work on this repo, two one-time settings are required:

1. Repo Settings → Actions → General → Workflow permissions: enable "Allow GitHub Actions to create and approve pull requests". Without it the job fails with: GitHub Actions is not permitted to create or approve pull requests.
2. release-please-config.json contains last-release-sha: 3e5bd90 at root level — that SHA is the last manual release (release: v0.3.17). The bot uses it to skip the pre-release-please history that contains git tags but no Release PRs (otherwise it would bump 0.3.17 → 0.4.0 on the first run, since it falls back to the old git tag v0.3.8 as the anchor).

Cleanup after the first release-please Release PR is merged (i.e. once the bot has tracked one release via PR):

1. Remove the last-release-sha key from release-please-config.json.
2. Commit as chore(ci): drop last-release-sha after first release-please run.
3. The bot will then self-track versions via merged Release PRs.