Skip to main content

Installation

What is VibeSpec Installation?​

Installing VibeSpec means copying the system files into your project repository and understanding how to activate the system in your IDE. Unlike traditional software installation, VibeSpec doesn't require package managers, external dependencies, or system-level configuration.

VibeSpec operates through explicit files that you copy into your project directory. These files contain the agents, memory systems, safety governance rules, and workflow protocols that enable vibe coding. Once copied, the system works in any IDE that can access files—no plugins or extensions required.

"Activation" refers to the process of loading these files into your AI assistant's context through a specific prompt-as-interface sequence. This transforms your AI assistant from a general-purpose tool into a specialized VibeSpec system with persistent memory, agent coordination, and safety enforcement.

The installation is a one-time setup per project, while activation becomes part of your daily workflow whenever you start a development session. Understanding this distinction is crucial for effective VibeSpec usage.

Why This Matters​

Problems It Solves​

Complex Setup Barriers: Traditional development systems often require extensive configuration, dependency management, and environment setup. VibeSpec's file-based approach eliminates these barriers—if you can copy files, you can install VibeSpec.

IDE Lock-in: Many AI coding tools require specific IDE plugins or extensions, limiting your choice of development environment. VibeSpec works in any IDE that can access files, from VS Code to Vim to web-based editors.

Version Conflicts: Traditional tools often have dependency conflicts or version compatibility issues. VibeSpec files are self-contained and version-controlled with your project, eliminating compatibility problems.

Team Onboarding Friction: New team members typically face complex setup procedures for development tools. With VibeSpec, onboarding means cloning the repository—the system is already configured and ready to use.

Benefits You'll Gain​

Universal Compatibility: VibeSpec works in any development environment that can access files. You're not locked into specific IDEs, platforms, or toolchains.

Zero Dependencies: No external services, package installations, or system configuration required. Everything needed is contained in the files you copy.

Instant Team Sharing: When you commit VibeSpec files to version control, every team member gets the same system configuration, memory, and patterns automatically.

Portable Intelligence: Your project's accumulated knowledge, decisions, and patterns travel with the codebase. Moving between machines or environments preserves all context.

Real-World Impact​

A distributed team working across VS Code, IntelliJ, and Vim found that VibeSpec enabled consistent AI assistance regardless of individual IDE preferences. New team members could contribute effectively within hours of cloning the repository, compared to days of traditional toolchain setup.

How to Install VibeSpec​

Step 1: Clone the VibeSpec Repository​

Clone to a temporary location:

git clone https://github.com/anasdevai/vibe-specs.git

What this does: Downloads the complete VibeSpec system files to your local machine for copying into your project.

Step 2: Copy VibeSpec Files to Your Project​

Copy the system files:

# Navigate to your project directory
cd /path/to/your/project

# Copy VibeSpec system files
cp -r /path/to/vibe-specs/.vibespec ./
cp -r /path/to/vibe-specs/agents ./
cp -r /path/to/vibe-specs/memory ./
cp -r /path/to/vibe-specs/specs ./
cp -r /path/to/vibe-specs/tasks ./
cp -r /path/to/vibe-specs/prompts ./

What this does: Copies all VibeSpec system files into your project, creating the file structure needed for operation.

Step 3: Verify Installation​

Check file structure:

ls -la
# You should see:
# .vibespec/
# agents/
# memory/
# specs/
# tasks/
# prompts/

What to expect: Your project now contains all VibeSpec system files and is ready for activation.

Step 4: Initial Activation​

Copy the activation prompt:

SYSTEM: Activate VibeSpec.
Enforce:
- Spec-driven workflow
- Multi-agent role separation
- Persistent memory
- Safety and clarity governance

Initialize:
- Project memory
- Agent registry
- Terminology store

Do not generate content yet.

What this does: Loads all VibeSpec files into your AI assistant's context, transforming it into a VibeSpec system.

Advanced Installation Options​

For existing projects with custom structure:

# Create VibeSpec directory in custom location
mkdir -p tools/vibespec
cp -r /path/to/vibe-specs/* tools/vibespec/

# Update paths in activation prompt accordingly

For team standardization:

# Add VibeSpec as git submodule
git submodule add https://github.com/anasdevai/vibe-specs.git tools/vibespec
git submodule update --init --recursive

What to Expect​

Successful Installation Verification​

After copying files, your project structure should look like this:

your-project/
├── .vibespec/
│   ├── system.md
│   ├── workflow.md
│   ├── safety.md
│   └── memory-policy.md
├── agents/
│   ├── architect.agent.md
│   ├── coder.agent.md
│   ├── reviewer.agent.md
│   ├── debugger.agent.md
│   └── test.agent.md
├── memory/
│   ├── decisions.md
│   ├── mistakes.md
│   ├── patterns.md
│   └── project.json
├── specs/
│   ├── product.md
│   ├── architecture.md
│   ├── constraints.md
│   └── acceptance.md
├── tasks/
│   ├── backlog.md
│   ├── active.md
│   └── done.md
└── prompts/
    └── start.md

Successful Activation Response​

When you use the activation prompt, you should see:

[VibeSpec Engine]
Active Agent: None
Task: System Initialization
Memory Status: Loading...

System Files Loaded:
✅ .vibespec/system.md
✅ .vibespec/workflow.md
✅ .vibespec/safety.md
✅ .vibespec/memory-policy.md

Agents Registered:
✅ Architect Agent
✅ Coder Agent
✅ Reviewer Agent
✅ Debugger Agent
✅ Test Agent

Memory Loaded:
✅ memory/decisions.md (0 entries - new project)
✅ memory/mistakes.md (0 entries - new project)
✅ memory/patterns.md (0 entries - new project)
✅ memory/project.json (initialized)

VibeSpec Engine initialized and ready.

Next Action: Activate an agent to begin development workflow.

Quality Indicators​

  • ✅ Complete File Structure: All required directories and files present
  • ✅ Successful Activation: System loads without errors
  • ✅ Agent Registration: All five agents available
  • ✅ Memory Initialization: Memory files loaded (empty for new projects)
  • ✅ IDE Independence: Works in your chosen development environment

IDE-Specific Considerations​

VS Code: Works through chat interfaces or AI extensions IntelliJ/PyCharm: Compatible with AI assistant plugins Vim/Neovim: Use through terminal-based AI tools Web IDEs: Works in any browser-based development environment Terminal: Compatible with command-line AI tools

Troubleshooting Installation Issues​

  • If you see: "File not found" errors during copying

  • It means: Source path is incorrect or VibeSpec repository not cloned properly

  • Solution: Verify clone location and use absolute paths for copying

  • If you see: "Permission denied" during file operations

  • It means: Insufficient file system permissions

  • Solution: Use sudo if necessary or check directory permissions

  • If you see: Activation prompt doesn't load system files

  • It means: Files not copied to correct location or AI assistant can't access them

  • Solution: Verify file structure and ensure AI assistant has access to project directory

Common Mistakes and Warnings​

⚠️ Critical Warnings​

  • Don't Modify System Files: Never edit files in .vibespec/ directory unless you understand the implications. These files define core system behavior and incorrect modifications can break VibeSpec functionality.

  • Version Control Inclusion: Always commit VibeSpec files to version control. The system's value comes from shared memory and patterns—excluding these files defeats the purpose of persistent intelligence.

Common Mistakes​

Mistake: Installing VibeSpec globally instead of per-project​

Why it happens: Developers treat VibeSpec like a traditional tool that should be installed once
How to avoid: Understand that VibeSpec is project-specific and should be copied into each project
If it happens: Remove global installation and copy files into individual project directories

Mistake: Skipping file structure verification​

Why it happens: Developers assume copying worked without checking the results
How to avoid: Always verify file structure after copying and before first activation
If it happens: Check for missing files and re-copy as needed

Mistake: Modifying system files immediately after installation​

Why it happens: Developers want to customize the system before understanding how it works
How to avoid: Use VibeSpec with default configuration first, then customize based on experience
If it happens: Restore original files and learn the system before making modifications

Mistake: Expecting activation to work without proper file structure​

Why it happens: Developers try to activate VibeSpec before completing installation
How to avoid: Complete all installation steps before attempting activation
If it happens: Complete file copying and verify structure before re-attempting activation

Best Practices​

  • ✅ Verify Before Activating: Always check file structure before first activation attempt
  • ✅ Use Version Control: Commit VibeSpec files to share system state with team members
  • ✅ Document Customizations: If you modify system files, document changes in memory/decisions.md
  • ✅ Test in Clean Environment: Verify installation works in fresh project clone
  • ✅ Keep Backups: Maintain copies of working VibeSpec configurations for recovery