Iterate project

Category: Tools & Productivity | Uploader: flashpoint493 | Downloads: 0 | Version: v1.0（Latest）

You are helping a user set up VibeCollab in their project.

Changelog: Source: GitHub https://github.com/flashpoint493/VibeCollab

Directory Structure

Current level: tree/master/

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 2.1 KB
  - 📄 publish.yml 2.7 KB
📁 .opencode/
- 📁 skills/
  - 📄 vibecollab.md 7.9 KB
📁 .vibecollab/
- 📁 insights/
  - 📄 INS-001.yaml 766 B
  - 📄 INS-002.yaml 880 B
  - 📄 INS-003.yaml 798 B
  - 📄 INS-004.yaml 963 B
  - 📄 INS-005.yaml 914 B
  - 📄 INS-006.yaml 969 B
  - 📄 INS-007.yaml 929 B
  - 📄 INS-008.yaml 961 B
  - 📄 INS-009.yaml 940 B
  - 📄 INS-010.yaml 957 B
  - 📄 INS-011.yaml 893 B
  - 📄 INS-012.yaml 914 B
  - 📄 INS-013.yaml 884 B
  - 📄 INS-014.yaml 822 B
  - 📄 INS-015.yaml 961 B
  - 📄 INS-016.yaml 834 B
  - 📄 INS-017.yaml 882 B
  - 📄 INS-018.yaml 950 B
  - 📄 INS-019.yaml 832 B
  - 📄 INS-020.yaml 929 B
  - 📄 INS-021.yaml 842 B
  - 📄 INS-022.yaml 884 B
  - 📄 INS-023.yaml 887 B
  - 📄 INS-024.yaml 857 B
  - 📄 INS-025.yaml 903 B
  - 📄 INS-026.yaml 849 B
  - 📄 INS-027.yaml 904 B
  - 📄 INS-028.yaml 836 B
  - 📄 INS-029.yaml 900 B
  - 📄 INS-030.yaml 930 B
  - 📄 INS-035.yaml 556 B
  - 📄 INS-036.yaml 1.3 KB
  - 📄 INS-037.yaml 2.0 KB
  - 📄 INS-038.yaml 2.4 KB
  - 📄 INS-039.yaml 2.1 KB
  - 📄 INS-040.yaml 2.7 KB
  - 📄 INS-041.yaml 2.4 KB
  - 📄 INS-042.yaml 3.4 KB
  - 📄 INS-043.yaml 4.8 KB
  - 📄 INS-044.yaml 2.6 KB
  - 📄 INS-045.yaml 2.4 KB
  - 📄 INS-046.yaml 2.0 KB
  - 📄 registry.yaml 2.8 KB
- 📄 .gitignore 97 B
- 📄 insight_signal.json 142 B
- 📄 tasks.json 4.3 KB
📁 docs/
- 📁 roles/
  - 📁 architect/
    
    📄 .metadata.yaml 327 B
    
    📄 CONTEXT.md 328 B
  - 📁 dev/
    
    📄 CONTEXT.md 1.4 KB
  - 📁 insight_collector/
    
    📄 .metadata.yaml 131 B
    
    📄 CONTEXT.md 8.0 KB
  - 📄 COLLABORATION.md 2.4 KB
- 📄 CHANGELOG.md 4.7 KB
- 📄 CONTEXT.md 3.3 KB
- 📄 DECISIONS.md 7.3 KB
- 📄 PRD.md 383 B
- 📄 QA_TEST_CASES.md 304 B
- 📄 ROADMAP.md 32.9 KB
📁 examples/
- 📄 demo_bootstrap.yaml 4.7 KB
- 📄 demo_loop.yaml 2.9 KB
- 📄 mock_host.py 458 B
📁 schema/
- 📄 extension.schema.yaml 4.9 KB
- 📄 insight.schema.yaml 9.0 KB
- 📄 project.schema.yaml 9.0 KB
📁 scripts/
- 📄 bump_version.py 8.1 KB
- 📄 migrate_to_roles.py 9.4 KB
- 📄 prepare-commit-msg.example 1.8 KB
📁 src/
- 📁 vibecollab/
  - 📁 agent/
    
    📄 __init__.py 36 B
    
    📄 executor.py 12.0 KB
    
    📄 llm_client.py 14.7 KB
    
    📄 mcp_server.py 33.5 KB
  - 📁 cli/
    
    📄 __init__.py 290 B
    
    📄 ai.py 36.4 KB
    
    📄 config.py 10.9 KB
    
    📄 guide.py 39.8 KB
    
    📄 index.py 7.1 KB
    
    📄 insight.py 31.9 KB
    
    📄 lifecycle.py 6.7 KB
    
    📄 main.py 71.6 KB
    
    📄 mcp.py 5.9 KB
    
    📄 roadmap.py 7.2 KB
    
    📄 skill.py 19.0 KB
    
    📄 task.py 11.2 KB
  - 📁 contrib/
    
    📄 __init__.py 57 B
    
    📄 auto_driver.py 15.9 KB
  - 📁 core/
    
    📄 __init__.py 38 B
    
    📄 config_manager.py 6.4 KB
    
    📄 execution_plan.py 47.3 KB
    
    📄 extension.py 13.0 KB
    
    📄 generator.py 2.9 KB
    
    📄 health.py 14.6 KB
    
    📄 pattern_engine.py 12.8 KB
    
    📄 pipeline.py 15.2 KB
    
    📄 project.py 12.9 KB
    
    📄 protocol_checker.py 31.0 KB
    
    📄 templates.py 3.6 KB
  - 📁 domain/
    
    📄 __init__.py 32 B
    
    📄 conflict_detector.py 16.7 KB
    
    📄 developer.py 370 B
    
    📄 event_log.py 9.1 KB
    
    📄 lifecycle.py 10.4 KB
    
    📄 prd_manager.py 10.3 KB
    
    📄 roadmap_parser.py 12.9 KB
    
    📄 role.py 33.2 KB
    
    📄 session_store.py 5.4 KB
    
    📄 task_manager.py 24.5 KB
  - 📁 i18n/
    
    📁 locales/
    
    📁 zh_CN/
    
    📁 LC_MESSAGES/
    
    📄 vibecollab.mo 6.2 KB
    
    📄 vibecollab.po 31.0 KB
    
    📄 vibecollab.pot 28.8 KB
    
    📄 __init__.py 3.9 KB
  - 📁 insight/
    
    📄 __init__.py 43 B
    
    📄 embedder.py 9.2 KB
    
    📄 manager.py 46.5 KB
    
    📄 signal.py 20.5 KB
  - 📁 patterns/
    
    📄 01_header.md.j2 134 B
    
    📄 02_philosophy.md.j2 1.4 KB
    
    📄 03_roles.md.j2 1.2 KB
    
    📄 04_decision_levels.md.j2 820 B
    
    📄 05_task_unit.md.j2 474 B
    
    📄 06_dialogue_protocol.md.j2 2.3 KB
    
    📄 07_requirement_clarification.md.j2 2.4 KB
    
    📄 08_iteration_protocols.md.j2 3.2 KB
    
    📄 09_qa_protocol.md.j2 1.7 KB
    
    📄 10_git_workflow.md.j2 1.1 KB
    
    📄 11_testing.md.j2 1.9 KB
    
    📄 12_milestone.md.j2 1.2 KB
    
    📄 13_iteration.md.j2 1.2 KB
    
    📄 14_lifecycle_rules.md.j2 3.6 KB
    
    📄 15_documentation.md.j2 1.3 KB
    
    📄 16_multi_developer.md.j2 12.9 KB
    
    📄 17_prompt_engineering.md.j2 1.7 KB
    
    📄 18_symbology.md.j2 412 B
    
    📄 19_decisions_summary.md.j2 506 B
    
    📄 20_extension_sections.md.j2 1.3 KB
    
    📄 21_protocol_check.md.j2 2.7 KB
    
    📄 22_prd_management.md.j2 3.9 KB
    
    📄 23_quick_reference.md.j2 792 B
    
    📄 24_changelog.md.j2 467 B
    
    📄 25_git_history.md.j2 274 B
    
    📄 26_footer.md.j2 222 B
    
    📄 27_insight_workflow.md.j2 3.2 KB
    
    📄 manifest.yaml 3.6 KB
  - 📁 plans/
    
    📄 dev-loop.yaml 2.2 KB
    
    📄 doc-sync.yaml 1.5 KB
    
    📄 feature-dev.yaml 1.6 KB
    
    📄 insight-harvest.yaml 1.7 KB
    
    📄 quick-fix.yaml 1.1 KB
    
    📄 self-test-auto.yaml 863 B
  - 📁 search/
    
    📄 __init__.py 34 B
    
    📄 indexer.py 8.9 KB
    
    📄 vector_store.py 9.9 KB
  - 📁 templates/
    
    📁 domains/
    
    📄 data.extension.yaml 3.5 KB
    
    📄 game.extension.yaml 3.8 KB
    
    📄 web.extension.yaml 3.6 KB
    
    📄 default.project.yaml 17.7 KB
  - 📁 utils/
    
    📄 __init__.py 34 B
    
    📄 git.py 4.7 KB
    
    📄 llmstxt.py 5.1 KB
  - 📄 __init__.py 1.3 KB
  - 📄 _compat.py 5.9 KB
📁 tests/
- 📄 __init__.py 23 B
- 📄 test_agent_executor.py 31.3 KB
- 📄 test_cli.py 19.0 KB
- 📄 test_cli_ai.py 32.1 KB
- 📄 test_cli_dev.py 9.1 KB
- 📄 test_cli_guide.py 31.0 KB
- 📄 test_cli_index.py 9.6 KB
- 📄 test_cli_insight.py 23.2 KB
- 📄 test_cli_lifecycle.py 4.5 KB
- 📄 test_cli_task_richtext.py 6.7 KB
- 📄 test_config_manager.py 14.2 KB
- 📄 test_conflict_detector.py 27.6 KB
- 📄 test_developer.py 25.4 KB
- 📄 test_embedder.py 5.9 KB
- 📄 test_event_log.py 11.5 KB
- 📄 test_execution_plan.py 58.1 KB
- 📄 test_extension.py 11.6 KB
- 📄 test_generator.py 7.7 KB
- 📄 test_git_utils.py 7.0 KB
- 📄 test_health.py 17.2 KB
- 📄 test_indexer.py 9.1 KB
- 📄 test_insight_manager.py 42.7 KB
- 📄 test_insight_quality.py 18.6 KB
- 📄 test_insight_signal.py 16.6 KB
- 📄 test_lifecycle.py 7.1 KB
- 📄 test_llm_client.py 28.9 KB
- 📄 test_llmstxt.py 4.6 KB
- 📄 test_mcp_server.py 16.4 KB
- 📄 test_mcp_server_closures.py 13.7 KB
- 📄 test_pattern_engine.py 18.4 KB
- 📄 test_pipeline.py 28.2 KB
- 📄 test_prd_manager.py 22.0 KB
- 📄 test_protocol_checker.py 35.0 KB
- 📄 test_protocol_checker_git.py 19.7 KB
- 📄 test_roadmap_parser.py 23.0 KB
- 📄 test_session_store.py 6.0 KB
- 📄 test_task_insight_integration.py 18.7 KB
- 📄 test_task_manager.py 23.0 KB
- 📄 test_task_workflow_integration.py 20.8 KB
- 📄 test_templates.py 4.1 KB
- 📄 test_vector_store.py 9.9 KB
📄 .gitignore 752 B
📄 CONTRIBUTING_AI.md 46.3 KB
📄 LICENSE 1.1 KB
📄 llms.txt 1.7 KB
📄 project.yaml 18.0 KB
📄 pyproject.toml 2.3 KB
📄 README.md 20.0 KB
📄 README.pypi.md 14.1 KB
📄 README.zh-CN.md 36.5 KB
📄 skill.md 16.7 KB

SKILL.md

# 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 are included by default (use `--no-insights` 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 |
| `search_docs` | Semantic search across project documents |
| `task_list` | List current tasks |
| `task_create` | Create a new task (auto-links insights) |
| `task_transition` | Move task status (TODO → IN_PROGRESS → REVIEW → DONE) |
| `developer_context` | Get a specific role's context |
| `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 by default)
                     → call session_save
                     → git commit
```

> **Key**: Insight is 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

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

Iterate project

Directory Structure

SKILL.md

Report

Notice