vibeflow

VibeFlow

What is VibeFlow?

VibeFlow is a docs-first development workflow for Claude Code. Clone it into your project and it enforces the discipline that vibe coding usually skips: write specs first, then tests, then code, with guardrails that block you from cutting corners.

Two layers make this work:

• Workflow: A staged pipeline that walks you from spec to ship, with validated checkpoints between each phase. Four track sizes (Micro → Large) so a config tweak doesn't need the same process as a new auth system.
• Guardrails: Hooks that run on every prompt. They block work on main, prevent stage-skipping, and validate your docs automatically. No self-reporting.

The result: specs that actually drive tests, tests that actually drive code, and decisions that are traceable from doc to branch to PR.

Projects Using VibeFlow: Open a PR to add yours!

Project	Description
	CV-Tailor: A full-stack app that transforms work artifacts (GitHub repos, PDFs, web content) into customized, job-specific CVs and cover letters using OpenAI API.

The Pipeline

Quick Start

Installation

claude plugin marketplace add hardness1020/VibeFlow
claude plugin install vibeflow@vibeflow

Skills appear as /vibeflow:<skill-name> and hooks enforce the workflow.

To update the plugin after installation, run claude plugin update vibeflow.

---

Step 1 — Clarify your idea (optional)

/clarify-demand

Describe what you want to build. VibeFlow asks clarifying questions and checks feasibility before you commit to a plan.

Step 2 — Register a work item

/manage-work register "Add search feature" 1 small

This creates a feat/add-search-feature branch, picks the right track (Micro/Small/Medium/Large), and starts tracking your progress.

Step 3 — Write your docs

Depending on your track size, produce the required documentation before any code:

/define-prd 1                          # Stage A (Large only) — PRD with success metrics
/analyze-codebase 1                    # Stage B (Medium+)   — codebase discovery
/define-tech-spec 1 add-search-feature # Stage C (Medium+)   — architecture & API contracts
/record-decision 1 add-search-feature  # Stage D (Medium+)   — ADRs for non-trivial choices
/create-feature-spec 1 add-search-feature # Stage E (Small+) — feature spec with acceptance criteria

Small tracks start at /create-feature-spec; Medium adds B-D; Large adds the PRD on top. Micro tracks skip docs entirely and go straight to TDD.

Step 4 — TDD cycle: red → green → refactor

/run-tdd red        # write failing tests from spec
/run-tdd green      # write minimal code to pass
/run-tdd refactor   # clean up with integration tests

Step 5 — Close and merge

/manage-work close 1

Validates that implementation is complete (Checkpoint #4), marks the work item as DONE, and you're ready to merge.

Customizing for your project (optional)

Copy the local overrides template to set personal preferences (test runner, language style, environment details):

cp .claude/CLAUDE.local.md.example CLAUDE.local.md

CLAUDE.local.md is gitignored — it won't affect other contributors.

---

For Contributors & Advanced Users

Everything below is for people modifying VibeFlow itself or wanting to understand the internals.

Workflow Pipeline

Each stage produces a specific artifact. See the pipeline diagram above for stage flow, track sizes, and checkpoint gates.