Iterate project

分类: 工具与效率 | 上传者: flashpoint493 | 下载: 0 | 版本: v1.0（最新）

您正在帮助用户在其项目中设置 VibeCollab。

更新日志: Source: GitHub https://github.com/flashpoint493/VibeCollab

目录结构

当前层级: tree/master/

📁 .github/
- 📁 workflows/
  - 📄 ci.yml 2.1 KB
  - 📄 publish.yml 2.8 KB
📁 .opencode/
- 📁 skills/
  - 📄 vibecollab.md 7.9 KB
📁 .vibecollab/
- 📁 docs/
  - 📄 changelog.yaml 9.4 KB
  - 📄 context.yaml 2.2 KB
  - 📄 decisions.yaml 7.3 KB
  - 📄 prd.yaml 152 B
  - 📄 qa.yaml 8.5 KB
  - 📄 roadmap.yaml 14.7 KB
- 📁 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
  - 📄 INS-047.yaml 2.1 KB
  - 📄 INS-048.yaml 2.8 KB
  - 📄 INS-049.yaml 2.4 KB
  - 📄 INS-050.yaml 4.6 KB
  - 📄 INS-051.yaml 2.5 KB
  - 📄 INS-052.yaml 938 B
  - 📄 INS-053.yaml 1.6 KB
  - 📄 INS-054.yaml 1.7 KB
  - 📄 INS-055.yaml 794 B
  - 📄 INS-056.yaml 2.3 KB
  - 📄 ins-057.yaml 1.0 KB
  - 📄 INS-058.yaml 2.1 KB
  - 📄 INS-059.yaml 3.4 KB
  - 📄 INS-060.yaml 3.8 KB
  - 📄 INS-061.yaml 4.2 KB
  - 📄 INS-062.yaml 580 B
  - 📄 INS-063.yaml 2.2 KB
  - 📄 INS-064.yaml 1.5 KB
  - 📄 INS-065.yaml 3.6 KB
  - 📄 INS-066.yaml 5.7 KB
  - 📄 INS-WF-001_workflow_integration_pattern.yaml 4.2 KB
  - 📄 registry.yaml 4.0 KB
- 📁 roles/
  - 📁 architect/
    
    📄 .metadata.yaml 327 B
    
    📄 CONTEXT.md 971 B
    
    📄 context.yaml 1.7 KB
  - 📁 dev/
    
    📄 .metadata.yaml 742 B
    
    📄 CONTEXT.md 1.5 KB
    
    📄 context.yaml 1.5 KB
  - 📁 insight_collector/
    
    📄 .metadata.yaml 131 B
    
    📄 CONTEXT.md 8.4 KB
    
    📄 context.yaml 1.6 KB
  - 📄 COLLABORATION.md 2.4 KB
- 📁 sessions/
  - 📄 2026-04-01T06-35-18.json 992 B
- 📁 workflows/
  - 📄 daily-sync.yaml 1.3 KB
  - 📄 insight-collect.yaml 1.6 KB
  - 📄 release-prep.yaml 2.1 KB
- 📄 .gitignore 97 B
- 📄 insight_signal.json 175 B
- 📄 tasks.json 24.6 KB
📁 docs/
- 📄 CHANGELOG.md 1.2 KB
- 📄 CONTEXT.md 2.1 KB
- 📄 context.yaml 1.8 KB
- 📄 DECISIONS.md 6.6 KB
- 📄 PRD.md 335 B
- 📄 QA_TEST_CASES.md 265 B
- 📄 ROADMAP.md 5.8 KB
- 📄 v0.12.0-migration-guide.md 8.1 KB
📁 examples/
- 📄 demo_bootstrap.yaml 4.7 KB
- 📄 demo_loop.yaml 2.9 KB
- 📄 mock_host.py 458 B
📁 schema/
- 📄 changelog.schema.yaml 3.4 KB
- 📄 context.schema.yaml 4.5 KB
- 📄 decisions.schema.yaml 3.8 KB
- 📄 extension.schema.yaml 4.9 KB
- 📄 insight.schema.yaml 9.0 KB
- 📄 prd.schema.yaml 3.9 KB
- 📄 project.schema.yaml 9.0 KB
- 📄 qa.schema.yaml 3.1 KB
- 📄 roadmap.schema.yaml 5.4 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 37.7 KB
  - 📁 cli/
    
    📄 __init__.py 290 B
    
    📄 ai.py 36.4 KB
    
    📄 config.py 10.9 KB
    
    📄 guide.py 40.0 KB
    
    📄 index.py 7.1 KB
    
    📄 insight.py 44.0 KB
    
    📄 lifecycle.py 6.7 KB
    
    📄 main.py 105.8 KB
    
    📄 mcp.py 4.7 KB
    
    📄 roadmap.py 7.2 KB
    
    📄 skill.py 4.7 KB
    
    📄 task.py 11.5 KB
  - 📁 contrib/
    
    📄 __init__.py 57 B
    
    📄 auto_driver.py 15.9 KB
  - 📁 core/
    
    📄 __init__.py 38 B
    
    📄 config_manager.py 6.4 KB
    
    📄 docs_renderer.py 8.1 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 17.4 KB
    
    📄 project.py 14.2 KB
    
    📄 protocol_checker.py 36.4 KB
    
    📄 template_library.py 13.7 KB
    
    📄 templates.py 3.6 KB
    
    📄 workflow.py 4.1 KB
  - 📁 domain/
    
    📄 __init__.py 32 B
    
    📄 conflict_detector.py 16.8 KB
    
    📄 developer.py 370 B
    
    📄 event_log.py 9.1 KB
    
    📄 guard.py 7.3 KB
    
    📄 hook_manager.py 7.0 KB
    
    📄 lifecycle.py 10.4 KB
    
    📄 prd_manager.py 14.2 KB
    
    📄 roadmap_parser.py 16.4 KB
    
    📄 role.py 40.2 KB
    
    📄 session_store.py 5.4 KB
    
    📄 skill_registry.py 5.0 KB
    
    📄 task_manager.py 25.6 KB
    
    📄 trigger_registry.py 6.0 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
  - 📁 ide_adapter/
    
    📁 adapters/
    
    📄 __init__.py 962 B
    
    📄 augment.py 3.2 KB
    
    📄 claude.py 2.5 KB
    
    📄 cline.py 4.7 KB
    
    📄 codebuddy.py 4.6 KB
    
    📄 continue_.py 3.8 KB
    
    📄 copilot.py 2.7 KB
    
    📄 cursor.py 2.7 KB
    
    📄 gemini.py 2.5 KB
    
    📄 kimicode.py 2.8 KB
    
    📄 kiro.py 2.5 KB
    
    📄 opencode.py 6.5 KB
    
    📄 roocode.py 2.7 KB
    
    📄 trae.py 2.5 KB
    
    📄 warp.py 2.9 KB
    
    📄 windsurf.py 2.5 KB
    
    📄 __init__.py 2.7 KB
    
    📄 base.py 8.4 KB
    
    📄 registry.py 4.8 KB
  - 📁 insight/
    
    📄 __init__.py 426 B
    
    📄 derivation_detector.py 16.0 KB
    
    📄 embedder.py 9.2 KB
    
    📄 manager.py 47.4 KB
    
    📄 signal.py 20.7 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 11.0 KB
    
    📄 vector_store.py 9.9 KB
  - 📁 templates/
    
    📁 docs/
    
    📄 changelog.md.j2 842 B
    
    📄 changelog.yaml.j2 296 B
    
    📄 collaboration.yaml.j2 2.0 KB
    
    📄 context.md.j2 1.6 KB
    
    📄 context.yaml.j2 961 B
    
    📄 decision_levels.yaml.j2 1.5 KB
    
    📄 decisions.md.j2 1.5 KB
    
    📄 decisions.yaml.j2 381 B
    
    📄 documentation.yaml.j2 2.4 KB
    
    📄 extensions.yaml.j2 1.8 KB
    
    📄 git_workflow.yaml.j2 2.9 KB
    
    📄 guidelines.yaml.j2 1.7 KB
    
    📄 insights.yaml.j2 2.7 KB
    
    📄 iteration.yaml.j2 2.5 KB
    
    📄 lifecycle.yaml.j2 2.8 KB
    
    📄 manifest.yaml 6.7 KB
    
    📄 milestone.yaml.j2 2.0 KB
    
    📄 philosophy.yaml.j2 925 B
    
    📄 prd.md.j2 1.6 KB
    
    📄 prd.yaml.j2 538 B
    
    📄 prd_management.yaml.j2 3.0 KB
    
    📄 protocol_check.yaml.j2 2.5 KB
    
    📄 qa.md.j2 1.1 KB
    
    📄 qa.yaml.j2 414 B
    
    📄 quick_reference.yaml.j2 1.9 KB
    
    📄 roadmap.md.j2 1.5 KB
    
    📄 roadmap.yaml.j2 1.0 KB
    
    📄 roles.yaml.j2 706 B
    
    📄 symbology.yaml.j2 2.0 KB
    
    📄 testing.yaml.j2 2.8 KB
    
    📄 workflow.yaml.j2 3.2 KB
    
    📁 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 6.0 KB
📁 tests/
- 📄 __init__.py 23 B
- 📄 test_adapters.py 15.5 KB
- 📄 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 33.3 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.9 KB
- 📄 test_derivation_detector.py 14.4 KB
- 📄 test_developer.py 25.7 KB
- 📄 test_docs_renderer.py 6.2 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_guard_engine.py 5.4 KB
- 📄 test_health.py 17.2 KB
- 📄 test_hook_manager.py 12.5 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_permission_enforcement.py 10.4 KB
- 📄 test_pipeline.py 28.2 KB
- 📄 test_prd_manager.py 22.3 KB
- 📄 test_protocol_checker.py 39.7 KB
- 📄 test_protocol_checker_git.py 20.2 KB
- 📄 test_roadmap_parser.py 23.0 KB
- 📄 test_role_permissions.py 19.6 KB
- 📄 test_session_store.py 6.0 KB
- 📄 test_skill_registry.py 7.2 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_template_cli.py 12.5 KB
- 📄 test_templates.py 4.1 KB
- 📄 test_trigger_registry.py 6.9 KB
- 📄 test_vector_store.py 9.9 KB
- 📄 test_workflow.py 14.6 KB
📄 .gitignore 752 B
📄 check_output.txt 3.9 KB
📄 CONTRIBUTING_AI.md 46.3 KB
📄 LICENSE 1.1 KB
📄 llms.txt 1.7 KB
📄 project.yaml 19.1 KB
📄 pyproject.toml 2.3 KB
📄 README.md 24.1 KB
📄 README.pypi.md 15.3 KB
📄 README.zh-CN.md 38.2 KB
📄 skill.md 18.5 KB
📄 test_output.txt 368 B
📄 USAGE.md 6.3 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 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

---

## v0.12.0 New Features

### YAML Document Management

VibeCollab v0.12.0 introduces a YAML-first document system where YAML files are the source of truth and Markdown files are generated views.

#### List renderable documents
```bash
vibecollab docs list
```

#### Render YAML to Markdown
```bash
vibecollab docs render --all
vibecollab docs render -i docs/context.yaml
```

#### Validate YAML document
```bash
vibecollab docs validate docs/context.yaml
```

### Workflow Automation Enhancements

#### List available workflows
```bash
vibecollab plan list
```

#### Run a workflow
```bash
vibecollab plan run daily-sync
vibecollab plan run release-prep --dry-run
```

#### Validate workflow
```bash
vibecollab plan validate daily-sync
```

### Insight Derivation

#### Show derivation graph
```bash
vibecollab insight graph --show-derivation
```

#### Auto-detect derivation
```bash
vibecollab insight derive --from-task TASK-DEV-001
```

### YAML Data Layer Principle

- YAML files (`docs/*.yaml`) are the source of truth
- Markdown files (`docs/*.md`) are generated views
- Always edit YAML, render to Markdown
- Use `vibecollab docs render --all` after YAML changes

> **Note**: This principle ensures single source of truth for project documentation. When updating documentation, modify the YAML files first, then render to Markdown to maintain consistency.

登录后下载/点赞/收藏 ❤ 9 | ★ 0

Iterate project

目录结构

SKILL.md

举报内容

提示