Vibe Coding Workspace Documentation

Welcome to your comprehensive development workspace! This directory contains all the documentation you need to effectively use and maintain your development environment.

📖 Table of Contents

• Getting Started
• Workspace Structure
• Available Tools
• Project Creation
• Common Commands
• Configuration
• Troubleshooting
• Contributing

🚀 Getting Started

First Time Setup

1. Initialize the workspace

   source ./init.sh

2. Check dependencies

   ./scripts/check-deps.sh

3. Create your first project

   make new-project NAME=my-first-app TYPE=python

Daily Workflow

1. Activate the environment

   source ./init.sh --quiet

2. Check what's available

   make help

3. Start coding!

📁 Workspace Structure

vibe-coding/
├── 📁 projects/           # Your development projects
├── 📁 tools/             # Development tools and environments
│   ├── python-env/       # Python packages and tools
│   ├── node-env/         # Node.js packages and tools
│   └── requirements.txt  # Python package list
├── 📁 scripts/           # Utility scripts
│   ├── new-project.sh    # Create new projects
│   ├── backup.sh         # Backup your work
│   ├── clean.sh          # Clean temporary files
│   └── check-deps.sh     # Check dependencies
├── 📁 configs/           # Configuration files
│   └── .editorconfig     # Editor settings
├── 📁 templates/         # Project templates
│   ├── python-project-structure/
│   ├── node-project-structure/
│   ├── .gitignore        # Comprehensive gitignore
│   ├── README.md         # README template
│   ├── Dockerfile        # Docker template
│   ├── docker-compose.yml
│   ├── .env.example      # Environment variables template
│   └── html-boilerplate/ # Static website templates
├── 📁 docs/              # Documentation (this directory)
├── 📁 sandbox/           # Experimental and temporary work
├── 📁 backups/           # Automatic backups
├── 🔧 init.sh            # Environment initialization script
├── 🔧 Makefile           # Common commands and tasks
├── 📄 .gitignore         # Git ignore rules
└── 📄 .gitconfig         # Git configuration and aliases

🛠 Available Tools

Python Tools

• Runtime: Python 3.12.3
• Package Manager: pip
• Packages: numpy, pandas, requests, fastapi, flask, jupyter, pytest, black, flake8, and more
• Location: ~/.local/bin (added to PATH)

Node.js Tools

• Runtime: Node.js v22.20.0
• Package Manager: npm 11.6.1
• Packages: typescript, eslint, prettier, jest, react, vue, express, and more
• Location: tools/node-env/node_modules/.bin

Development Utilities

• Git: Version control with useful aliases
• Make: Build automation and common tasks
• EditorConfig: Consistent coding styles across editors

🎯 Project Creation

Creating a New Project

# Using Make (recommended)
make new-project NAME=my-app TYPE=python

# Using script directly
./scripts/new-project.sh my-app python

Available Project Types

Type	Description	Technologies
python	Python application with FastAPI	Python, FastAPI, pytest, black
node	Node.js application with Express	Node.js, Express, Jest, ESLint
static	Static website	HTML, CSS, JavaScript
react	React application	React, TypeScript, Vite
vue	Vue.js application	Vue.js, TypeScript, Vite

Project Structure Examples

Python Project:

my-python-app/
├── src/my_python_app/
│   ├── main.py
│   ├── config.py
│   └── api/
├── tests/
├── pyproject.toml
├── requirements.txt
└── README.md

Node.js Project:

my-node-app/
├── src/
│   ├── index.js
│   ├── controllers/
│   └── routes/
├── tests/
├── package.json
└── README.md

🚀 Common Commands

Workspace Management

# Show all available commands
make help

# Check workspace status
make status

# Check all dependencies
make check-deps

# Clean temporary files
make clean

# Create backup
make backup

# Initialize environment
source ./init.sh

Development Workflow

# Create a new project
make new-project NAME=myapp TYPE=python

# Install dependencies
make install-python    # Python packages
make install-node      # Node.js packages

# Code quality
make lint              # Run linters
make format            # Format code

# Testing
make test              # Run all tests

Git Shortcuts

# Quick status
git s

# Add and commit
git a && git cm "message"

# Pretty log
git lg

# Check all aliases
git aliases

⚙️ Configuration

Environment Variables

The workspace uses several environment variables that are automatically set:

• VIBE_CODING_ROOT: Workspace root directory
• VIBE_CODING_PROJECTS: Projects directory
• VIBE_CODING_TEMPLATES: Templates directory
• PATH: Enhanced with Python and Node.js tools

Customizing Your Environment

1. Python packages: Add to tools/requirements.txt
2. Node.js packages: Modify tools/node-env/package.json
3. Git aliases: Edit .gitconfig
4. Editor settings: Modify configs/.editorconfig

Project Templates

You can customize project templates in the templates/ directory:

• Edit existing templates to match your preferences
• Add new templates for different frameworks
• Modify the new-project.sh script to support new types

🔧 Troubleshooting

Common Issues

Q: Python packages not found after installation

# Ensure PATH is set correctly
source ./init.sh

# Check if packages are installed
pip list | grep numpy

Q: Node.js tools not working

# Install Node.js packages
make install-node

# Verify installation
npm list --depth=0

Q: Git aliases not working

# Check if gitconfig is loaded
git config --list | grep alias

# Source the config manually
git config --local include.path ../.gitconfig

Q: Permission denied on scripts

# Make scripts executable
chmod +x scripts/*.sh init.sh

Getting Help

1. Check dependencies: ./scripts/check-deps.sh
2. Show status: make status
3. View logs: Check the output of failed commands
4. Reset environment: source ./init.sh

Performance Tips

• Use make clean regularly to remove temporary files
• Create backups with make backup before major changes
• Use the sandbox directory for experiments
• Keep projects organized in the projects directory

🤝 Contributing

Adding New Features

1. New project types:

   • Add templates in templates/
   • Modify scripts/new-project.sh
   • Update documentation

2. New tools:

   • Add to appropriate requirements file
   • Update scripts/check-deps.sh
   • Document in this README

3. New scripts:

   • Add to scripts/ directory
   • Make executable: chmod +x
   • Add to Makefile if needed

Best Practices

• Keep scripts simple and well-documented
• Use consistent error handling and colored output
• Test changes with scripts/check-deps.sh
• Update documentation for any changes
• Follow existing code style and patterns

📚 Additional Resources

• Python Documentation
• Node.js Documentation
• Git Documentation
• Make Documentation

---

Happy Coding! 🚀

For questions or issues, check the troubleshooting section or review the scripts in the scripts/ directory for implementation details.