Bamdra VibeFlow

AI-native development workflow for multi-agent collaboration

面向多智能体协作的 AI 原生开发工作流

English Docs | 中文文档

Bamdra VibeFlow defines a minimal set of files and slash commands that let Claude Code, Codex, and other AI agents collaborate on a project with a shared, consistent context — no matter which orchestration backend you use.

---

Quick Install

Shell (recommended):

curl -fsSL https://raw.githubusercontent.com/bamdra/vibeflow/main/install.sh | sh

Python (no curl required):

python3 -c "$(curl -fsSL https://raw.githubusercontent.com/bamdra/vibeflow/main/install.py)"

From source:

git clone https://github.com/bamdra/vibeflow.git
cd vibeflow
python3 scripts/install_claude_commands.py
python3 scripts/install_codex_skill.py

Override install paths with environment variables:

CLAUDE_COMMANDS_DIR=~/.claude/commands \
CODEX_SKILLS_DIR=~/.codex/skills \
  curl -fsSL https://raw.githubusercontent.com/bamdra/vibeflow/main/install.sh | sh

---

What is it?

VibeFlow gives each AI agent a consistent answer to three questions:

1. What am I doing right now? — INSTRUCTIONS.md
2. How does this system work? — ARCH.md
3. Where did we leave off? — STATUS.md

A fourth file, .vibeflow/orchestration.yaml, tells agents which collaboration mode to use and how to dispatch work to other agents.

User message
     │
     ▼
Claude Code  ──reads──▶  INSTRUCTIONS.md
     │                   ARCH.md
     │                   STATUS.md
     │                   .vibeflow/orchestration.yaml
     │
     ├─ solo ──────────▶  Claude executes directly
     │
     ├─ paired ────────▶  Claude: analysis + design + review
     │                    Codex:  implement + verify
     │
     └─ orchestrated ──▶  vibebridge / ccb routes tasks
                          to agents by role

---

Usage

1. Initialize a project

In Claude Code, run:

/bamdra-vibeflow-init

Or configure the orchestration settings:

/bamdra-vibeflow-config

Or from the terminal:

python3 scripts/bamdra_vibeflow.py inspect --project .
python3 scripts/bamdra_vibeflow.py scaffold --project . --write

2. Plan tasks

/bamdra-vibeflow-plan

Discuss requirements and design. Conclusions are saved to .vibeflow/notes/solution-plan.md and the current task is distilled into INSTRUCTIONS.md.

3. Run tasks

/bamdra-vibeflow-run

VibeFlow reads INSTRUCTIONS.md, picks the best collaboration mode, dispatches work to other agents if needed, and syncs STATUS.md when done.

---

Collaboration Modes

Mode	When to use	How it works
solo	Simple tasks, single agent	Claude does everything
paired	Medium tasks, Claude + Codex available	Claude: analysis/design/review; Codex: implement/verify
orchestrated	Complex tasks, explicit scheduling	Provider routes tasks to agents by role

VibeFlow auto-detects available modes and degrades gracefully: orchestrated → paired → solo.

---

Provider Support

The orchestrated mode works with multiple backends:

Provider	Type	Status	Command
vibebridge	Local broker (default)	Recommended	bvb ask <agent> "<prompt>"
ccb	Terminal launcher	Compat mode	ask <agent> "<prompt>"
internal	Custom	Reserved	—
none	—	Not configured	—

Configure in .vibeflow/orchestration.yaml:

orchestrator:
  provider: vibebridge   # or: ccb, none
  fallback_to: paired

---

Project Files

your-project/
├── INSTRUCTIONS.md              # Current task sheet (one task at a time)
├── ARCH.md                      # Architecture facts
├── STATUS.md                    # Progress and next steps
└── .vibeflow/
    ├── orchestration.yaml       # Mode and provider config
    └── notes/
        └── solution-plan.md     # Design notes (multi-round)

INSTRUCTIONS.md is a task sheet (当前执行单), not a backlog. It should contain only the current task, its constraints, and acceptance criteria. Everything else lives in ARCH.md, STATUS.md, or .vibeflow/notes/.

---

Repository Structure

.
├── install.sh                   # One-line shell installer
├── install.py                   # Self-contained Python installer
├── scripts/
│   ├── bamdra_vibeflow.py       # CLI: inspect / scaffold / summary
│   ├── install_claude_commands.py
│   └── install_codex_skill.py
├── vibeflow/
│   └── templates/               # Workflow file templates
├── skills/
│   └── bamdra-vibeflow/         # Codex Skill
├── .claude/
│   └── commands/                # Claude Code slash commands
├── docs/                        # Specifications and guides
└── examples/
    └── minimal-project/

---

Requirements

• Python 3.8+
• Claude Code (for slash commands)
• Codex CLI (optional, for paired/orchestrated modes)
• bamdra-vibebridge (optional, recommended for orchestrated mode)

---

Documentation

English:

• Getting Started
• Installation
• Usage
• Best Practices
• Orchestration Config Reference
• Provider Guide
• Architecture
• Compatibility
• Contributing

中文：

• 快速上手
• 安装说明
• 使用说明
• 最佳实践
• 调度配置参考
• Provider 配置指南
• 架构说明
• 兼容矩阵
• 贡献指南

---

Contributing

Contributions welcome. Please open an issue before submitting a large PR.

---

License

MIT