# VibeCollab — Setup Instructions for AI Assistants

You are helping a user set up VibeCollab in their project.
Execute the following steps in order. Stop and report if any step fails.

## Prerequisites

VibeCollab requires **Python 3.10 or higher**. Recommended version: **Python 3.12** (best balance of performance and compatibility).

Before installing, check the user's Python version:

```bash
python --version
```

If Python is not installed or is below 3.10, guide the user to install Python 3.12+ from https://www.python.org/downloads/

**Virtual environment** (strongly recommended): To keep the user's system clean and avoid dependency conflicts, always create a virtual environment before installing:

```bash
# Create a virtual environment (run once)
python -m venv .venv

# Activate it
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate
```

> If the project already has a virtual environment (`.venv/`, `venv/`, or similar), activate it instead of creating a new one.

## Step 1: Install

```bash
pip install vibe-collab
```

## Step 2: Initialize

Run in the user's project root directory:

```bash
vibecollab init -n "<PROJECT_NAME>" -d <DOMAIN>
```

- `<PROJECT_NAME>`: Ask the user for their project name
- `<DOMAIN>`: Ask the user to choose: `web` / `mobile` / `game` / `data` / `generic`

This creates `project.yaml`, `CONTRIBUTING_AI.md`, and `docs/` directory with protocol documents.

### For Existing Projects

If the project already has code (not an empty directory), do the following **after** `vibecollab init`:

1. **Backfill CONTEXT.md**: Review recent git commits and summarize the project's current state, active tasks, and recent decisions into `docs/CONTEXT.md`

2. **Backfill DECISIONS.md**: Look for important architectural choices in git history and record them in `docs/DECISIONS.md` with proper decision levels (S/A/B/C)

3. **Create ROADMAP.md**: If the project has future plans, create `docs/ROADMAP.md` following the milestone format (see ROADMAP Format section below)

4. **Capture Insights**: If reusable development experiences are found (debugging tricks, architectural patterns, workflow optimizations), capture them using `insight_add` MCP tool

### Quick Start After Init

After initialization completes, tell the user:

> VibeCollab is ready! Here's how to start:
> 
> 1. **Describe your current task** — I'll help you work on it while following the collaboration protocol
> 2. **Or say "onboard"** — I'll read the project context and suggest what to do next
> 3. **Or show me a file/feature** — I'll understand it within the project's structured context

This gives users an immediate path forward instead of leaving them wondering "what now?"

## Step 2.5: Install Git Hooks (Recommended)

Install the pre-commit hook to ensure every commit passes consistency checks:

```bash
vibecollab hooks install
```

**What it does:**
- Automatically runs `vibecollab check` before every `git commit`
- Validates insight fingerprints, protocol compliance, and document freshness
- Blocks the commit if critical errors are found (prevents bad commits)

**Why use it:**
- Catches consistency issues before they reach the repository
- Ensures all insights have valid fingerprints
- Maintains protocol compliance automatically

**If a commit is blocked:**
- Fix the reported errors (recommended)
- Or bypass with `git commit --no-verify` (emergency only)

> **Note:** If `vibecollab hooks` command is not available (older versions), the hook can be manually installed. The hook will be auto-installed in future versions during `vibecollab init`.

## Step 3: Connect MCP to IDE

Ask the user which IDE they use, then run:

```bash
vibecollab mcp inject --ide cursor   # or: cline / codebuddy / all
```

This injects VibeCollab MCP Server config into the IDE config file.
Use `--ide all` to inject config for all supported IDEs at once.

**OpenClaw / other MCP agents**: VibeCollab is a standard MCP Server. Any MCP-compatible agent can connect directly:

```bash
openclaw mcp add --transport stdio vibecollab vibecollab mcp serve
```

## Step 4: Verify

```bash
vibecollab check
```

Should return zero errors. Warnings about document staleness are normal for new projects. Insight consistency checks and guard protection checks are included by default (use `--no-insights` or `--no-guards` to skip).

## Setup Complete

VibeCollab is ready. You now have MCP tools available in your IDE:

| Tool | When to use |
|------|-------------|
| `onboard` | **Start of every conversation** — get project context |
| `check` | **End of every conversation** — verify protocol compliance |
| `next_step` | When unsure what to do next |
| `insight_search` | Search past development experience |
| `insight_add` | Save a reusable insight |
| `insight_suggest` | Get signal-driven insight recommendations |
| `insight_graph` | View insight relationship graph |
| `insight_export` | Export insights in YAML format |
| `insight_import` | Import insights from other projects |
| `search_docs` | Semantic search across project documents |
| `task_list` | List current tasks |
| `task_create` | Create a new task (auto-links insights, **permission-checked**) |
| `task_transition` | Move task status (TODO → IN_PROGRESS → REVIEW → DONE, **permission-checked**) |
| `task_solidify` | Solidify a task through validation gates |
| `guard_check` | Pre-flight check before file operations (block/warn/allow) |
| `guard_list_rules` | List all configured guard protection rules |
| `role_context` | Get a specific role's context (for multi-role projects) |
| `role_list` | List all roles and their permissions |
| `project_prompt` | Generate full context prompt |
| `roadmap_status` | View milestone progress |
| `roadmap_sync` | Sync ROADMAP.md <-> tasks.json |
| `session_save` | **End of conversation** — save session summary |

## Execution Plan — YAML-Driven Workflow Automation

VibeCollab includes a plan runner that orchestrates multi-round workflows with two modes:

| Mode | Command | Host Adapter | Description |
|------|---------|-------------|-------------|
| **File Exchange** | `vibecollab plan run --host file_exchange` | `file_exchange` | File polling with IDE AI (requires IDE rules setup) |
| **Subprocess** | `vibecollab plan run --host subprocess` | `subprocess` | Drives CLI tools (aider, claude) via stdin/stdout |
| **Auto (Keyboard)** | `vibecollab plan run --host auto:cursor` | `auto` | Keyboard simulation for hands-free IDE automation |

All modes use `vibecollab plan run` as the **unified execution engine**.

### Mode 1: File Exchange

Use when you want to stay in the IDE conversation and have AI execute plan steps.

```bash
vibecollab plan run plans/dev.yaml -v
```

**How it works**: vibecollab writes instructions to a file, IDE AI monitors and executes, writes response back.

```
vibecollab plan run              IDE AI (Cursor/Cline)
       │                                │
       │  write instruction.md          │
       ├──────────────────────────────->│
       │                                │ execute with tool-use
       │  poll response.md              │
       │<───────────────────────────────┤ write response
       │                                │
       │  check goal, next round        │
       └────────────────────────────────┘
```

**Limitation**: Requires active IDE conversation. If conversation ends, loop stops.

**IDE Setup** — Add to Cursor Rules or Cline Custom Instructions:

```
Monitor .vibecollab/loop/instruction.md for new instructions.
When you see <!-- VIBECOLLAB_INSTRUCTION -->, execute the task using your tools.
After completion, write results to .vibecollab/loop/response.md and include
<!-- VIBECOLLAB_RESPONSE_READY --> at the end to signal completion.
```

### Mode 2: Auto (Keyboard Simulation)

Use when you want hands-free automation that can run for hours. The `auto` host adapter drives IDE AI through keyboard simulation (pyautogui).

**Step 1**: Create a launcher script
```bash
vibecollab auto init plans/dev.yaml --ide cursor
```
This creates `auto_dev.bat` that runs `vibecollab plan run ... --host auto:cursor`.

**Step 2**: Double-click the .bat file to start
- A cmd window opens
- Auto adapter finds IDE window, simulates Ctrl+L → paste → Enter
- PlanRunner polls response.md for completion
- Loop continues until goal met or max rounds

**How it works**:

```
vibecollab plan run --host auto:cursor    IDE Window (Cursor/Cline)
       │                                         │
       │  PlanRunner._exec_loop()                │
       │  → AutoAdapter.send(instruction)        │
       │    → pyautogui: Ctrl+L                  │
       │    → paste instruction via clipboard     │
       │    → Enter                               │
       ├──────────────────────────────────────->│
       │                                         │ AI executes task
       │    <- poll response.md                   │
       │<────────────────────────────────────────┤ write response
       │                                         │
       │  check_goal() → next round              │
       └─────────────────────────────────────────┘
```

**Requirements**: `pip install vibe-collab[auto]` (includes pyautogui, pygetwindow, pyperclip)

**Commands**:
```bash
vibecollab auto list                     # Show preset plans
vibecollab auto init --preset dev-loop   # Copy preset & create .bat launcher
vibecollab auto init plans/custom.yaml   # Create .bat from local plan
vibecollab auto status                   # Check status
vibecollab auto stop                     # Stop running process

# Direct CLI usage (equivalent to double-clicking .bat):
vibecollab plan run plans/dev.yaml --host auto:cursor -v
```

### Preset Plans

VibeCollab includes ready-to-use automation plans:

| Plan | Purpose | Rounds |
|------|---------|--------|
| `dev-loop` | **Full development cycle** — onboard, develop, insight, check | 50 |
| `feature-dev` | **Feature implementation** — follow ROADMAP tasks | 30 |
| `quick-fix` | **Bug fixes** — rapid check-fix-commit loop | 10 |
| `doc-sync` | **Documentation** — sync CONTEXT/CHANGELOG/ROADMAP | 5 |
| `insight-harvest` | **Knowledge capture** — extract insights from work | 10 |

**Quick Start**:
```bash
# List available presets
vibecollab auto list

# Use a preset plan (copies to plans/ and creates .bat)
vibecollab auto init --preset dev-loop

# Double-click the generated .bat file to start!
```

### Example Plan

```yaml
name: "Iterate project"
host: file_exchange
steps:
  - action: loop
    max_rounds: 20
    goal: "All vibecollab checks pass"
    state_command: "vibecollab next --json"
    prompt_template: |
      ## Round {{round}}/{{max_rounds}}
      
      Current state:
      {{state}}
      
      Please complete the next recommended task using your tools.
      Run `vibecollab check` when done.
    check_command: "vibecollab check"
    check_expect:
      exit_code: 0
```

### CLI Commands

```bash
vibecollab plan run <plan.yaml>                     # Execute (default: file_exchange)
vibecollab plan run <plan.yaml> -v                  # Verbose logging
vibecollab plan run <plan.yaml> --host auto:cursor  # Auto adapter (keyboard simulation)
vibecollab plan run <plan.yaml> --dry-run           # Preview only
vibecollab plan validate <plan.yaml>                # Validate syntax
```

### Plan Step Actions

| Action | Purpose | Example |
|--------|---------|---------|
| `cli` | Run shell command | `command: "vibecollab check"` |
| `assert` | Check file/content | `file: "README.md"`, `contains: "test"` |
| `wait` | Delay | `seconds: 1` |
| `prompt` | Send single message to host | `message: "Create a task"` |
| `loop` | Multi-round iteration | `max_rounds: 20`, `state_command: "..."` |

### Loop Configuration

| Field | Description |
|-------|-------------|
| `max_rounds` | Maximum iteration rounds |
| `goal` | Human-readable goal description |
| `state_command` | Command to gather current project state |
| `prompt_template` | Template with `{{state}}`, `{{round}}`, `{{max_rounds}}`, `{{goal}}` |
| `check_command` | Command to test if goal is met |
| `check_expect` | Expected `exit_code` and/or `stdout_contains` |

### Host Adapters

| Host | Config | Use Case |
|------|--------|----------|
| `file_exchange` | `host: file_exchange` | **Cursor/Cline/CodeBuddy** — drives IDE AI via file polling |
| `subprocess` | `host: {type: subprocess, command: "aider"}` | CLI tools (aider, claude, etc.) with stdin/stdout |
| `auto` | `host: auto:cursor` or `--host auto:cursor` | **Cursor/Cline/CodeBuddy** — drives IDE AI via keyboard simulation (pyautogui) |

> The `auto` adapter supports IDE sub-options via colon syntax: `auto:cursor`, `auto:cline`, `auto:codebuddy`. Default: `auto:cursor`.

### Auto Adapter Options

```yaml
host:
  type: auto:cursor              # or auto:cline, auto:codebuddy
  response_timeout: 600          # wait up to 10 minutes per round (default: 600)
  poll_interval: 5               # check every 5 seconds (default: 5)
```

Or via CLI flag:
```bash
vibecollab plan run plans/dev.yaml --host auto:cursor -v
```

### File Exchange Options

```yaml
host:
  type: file_exchange
  timeout: 600           # wait up to 10 minutes per round (default: 300)
  poll_interval: 3       # check every 3 seconds (default: 2)
  exchange_dir: ".vibecollab/loop"  # directory for exchange files
```

### Variable Passing

Steps can store output and pass to later steps:

```yaml
steps:
  - action: cli
    command: "vibecollab health --json"
    store_as: health_data
  - action: prompt
    message: "Health report: {{health_data}}"
```

## ROADMAP Format

If the project has a `docs/ROADMAP.md`, milestones must use this format for `roadmap_status` / `roadmap_sync` to work:

```markdown
### v0.1.0 - Milestone title

- [ ] Feature description (TASK-DEV-001)
- [x] Completed feature TASK-DEV-002
```

- Only `###` (H3) headers are recognized — `####` or `##` will not be parsed
- Version must start with `v` (semantic versioning)
- Task IDs follow `TASK-{ROLE}-{SEQ}` format (e.g., `TASK-DEV-001`)

## Daily Workflow

```
Conversation start → call onboard
                      ↓
                 Work on tasks
                      ↓
    Reusable experience? → call insight_add (capture knowledge)
                      ↓
    Need past experience? → call insight_search
                      ↓
    Important decisions → record in docs/DECISIONS.md
                      ↓
    Conversation end → update docs/CONTEXT.md
                     → update docs/CHANGELOG.md
                     → call check (includes Insight consistency + Guard protection by default)
                     → call session_save
                     → git commit
```

> **Key**: Insight and Guard checks are enabled by default in `check`. Every conversation should consider capturing reusable knowledge via `insight_add`.

## Best Practice: Task-Insight Iteration Cycle

When using `vibecollab --help` to drive development, follow this systematic workflow:

### 1. State Assessment
```bash
# Check current tasks and insights
vibecollab task list                    # View TODO tasks
vibecollab task suggest <TASK-ID>       # Get relevant insights
vibecollab insight status               # Check insight system health
git status                              # Verify sync state
```

### 2. Task-Insight Loop
```
Select Task → Query Insights → Execute → Capture Insight → Git Sync
     ↑                                                    ↓
     └──────────────── Next Task ←──────────────←────────┘
```

**Pattern**: Always link tasks with insights:
- Before starting: `vibecollab task suggest <task>` to find relevant experience
- During work: Apply insights from registry (INS-XXX.yaml files)
- After completion: Create new insight via `insight_add` or manual INS-XXX.yaml

### 3. Git Synchronization Rules
- **Immediate**: After every insight creation (`git add .vibecollab/insights/`)
- **Batch**: After documentation updates (`git add docs/`)
- **Atomic**: One logical change = one commit with conventional format:
  ```
  feat(insight): INS-XXX brief description
  
  - Detail 1
  - Detail 2
  
  Refs: TASK-XXX
  ```

### 4. Documentation Update Sequence
1. **CHANGELOG.md**: Add to `[Unreleased]` section immediately
2. **ROADMAP.md**: Mark milestones, update task status
3. **Context files**: Update `docs/roles/<role>/CONTEXT.md`
4. **Re-index**: `vibecollab index` to update vector search

### 5. Continuous Accumulation
Each iteration should:
- ✅ Complete at least one task
- ✅ Create or update at least one insight
- ✅ Synchronize to git
- ✅ Update relevant documentation
- ✅ Verify with `vibecollab check`

**Reference Insights**:
- INS-036: Release Engineering Task-Insight Cycle
- INS-037: VibeCollab --help Systematic Workflow