From 2a40ce5ea4c85dc4325b8abb5ec06abeebfb6b25 Mon Sep 17 00:00:00 2001 From: Jeremy Eder Date: Wed, 13 Aug 2025 01:00:44 -0400 Subject: [PATCH 1/3] Add vTeam shared Claude Code configuration with hooks-based enforcement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add hook-based automatic configuration management via .claude/settings.json - Add pre-commit enforcement script ensuring latest team configs are active - Add session start status check displaying current configuration state - Add comprehensive Mermaid workflow diagrams for developer understanding - Add hierarchical configuration support with developer override flexibility - Add global team standards and language-specific project templates - Add automated dependency management via dependabot - Add comprehensive documentation with visual workflow guides - Update main README.md with shared-configs overview and quick setup Key Features: - ✅ Zero-maintenance automatic configuration enforcement - ✅ Developer customization via .claude/settings.local.json - ✅ Visual workflow documentation with Mermaid diagrams - ✅ Symlink-based template and configuration management - ✅ Git hooks ensure team standards on every commit/push 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.md | 22 +- vTeam/shared-configs/.claude/settings.json | 45 +++ vTeam/shared-configs/.github/dependabot.yml | 9 + vTeam/shared-configs/.gitignore | 29 ++ vTeam/shared-configs/README.md | 275 ++++++++++++++++++ vTeam/shared-configs/claude/INSTALL.md | 267 +++++++++++++++++ vTeam/shared-configs/claude/README.md | 56 ++++ vTeam/shared-configs/claude/global-CLAUDE.md | 52 ++++ .../project-templates/javascript-CLAUDE.md | 90 ++++++ .../claude/project-templates/python-CLAUDE.md | 88 ++++++ .../claude/project-templates/shell-CLAUDE.md | 98 +++++++ vTeam/shared-configs/hooks/enforce-config.sh | 115 ++++++++ vTeam/shared-configs/hooks/status-check.sh | 76 +++++ 13 files changed, 1221 insertions(+), 1 deletion(-) create mode 100644 vTeam/shared-configs/.claude/settings.json create mode 100644 vTeam/shared-configs/.github/dependabot.yml create mode 100644 vTeam/shared-configs/.gitignore create mode 100644 vTeam/shared-configs/README.md create mode 100644 vTeam/shared-configs/claude/INSTALL.md create mode 100644 vTeam/shared-configs/claude/README.md create mode 100644 vTeam/shared-configs/claude/global-CLAUDE.md create mode 100644 vTeam/shared-configs/claude/project-templates/javascript-CLAUDE.md create mode 100644 vTeam/shared-configs/claude/project-templates/python-CLAUDE.md create mode 100644 vTeam/shared-configs/claude/project-templates/shell-CLAUDE.md create mode 100755 vTeam/shared-configs/hooks/enforce-config.sh create mode 100755 vTeam/shared-configs/hooks/status-check.sh diff --git a/README.md b/README.md index 2103b57fd..32a69ecfe 100644 --- a/README.md +++ b/README.md @@ -45,4 +45,24 @@ RAT employs a microservices-based architecture with event-driven communication: - **Agent-Based Processing**: Specialized AI agents handle different aspects of refinement - **Jira Integration**: Seamless workflow integration with existing processes - **Data Source Connectivity**: Links to RFEs, repositories, architectural decision records -- **Automated Workflow**: Event-driven processing with minimal manual intervention \ No newline at end of file +- **Automated Workflow**: Event-driven processing with minimal manual intervention + +## Shared Configuration + +This repository includes shared Claude Code configuration for team development standards and workflows. + +### vTeam Shared-Configs + +The `vTeam/shared-configs/` directory provides: + +- **🔄 Automatic enforcement** - Hooks ensure team standards on every Git operation +- **⚙️ Developer flexibility** - Personal overrides via `.claude/settings.local.json` +- **📊 Visual documentation** - Mermaid workflow diagrams show configuration hierarchy +- **🛠️ Project templates** - Python, JavaScript, Shell development templates + +**Quick Setup:** +```bash +cp vTeam/shared-configs/.claude/settings.json ~/.claude/settings.json +``` + +📚 **Full Documentation:** [vTeam/shared-configs/README.md](vTeam/shared-configs/README.md) \ No newline at end of file diff --git a/vTeam/shared-configs/.claude/settings.json b/vTeam/shared-configs/.claude/settings.json new file mode 100644 index 000000000..41ca14188 --- /dev/null +++ b/vTeam/shared-configs/.claude/settings.json @@ -0,0 +1,45 @@ +{ + "hooks": { + "preToolUse": [ + { + "name": "enforce-vteam-config", + "description": "Ensure latest vTeam shared configuration is active before Git operations", + "match": { + "tool": "Bash", + "command": "git commit*" + }, + "command": "./vTeam/shared-configs/hooks/enforce-config.sh" + }, + { + "name": "enforce-vteam-config-push", + "description": "Ensure latest vTeam shared configuration is active before Git push", + "match": { + "tool": "Bash", + "command": "git push*" + }, + "command": "./vTeam/shared-configs/hooks/enforce-config.sh" + } + ], + "sessionStart": [ + { + "name": "vteam-welcome", + "description": "Display vTeam configuration status on session start", + "command": "./vTeam/shared-configs/hooks/status-check.sh" + } + ] + }, + "permissions": { + "allow": [ + "Bash(git:*)", + "Bash(npm:*)", + "Bash(python:*)", + "Bash(uv:*)", + "Bash(black:*)", + "Bash(isort:*)", + "Bash(flake8:*)", + "Bash(pytest:*)", + "Bash(shellcheck:*)", + "Bash(markdownlint:*)" + ] + } +} \ No newline at end of file diff --git a/vTeam/shared-configs/.github/dependabot.yml b/vTeam/shared-configs/.github/dependabot.yml new file mode 100644 index 000000000..260902f95 --- /dev/null +++ b/vTeam/shared-configs/.github/dependabot.yml @@ -0,0 +1,9 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + commit-message: + prefix: "ci" + include: "scope" \ No newline at end of file diff --git a/vTeam/shared-configs/.gitignore b/vTeam/shared-configs/.gitignore new file mode 100644 index 000000000..0e32ff597 --- /dev/null +++ b/vTeam/shared-configs/.gitignore @@ -0,0 +1,29 @@ +# macOS +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# Editor and IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Temporary files +*.tmp +*.temp +.cache/ + +# Logs +*.log +logs/ + +# Environment files +.env +.env.local +.env.*.local \ No newline at end of file diff --git a/vTeam/shared-configs/README.md b/vTeam/shared-configs/README.md new file mode 100644 index 000000000..cded650ea --- /dev/null +++ b/vTeam/shared-configs/README.md @@ -0,0 +1,275 @@ +# vTeam Shared Claude Configuration + +> Shared Claude Code configuration templates and standards for team development + +## Quick Start + +```bash +# Clone the repository +git clone https://github.com/jeremyeder/vTeam.git +cd vTeam/shared-configs + +# Copy team settings to your Claude configuration +cp .claude/settings.json ~/.claude/settings.json + +# Start using Claude Code with team standards! +# Configuration will be automatically enforced on first Git operation +``` + +## How It Works + +### Configuration Hierarchy + +```mermaid +flowchart TD + A[Developer Action] --> B{Claude Settings Hierarchy} + B --> C[".claude/settings.local.json
🏆 HIGHEST PRIORITY
Personal overrides
(never committed)"] + B --> D[".claude/settings.json
📋 TEAM STANDARDS
vTeam shared config
(in git repository)"] + B --> E["~/.claude/settings.json
⚙️ PERSONAL DEFAULTS
Global user settings
(copied from team)"] + C --> F[Final Configuration] + D --> F + E --> F + F --> G[Claude Code Execution] +``` + +### Developer Workflow + +```mermaid +sequenceDiagram + participant Dev as Developer + participant Repo as vTeam Repository + participant Claude as Claude Code + participant Hooks as Team Hooks + + Dev->>Repo: git clone vTeam repository + Dev->>Claude: cp .claude/settings.json ~/.claude/ + Note over Claude: Team hooks now active + + Dev->>Claude: Start Claude session + Hooks->>Dev: Display configuration status + + Dev->>Repo: First git commit attempt + Hooks->>Claude: enforce-config.sh executes + Hooks->>Claude: Auto-create ~/.claude/CLAUDE.md symlink + Hooks->>Claude: Auto-create ~/.claude/project-templates symlink + Hooks->>Dev: ✅ Team configuration enforced + + Dev->>Repo: git commit proceeds + Note over Dev: All future work uses team standards +``` + +## Overview + +This directory contains shared Claude Code configuration files that provide: + +- **Consistent development standards** across team projects +- **Automatic enforcement** via Claude Code hooks +- **Reusable project templates** for common technologies +- **Developer override flexibility** with clear hierarchy +- **Best practices** for code quality and team collaboration + +## What's Included + +### Core Configuration Files + +- **`.claude/settings.json`** - Team hooks and enforcement rules +- **`.gitignore`** - Comprehensive ignore rules for development files +- **`CLAUDE.md`** - Project-specific Claude Code guidance template +- **`LICENSE`** - MIT license for open source projects +- **`.github/dependabot.yml`** - Automated dependency management + +### Hooks & Enforcement + +- **`hooks/enforce-config.sh`** - Pre-commit configuration enforcement +- **`hooks/status-check.sh`** - Session start status display +- **Automatic symlink management** - Global config and templates +- **Pre-commit/push validation** - Ensures team standards + +### Global Configuration + +- **`claude/global-CLAUDE.md`** - Team-wide Claude Code standards +- **Development principles** - Git workflow, code quality, testing +- **File management standards** - Branch verification, linting requirements +- **Team collaboration guidelines** - GitHub Flow, commit standards + +### Project Templates + +Pre-configured CLAUDE.md templates for: + +- **`python-CLAUDE.md`** - Python projects with uv, black, pytest +- **`javascript-CLAUDE.md`** - JavaScript/Node.js projects +- **`shell-CLAUDE.md`** - Shell script projects with ShellCheck + +## Installation + +### Hook-Based Setup (Recommended) + +```bash +# Copy team hooks to your Claude configuration +cp vTeam/shared-configs/.claude/settings.json ~/.claude/settings.json + +# Configuration will be automatically managed by hooks +# First Git operation will set up symlinks automatically +``` + +### Manual Setup (Alternative) + +```bash +# Create .claude directory +mkdir -p ~/.claude + +# Link global configuration +ln -sf "$(pwd)/claude/global-CLAUDE.md" ~/.claude/CLAUDE.md + +# Link project templates +ln -sf "$(pwd)/claude/project-templates" ~/.claude/ +``` + +## Usage + +### For New Projects + +1. **Copy project template** to your project root as `CLAUDE.md`: + ```bash + cp ~/.claude/project-templates/python-CLAUDE.md myproject/CLAUDE.md + ``` + +2. **Customize for your project** - update architecture, commands, etc. + +3. **Start development** with Claude Code understanding your project context + +### For Existing Projects + +1. **Add CLAUDE.md** using appropriate template as starting point +2. **Update development commands** to match your project's needs +3. **Follow team standards** from global configuration + +## Configuration Management + +### Automatic Updates +- **Hooks enforce latest config** on every Git commit/push +- **No manual updates needed** - configuration stays current +- **Session status checks** display current configuration state + +### Manual Updates (if needed) +```bash +# Pull latest changes +git pull origin main + +# Hooks will automatically update configuration on next Git operation +# Or run manually: +./hooks/enforce-config.sh +``` + +## Developer Customization + +### Configuration Hierarchy (Highest → Lowest Priority) +1. **Local Project Settings** (`.claude/settings.local.json`) - **Your overrides** +2. **Shared Project Settings** (`.claude/settings.json`) - **vTeam standards** +3. **User Global Settings** (`~/.claude/settings.json`) - **Personal defaults** + +### Personal Overrides + +Create `.claude/settings.local.json` in any project for personal customizations: + +```json +{ + "hooks": { + "postToolUse": [ + {"name": "my-logging", "command": "echo 'Tool used'"} + ] + }, + "permissions": { + "allow": ["Bash(my-custom-tool:*)"] + } +} +``` + +### File Structure & Configuration Flow + +```mermaid +graph TB + subgraph "vTeam Repository" + A[".claude/settings.json
Team hooks & standards"] + B["hooks/enforce-config.sh
Pre-commit enforcement"] + C["claude/global-CLAUDE.md
Team-wide standards"] + D["claude/project-templates/
Language templates"] + A --> B + end + + subgraph "Developer Machine" + E["~/.claude/settings.json
Personal global config"] + F["~/.claude/CLAUDE.md
Global team standards"] + G["~/.claude/project-templates/
Shared templates"] + H[".claude/settings.local.json
Personal overrides"] + end + + subgraph "Claude Code" + I["Final Configuration
Merged hierarchy"] + J["Development Actions
Git, linting, etc."] + end + + A -.->|copied once| E + B -.->|creates symlinks| F + B -.->|creates symlinks| G + C -.->|symlinked to| F + D -.->|symlinked to| G + + H -->|highest priority| I + A -->|team standards| I + E -->|personal defaults| I + + I --> J + J -.->|triggers| B +``` + +**What you CAN override:** +- ✅ Add personal hooks and automation +- ✅ Extend permissions for custom tools +- ✅ Personal workflow preferences +- ✅ Custom aliases and shortcuts + +**What gets enforced:** +- 🔒 Pre-commit/push configuration validation +- 🔒 Core team development standards +- 🔒 Quality and linting requirements + +## Team Standards + +### Git Workflow +- **Always work in feature branches** unless explicitly told otherwise +- **Mandatory branch verification** before any file modifications +- **Squash commits** for clean history +- **Follow GitHub Flow** for all repositories + +### Code Quality +- **Run linters locally** before every commit/push +- **Never push** if linters report errors or warnings +- **Use language-specific tooling** (black for Python, prettier for JS, etc.) +- **Always run tests** before pushing changes + +### Development Environment +- **Use virtual environments** for Python projects (prefer `uv` over `pip`) +- **Automate dependency management** with dependabot +- **Document project-specific commands** in project CLAUDE.md + +## Contributing + +To update shared configuration: + +1. **Create feature branch** from main +2. **Make changes** to templates, hooks, or global config +3. **Test changes** locally by copying `.claude/settings.json` +4. **Create pull request** with clear description of changes +5. **Team review** before merging + +## Support + +- **Documentation**: See `claude/INSTALL.md` for detailed setup +- **Issues**: Report problems via GitHub Issues +- **Questions**: Reach out to team leads for guidance + +--- + +**Latest Update**: Hook-based automatic configuration management +**Compatibility**: Claude Code with hierarchical settings and project-specific CLAUDE.md support \ No newline at end of file diff --git a/vTeam/shared-configs/claude/INSTALL.md b/vTeam/shared-configs/claude/INSTALL.md new file mode 100644 index 000000000..910fa5eb1 --- /dev/null +++ b/vTeam/shared-configs/claude/INSTALL.md @@ -0,0 +1,267 @@ +# vTeam Claude Configuration Installation Guide + +Comprehensive setup instructions for vTeam shared Claude Code configurations. + +## Quick Setup (Recommended) + +Use the automated installation script: + +```bash +cd vTeam/shared-configs +./install.sh +``` + +This handles everything automatically including backups and verification. + +## Manual Setup + +If you prefer manual installation or need to troubleshoot: + +### 1. Install Global Configuration + +```bash +# Create .claude directory if needed +mkdir -p ~/.claude + +# Link global configuration +ln -sf "$(pwd)/claude/global-CLAUDE.md" ~/.claude/CLAUDE.md + +# Link project templates +ln -sf "$(pwd)/claude/project-templates" ~/.claude/ +``` + +### 2. Add Convenience Aliases (Optional) + +Add to your shell configuration (~/.bashrc, ~/.zshrc, etc.): + +```bash +# vTeam Claude template aliases +alias claude-python="cp ~/.claude/project-templates/python-CLAUDE.md ./CLAUDE.md" +alias claude-js="cp ~/.claude/project-templates/javascript-CLAUDE.md ./CLAUDE.md" +alias claude-shell="cp ~/.claude/project-templates/shell-CLAUDE.md ./CLAUDE.md" + +# Reload shell configuration +source ~/.bashrc # or ~/.zshrc +``` + +## Usage + +### For New Projects +```bash +# Use automated installation aliases +claude-python # Copy Python template +claude-js # Copy JavaScript template +claude-shell # Copy Shell template + +# Or copy manually +cp ~/.claude/project-templates/python-CLAUDE.md ./CLAUDE.md +``` + +### For Existing Projects +1. Choose appropriate template from `~/.claude/project-templates/` +2. Copy to project root as `CLAUDE.md` +3. Customize development commands and architecture for your project + +## Verification + +### Check Installation +```bash +# Verify global config symlink +ls -la ~/.claude/CLAUDE.md + +# Verify project templates symlink +ls -la ~/.claude/project-templates + +# Check project config exists +ls -la ./CLAUDE.md +``` + +### Test Configuration +```bash +# Test with Claude Code +claude --help + +# Check project-specific guidance loads +claude "What are the development commands for this project?" +``` + +## Directory Structure After Setup + +``` +~/.claude/ +├── CLAUDE.md -> /path/to/vTeam/shared-configs/claude/global-CLAUDE.md +└── project-templates/ -> /path/to/vTeam/shared-configs/claude/project-templates/ + +vTeam/shared-configs/ +├── install.sh # Automated installation +├── uninstall.sh # Automated removal +├── update.sh # Update configuration +├── README.md # Team documentation +├── .gitignore # Development ignore rules +├── CLAUDE.md # Project template +├── LICENSE # MIT license +├── .github/dependabot.yml # Dependency automation +└── claude/ + ├── INSTALL.md # This file + ├── global-CLAUDE.md # Global team standards + └── project-templates/ + ├── python-CLAUDE.md + ├── javascript-CLAUDE.md + └── shell-CLAUDE.md +``` + +## Lifecycle Management + +### Update Configuration +```bash +cd vTeam/shared-configs +./update.sh +``` +Pulls latest changes and reinstalls configuration. + +### Uninstall +```bash +cd vTeam/shared-configs +./uninstall.sh +``` +Removes configuration and restores backups. + +## Troubleshooting + +### Symlinks Not Working +```bash +# Check if path is correct +ls -la ~/.claude/CLAUDE.md + +# Recreate symlink +rm ~/.claude/CLAUDE.md +ln -sf "/full/path/to/vTeam/shared-configs/claude/global-CLAUDE.md" ~/.claude/CLAUDE.md +``` + +### Templates Not Found +```bash +# Verify templates directory +ls ~/.claude/project-templates/ + +# Recreate templates symlink +rm ~/.claude/project-templates +ln -sf "/full/path/to/vTeam/shared-configs/claude/project-templates" ~/.claude/ +``` + +### Restore Previous Configuration +```bash +# Find backup directory +ls -la ~/.claude-backup-* + +# Manually restore if needed +cp ~/.claude-backup-YYYYMMDD-HHMMSS/CLAUDE.md ~/.claude/ +``` + +## Detailed Configuration Flow + +### Hook Execution Sequence + +```mermaid +sequenceDiagram + participant Dev as Developer + participant Git as Git Command + participant Hook as enforce-config.sh + participant FS as File System + participant Claude as Claude Code + + Dev->>Git: git commit + Git->>Hook: Pre-tool hook triggers + Hook->>FS: Check ~/.claude/CLAUDE.md symlink + + alt Symlink missing or incorrect + Hook->>FS: Backup existing file + Hook->>FS: Create symlink to vTeam config + Hook->>FS: Create templates symlink + Hook->>Dev: ✅ Configuration updated + else Symlink correct + Hook->>Dev: ✅ Configuration current + end + + Hook->>Git: Allow commit to proceed + Git->>Dev: Commit successful +``` + +### Configuration Hierarchy Deep Dive + +```mermaid +graph LR + subgraph "Configuration Sources" + A["vTeam Repository
.claude/settings.json"] + B["Developer Machine
~/.claude/settings.json"] + C["Project Override
.claude/settings.local.json"] + end + + subgraph "Merge Process" + D["Base Settings
(User Global)"] + E["Team Standards
(Shared Project)"] + F["Personal Overrides
(Local Project)"] + end + + subgraph "Final Result" + G["Active Configuration
in Claude Code"] + end + + B --> D + A --> E + C --> F + + D --> G + E --> G + F --> G + + style F fill:#e1f5fe + style E fill:#f3e5f5 + style D fill:#fff3e0 +``` + +### File System Layout + +```mermaid +graph TD + subgraph "vTeam Repository Structure" + A["vTeam/shared-configs/"] + A --> B[".claude/settings.json"] + A --> C["hooks/enforce-config.sh"] + A --> D["hooks/status-check.sh"] + A --> E["claude/global-CLAUDE.md"] + A --> F["claude/project-templates/"] + F --> G["python-CLAUDE.md"] + F --> H["javascript-CLAUDE.md"] + F --> I["shell-CLAUDE.md"] + end + + subgraph "Developer Machine After Setup" + J["~/.claude/"] + J --> K["settings.json (copied)"] + J --> L["CLAUDE.md → vTeam/shared-configs/claude/global-CLAUDE.md"] + J --> M["project-templates/ → vTeam/shared-configs/claude/project-templates/"] + end + + subgraph "Project-Specific Overrides" + N["project/.claude/"] + N --> O["settings.local.json (optional)"] + end + + B -.->|copied once| K + E -.->|symlinked| L + F -.->|symlinked| M + + style L stroke:#2196F3,stroke-width:3px + style M stroke:#2196F3,stroke-width:3px + style O stroke:#4CAF50,stroke-width:3px +``` + +## Team Benefits + +This setup provides: +- ✅ **Consistent standards** across all team projects +- ✅ **Automatic enforcement** via pre-commit hooks +- ✅ **Developer flexibility** through local overrides +- ✅ **Zero maintenance** - configuration stays current +- ✅ **Version controlled** team standards +- ✅ **Visual workflow** documentation for team collaboration \ No newline at end of file diff --git a/vTeam/shared-configs/claude/README.md b/vTeam/shared-configs/claude/README.md new file mode 100644 index 000000000..da9a679c9 --- /dev/null +++ b/vTeam/shared-configs/claude/README.md @@ -0,0 +1,56 @@ +# Claude Configuration Management + +This directory contains Claude Code configuration files for managing global and project-specific settings. + +## Structure + +``` +claude/ +├── README.md # This file +├── global-CLAUDE.md # Global configuration (symlink to ~/.claude/CLAUDE.md) +└── project-templates/ # Templates for common project types + ├── python-CLAUDE.md + ├── javascript-CLAUDE.md + └── shell-CLAUDE.md +``` + +## Setup Instructions + +### Global Configuration +```bash +# Create symlink for global Claude configuration +ln -sf ~/repos/dotfiles/claude/global-CLAUDE.md ~/.claude/CLAUDE.md +``` + +### Project-Specific Configuration +For new projects, copy the appropriate template: +```bash +# For Python projects +cp ~/repos/dotfiles/claude/project-templates/python-CLAUDE.md /path/to/project/CLAUDE.md + +# For JavaScript projects +cp ~/repos/dotfiles/claude/project-templates/javascript-CLAUDE.md /path/to/project/CLAUDE.md + +# For shell projects +cp ~/repos/dotfiles/claude/project-templates/shell-CLAUDE.md /path/to/project/CLAUDE.md +``` + +## Best Practices + +1. **Global Configuration**: Use `~/.claude/CLAUDE.md` for settings that apply to ALL projects +2. **Project Configuration**: Use `PROJECT_ROOT/CLAUDE.md` for project-specific commands and context +3. **Version Control**: Keep both global and project configurations in git +4. **Symlinks**: Use symlinks to maintain a single source of truth for global config +5. **Templates**: Use project templates to ensure consistency across similar projects + +## Configuration Hierarchy + +Claude Code follows this configuration hierarchy (highest to lowest priority): +1. Project-specific `CLAUDE.md` (in project root) +2. Global `~/.claude/CLAUDE.md` +3. Built-in Claude Code defaults + +This allows you to: +- Set organization-wide standards in global config +- Override with project-specific requirements +- Maintain consistency across all your projects \ No newline at end of file diff --git a/vTeam/shared-configs/claude/global-CLAUDE.md b/vTeam/shared-configs/claude/global-CLAUDE.md new file mode 100644 index 000000000..be4f7585c --- /dev/null +++ b/vTeam/shared-configs/claude/global-CLAUDE.md @@ -0,0 +1,52 @@ +# Global Claude Configuration + +This file contains global Claude Code configuration that applies to all projects. +This should be symlinked to ~/.claude/CLAUDE.md + +## Global Operating Principles + +### Git and Version Control +- **MANDATORY BRANCH VERIFICATION**: ALWAYS check current git branch with `git branch --show-current` as the FIRST action before ANY task that could modify files +- When using git, ALWAYS work in feature branches unless told explicitly otherwise +- **Always squash commits** for clean history +- **Make sure to commit frequently** with succinct commit messages that are immediately useful to the reader + +### Development Standards +- **Always use python virtual environments** to avoid affecting system python packages +- **ALWAYS use uv instead of pip** where possible +- **ALWAYS run markdownlint locally** on any markdown files that you work with +- **ALWAYS automatically resolve any issues reported by linters** +- **ALWAYS try to minimize rework** + +### GitHub Best Practices +- **When setting up GitHub projects, ALWAYS use repository-level projects**. NEVER use user-level projects +- **NEVER change visibility of a github repository** without explicitly being told to do so +- When working with GitHub repositories, always follow GitHub Flow +- **ALWAYS setup dependabot automation** when creating a new github repository +- **Warn if in a GitHub git repo and GitHub Actions integration is not installed** for Claude + +### Code Quality +- **NEVER push if linters report errors or warnings** +- **NEVER push if tests fail** +- **ALWAYS fix issues immediately after running linters** +- **ALWAYS make sure all dates that you use match reality** +- When creating new python applications, you only need to support versions N and N-1 + +### File Management +- **ALWAYS keep your utility/working scripts in git** and well-isolated from the primary codebase +- **NOTHING may ever depend on these scripts** +- **NEVER make changes to files unless you are on the correct feature branch** for those changes +- **NEVER create files unless they're absolutely necessary** for achieving your goal +- **ALWAYS prefer editing an existing file to creating a new one** +- **NEVER proactively create documentation files** (*.md) or README files unless explicitly requested + +### Linting Workflow +**MANDATORY: ALWAYS run the complete linting workflow locally before ANY git push or commit** + +Check the project's CLAUDE.md file for language-specific linting commands and workflows. + +### Testing Best Practices +- **ALWAYS run tests immediately after making implementation changes** +- When fixing API bugs, update both implementation AND corresponding tests in the same commit +- Never assume tests will pass after changing HTTP methods, endpoints, or response formats +- Implementation changes without test updates = guaranteed CI failures \ No newline at end of file diff --git a/vTeam/shared-configs/claude/project-templates/javascript-CLAUDE.md b/vTeam/shared-configs/claude/project-templates/javascript-CLAUDE.md new file mode 100644 index 000000000..57b2a6b5f --- /dev/null +++ b/vTeam/shared-configs/claude/project-templates/javascript-CLAUDE.md @@ -0,0 +1,90 @@ +# CLAUDE.md - JavaScript/Node.js Project + +This file provides guidance to Claude Code (claude.ai/code) when working with this JavaScript project. + +## Development Commands + +### Environment Setup +```bash +# Install dependencies +npm install +# or +yarn install + +# Install development dependencies +npm install --only=dev +``` + +### Code Quality +```bash +# Format code +npm run format +# or +npx prettier --write . + +# Lint code +npm run lint +# or +npx eslint . + +# Fix auto-fixable lint issues +npm run lint:fix +# or +npx eslint . --fix +``` + +### Testing +```bash +# Run all tests +npm test + +# Run tests in watch mode +npm run test:watch + +# Run tests with coverage +npm run test:coverage + +# Run specific test file +npm test -- test-file.test.js +``` + +### Build and Development +```bash +# Start development server +npm run dev + +# Build for production +npm run build + +# Preview production build +npm run preview +``` + +## Project Architecture + + + +## Configuration + +### Node.js Version +- Target: Node.js 18+ (LTS and current) + +### Code Style +- Formatter: Prettier +- Linter: ESLint +- Line length: 80-100 characters +- Semicolons: Consistent with project preference + +### Testing Framework +- Test runner: Jest/Vitest/Mocha (specify which) +- Coverage tool: Built-in coverage +- Test location: tests/ or __tests__/ directory + +## Pre-commit Requirements + +Before any commit, ALWAYS run: +1. `npm run format` (or `npx prettier --write .`) +2. `npm run lint` (or `npx eslint .`) +3. `npm test` + +All commands must pass without errors or warnings. \ No newline at end of file diff --git a/vTeam/shared-configs/claude/project-templates/python-CLAUDE.md b/vTeam/shared-configs/claude/project-templates/python-CLAUDE.md new file mode 100644 index 000000000..b51eeff3f --- /dev/null +++ b/vTeam/shared-configs/claude/project-templates/python-CLAUDE.md @@ -0,0 +1,88 @@ +# CLAUDE.md - Python Project + +This file provides guidance to Claude Code (claude.ai/code) when working with this Python project. + +## Development Commands + +### Environment Setup +```bash +# Create virtual environment +uv venv +source .venv/bin/activate # Linux/macOS +# .venv\Scripts\activate # Windows + +# Install dependencies +uv pip install -r requirements.txt +uv pip install -r requirements-dev.txt # If dev requirements exist +``` + +### Code Quality +```bash +# Format code +black . + +# Sort imports +isort . + +# Lint code +flake8 . + +# Type checking (if using mypy) +mypy . +``` + +### Testing +```bash +# Run all tests +python -m pytest + +# Run with coverage +python -m pytest --cov=. + +# Run specific test file +python -m pytest tests/test_example.py + +# Run specific test +python -m pytest tests/test_example.py::test_function_name +``` + +### Package Management +```bash +# Add new dependency +uv add package-name + +# Add development dependency +uv add --dev package-name + +# Update dependencies +uv lock --upgrade +``` + +## Project Architecture + + + +## Configuration + +### Python Version +- Target: Python 3.11+ (latest stable and N-1) + +### Code Style +- Line length: 88 characters (black default) +- Import sorting: isort with black compatibility +- Linting: flake8 with project-specific rules + +### Testing Framework +- Test runner: pytest +- Coverage tool: pytest-cov +- Test location: tests/ directory + +## Pre-commit Requirements + +Before any commit, ALWAYS run: +1. `black .` +2. `isort .` +3. `flake8 .` +4. `python -m pytest` + +All commands must pass without errors or warnings. \ No newline at end of file diff --git a/vTeam/shared-configs/claude/project-templates/shell-CLAUDE.md b/vTeam/shared-configs/claude/project-templates/shell-CLAUDE.md new file mode 100644 index 000000000..a85ff5cad --- /dev/null +++ b/vTeam/shared-configs/claude/project-templates/shell-CLAUDE.md @@ -0,0 +1,98 @@ +# CLAUDE.md - Shell Script Project + +This file provides guidance to Claude Code (claude.ai/code) when working with this shell script project. + +## Development Commands + +### Code Quality +```bash +# Lint shell scripts +shellcheck *.sh + +# Lint with specific exclusions (if needed) +shellcheck -e SC1090 -e SC1091 *.sh + +# Format shell scripts (if using shfmt) +shfmt -w *.sh +``` + +### Testing +```bash +# Run tests (if using bats) +bats tests/ + +# Run specific test file +bats tests/test-example.bats + +# Manual testing +bash script-name.sh --help +bash script-name.sh --test-mode +``` + +### Execution +```bash +# Make scripts executable +chmod +x *.sh + +# Run script +./script-name.sh + +# Source script (for functions/aliases) +source script-name.sh +``` + +## Project Architecture + + + +## Configuration + +### Shell Compatibility +- Target: Bash 4.0+ (specify if using other shells) +- Shebang: `#!/usr/bin/env bash` or `#!/bin/bash` + +### Code Style +- Indentation: 2 or 4 spaces (consistent) +- Variable naming: snake_case for local, UPPER_CASE for globals/exports +- Function naming: snake_case +- Error handling: Use `set -euo pipefail` for strict mode + +### Testing Framework +- Test runner: bats-core (or specify alternative) +- Test location: tests/ directory +- Test files: *.bats format + +## Shell Script Best Practices + +### Error Handling +```bash +#!/usr/bin/env bash +set -euo pipefail # Exit on error, undefined vars, pipe failures +``` + +### Function Structure +```bash +function_name() { + local arg1="$1" + local arg2="${2:-default_value}" + + # Function body + echo "Processing: $arg1" +} +``` + +### Variable Quoting +```bash +# Always quote variables +echo "$variable" +cp "$source_file" "$destination_file" +``` + +## Pre-commit Requirements + +Before any commit, ALWAYS run: +1. `shellcheck *.sh` (or with project-specific exclusions) +2. Manual testing of modified scripts +3. Verify executable permissions are set correctly + +All ShellCheck warnings must be resolved or explicitly excluded with comments. \ No newline at end of file diff --git a/vTeam/shared-configs/hooks/enforce-config.sh b/vTeam/shared-configs/hooks/enforce-config.sh new file mode 100755 index 000000000..a91d90b88 --- /dev/null +++ b/vTeam/shared-configs/hooks/enforce-config.sh @@ -0,0 +1,115 @@ +#!/bin/bash +set -euo pipefail + +# vTeam Shared Configuration Enforcement Script +# Ensures latest vTeam configuration is active before Git operations + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SHARED_CONFIGS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +CLAUDE_DIR="$HOME/.claude" + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +info() { + echo -e "${GREEN}[vTeam]${NC} $1" +} + +warn() { + echo -e "${YELLOW}[vTeam]${NC} $1" +} + +error() { + echo -e "${RED}[vTeam]${NC} $1" +} + +step() { + echo -e "${BLUE}[vTeam]${NC} $1" +} + +# Check if we're in a vTeam repository +if [[ ! -d "$SHARED_CONFIGS_DIR" ]]; then + error "vTeam shared-configs directory not found" + exit 1 +fi + +# Create .claude directory if it doesn't exist +if [[ ! -d "$CLAUDE_DIR" ]]; then + step "Creating ~/.claude directory" + mkdir -p "$CLAUDE_DIR" +fi + +# Function to check if symlink is up to date +check_symlink() { + local target="$1" + local link="$2" + + if [[ ! -L "$link" ]]; then + return 1 # Not a symlink + fi + + local current_target + current_target="$(readlink "$link")" + + if [[ "$current_target" != "$target" ]]; then + return 1 # Points to wrong target + fi + + return 0 # Symlink is correct +} + +# Check and update global configuration +GLOBAL_TARGET="$SHARED_CONFIGS_DIR/claude/global-CLAUDE.md" +GLOBAL_LINK="$CLAUDE_DIR/CLAUDE.md" + +if ! check_symlink "$GLOBAL_TARGET" "$GLOBAL_LINK"; then + step "Updating global CLAUDE.md configuration" + + # Backup existing file if it's not a symlink + if [[ -f "$GLOBAL_LINK" ]] && [[ ! -L "$GLOBAL_LINK" ]]; then + BACKUP_NAME="CLAUDE.md.backup-$(date +%Y%m%d-%H%M%S)" + warn "Backing up existing $GLOBAL_LINK to $BACKUP_NAME" + mv "$GLOBAL_LINK" "$CLAUDE_DIR/$BACKUP_NAME" + fi + + # Remove existing link if present + [[ -L "$GLOBAL_LINK" ]] && rm "$GLOBAL_LINK" + + # Create new symlink + ln -sf "$GLOBAL_TARGET" "$GLOBAL_LINK" + info "✓ Global configuration linked" +fi + +# Check and update project templates +TEMPLATES_TARGET="$SHARED_CONFIGS_DIR/claude/project-templates" +TEMPLATES_LINK="$CLAUDE_DIR/project-templates" + +if ! check_symlink "$TEMPLATES_TARGET" "$TEMPLATES_LINK"; then + step "Updating project templates" + + # Backup existing directory if it's not a symlink + if [[ -d "$TEMPLATES_LINK" ]] && [[ ! -L "$TEMPLATES_LINK" ]]; then + BACKUP_NAME="project-templates.backup-$(date +%Y%m%d-%H%M%S)" + warn "Backing up existing $TEMPLATES_LINK to $BACKUP_NAME" + mv "$TEMPLATES_LINK" "$CLAUDE_DIR/$BACKUP_NAME" + fi + + # Remove existing link if present + [[ -L "$TEMPLATES_LINK" ]] && rm "$TEMPLATES_LINK" + + # Create new symlink + ln -sf "$TEMPLATES_TARGET" "$TEMPLATES_LINK" + info "✓ Project templates linked" +fi + +# Verify installation +if [[ -L "$GLOBAL_LINK" ]] && [[ -L "$TEMPLATES_LINK" ]]; then + info "✓ vTeam configuration is active and up to date" +else + error "Configuration verification failed" + exit 1 +fi \ No newline at end of file diff --git a/vTeam/shared-configs/hooks/status-check.sh b/vTeam/shared-configs/hooks/status-check.sh new file mode 100755 index 000000000..e38469e69 --- /dev/null +++ b/vTeam/shared-configs/hooks/status-check.sh @@ -0,0 +1,76 @@ +#!/bin/bash +set -euo pipefail + +# vTeam Configuration Status Check Script +# Displays current vTeam configuration status on Claude session start + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SHARED_CONFIGS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +CLAUDE_DIR="$HOME/.claude" + +# Colors for output +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +info() { + echo -e "${GREEN}[vTeam]${NC} $1" +} + +warn() { + echo -e "${YELLOW}[vTeam]${NC} $1" +} + +status() { + echo -e "${BLUE}[vTeam]${NC} $1" +} + +# Only show status if we're in a vTeam repository +if [[ ! -d "$SHARED_CONFIGS_DIR" ]]; then + exit 0 # Silent exit if not in vTeam repo +fi + +# Check configuration status +GLOBAL_LINK="$CLAUDE_DIR/CLAUDE.md" +TEMPLATES_LINK="$CLAUDE_DIR/project-templates" + +echo +status "=== vTeam Configuration Status ===" + +# Check global config +if [[ -L "$GLOBAL_LINK" ]]; then + TARGET=$(readlink "$GLOBAL_LINK") + if [[ "$TARGET" == "$SHARED_CONFIGS_DIR/claude/global-CLAUDE.md" ]]; then + info "✓ Global configuration: Active" + else + warn "⚠ Global configuration: Linked to different source" + fi +else + warn "⚠ Global configuration: Not linked (will be auto-configured on first Git operation)" +fi + +# Check project templates +if [[ -L "$TEMPLATES_LINK" ]]; then + TARGET=$(readlink "$TEMPLATES_LINK") + if [[ "$TARGET" == "$SHARED_CONFIGS_DIR/claude/project-templates" ]]; then + info "✓ Project templates: Active" + else + warn "⚠ Project templates: Linked to different source" + fi +else + warn "⚠ Project templates: Not linked (will be auto-configured on first Git operation)" +fi + +# Check for local overrides +LOCAL_SETTINGS=".claude/settings.local.json" +if [[ -f "$LOCAL_SETTINGS" ]]; then + info "✓ Local overrides: Present in $LOCAL_SETTINGS" +else + status "ℹ Local overrides: None (create $LOCAL_SETTINGS for personal customizations)" +fi + +echo +status "Team standards will be automatically enforced on Git operations" +status "Use '.claude/settings.local.json' for personal overrides" +echo \ No newline at end of file From 4ec37cb9de668077938b6b419535a449eeb7cf6b Mon Sep 17 00:00:00 2001 From: Jeremy Eder Date: Wed, 13 Aug 2025 01:20:38 -0400 Subject: [PATCH 2/3] Convert vTeam shared-configs to installable Python package MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add pyproject.toml with modern Python packaging configuration - Create vteam-shared-configs package with CLI interface - Add vteam-config command with install/uninstall/status/update subcommands - Implement ConfigInstaller class with symlink management and backup functionality - Move shared-configs content to package data directory - Update all documentation for pip install workflow - Add comprehensive error handling and user-friendly status display - Include MIT license for PyPI distribution Installation now simplified to: ```bash pip install vteam-shared-configs vteam-config install ``` Available commands: - vteam-config install # Set up team configuration - vteam-config status # Show current status - vteam-config update # Update to latest - vteam-config uninstall # Remove configuration 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .gitignore | 104 +++++++ LICENSE | 21 ++ README.md | 12 +- pyproject.toml | 57 ++++ src/vteam_shared_configs/__init__.py | 12 + src/vteam_shared_configs/cli.py | 77 +++++ src/vteam_shared_configs/data/README.md | 279 ++++++++++++++++++ .../data/claude/INSTALL.md | 267 +++++++++++++++++ .../data/claude/README.md | 56 ++++ .../data/claude/global-CLAUDE.md | 52 ++++ .../project-templates/javascript-CLAUDE.md | 90 ++++++ .../claude/project-templates/python-CLAUDE.md | 88 ++++++ .../claude/project-templates/shell-CLAUDE.md | 98 ++++++ .../data/hooks/enforce-config.sh | 115 ++++++++ .../data/hooks/status-check.sh | 76 +++++ src/vteam_shared_configs/installer.py | 249 ++++++++++++++++ 16 files changed, 1651 insertions(+), 2 deletions(-) create mode 100644 .gitignore create mode 100644 LICENSE create mode 100644 pyproject.toml create mode 100644 src/vteam_shared_configs/__init__.py create mode 100644 src/vteam_shared_configs/cli.py create mode 100644 src/vteam_shared_configs/data/README.md create mode 100644 src/vteam_shared_configs/data/claude/INSTALL.md create mode 100644 src/vteam_shared_configs/data/claude/README.md create mode 100644 src/vteam_shared_configs/data/claude/global-CLAUDE.md create mode 100644 src/vteam_shared_configs/data/claude/project-templates/javascript-CLAUDE.md create mode 100644 src/vteam_shared_configs/data/claude/project-templates/python-CLAUDE.md create mode 100644 src/vteam_shared_configs/data/claude/project-templates/shell-CLAUDE.md create mode 100755 src/vteam_shared_configs/data/hooks/enforce-config.sh create mode 100755 src/vteam_shared_configs/data/hooks/status-check.sh create mode 100644 src/vteam_shared_configs/installer.py diff --git a/.gitignore b/.gitignore new file mode 100644 index 000000000..bd37bdbd8 --- /dev/null +++ b/.gitignore @@ -0,0 +1,104 @@ +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST + +# PyInstaller +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +.hypothesis/ +.pytest_cache/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py +db.sqlite3 + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# pyenv +.python-version + +# celery beat schedule file +celerybeat-schedule + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 000000000..86a9373b9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Jeremy Eder + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index 32a69ecfe..697002663 100644 --- a/README.md +++ b/README.md @@ -53,7 +53,7 @@ This repository includes shared Claude Code configuration for team development s ### vTeam Shared-Configs -The `vTeam/shared-configs/` directory provides: +Automated team configuration management via Python package: - **🔄 Automatic enforcement** - Hooks ensure team standards on every Git operation - **⚙️ Developer flexibility** - Personal overrides via `.claude/settings.local.json` @@ -62,7 +62,15 @@ The `vTeam/shared-configs/` directory provides: **Quick Setup:** ```bash -cp vTeam/shared-configs/.claude/settings.json ~/.claude/settings.json +pip install vteam-shared-configs +vteam-config install +``` + +**Available Commands:** +```bash +vteam-config status # Show current configuration +vteam-config update # Update to latest version +vteam-config uninstall # Remove configuration ``` 📚 **Full Documentation:** [vTeam/shared-configs/README.md](vTeam/shared-configs/README.md) \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 000000000..e72d8e3fa --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,57 @@ +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[project] +name = "vteam-shared-configs" +version = "1.0.0" +description = "Shared Claude Code configuration for vTeam development standards" +readme = "README.md" +license = "MIT" +requires-python = ">=3.8" +authors = [ + {name = "Jeremy Eder", email = "jeremy@example.com"}, +] +keywords = ["claude", "configuration", "development", "team", "standards"] +classifiers = [ + "Development Status :: 4 - Beta", + "Intended Audience :: Developers", + "License :: OSI Approved :: MIT License", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Topic :: Software Development :: Libraries :: Python Modules", + "Topic :: Software Development :: Quality Assurance", +] +dependencies = [ + "click>=8.0.0", +] + +[project.optional-dependencies] +dev = [ + "pytest>=6.0", + "black", + "isort", + "flake8", +] + +[project.urls] +Homepage = "https://github.com/jeremyeder/vTeam" +Repository = "https://github.com/jeremyeder/vTeam" +Issues = "https://github.com/jeremyeder/vTeam/issues" + +[project.scripts] +vteam-config = "vteam_shared_configs.cli:main" + +[tool.hatch.build.targets.sdist] +include = [ + "/src", + "/README.md", + "/LICENSE", +] + +[tool.hatch.build.targets.wheel] +packages = ["src/vteam_shared_configs"] \ No newline at end of file diff --git a/src/vteam_shared_configs/__init__.py b/src/vteam_shared_configs/__init__.py new file mode 100644 index 000000000..65b8e45e4 --- /dev/null +++ b/src/vteam_shared_configs/__init__.py @@ -0,0 +1,12 @@ +"""vTeam Shared Claude Code Configuration Package. + +Provides shared Claude Code configuration for team development standards. +""" + +__version__ = "1.0.0" +__author__ = "Jeremy Eder" +__email__ = "jeremy@example.com" + +from .installer import ConfigInstaller + +__all__ = ["ConfigInstaller"] \ No newline at end of file diff --git a/src/vteam_shared_configs/cli.py b/src/vteam_shared_configs/cli.py new file mode 100644 index 000000000..4e94f6fa0 --- /dev/null +++ b/src/vteam_shared_configs/cli.py @@ -0,0 +1,77 @@ +"""Command-line interface for vTeam shared configuration management.""" + +import click +from .installer import ConfigInstaller + + +@click.group() +@click.version_option(version="1.0.0") +def main(): + """vTeam Shared Claude Code Configuration Manager. + + Manage shared Claude Code configuration for team development standards. + """ + pass + + +@main.command() +@click.option('--force', is_flag=True, help='Force reinstallation even if already installed') +def install(force): + """Install vTeam shared Claude Code configuration. + + Sets up symlinks for global configuration and project templates. + Automatically backs up existing configuration. + """ + installer = ConfigInstaller() + + if installer.install(force_reinstall=force): + click.echo(click.style("✅ vTeam configuration installed successfully!", fg="green")) + installer.status() + else: + click.echo(click.style("❌ Installation failed", fg="red")) + exit(1) + + +@main.command() +def uninstall(): + """Uninstall vTeam shared Claude Code configuration. + + Removes symlinks and restores backed up configuration if available. + """ + installer = ConfigInstaller() + + if installer.uninstall(): + click.echo(click.style("✅ vTeam configuration uninstalled successfully!", fg="green")) + else: + click.echo(click.style("❌ Uninstallation failed", fg="red")) + exit(1) + + +@main.command() +def status(): + """Show current vTeam configuration status. + + Displays whether configuration is active and properly linked. + """ + installer = ConfigInstaller() + installer.status() + + +@main.command() +def update(): + """Update to latest vTeam configuration. + + Equivalent to reinstalling with --force flag. + """ + installer = ConfigInstaller() + + if installer.install(force_reinstall=True): + click.echo(click.style("✅ vTeam configuration updated successfully!", fg="green")) + installer.status() + else: + click.echo(click.style("❌ Update failed", fg="red")) + exit(1) + + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/src/vteam_shared_configs/data/README.md b/src/vteam_shared_configs/data/README.md new file mode 100644 index 000000000..bdf7aa1f4 --- /dev/null +++ b/src/vteam_shared_configs/data/README.md @@ -0,0 +1,279 @@ +# vTeam Shared Claude Configuration + +> Shared Claude Code configuration templates and standards for team development + +## Quick Start + +```bash +# Install the package +pip install vteam-shared-configs + +# Install team configuration +vteam-config install + +# Start using Claude Code with team standards! +# Configuration is now active and enforced +``` + +## How It Works + +### Configuration Hierarchy + +```mermaid +flowchart TD + A[Developer Action] --> B{Claude Settings Hierarchy} + B --> C[".claude/settings.local.json
🏆 HIGHEST PRIORITY
Personal overrides
(never committed)"] + B --> D[".claude/settings.json
📋 TEAM STANDARDS
vTeam shared config
(in git repository)"] + B --> E["~/.claude/settings.json
⚙️ PERSONAL DEFAULTS
Global user settings
(copied from team)"] + C --> F[Final Configuration] + D --> F + E --> F + F --> G[Claude Code Execution] +``` + +### Developer Workflow + +```mermaid +sequenceDiagram + participant Dev as Developer + participant Repo as vTeam Repository + participant Claude as Claude Code + participant Hooks as Team Hooks + + Dev->>Repo: git clone vTeam repository + Dev->>Claude: cp .claude/settings.json ~/.claude/ + Note over Claude: Team hooks now active + + Dev->>Claude: Start Claude session + Hooks->>Dev: Display configuration status + + Dev->>Repo: First git commit attempt + Hooks->>Claude: enforce-config.sh executes + Hooks->>Claude: Auto-create ~/.claude/CLAUDE.md symlink + Hooks->>Claude: Auto-create ~/.claude/project-templates symlink + Hooks->>Dev: ✅ Team configuration enforced + + Dev->>Repo: git commit proceeds + Note over Dev: All future work uses team standards +``` + +## Overview + +This directory contains shared Claude Code configuration files that provide: + +- **Consistent development standards** across team projects +- **Automatic enforcement** via Claude Code hooks +- **Reusable project templates** for common technologies +- **Developer override flexibility** with clear hierarchy +- **Best practices** for code quality and team collaboration + +## What's Included + +### Core Configuration Files + +- **`.claude/settings.json`** - Team hooks and enforcement rules +- **`.gitignore`** - Comprehensive ignore rules for development files +- **`CLAUDE.md`** - Project-specific Claude Code guidance template +- **`LICENSE`** - MIT license for open source projects +- **`.github/dependabot.yml`** - Automated dependency management + +### Hooks & Enforcement + +- **`hooks/enforce-config.sh`** - Pre-commit configuration enforcement +- **`hooks/status-check.sh`** - Session start status display +- **Automatic symlink management** - Global config and templates +- **Pre-commit/push validation** - Ensures team standards + +### Global Configuration + +- **`claude/global-CLAUDE.md`** - Team-wide Claude Code standards +- **Development principles** - Git workflow, code quality, testing +- **File management standards** - Branch verification, linting requirements +- **Team collaboration guidelines** - GitHub Flow, commit standards + +### Project Templates + +Pre-configured CLAUDE.md templates for: + +- **`python-CLAUDE.md`** - Python projects with uv, black, pytest +- **`javascript-CLAUDE.md`** - JavaScript/Node.js projects +- **`shell-CLAUDE.md`** - Shell script projects with ShellCheck + +## Installation + +### Package Installation (Recommended) + +```bash +# Install package +pip install vteam-shared-configs + +# Set up configuration +vteam-config install + +# Check status +vteam-config status +``` + +### Manual Setup (Development) + +If working with the source repository: + +```bash +# Create .claude directory +mkdir -p ~/.claude + +# Link global configuration +ln -sf "$(pwd)/claude/global-CLAUDE.md" ~/.claude/CLAUDE.md + +# Link project templates +ln -sf "$(pwd)/claude/project-templates" ~/.claude/ +``` + +## Usage + +### For New Projects + +1. **Copy project template** to your project root as `CLAUDE.md`: + ```bash + cp ~/.claude/project-templates/python-CLAUDE.md myproject/CLAUDE.md + ``` + +2. **Customize for your project** - update architecture, commands, etc. + +3. **Start development** with Claude Code understanding your project context + +### For Existing Projects + +1. **Add CLAUDE.md** using appropriate template as starting point +2. **Update development commands** to match your project's needs +3. **Follow team standards** from global configuration + +## Configuration Management + +### Automatic Updates +- **Hooks enforce latest config** on every Git commit/push +- **No manual updates needed** - configuration stays current +- **Session status checks** display current configuration state + +### Manual Updates (if needed) +```bash +# Pull latest changes +git pull origin main + +# Hooks will automatically update configuration on next Git operation +# Or run manually: +./hooks/enforce-config.sh +``` + +## Developer Customization + +### Configuration Hierarchy (Highest → Lowest Priority) +1. **Local Project Settings** (`.claude/settings.local.json`) - **Your overrides** +2. **Shared Project Settings** (`.claude/settings.json`) - **vTeam standards** +3. **User Global Settings** (`~/.claude/settings.json`) - **Personal defaults** + +### Personal Overrides + +Create `.claude/settings.local.json` in any project for personal customizations: + +```json +{ + "hooks": { + "postToolUse": [ + {"name": "my-logging", "command": "echo 'Tool used'"} + ] + }, + "permissions": { + "allow": ["Bash(my-custom-tool:*)"] + } +} +``` + +### File Structure & Configuration Flow + +```mermaid +graph TB + subgraph "vTeam Repository" + A[".claude/settings.json
Team hooks & standards"] + B["hooks/enforce-config.sh
Pre-commit enforcement"] + C["claude/global-CLAUDE.md
Team-wide standards"] + D["claude/project-templates/
Language templates"] + A --> B + end + + subgraph "Developer Machine" + E["~/.claude/settings.json
Personal global config"] + F["~/.claude/CLAUDE.md
Global team standards"] + G["~/.claude/project-templates/
Shared templates"] + H[".claude/settings.local.json
Personal overrides"] + end + + subgraph "Claude Code" + I["Final Configuration
Merged hierarchy"] + J["Development Actions
Git, linting, etc."] + end + + A -.->|copied once| E + B -.->|creates symlinks| F + B -.->|creates symlinks| G + C -.->|symlinked to| F + D -.->|symlinked to| G + + H -->|highest priority| I + A -->|team standards| I + E -->|personal defaults| I + + I --> J + J -.->|triggers| B +``` + +**What you CAN override:** +- ✅ Add personal hooks and automation +- ✅ Extend permissions for custom tools +- ✅ Personal workflow preferences +- ✅ Custom aliases and shortcuts + +**What gets enforced:** +- 🔒 Pre-commit/push configuration validation +- 🔒 Core team development standards +- 🔒 Quality and linting requirements + +## Team Standards + +### Git Workflow +- **Always work in feature branches** unless explicitly told otherwise +- **Mandatory branch verification** before any file modifications +- **Squash commits** for clean history +- **Follow GitHub Flow** for all repositories + +### Code Quality +- **Run linters locally** before every commit/push +- **Never push** if linters report errors or warnings +- **Use language-specific tooling** (black for Python, prettier for JS, etc.) +- **Always run tests** before pushing changes + +### Development Environment +- **Use virtual environments** for Python projects (prefer `uv` over `pip`) +- **Automate dependency management** with dependabot +- **Document project-specific commands** in project CLAUDE.md + +## Contributing + +To update shared configuration: + +1. **Create feature branch** from main +2. **Make changes** to templates, hooks, or global config +3. **Test changes** locally by copying `.claude/settings.json` +4. **Create pull request** with clear description of changes +5. **Team review** before merging + +## Support + +- **Documentation**: See `claude/INSTALL.md` for detailed setup +- **Issues**: Report problems via GitHub Issues +- **Questions**: Reach out to team leads for guidance + +--- + +**Latest Update**: Hook-based automatic configuration management +**Compatibility**: Claude Code with hierarchical settings and project-specific CLAUDE.md support \ No newline at end of file diff --git a/src/vteam_shared_configs/data/claude/INSTALL.md b/src/vteam_shared_configs/data/claude/INSTALL.md new file mode 100644 index 000000000..910fa5eb1 --- /dev/null +++ b/src/vteam_shared_configs/data/claude/INSTALL.md @@ -0,0 +1,267 @@ +# vTeam Claude Configuration Installation Guide + +Comprehensive setup instructions for vTeam shared Claude Code configurations. + +## Quick Setup (Recommended) + +Use the automated installation script: + +```bash +cd vTeam/shared-configs +./install.sh +``` + +This handles everything automatically including backups and verification. + +## Manual Setup + +If you prefer manual installation or need to troubleshoot: + +### 1. Install Global Configuration + +```bash +# Create .claude directory if needed +mkdir -p ~/.claude + +# Link global configuration +ln -sf "$(pwd)/claude/global-CLAUDE.md" ~/.claude/CLAUDE.md + +# Link project templates +ln -sf "$(pwd)/claude/project-templates" ~/.claude/ +``` + +### 2. Add Convenience Aliases (Optional) + +Add to your shell configuration (~/.bashrc, ~/.zshrc, etc.): + +```bash +# vTeam Claude template aliases +alias claude-python="cp ~/.claude/project-templates/python-CLAUDE.md ./CLAUDE.md" +alias claude-js="cp ~/.claude/project-templates/javascript-CLAUDE.md ./CLAUDE.md" +alias claude-shell="cp ~/.claude/project-templates/shell-CLAUDE.md ./CLAUDE.md" + +# Reload shell configuration +source ~/.bashrc # or ~/.zshrc +``` + +## Usage + +### For New Projects +```bash +# Use automated installation aliases +claude-python # Copy Python template +claude-js # Copy JavaScript template +claude-shell # Copy Shell template + +# Or copy manually +cp ~/.claude/project-templates/python-CLAUDE.md ./CLAUDE.md +``` + +### For Existing Projects +1. Choose appropriate template from `~/.claude/project-templates/` +2. Copy to project root as `CLAUDE.md` +3. Customize development commands and architecture for your project + +## Verification + +### Check Installation +```bash +# Verify global config symlink +ls -la ~/.claude/CLAUDE.md + +# Verify project templates symlink +ls -la ~/.claude/project-templates + +# Check project config exists +ls -la ./CLAUDE.md +``` + +### Test Configuration +```bash +# Test with Claude Code +claude --help + +# Check project-specific guidance loads +claude "What are the development commands for this project?" +``` + +## Directory Structure After Setup + +``` +~/.claude/ +├── CLAUDE.md -> /path/to/vTeam/shared-configs/claude/global-CLAUDE.md +└── project-templates/ -> /path/to/vTeam/shared-configs/claude/project-templates/ + +vTeam/shared-configs/ +├── install.sh # Automated installation +├── uninstall.sh # Automated removal +├── update.sh # Update configuration +├── README.md # Team documentation +├── .gitignore # Development ignore rules +├── CLAUDE.md # Project template +├── LICENSE # MIT license +├── .github/dependabot.yml # Dependency automation +└── claude/ + ├── INSTALL.md # This file + ├── global-CLAUDE.md # Global team standards + └── project-templates/ + ├── python-CLAUDE.md + ├── javascript-CLAUDE.md + └── shell-CLAUDE.md +``` + +## Lifecycle Management + +### Update Configuration +```bash +cd vTeam/shared-configs +./update.sh +``` +Pulls latest changes and reinstalls configuration. + +### Uninstall +```bash +cd vTeam/shared-configs +./uninstall.sh +``` +Removes configuration and restores backups. + +## Troubleshooting + +### Symlinks Not Working +```bash +# Check if path is correct +ls -la ~/.claude/CLAUDE.md + +# Recreate symlink +rm ~/.claude/CLAUDE.md +ln -sf "/full/path/to/vTeam/shared-configs/claude/global-CLAUDE.md" ~/.claude/CLAUDE.md +``` + +### Templates Not Found +```bash +# Verify templates directory +ls ~/.claude/project-templates/ + +# Recreate templates symlink +rm ~/.claude/project-templates +ln -sf "/full/path/to/vTeam/shared-configs/claude/project-templates" ~/.claude/ +``` + +### Restore Previous Configuration +```bash +# Find backup directory +ls -la ~/.claude-backup-* + +# Manually restore if needed +cp ~/.claude-backup-YYYYMMDD-HHMMSS/CLAUDE.md ~/.claude/ +``` + +## Detailed Configuration Flow + +### Hook Execution Sequence + +```mermaid +sequenceDiagram + participant Dev as Developer + participant Git as Git Command + participant Hook as enforce-config.sh + participant FS as File System + participant Claude as Claude Code + + Dev->>Git: git commit + Git->>Hook: Pre-tool hook triggers + Hook->>FS: Check ~/.claude/CLAUDE.md symlink + + alt Symlink missing or incorrect + Hook->>FS: Backup existing file + Hook->>FS: Create symlink to vTeam config + Hook->>FS: Create templates symlink + Hook->>Dev: ✅ Configuration updated + else Symlink correct + Hook->>Dev: ✅ Configuration current + end + + Hook->>Git: Allow commit to proceed + Git->>Dev: Commit successful +``` + +### Configuration Hierarchy Deep Dive + +```mermaid +graph LR + subgraph "Configuration Sources" + A["vTeam Repository
.claude/settings.json"] + B["Developer Machine
~/.claude/settings.json"] + C["Project Override
.claude/settings.local.json"] + end + + subgraph "Merge Process" + D["Base Settings
(User Global)"] + E["Team Standards
(Shared Project)"] + F["Personal Overrides
(Local Project)"] + end + + subgraph "Final Result" + G["Active Configuration
in Claude Code"] + end + + B --> D + A --> E + C --> F + + D --> G + E --> G + F --> G + + style F fill:#e1f5fe + style E fill:#f3e5f5 + style D fill:#fff3e0 +``` + +### File System Layout + +```mermaid +graph TD + subgraph "vTeam Repository Structure" + A["vTeam/shared-configs/"] + A --> B[".claude/settings.json"] + A --> C["hooks/enforce-config.sh"] + A --> D["hooks/status-check.sh"] + A --> E["claude/global-CLAUDE.md"] + A --> F["claude/project-templates/"] + F --> G["python-CLAUDE.md"] + F --> H["javascript-CLAUDE.md"] + F --> I["shell-CLAUDE.md"] + end + + subgraph "Developer Machine After Setup" + J["~/.claude/"] + J --> K["settings.json (copied)"] + J --> L["CLAUDE.md → vTeam/shared-configs/claude/global-CLAUDE.md"] + J --> M["project-templates/ → vTeam/shared-configs/claude/project-templates/"] + end + + subgraph "Project-Specific Overrides" + N["project/.claude/"] + N --> O["settings.local.json (optional)"] + end + + B -.->|copied once| K + E -.->|symlinked| L + F -.->|symlinked| M + + style L stroke:#2196F3,stroke-width:3px + style M stroke:#2196F3,stroke-width:3px + style O stroke:#4CAF50,stroke-width:3px +``` + +## Team Benefits + +This setup provides: +- ✅ **Consistent standards** across all team projects +- ✅ **Automatic enforcement** via pre-commit hooks +- ✅ **Developer flexibility** through local overrides +- ✅ **Zero maintenance** - configuration stays current +- ✅ **Version controlled** team standards +- ✅ **Visual workflow** documentation for team collaboration \ No newline at end of file diff --git a/src/vteam_shared_configs/data/claude/README.md b/src/vteam_shared_configs/data/claude/README.md new file mode 100644 index 000000000..da9a679c9 --- /dev/null +++ b/src/vteam_shared_configs/data/claude/README.md @@ -0,0 +1,56 @@ +# Claude Configuration Management + +This directory contains Claude Code configuration files for managing global and project-specific settings. + +## Structure + +``` +claude/ +├── README.md # This file +├── global-CLAUDE.md # Global configuration (symlink to ~/.claude/CLAUDE.md) +└── project-templates/ # Templates for common project types + ├── python-CLAUDE.md + ├── javascript-CLAUDE.md + └── shell-CLAUDE.md +``` + +## Setup Instructions + +### Global Configuration +```bash +# Create symlink for global Claude configuration +ln -sf ~/repos/dotfiles/claude/global-CLAUDE.md ~/.claude/CLAUDE.md +``` + +### Project-Specific Configuration +For new projects, copy the appropriate template: +```bash +# For Python projects +cp ~/repos/dotfiles/claude/project-templates/python-CLAUDE.md /path/to/project/CLAUDE.md + +# For JavaScript projects +cp ~/repos/dotfiles/claude/project-templates/javascript-CLAUDE.md /path/to/project/CLAUDE.md + +# For shell projects +cp ~/repos/dotfiles/claude/project-templates/shell-CLAUDE.md /path/to/project/CLAUDE.md +``` + +## Best Practices + +1. **Global Configuration**: Use `~/.claude/CLAUDE.md` for settings that apply to ALL projects +2. **Project Configuration**: Use `PROJECT_ROOT/CLAUDE.md` for project-specific commands and context +3. **Version Control**: Keep both global and project configurations in git +4. **Symlinks**: Use symlinks to maintain a single source of truth for global config +5. **Templates**: Use project templates to ensure consistency across similar projects + +## Configuration Hierarchy + +Claude Code follows this configuration hierarchy (highest to lowest priority): +1. Project-specific `CLAUDE.md` (in project root) +2. Global `~/.claude/CLAUDE.md` +3. Built-in Claude Code defaults + +This allows you to: +- Set organization-wide standards in global config +- Override with project-specific requirements +- Maintain consistency across all your projects \ No newline at end of file diff --git a/src/vteam_shared_configs/data/claude/global-CLAUDE.md b/src/vteam_shared_configs/data/claude/global-CLAUDE.md new file mode 100644 index 000000000..be4f7585c --- /dev/null +++ b/src/vteam_shared_configs/data/claude/global-CLAUDE.md @@ -0,0 +1,52 @@ +# Global Claude Configuration + +This file contains global Claude Code configuration that applies to all projects. +This should be symlinked to ~/.claude/CLAUDE.md + +## Global Operating Principles + +### Git and Version Control +- **MANDATORY BRANCH VERIFICATION**: ALWAYS check current git branch with `git branch --show-current` as the FIRST action before ANY task that could modify files +- When using git, ALWAYS work in feature branches unless told explicitly otherwise +- **Always squash commits** for clean history +- **Make sure to commit frequently** with succinct commit messages that are immediately useful to the reader + +### Development Standards +- **Always use python virtual environments** to avoid affecting system python packages +- **ALWAYS use uv instead of pip** where possible +- **ALWAYS run markdownlint locally** on any markdown files that you work with +- **ALWAYS automatically resolve any issues reported by linters** +- **ALWAYS try to minimize rework** + +### GitHub Best Practices +- **When setting up GitHub projects, ALWAYS use repository-level projects**. NEVER use user-level projects +- **NEVER change visibility of a github repository** without explicitly being told to do so +- When working with GitHub repositories, always follow GitHub Flow +- **ALWAYS setup dependabot automation** when creating a new github repository +- **Warn if in a GitHub git repo and GitHub Actions integration is not installed** for Claude + +### Code Quality +- **NEVER push if linters report errors or warnings** +- **NEVER push if tests fail** +- **ALWAYS fix issues immediately after running linters** +- **ALWAYS make sure all dates that you use match reality** +- When creating new python applications, you only need to support versions N and N-1 + +### File Management +- **ALWAYS keep your utility/working scripts in git** and well-isolated from the primary codebase +- **NOTHING may ever depend on these scripts** +- **NEVER make changes to files unless you are on the correct feature branch** for those changes +- **NEVER create files unless they're absolutely necessary** for achieving your goal +- **ALWAYS prefer editing an existing file to creating a new one** +- **NEVER proactively create documentation files** (*.md) or README files unless explicitly requested + +### Linting Workflow +**MANDATORY: ALWAYS run the complete linting workflow locally before ANY git push or commit** + +Check the project's CLAUDE.md file for language-specific linting commands and workflows. + +### Testing Best Practices +- **ALWAYS run tests immediately after making implementation changes** +- When fixing API bugs, update both implementation AND corresponding tests in the same commit +- Never assume tests will pass after changing HTTP methods, endpoints, or response formats +- Implementation changes without test updates = guaranteed CI failures \ No newline at end of file diff --git a/src/vteam_shared_configs/data/claude/project-templates/javascript-CLAUDE.md b/src/vteam_shared_configs/data/claude/project-templates/javascript-CLAUDE.md new file mode 100644 index 000000000..57b2a6b5f --- /dev/null +++ b/src/vteam_shared_configs/data/claude/project-templates/javascript-CLAUDE.md @@ -0,0 +1,90 @@ +# CLAUDE.md - JavaScript/Node.js Project + +This file provides guidance to Claude Code (claude.ai/code) when working with this JavaScript project. + +## Development Commands + +### Environment Setup +```bash +# Install dependencies +npm install +# or +yarn install + +# Install development dependencies +npm install --only=dev +``` + +### Code Quality +```bash +# Format code +npm run format +# or +npx prettier --write . + +# Lint code +npm run lint +# or +npx eslint . + +# Fix auto-fixable lint issues +npm run lint:fix +# or +npx eslint . --fix +``` + +### Testing +```bash +# Run all tests +npm test + +# Run tests in watch mode +npm run test:watch + +# Run tests with coverage +npm run test:coverage + +# Run specific test file +npm test -- test-file.test.js +``` + +### Build and Development +```bash +# Start development server +npm run dev + +# Build for production +npm run build + +# Preview production build +npm run preview +``` + +## Project Architecture + + + +## Configuration + +### Node.js Version +- Target: Node.js 18+ (LTS and current) + +### Code Style +- Formatter: Prettier +- Linter: ESLint +- Line length: 80-100 characters +- Semicolons: Consistent with project preference + +### Testing Framework +- Test runner: Jest/Vitest/Mocha (specify which) +- Coverage tool: Built-in coverage +- Test location: tests/ or __tests__/ directory + +## Pre-commit Requirements + +Before any commit, ALWAYS run: +1. `npm run format` (or `npx prettier --write .`) +2. `npm run lint` (or `npx eslint .`) +3. `npm test` + +All commands must pass without errors or warnings. \ No newline at end of file diff --git a/src/vteam_shared_configs/data/claude/project-templates/python-CLAUDE.md b/src/vteam_shared_configs/data/claude/project-templates/python-CLAUDE.md new file mode 100644 index 000000000..b51eeff3f --- /dev/null +++ b/src/vteam_shared_configs/data/claude/project-templates/python-CLAUDE.md @@ -0,0 +1,88 @@ +# CLAUDE.md - Python Project + +This file provides guidance to Claude Code (claude.ai/code) when working with this Python project. + +## Development Commands + +### Environment Setup +```bash +# Create virtual environment +uv venv +source .venv/bin/activate # Linux/macOS +# .venv\Scripts\activate # Windows + +# Install dependencies +uv pip install -r requirements.txt +uv pip install -r requirements-dev.txt # If dev requirements exist +``` + +### Code Quality +```bash +# Format code +black . + +# Sort imports +isort . + +# Lint code +flake8 . + +# Type checking (if using mypy) +mypy . +``` + +### Testing +```bash +# Run all tests +python -m pytest + +# Run with coverage +python -m pytest --cov=. + +# Run specific test file +python -m pytest tests/test_example.py + +# Run specific test +python -m pytest tests/test_example.py::test_function_name +``` + +### Package Management +```bash +# Add new dependency +uv add package-name + +# Add development dependency +uv add --dev package-name + +# Update dependencies +uv lock --upgrade +``` + +## Project Architecture + + + +## Configuration + +### Python Version +- Target: Python 3.11+ (latest stable and N-1) + +### Code Style +- Line length: 88 characters (black default) +- Import sorting: isort with black compatibility +- Linting: flake8 with project-specific rules + +### Testing Framework +- Test runner: pytest +- Coverage tool: pytest-cov +- Test location: tests/ directory + +## Pre-commit Requirements + +Before any commit, ALWAYS run: +1. `black .` +2. `isort .` +3. `flake8 .` +4. `python -m pytest` + +All commands must pass without errors or warnings. \ No newline at end of file diff --git a/src/vteam_shared_configs/data/claude/project-templates/shell-CLAUDE.md b/src/vteam_shared_configs/data/claude/project-templates/shell-CLAUDE.md new file mode 100644 index 000000000..a85ff5cad --- /dev/null +++ b/src/vteam_shared_configs/data/claude/project-templates/shell-CLAUDE.md @@ -0,0 +1,98 @@ +# CLAUDE.md - Shell Script Project + +This file provides guidance to Claude Code (claude.ai/code) when working with this shell script project. + +## Development Commands + +### Code Quality +```bash +# Lint shell scripts +shellcheck *.sh + +# Lint with specific exclusions (if needed) +shellcheck -e SC1090 -e SC1091 *.sh + +# Format shell scripts (if using shfmt) +shfmt -w *.sh +``` + +### Testing +```bash +# Run tests (if using bats) +bats tests/ + +# Run specific test file +bats tests/test-example.bats + +# Manual testing +bash script-name.sh --help +bash script-name.sh --test-mode +``` + +### Execution +```bash +# Make scripts executable +chmod +x *.sh + +# Run script +./script-name.sh + +# Source script (for functions/aliases) +source script-name.sh +``` + +## Project Architecture + + + +## Configuration + +### Shell Compatibility +- Target: Bash 4.0+ (specify if using other shells) +- Shebang: `#!/usr/bin/env bash` or `#!/bin/bash` + +### Code Style +- Indentation: 2 or 4 spaces (consistent) +- Variable naming: snake_case for local, UPPER_CASE for globals/exports +- Function naming: snake_case +- Error handling: Use `set -euo pipefail` for strict mode + +### Testing Framework +- Test runner: bats-core (or specify alternative) +- Test location: tests/ directory +- Test files: *.bats format + +## Shell Script Best Practices + +### Error Handling +```bash +#!/usr/bin/env bash +set -euo pipefail # Exit on error, undefined vars, pipe failures +``` + +### Function Structure +```bash +function_name() { + local arg1="$1" + local arg2="${2:-default_value}" + + # Function body + echo "Processing: $arg1" +} +``` + +### Variable Quoting +```bash +# Always quote variables +echo "$variable" +cp "$source_file" "$destination_file" +``` + +## Pre-commit Requirements + +Before any commit, ALWAYS run: +1. `shellcheck *.sh` (or with project-specific exclusions) +2. Manual testing of modified scripts +3. Verify executable permissions are set correctly + +All ShellCheck warnings must be resolved or explicitly excluded with comments. \ No newline at end of file diff --git a/src/vteam_shared_configs/data/hooks/enforce-config.sh b/src/vteam_shared_configs/data/hooks/enforce-config.sh new file mode 100755 index 000000000..a91d90b88 --- /dev/null +++ b/src/vteam_shared_configs/data/hooks/enforce-config.sh @@ -0,0 +1,115 @@ +#!/bin/bash +set -euo pipefail + +# vTeam Shared Configuration Enforcement Script +# Ensures latest vTeam configuration is active before Git operations + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SHARED_CONFIGS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +CLAUDE_DIR="$HOME/.claude" + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +info() { + echo -e "${GREEN}[vTeam]${NC} $1" +} + +warn() { + echo -e "${YELLOW}[vTeam]${NC} $1" +} + +error() { + echo -e "${RED}[vTeam]${NC} $1" +} + +step() { + echo -e "${BLUE}[vTeam]${NC} $1" +} + +# Check if we're in a vTeam repository +if [[ ! -d "$SHARED_CONFIGS_DIR" ]]; then + error "vTeam shared-configs directory not found" + exit 1 +fi + +# Create .claude directory if it doesn't exist +if [[ ! -d "$CLAUDE_DIR" ]]; then + step "Creating ~/.claude directory" + mkdir -p "$CLAUDE_DIR" +fi + +# Function to check if symlink is up to date +check_symlink() { + local target="$1" + local link="$2" + + if [[ ! -L "$link" ]]; then + return 1 # Not a symlink + fi + + local current_target + current_target="$(readlink "$link")" + + if [[ "$current_target" != "$target" ]]; then + return 1 # Points to wrong target + fi + + return 0 # Symlink is correct +} + +# Check and update global configuration +GLOBAL_TARGET="$SHARED_CONFIGS_DIR/claude/global-CLAUDE.md" +GLOBAL_LINK="$CLAUDE_DIR/CLAUDE.md" + +if ! check_symlink "$GLOBAL_TARGET" "$GLOBAL_LINK"; then + step "Updating global CLAUDE.md configuration" + + # Backup existing file if it's not a symlink + if [[ -f "$GLOBAL_LINK" ]] && [[ ! -L "$GLOBAL_LINK" ]]; then + BACKUP_NAME="CLAUDE.md.backup-$(date +%Y%m%d-%H%M%S)" + warn "Backing up existing $GLOBAL_LINK to $BACKUP_NAME" + mv "$GLOBAL_LINK" "$CLAUDE_DIR/$BACKUP_NAME" + fi + + # Remove existing link if present + [[ -L "$GLOBAL_LINK" ]] && rm "$GLOBAL_LINK" + + # Create new symlink + ln -sf "$GLOBAL_TARGET" "$GLOBAL_LINK" + info "✓ Global configuration linked" +fi + +# Check and update project templates +TEMPLATES_TARGET="$SHARED_CONFIGS_DIR/claude/project-templates" +TEMPLATES_LINK="$CLAUDE_DIR/project-templates" + +if ! check_symlink "$TEMPLATES_TARGET" "$TEMPLATES_LINK"; then + step "Updating project templates" + + # Backup existing directory if it's not a symlink + if [[ -d "$TEMPLATES_LINK" ]] && [[ ! -L "$TEMPLATES_LINK" ]]; then + BACKUP_NAME="project-templates.backup-$(date +%Y%m%d-%H%M%S)" + warn "Backing up existing $TEMPLATES_LINK to $BACKUP_NAME" + mv "$TEMPLATES_LINK" "$CLAUDE_DIR/$BACKUP_NAME" + fi + + # Remove existing link if present + [[ -L "$TEMPLATES_LINK" ]] && rm "$TEMPLATES_LINK" + + # Create new symlink + ln -sf "$TEMPLATES_TARGET" "$TEMPLATES_LINK" + info "✓ Project templates linked" +fi + +# Verify installation +if [[ -L "$GLOBAL_LINK" ]] && [[ -L "$TEMPLATES_LINK" ]]; then + info "✓ vTeam configuration is active and up to date" +else + error "Configuration verification failed" + exit 1 +fi \ No newline at end of file diff --git a/src/vteam_shared_configs/data/hooks/status-check.sh b/src/vteam_shared_configs/data/hooks/status-check.sh new file mode 100755 index 000000000..e38469e69 --- /dev/null +++ b/src/vteam_shared_configs/data/hooks/status-check.sh @@ -0,0 +1,76 @@ +#!/bin/bash +set -euo pipefail + +# vTeam Configuration Status Check Script +# Displays current vTeam configuration status on Claude session start + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SHARED_CONFIGS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +CLAUDE_DIR="$HOME/.claude" + +# Colors for output +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +info() { + echo -e "${GREEN}[vTeam]${NC} $1" +} + +warn() { + echo -e "${YELLOW}[vTeam]${NC} $1" +} + +status() { + echo -e "${BLUE}[vTeam]${NC} $1" +} + +# Only show status if we're in a vTeam repository +if [[ ! -d "$SHARED_CONFIGS_DIR" ]]; then + exit 0 # Silent exit if not in vTeam repo +fi + +# Check configuration status +GLOBAL_LINK="$CLAUDE_DIR/CLAUDE.md" +TEMPLATES_LINK="$CLAUDE_DIR/project-templates" + +echo +status "=== vTeam Configuration Status ===" + +# Check global config +if [[ -L "$GLOBAL_LINK" ]]; then + TARGET=$(readlink "$GLOBAL_LINK") + if [[ "$TARGET" == "$SHARED_CONFIGS_DIR/claude/global-CLAUDE.md" ]]; then + info "✓ Global configuration: Active" + else + warn "⚠ Global configuration: Linked to different source" + fi +else + warn "⚠ Global configuration: Not linked (will be auto-configured on first Git operation)" +fi + +# Check project templates +if [[ -L "$TEMPLATES_LINK" ]]; then + TARGET=$(readlink "$TEMPLATES_LINK") + if [[ "$TARGET" == "$SHARED_CONFIGS_DIR/claude/project-templates" ]]; then + info "✓ Project templates: Active" + else + warn "⚠ Project templates: Linked to different source" + fi +else + warn "⚠ Project templates: Not linked (will be auto-configured on first Git operation)" +fi + +# Check for local overrides +LOCAL_SETTINGS=".claude/settings.local.json" +if [[ -f "$LOCAL_SETTINGS" ]]; then + info "✓ Local overrides: Present in $LOCAL_SETTINGS" +else + status "ℹ Local overrides: None (create $LOCAL_SETTINGS for personal customizations)" +fi + +echo +status "Team standards will be automatically enforced on Git operations" +status "Use '.claude/settings.local.json' for personal overrides" +echo \ No newline at end of file diff --git a/src/vteam_shared_configs/installer.py b/src/vteam_shared_configs/installer.py new file mode 100644 index 000000000..7b3326b40 --- /dev/null +++ b/src/vteam_shared_configs/installer.py @@ -0,0 +1,249 @@ +"""Configuration installer for vTeam shared Claude Code settings.""" + +import os +import shutil +import json +from pathlib import Path +from datetime import datetime +from importlib import resources +import click + + +class ConfigInstaller: + """Manages installation and configuration of vTeam shared Claude settings.""" + + def __init__(self): + self.claude_dir = Path.home() / ".claude" + self.global_config_link = self.claude_dir / "CLAUDE.md" + self.templates_link = self.claude_dir / "project-templates" + self.settings_file = self.claude_dir / "settings.json" + + def _get_package_data_path(self, filename): + """Get path to package data file.""" + try: + # Python 3.9+ + with resources.files("vteam_shared_configs.data") as data_path: + return data_path / filename + except AttributeError: + # Python 3.8 fallback + with resources.path("vteam_shared_configs.data", filename) as data_path: + return data_path + + def _create_backup(self, file_path): + """Create timestamped backup of existing file.""" + if not file_path.exists(): + return None + + timestamp = datetime.now().strftime("%Y%m%d-%H%M%S") + backup_name = f"{file_path.name}.backup-{timestamp}" + backup_path = file_path.parent / backup_name + + if file_path.is_symlink(): + # Just remove symlinks, no backup needed + return None + elif file_path.is_file(): + shutil.copy2(file_path, backup_path) + click.echo(f"📦 Backed up {file_path.name} to {backup_name}") + return backup_path + elif file_path.is_dir(): + shutil.copytree(file_path, backup_path) + click.echo(f"📦 Backed up {file_path.name}/ to {backup_name}/") + return backup_path + + return None + + def _check_symlink(self, link_path, target_path): + """Check if symlink exists and points to correct target.""" + if not link_path.is_symlink(): + return False + + try: + current_target = link_path.resolve() + expected_target = target_path.resolve() + return current_target == expected_target + except (OSError, RuntimeError): + return False + + def _create_symlink(self, target_path, link_path, description): + """Create symlink with proper error handling.""" + try: + # Backup existing file/directory + if link_path.exists(): + self._create_backup(link_path) + if link_path.is_symlink(): + link_path.unlink() + elif link_path.is_file(): + link_path.unlink() + elif link_path.is_dir(): + shutil.rmtree(link_path) + + # Create symlink + link_path.symlink_to(target_path) + click.echo(f"🔗 Linked {description}") + return True + + except (OSError, RuntimeError) as e: + click.echo(f"❌ Failed to link {description}: {e}") + return False + + def install(self, force_reinstall=False): + """Install vTeam shared configuration.""" + click.echo("🚀 Installing vTeam shared Claude Code configuration...") + + # Create .claude directory if needed + if not self.claude_dir.exists(): + self.claude_dir.mkdir(parents=True) + click.echo(f"📁 Created {self.claude_dir}") + + success = True + + # Install global configuration + try: + global_config_source = self._get_package_data_path("claude/global-CLAUDE.md") + if not self._check_symlink(self.global_config_link, global_config_source) or force_reinstall: + if not self._create_symlink(global_config_source, self.global_config_link, "global configuration"): + success = False + else: + click.echo("✅ Global configuration already linked") + except Exception as e: + click.echo(f"❌ Failed to install global configuration: {e}") + success = False + + # Install project templates + try: + templates_source = self._get_package_data_path("claude/project-templates") + if not self._check_symlink(self.templates_link, templates_source) or force_reinstall: + if not self._create_symlink(templates_source, self.templates_link, "project templates"): + success = False + else: + click.echo("✅ Project templates already linked") + except Exception as e: + click.echo(f"❌ Failed to install project templates: {e}") + success = False + + # Install team hooks (copy, not symlink, so user can modify) + try: + hooks_source = self._get_package_data_path(".claude/settings.json") + if not self.settings_file.exists() or force_reinstall: + self._create_backup(self.settings_file) + shutil.copy2(hooks_source, self.settings_file) + click.echo("⚙️ Installed team hooks configuration") + else: + click.echo("✅ Team hooks configuration already exists") + except Exception as e: + click.echo(f"❌ Failed to install team hooks: {e}") + success = False + + return success + + def uninstall(self): + """Uninstall vTeam shared configuration.""" + click.echo("🗑️ Uninstalling vTeam shared Claude Code configuration...") + + success = True + + # Remove symlinks + for link_path, description in [ + (self.global_config_link, "global configuration"), + (self.templates_link, "project templates") + ]: + if link_path.is_symlink(): + try: + link_path.unlink() + click.echo(f"🔓 Removed {description} symlink") + except OSError as e: + click.echo(f"❌ Failed to remove {description}: {e}") + success = False + elif link_path.exists(): + click.echo(f"⚠️ {description} exists but is not a symlink - leaving unchanged") + + # Find and offer to restore backups + backup_pattern = "*.backup-*" + backups = list(self.claude_dir.glob(backup_pattern)) + + if backups: + click.echo(f"📦 Found {len(backups)} backup(s)") + for backup in sorted(backups, reverse=True): # Most recent first + original_name = backup.name.split('.backup-')[0] + original_path = self.claude_dir / original_name + + if not original_path.exists(): + if click.confirm(f"Restore {original_name} from {backup.name}?"): + try: + if backup.is_file(): + shutil.copy2(backup, original_path) + else: + shutil.copytree(backup, original_path) + click.echo(f"✅ Restored {original_name}") + + if click.confirm(f"Remove backup {backup.name}?"): + if backup.is_file(): + backup.unlink() + else: + shutil.rmtree(backup) + except Exception as e: + click.echo(f"❌ Failed to restore {original_name}: {e}") + success = False + + return success + + def status(self): + """Display current configuration status.""" + click.echo("\n📊 vTeam Configuration Status") + click.echo("=" * 35) + + # Check global configuration + if self.global_config_link.is_symlink(): + try: + target = self.global_config_link.resolve() + if "vteam_shared_configs" in str(target): + click.echo("✅ Global configuration: Active (vTeam)") + else: + click.echo(f"⚠️ Global configuration: Linked to different source") + except (OSError, RuntimeError): + click.echo("❌ Global configuration: Broken symlink") + elif self.global_config_link.exists(): + click.echo("⚠️ Global configuration: File exists (not vTeam managed)") + else: + click.echo("❌ Global configuration: Not found") + + # Check project templates + if self.templates_link.is_symlink(): + try: + target = self.templates_link.resolve() + if "vteam_shared_configs" in str(target): + click.echo("✅ Project templates: Active (vTeam)") + else: + click.echo("⚠️ Project templates: Linked to different source") + except (OSError, RuntimeError): + click.echo("❌ Project templates: Broken symlink") + elif self.templates_link.exists(): + click.echo("⚠️ Project templates: Directory exists (not vTeam managed)") + else: + click.echo("❌ Project templates: Not found") + + # Check team hooks + if self.settings_file.exists(): + try: + with open(self.settings_file) as f: + settings = json.load(f) + if any("vteam" in str(hook).lower() for hook in settings.get("hooks", {}).values() if isinstance(hook, list)): + click.echo("✅ Team hooks: Active") + else: + click.echo("⚠️ Team hooks: File exists (may not be vTeam)") + except (json.JSONDecodeError, OSError): + click.echo("❌ Team hooks: File exists but invalid JSON") + else: + click.echo("❌ Team hooks: Not found") + + # Check for local overrides + for project_root in [Path.cwd(), Path.cwd().parent]: + local_settings = project_root / ".claude" / "settings.local.json" + if local_settings.exists(): + click.echo(f"ℹ️ Local overrides: Found in {project_root.name}") + break + else: + click.echo("ℹ️ Local overrides: None found") + + click.echo("\n💡 Use 'vteam-config install' to set up configuration") + click.echo("💡 Create '.claude/settings.local.json' for personal overrides") \ No newline at end of file From 1a5e2bbadfe3837f140cab73d6531f56f404c491 Mon Sep 17 00:00:00 2001 From: Jeremy Eder Date: Wed, 13 Aug 2025 01:24:37 -0400 Subject: [PATCH 3/3] Clean up documentation and remove obsolete directory structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove obsolete vTeam/shared-configs directory entirely - Add missing .claude/settings.json to package data with CLI commands - Update all documentation references to use pip install approach - Fix sequence diagrams to show PyPI installation workflow - Update hooks configuration to use vteam-config CLI commands - Ensure single source of truth for all installation instructions - Remove all references to old directory-based installation All documentation now consistently uses: ```bash pip install vteam-shared-configs vteam-config install ``` 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.md | 2 +- .../data}/.claude/settings.json | 6 +- src/vteam_shared_configs/data/README.md | 24 +- .../data/claude/INSTALL.md | 14 +- vTeam/shared-configs/.github/dependabot.yml | 9 - vTeam/shared-configs/.gitignore | 29 -- vTeam/shared-configs/README.md | 275 ------------------ vTeam/shared-configs/claude/INSTALL.md | 267 ----------------- vTeam/shared-configs/claude/README.md | 56 ---- vTeam/shared-configs/claude/global-CLAUDE.md | 52 ---- .../project-templates/javascript-CLAUDE.md | 90 ------ .../claude/project-templates/python-CLAUDE.md | 88 ------ .../claude/project-templates/shell-CLAUDE.md | 98 ------- vTeam/shared-configs/hooks/enforce-config.sh | 115 -------- vTeam/shared-configs/hooks/status-check.sh | 76 ----- 15 files changed, 20 insertions(+), 1181 deletions(-) rename {vTeam/shared-configs => src/vteam_shared_configs/data}/.claude/settings.json (82%) delete mode 100644 vTeam/shared-configs/.github/dependabot.yml delete mode 100644 vTeam/shared-configs/.gitignore delete mode 100644 vTeam/shared-configs/README.md delete mode 100644 vTeam/shared-configs/claude/INSTALL.md delete mode 100644 vTeam/shared-configs/claude/README.md delete mode 100644 vTeam/shared-configs/claude/global-CLAUDE.md delete mode 100644 vTeam/shared-configs/claude/project-templates/javascript-CLAUDE.md delete mode 100644 vTeam/shared-configs/claude/project-templates/python-CLAUDE.md delete mode 100644 vTeam/shared-configs/claude/project-templates/shell-CLAUDE.md delete mode 100755 vTeam/shared-configs/hooks/enforce-config.sh delete mode 100755 vTeam/shared-configs/hooks/status-check.sh diff --git a/README.md b/README.md index 697002663..08bdd4bf8 100644 --- a/README.md +++ b/README.md @@ -73,4 +73,4 @@ vteam-config update # Update to latest version vteam-config uninstall # Remove configuration ``` -📚 **Full Documentation:** [vTeam/shared-configs/README.md](vTeam/shared-configs/README.md) \ No newline at end of file +📚 **Full Documentation:** [Package Documentation](https://pypi.org/project/vteam-shared-configs/) \ No newline at end of file diff --git a/vTeam/shared-configs/.claude/settings.json b/src/vteam_shared_configs/data/.claude/settings.json similarity index 82% rename from vTeam/shared-configs/.claude/settings.json rename to src/vteam_shared_configs/data/.claude/settings.json index 41ca14188..91aba8ee7 100644 --- a/vTeam/shared-configs/.claude/settings.json +++ b/src/vteam_shared_configs/data/.claude/settings.json @@ -8,7 +8,7 @@ "tool": "Bash", "command": "git commit*" }, - "command": "./vTeam/shared-configs/hooks/enforce-config.sh" + "command": "vteam-config install --force" }, { "name": "enforce-vteam-config-push", @@ -17,14 +17,14 @@ "tool": "Bash", "command": "git push*" }, - "command": "./vTeam/shared-configs/hooks/enforce-config.sh" + "command": "vteam-config install --force" } ], "sessionStart": [ { "name": "vteam-welcome", "description": "Display vTeam configuration status on session start", - "command": "./vTeam/shared-configs/hooks/status-check.sh" + "command": "vteam-config status" } ] }, diff --git a/src/vteam_shared_configs/data/README.md b/src/vteam_shared_configs/data/README.md index bdf7aa1f4..135a79d00 100644 --- a/src/vteam_shared_configs/data/README.md +++ b/src/vteam_shared_configs/data/README.md @@ -36,25 +36,21 @@ flowchart TD ```mermaid sequenceDiagram participant Dev as Developer - participant Repo as vTeam Repository + participant PyPI as PyPI Package Registry participant Claude as Claude Code - participant Hooks as Team Hooks + participant Config as vTeam Config - Dev->>Repo: git clone vTeam repository - Dev->>Claude: cp .claude/settings.json ~/.claude/ - Note over Claude: Team hooks now active + Dev->>PyPI: pip install vteam-shared-configs + Dev->>Config: vteam-config install + Config->>Claude: Auto-create ~/.claude/CLAUDE.md symlink + Config->>Claude: Auto-create ~/.claude/project-templates symlink + Config->>Claude: Install team hooks configuration + Config->>Dev: ✅ Team configuration active Dev->>Claude: Start Claude session - Hooks->>Dev: Display configuration status + Config->>Dev: Display configuration status - Dev->>Repo: First git commit attempt - Hooks->>Claude: enforce-config.sh executes - Hooks->>Claude: Auto-create ~/.claude/CLAUDE.md symlink - Hooks->>Claude: Auto-create ~/.claude/project-templates symlink - Hooks->>Dev: ✅ Team configuration enforced - - Dev->>Repo: git commit proceeds - Note over Dev: All future work uses team standards + Note over Dev: All development uses team standards ``` ## Overview diff --git a/src/vteam_shared_configs/data/claude/INSTALL.md b/src/vteam_shared_configs/data/claude/INSTALL.md index 910fa5eb1..873b7ec4a 100644 --- a/src/vteam_shared_configs/data/claude/INSTALL.md +++ b/src/vteam_shared_configs/data/claude/INSTALL.md @@ -4,11 +4,11 @@ Comprehensive setup instructions for vTeam shared Claude Code configurations. ## Quick Setup (Recommended) -Use the automated installation script: +Use the vteam-config CLI tool: ```bash -cd vTeam/shared-configs -./install.sh +pip install vteam-shared-configs +vteam-config install ``` This handles everything automatically including backups and verification. @@ -114,15 +114,13 @@ vTeam/shared-configs/ ### Update Configuration ```bash -cd vTeam/shared-configs -./update.sh +vteam-config update ``` -Pulls latest changes and reinstalls configuration. +Updates to latest team configuration. ### Uninstall ```bash -cd vTeam/shared-configs -./uninstall.sh +vteam-config uninstall ``` Removes configuration and restores backups. diff --git a/vTeam/shared-configs/.github/dependabot.yml b/vTeam/shared-configs/.github/dependabot.yml deleted file mode 100644 index 260902f95..000000000 --- a/vTeam/shared-configs/.github/dependabot.yml +++ /dev/null @@ -1,9 +0,0 @@ -version: 2 -updates: - - package-ecosystem: "github-actions" - directory: "/" - schedule: - interval: "weekly" - commit-message: - prefix: "ci" - include: "scope" \ No newline at end of file diff --git a/vTeam/shared-configs/.gitignore b/vTeam/shared-configs/.gitignore deleted file mode 100644 index 0e32ff597..000000000 --- a/vTeam/shared-configs/.gitignore +++ /dev/null @@ -1,29 +0,0 @@ -# macOS -.DS_Store -.DS_Store? -._* -.Spotlight-V100 -.Trashes -ehthumbs.db -Thumbs.db - -# Editor and IDE -.vscode/ -.idea/ -*.swp -*.swo -*~ - -# Temporary files -*.tmp -*.temp -.cache/ - -# Logs -*.log -logs/ - -# Environment files -.env -.env.local -.env.*.local \ No newline at end of file diff --git a/vTeam/shared-configs/README.md b/vTeam/shared-configs/README.md deleted file mode 100644 index cded650ea..000000000 --- a/vTeam/shared-configs/README.md +++ /dev/null @@ -1,275 +0,0 @@ -# vTeam Shared Claude Configuration - -> Shared Claude Code configuration templates and standards for team development - -## Quick Start - -```bash -# Clone the repository -git clone https://github.com/jeremyeder/vTeam.git -cd vTeam/shared-configs - -# Copy team settings to your Claude configuration -cp .claude/settings.json ~/.claude/settings.json - -# Start using Claude Code with team standards! -# Configuration will be automatically enforced on first Git operation -``` - -## How It Works - -### Configuration Hierarchy - -```mermaid -flowchart TD - A[Developer Action] --> B{Claude Settings Hierarchy} - B --> C[".claude/settings.local.json
🏆 HIGHEST PRIORITY
Personal overrides
(never committed)"] - B --> D[".claude/settings.json
📋 TEAM STANDARDS
vTeam shared config
(in git repository)"] - B --> E["~/.claude/settings.json
⚙️ PERSONAL DEFAULTS
Global user settings
(copied from team)"] - C --> F[Final Configuration] - D --> F - E --> F - F --> G[Claude Code Execution] -``` - -### Developer Workflow - -```mermaid -sequenceDiagram - participant Dev as Developer - participant Repo as vTeam Repository - participant Claude as Claude Code - participant Hooks as Team Hooks - - Dev->>Repo: git clone vTeam repository - Dev->>Claude: cp .claude/settings.json ~/.claude/ - Note over Claude: Team hooks now active - - Dev->>Claude: Start Claude session - Hooks->>Dev: Display configuration status - - Dev->>Repo: First git commit attempt - Hooks->>Claude: enforce-config.sh executes - Hooks->>Claude: Auto-create ~/.claude/CLAUDE.md symlink - Hooks->>Claude: Auto-create ~/.claude/project-templates symlink - Hooks->>Dev: ✅ Team configuration enforced - - Dev->>Repo: git commit proceeds - Note over Dev: All future work uses team standards -``` - -## Overview - -This directory contains shared Claude Code configuration files that provide: - -- **Consistent development standards** across team projects -- **Automatic enforcement** via Claude Code hooks -- **Reusable project templates** for common technologies -- **Developer override flexibility** with clear hierarchy -- **Best practices** for code quality and team collaboration - -## What's Included - -### Core Configuration Files - -- **`.claude/settings.json`** - Team hooks and enforcement rules -- **`.gitignore`** - Comprehensive ignore rules for development files -- **`CLAUDE.md`** - Project-specific Claude Code guidance template -- **`LICENSE`** - MIT license for open source projects -- **`.github/dependabot.yml`** - Automated dependency management - -### Hooks & Enforcement - -- **`hooks/enforce-config.sh`** - Pre-commit configuration enforcement -- **`hooks/status-check.sh`** - Session start status display -- **Automatic symlink management** - Global config and templates -- **Pre-commit/push validation** - Ensures team standards - -### Global Configuration - -- **`claude/global-CLAUDE.md`** - Team-wide Claude Code standards -- **Development principles** - Git workflow, code quality, testing -- **File management standards** - Branch verification, linting requirements -- **Team collaboration guidelines** - GitHub Flow, commit standards - -### Project Templates - -Pre-configured CLAUDE.md templates for: - -- **`python-CLAUDE.md`** - Python projects with uv, black, pytest -- **`javascript-CLAUDE.md`** - JavaScript/Node.js projects -- **`shell-CLAUDE.md`** - Shell script projects with ShellCheck - -## Installation - -### Hook-Based Setup (Recommended) - -```bash -# Copy team hooks to your Claude configuration -cp vTeam/shared-configs/.claude/settings.json ~/.claude/settings.json - -# Configuration will be automatically managed by hooks -# First Git operation will set up symlinks automatically -``` - -### Manual Setup (Alternative) - -```bash -# Create .claude directory -mkdir -p ~/.claude - -# Link global configuration -ln -sf "$(pwd)/claude/global-CLAUDE.md" ~/.claude/CLAUDE.md - -# Link project templates -ln -sf "$(pwd)/claude/project-templates" ~/.claude/ -``` - -## Usage - -### For New Projects - -1. **Copy project template** to your project root as `CLAUDE.md`: - ```bash - cp ~/.claude/project-templates/python-CLAUDE.md myproject/CLAUDE.md - ``` - -2. **Customize for your project** - update architecture, commands, etc. - -3. **Start development** with Claude Code understanding your project context - -### For Existing Projects - -1. **Add CLAUDE.md** using appropriate template as starting point -2. **Update development commands** to match your project's needs -3. **Follow team standards** from global configuration - -## Configuration Management - -### Automatic Updates -- **Hooks enforce latest config** on every Git commit/push -- **No manual updates needed** - configuration stays current -- **Session status checks** display current configuration state - -### Manual Updates (if needed) -```bash -# Pull latest changes -git pull origin main - -# Hooks will automatically update configuration on next Git operation -# Or run manually: -./hooks/enforce-config.sh -``` - -## Developer Customization - -### Configuration Hierarchy (Highest → Lowest Priority) -1. **Local Project Settings** (`.claude/settings.local.json`) - **Your overrides** -2. **Shared Project Settings** (`.claude/settings.json`) - **vTeam standards** -3. **User Global Settings** (`~/.claude/settings.json`) - **Personal defaults** - -### Personal Overrides - -Create `.claude/settings.local.json` in any project for personal customizations: - -```json -{ - "hooks": { - "postToolUse": [ - {"name": "my-logging", "command": "echo 'Tool used'"} - ] - }, - "permissions": { - "allow": ["Bash(my-custom-tool:*)"] - } -} -``` - -### File Structure & Configuration Flow - -```mermaid -graph TB - subgraph "vTeam Repository" - A[".claude/settings.json
Team hooks & standards"] - B["hooks/enforce-config.sh
Pre-commit enforcement"] - C["claude/global-CLAUDE.md
Team-wide standards"] - D["claude/project-templates/
Language templates"] - A --> B - end - - subgraph "Developer Machine" - E["~/.claude/settings.json
Personal global config"] - F["~/.claude/CLAUDE.md
Global team standards"] - G["~/.claude/project-templates/
Shared templates"] - H[".claude/settings.local.json
Personal overrides"] - end - - subgraph "Claude Code" - I["Final Configuration
Merged hierarchy"] - J["Development Actions
Git, linting, etc."] - end - - A -.->|copied once| E - B -.->|creates symlinks| F - B -.->|creates symlinks| G - C -.->|symlinked to| F - D -.->|symlinked to| G - - H -->|highest priority| I - A -->|team standards| I - E -->|personal defaults| I - - I --> J - J -.->|triggers| B -``` - -**What you CAN override:** -- ✅ Add personal hooks and automation -- ✅ Extend permissions for custom tools -- ✅ Personal workflow preferences -- ✅ Custom aliases and shortcuts - -**What gets enforced:** -- 🔒 Pre-commit/push configuration validation -- 🔒 Core team development standards -- 🔒 Quality and linting requirements - -## Team Standards - -### Git Workflow -- **Always work in feature branches** unless explicitly told otherwise -- **Mandatory branch verification** before any file modifications -- **Squash commits** for clean history -- **Follow GitHub Flow** for all repositories - -### Code Quality -- **Run linters locally** before every commit/push -- **Never push** if linters report errors or warnings -- **Use language-specific tooling** (black for Python, prettier for JS, etc.) -- **Always run tests** before pushing changes - -### Development Environment -- **Use virtual environments** for Python projects (prefer `uv` over `pip`) -- **Automate dependency management** with dependabot -- **Document project-specific commands** in project CLAUDE.md - -## Contributing - -To update shared configuration: - -1. **Create feature branch** from main -2. **Make changes** to templates, hooks, or global config -3. **Test changes** locally by copying `.claude/settings.json` -4. **Create pull request** with clear description of changes -5. **Team review** before merging - -## Support - -- **Documentation**: See `claude/INSTALL.md` for detailed setup -- **Issues**: Report problems via GitHub Issues -- **Questions**: Reach out to team leads for guidance - ---- - -**Latest Update**: Hook-based automatic configuration management -**Compatibility**: Claude Code with hierarchical settings and project-specific CLAUDE.md support \ No newline at end of file diff --git a/vTeam/shared-configs/claude/INSTALL.md b/vTeam/shared-configs/claude/INSTALL.md deleted file mode 100644 index 910fa5eb1..000000000 --- a/vTeam/shared-configs/claude/INSTALL.md +++ /dev/null @@ -1,267 +0,0 @@ -# vTeam Claude Configuration Installation Guide - -Comprehensive setup instructions for vTeam shared Claude Code configurations. - -## Quick Setup (Recommended) - -Use the automated installation script: - -```bash -cd vTeam/shared-configs -./install.sh -``` - -This handles everything automatically including backups and verification. - -## Manual Setup - -If you prefer manual installation or need to troubleshoot: - -### 1. Install Global Configuration - -```bash -# Create .claude directory if needed -mkdir -p ~/.claude - -# Link global configuration -ln -sf "$(pwd)/claude/global-CLAUDE.md" ~/.claude/CLAUDE.md - -# Link project templates -ln -sf "$(pwd)/claude/project-templates" ~/.claude/ -``` - -### 2. Add Convenience Aliases (Optional) - -Add to your shell configuration (~/.bashrc, ~/.zshrc, etc.): - -```bash -# vTeam Claude template aliases -alias claude-python="cp ~/.claude/project-templates/python-CLAUDE.md ./CLAUDE.md" -alias claude-js="cp ~/.claude/project-templates/javascript-CLAUDE.md ./CLAUDE.md" -alias claude-shell="cp ~/.claude/project-templates/shell-CLAUDE.md ./CLAUDE.md" - -# Reload shell configuration -source ~/.bashrc # or ~/.zshrc -``` - -## Usage - -### For New Projects -```bash -# Use automated installation aliases -claude-python # Copy Python template -claude-js # Copy JavaScript template -claude-shell # Copy Shell template - -# Or copy manually -cp ~/.claude/project-templates/python-CLAUDE.md ./CLAUDE.md -``` - -### For Existing Projects -1. Choose appropriate template from `~/.claude/project-templates/` -2. Copy to project root as `CLAUDE.md` -3. Customize development commands and architecture for your project - -## Verification - -### Check Installation -```bash -# Verify global config symlink -ls -la ~/.claude/CLAUDE.md - -# Verify project templates symlink -ls -la ~/.claude/project-templates - -# Check project config exists -ls -la ./CLAUDE.md -``` - -### Test Configuration -```bash -# Test with Claude Code -claude --help - -# Check project-specific guidance loads -claude "What are the development commands for this project?" -``` - -## Directory Structure After Setup - -``` -~/.claude/ -├── CLAUDE.md -> /path/to/vTeam/shared-configs/claude/global-CLAUDE.md -└── project-templates/ -> /path/to/vTeam/shared-configs/claude/project-templates/ - -vTeam/shared-configs/ -├── install.sh # Automated installation -├── uninstall.sh # Automated removal -├── update.sh # Update configuration -├── README.md # Team documentation -├── .gitignore # Development ignore rules -├── CLAUDE.md # Project template -├── LICENSE # MIT license -├── .github/dependabot.yml # Dependency automation -└── claude/ - ├── INSTALL.md # This file - ├── global-CLAUDE.md # Global team standards - └── project-templates/ - ├── python-CLAUDE.md - ├── javascript-CLAUDE.md - └── shell-CLAUDE.md -``` - -## Lifecycle Management - -### Update Configuration -```bash -cd vTeam/shared-configs -./update.sh -``` -Pulls latest changes and reinstalls configuration. - -### Uninstall -```bash -cd vTeam/shared-configs -./uninstall.sh -``` -Removes configuration and restores backups. - -## Troubleshooting - -### Symlinks Not Working -```bash -# Check if path is correct -ls -la ~/.claude/CLAUDE.md - -# Recreate symlink -rm ~/.claude/CLAUDE.md -ln -sf "/full/path/to/vTeam/shared-configs/claude/global-CLAUDE.md" ~/.claude/CLAUDE.md -``` - -### Templates Not Found -```bash -# Verify templates directory -ls ~/.claude/project-templates/ - -# Recreate templates symlink -rm ~/.claude/project-templates -ln -sf "/full/path/to/vTeam/shared-configs/claude/project-templates" ~/.claude/ -``` - -### Restore Previous Configuration -```bash -# Find backup directory -ls -la ~/.claude-backup-* - -# Manually restore if needed -cp ~/.claude-backup-YYYYMMDD-HHMMSS/CLAUDE.md ~/.claude/ -``` - -## Detailed Configuration Flow - -### Hook Execution Sequence - -```mermaid -sequenceDiagram - participant Dev as Developer - participant Git as Git Command - participant Hook as enforce-config.sh - participant FS as File System - participant Claude as Claude Code - - Dev->>Git: git commit - Git->>Hook: Pre-tool hook triggers - Hook->>FS: Check ~/.claude/CLAUDE.md symlink - - alt Symlink missing or incorrect - Hook->>FS: Backup existing file - Hook->>FS: Create symlink to vTeam config - Hook->>FS: Create templates symlink - Hook->>Dev: ✅ Configuration updated - else Symlink correct - Hook->>Dev: ✅ Configuration current - end - - Hook->>Git: Allow commit to proceed - Git->>Dev: Commit successful -``` - -### Configuration Hierarchy Deep Dive - -```mermaid -graph LR - subgraph "Configuration Sources" - A["vTeam Repository
.claude/settings.json"] - B["Developer Machine
~/.claude/settings.json"] - C["Project Override
.claude/settings.local.json"] - end - - subgraph "Merge Process" - D["Base Settings
(User Global)"] - E["Team Standards
(Shared Project)"] - F["Personal Overrides
(Local Project)"] - end - - subgraph "Final Result" - G["Active Configuration
in Claude Code"] - end - - B --> D - A --> E - C --> F - - D --> G - E --> G - F --> G - - style F fill:#e1f5fe - style E fill:#f3e5f5 - style D fill:#fff3e0 -``` - -### File System Layout - -```mermaid -graph TD - subgraph "vTeam Repository Structure" - A["vTeam/shared-configs/"] - A --> B[".claude/settings.json"] - A --> C["hooks/enforce-config.sh"] - A --> D["hooks/status-check.sh"] - A --> E["claude/global-CLAUDE.md"] - A --> F["claude/project-templates/"] - F --> G["python-CLAUDE.md"] - F --> H["javascript-CLAUDE.md"] - F --> I["shell-CLAUDE.md"] - end - - subgraph "Developer Machine After Setup" - J["~/.claude/"] - J --> K["settings.json (copied)"] - J --> L["CLAUDE.md → vTeam/shared-configs/claude/global-CLAUDE.md"] - J --> M["project-templates/ → vTeam/shared-configs/claude/project-templates/"] - end - - subgraph "Project-Specific Overrides" - N["project/.claude/"] - N --> O["settings.local.json (optional)"] - end - - B -.->|copied once| K - E -.->|symlinked| L - F -.->|symlinked| M - - style L stroke:#2196F3,stroke-width:3px - style M stroke:#2196F3,stroke-width:3px - style O stroke:#4CAF50,stroke-width:3px -``` - -## Team Benefits - -This setup provides: -- ✅ **Consistent standards** across all team projects -- ✅ **Automatic enforcement** via pre-commit hooks -- ✅ **Developer flexibility** through local overrides -- ✅ **Zero maintenance** - configuration stays current -- ✅ **Version controlled** team standards -- ✅ **Visual workflow** documentation for team collaboration \ No newline at end of file diff --git a/vTeam/shared-configs/claude/README.md b/vTeam/shared-configs/claude/README.md deleted file mode 100644 index da9a679c9..000000000 --- a/vTeam/shared-configs/claude/README.md +++ /dev/null @@ -1,56 +0,0 @@ -# Claude Configuration Management - -This directory contains Claude Code configuration files for managing global and project-specific settings. - -## Structure - -``` -claude/ -├── README.md # This file -├── global-CLAUDE.md # Global configuration (symlink to ~/.claude/CLAUDE.md) -└── project-templates/ # Templates for common project types - ├── python-CLAUDE.md - ├── javascript-CLAUDE.md - └── shell-CLAUDE.md -``` - -## Setup Instructions - -### Global Configuration -```bash -# Create symlink for global Claude configuration -ln -sf ~/repos/dotfiles/claude/global-CLAUDE.md ~/.claude/CLAUDE.md -``` - -### Project-Specific Configuration -For new projects, copy the appropriate template: -```bash -# For Python projects -cp ~/repos/dotfiles/claude/project-templates/python-CLAUDE.md /path/to/project/CLAUDE.md - -# For JavaScript projects -cp ~/repos/dotfiles/claude/project-templates/javascript-CLAUDE.md /path/to/project/CLAUDE.md - -# For shell projects -cp ~/repos/dotfiles/claude/project-templates/shell-CLAUDE.md /path/to/project/CLAUDE.md -``` - -## Best Practices - -1. **Global Configuration**: Use `~/.claude/CLAUDE.md` for settings that apply to ALL projects -2. **Project Configuration**: Use `PROJECT_ROOT/CLAUDE.md` for project-specific commands and context -3. **Version Control**: Keep both global and project configurations in git -4. **Symlinks**: Use symlinks to maintain a single source of truth for global config -5. **Templates**: Use project templates to ensure consistency across similar projects - -## Configuration Hierarchy - -Claude Code follows this configuration hierarchy (highest to lowest priority): -1. Project-specific `CLAUDE.md` (in project root) -2. Global `~/.claude/CLAUDE.md` -3. Built-in Claude Code defaults - -This allows you to: -- Set organization-wide standards in global config -- Override with project-specific requirements -- Maintain consistency across all your projects \ No newline at end of file diff --git a/vTeam/shared-configs/claude/global-CLAUDE.md b/vTeam/shared-configs/claude/global-CLAUDE.md deleted file mode 100644 index be4f7585c..000000000 --- a/vTeam/shared-configs/claude/global-CLAUDE.md +++ /dev/null @@ -1,52 +0,0 @@ -# Global Claude Configuration - -This file contains global Claude Code configuration that applies to all projects. -This should be symlinked to ~/.claude/CLAUDE.md - -## Global Operating Principles - -### Git and Version Control -- **MANDATORY BRANCH VERIFICATION**: ALWAYS check current git branch with `git branch --show-current` as the FIRST action before ANY task that could modify files -- When using git, ALWAYS work in feature branches unless told explicitly otherwise -- **Always squash commits** for clean history -- **Make sure to commit frequently** with succinct commit messages that are immediately useful to the reader - -### Development Standards -- **Always use python virtual environments** to avoid affecting system python packages -- **ALWAYS use uv instead of pip** where possible -- **ALWAYS run markdownlint locally** on any markdown files that you work with -- **ALWAYS automatically resolve any issues reported by linters** -- **ALWAYS try to minimize rework** - -### GitHub Best Practices -- **When setting up GitHub projects, ALWAYS use repository-level projects**. NEVER use user-level projects -- **NEVER change visibility of a github repository** without explicitly being told to do so -- When working with GitHub repositories, always follow GitHub Flow -- **ALWAYS setup dependabot automation** when creating a new github repository -- **Warn if in a GitHub git repo and GitHub Actions integration is not installed** for Claude - -### Code Quality -- **NEVER push if linters report errors or warnings** -- **NEVER push if tests fail** -- **ALWAYS fix issues immediately after running linters** -- **ALWAYS make sure all dates that you use match reality** -- When creating new python applications, you only need to support versions N and N-1 - -### File Management -- **ALWAYS keep your utility/working scripts in git** and well-isolated from the primary codebase -- **NOTHING may ever depend on these scripts** -- **NEVER make changes to files unless you are on the correct feature branch** for those changes -- **NEVER create files unless they're absolutely necessary** for achieving your goal -- **ALWAYS prefer editing an existing file to creating a new one** -- **NEVER proactively create documentation files** (*.md) or README files unless explicitly requested - -### Linting Workflow -**MANDATORY: ALWAYS run the complete linting workflow locally before ANY git push or commit** - -Check the project's CLAUDE.md file for language-specific linting commands and workflows. - -### Testing Best Practices -- **ALWAYS run tests immediately after making implementation changes** -- When fixing API bugs, update both implementation AND corresponding tests in the same commit -- Never assume tests will pass after changing HTTP methods, endpoints, or response formats -- Implementation changes without test updates = guaranteed CI failures \ No newline at end of file diff --git a/vTeam/shared-configs/claude/project-templates/javascript-CLAUDE.md b/vTeam/shared-configs/claude/project-templates/javascript-CLAUDE.md deleted file mode 100644 index 57b2a6b5f..000000000 --- a/vTeam/shared-configs/claude/project-templates/javascript-CLAUDE.md +++ /dev/null @@ -1,90 +0,0 @@ -# CLAUDE.md - JavaScript/Node.js Project - -This file provides guidance to Claude Code (claude.ai/code) when working with this JavaScript project. - -## Development Commands - -### Environment Setup -```bash -# Install dependencies -npm install -# or -yarn install - -# Install development dependencies -npm install --only=dev -``` - -### Code Quality -```bash -# Format code -npm run format -# or -npx prettier --write . - -# Lint code -npm run lint -# or -npx eslint . - -# Fix auto-fixable lint issues -npm run lint:fix -# or -npx eslint . --fix -``` - -### Testing -```bash -# Run all tests -npm test - -# Run tests in watch mode -npm run test:watch - -# Run tests with coverage -npm run test:coverage - -# Run specific test file -npm test -- test-file.test.js -``` - -### Build and Development -```bash -# Start development server -npm run dev - -# Build for production -npm run build - -# Preview production build -npm run preview -``` - -## Project Architecture - - - -## Configuration - -### Node.js Version -- Target: Node.js 18+ (LTS and current) - -### Code Style -- Formatter: Prettier -- Linter: ESLint -- Line length: 80-100 characters -- Semicolons: Consistent with project preference - -### Testing Framework -- Test runner: Jest/Vitest/Mocha (specify which) -- Coverage tool: Built-in coverage -- Test location: tests/ or __tests__/ directory - -## Pre-commit Requirements - -Before any commit, ALWAYS run: -1. `npm run format` (or `npx prettier --write .`) -2. `npm run lint` (or `npx eslint .`) -3. `npm test` - -All commands must pass without errors or warnings. \ No newline at end of file diff --git a/vTeam/shared-configs/claude/project-templates/python-CLAUDE.md b/vTeam/shared-configs/claude/project-templates/python-CLAUDE.md deleted file mode 100644 index b51eeff3f..000000000 --- a/vTeam/shared-configs/claude/project-templates/python-CLAUDE.md +++ /dev/null @@ -1,88 +0,0 @@ -# CLAUDE.md - Python Project - -This file provides guidance to Claude Code (claude.ai/code) when working with this Python project. - -## Development Commands - -### Environment Setup -```bash -# Create virtual environment -uv venv -source .venv/bin/activate # Linux/macOS -# .venv\Scripts\activate # Windows - -# Install dependencies -uv pip install -r requirements.txt -uv pip install -r requirements-dev.txt # If dev requirements exist -``` - -### Code Quality -```bash -# Format code -black . - -# Sort imports -isort . - -# Lint code -flake8 . - -# Type checking (if using mypy) -mypy . -``` - -### Testing -```bash -# Run all tests -python -m pytest - -# Run with coverage -python -m pytest --cov=. - -# Run specific test file -python -m pytest tests/test_example.py - -# Run specific test -python -m pytest tests/test_example.py::test_function_name -``` - -### Package Management -```bash -# Add new dependency -uv add package-name - -# Add development dependency -uv add --dev package-name - -# Update dependencies -uv lock --upgrade -``` - -## Project Architecture - - - -## Configuration - -### Python Version -- Target: Python 3.11+ (latest stable and N-1) - -### Code Style -- Line length: 88 characters (black default) -- Import sorting: isort with black compatibility -- Linting: flake8 with project-specific rules - -### Testing Framework -- Test runner: pytest -- Coverage tool: pytest-cov -- Test location: tests/ directory - -## Pre-commit Requirements - -Before any commit, ALWAYS run: -1. `black .` -2. `isort .` -3. `flake8 .` -4. `python -m pytest` - -All commands must pass without errors or warnings. \ No newline at end of file diff --git a/vTeam/shared-configs/claude/project-templates/shell-CLAUDE.md b/vTeam/shared-configs/claude/project-templates/shell-CLAUDE.md deleted file mode 100644 index a85ff5cad..000000000 --- a/vTeam/shared-configs/claude/project-templates/shell-CLAUDE.md +++ /dev/null @@ -1,98 +0,0 @@ -# CLAUDE.md - Shell Script Project - -This file provides guidance to Claude Code (claude.ai/code) when working with this shell script project. - -## Development Commands - -### Code Quality -```bash -# Lint shell scripts -shellcheck *.sh - -# Lint with specific exclusions (if needed) -shellcheck -e SC1090 -e SC1091 *.sh - -# Format shell scripts (if using shfmt) -shfmt -w *.sh -``` - -### Testing -```bash -# Run tests (if using bats) -bats tests/ - -# Run specific test file -bats tests/test-example.bats - -# Manual testing -bash script-name.sh --help -bash script-name.sh --test-mode -``` - -### Execution -```bash -# Make scripts executable -chmod +x *.sh - -# Run script -./script-name.sh - -# Source script (for functions/aliases) -source script-name.sh -``` - -## Project Architecture - - - -## Configuration - -### Shell Compatibility -- Target: Bash 4.0+ (specify if using other shells) -- Shebang: `#!/usr/bin/env bash` or `#!/bin/bash` - -### Code Style -- Indentation: 2 or 4 spaces (consistent) -- Variable naming: snake_case for local, UPPER_CASE for globals/exports -- Function naming: snake_case -- Error handling: Use `set -euo pipefail` for strict mode - -### Testing Framework -- Test runner: bats-core (or specify alternative) -- Test location: tests/ directory -- Test files: *.bats format - -## Shell Script Best Practices - -### Error Handling -```bash -#!/usr/bin/env bash -set -euo pipefail # Exit on error, undefined vars, pipe failures -``` - -### Function Structure -```bash -function_name() { - local arg1="$1" - local arg2="${2:-default_value}" - - # Function body - echo "Processing: $arg1" -} -``` - -### Variable Quoting -```bash -# Always quote variables -echo "$variable" -cp "$source_file" "$destination_file" -``` - -## Pre-commit Requirements - -Before any commit, ALWAYS run: -1. `shellcheck *.sh` (or with project-specific exclusions) -2. Manual testing of modified scripts -3. Verify executable permissions are set correctly - -All ShellCheck warnings must be resolved or explicitly excluded with comments. \ No newline at end of file diff --git a/vTeam/shared-configs/hooks/enforce-config.sh b/vTeam/shared-configs/hooks/enforce-config.sh deleted file mode 100755 index a91d90b88..000000000 --- a/vTeam/shared-configs/hooks/enforce-config.sh +++ /dev/null @@ -1,115 +0,0 @@ -#!/bin/bash -set -euo pipefail - -# vTeam Shared Configuration Enforcement Script -# Ensures latest vTeam configuration is active before Git operations - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -SHARED_CONFIGS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" -CLAUDE_DIR="$HOME/.claude" - -# Colors for output -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -BLUE='\033[0;34m' -NC='\033[0m' # No Color - -info() { - echo -e "${GREEN}[vTeam]${NC} $1" -} - -warn() { - echo -e "${YELLOW}[vTeam]${NC} $1" -} - -error() { - echo -e "${RED}[vTeam]${NC} $1" -} - -step() { - echo -e "${BLUE}[vTeam]${NC} $1" -} - -# Check if we're in a vTeam repository -if [[ ! -d "$SHARED_CONFIGS_DIR" ]]; then - error "vTeam shared-configs directory not found" - exit 1 -fi - -# Create .claude directory if it doesn't exist -if [[ ! -d "$CLAUDE_DIR" ]]; then - step "Creating ~/.claude directory" - mkdir -p "$CLAUDE_DIR" -fi - -# Function to check if symlink is up to date -check_symlink() { - local target="$1" - local link="$2" - - if [[ ! -L "$link" ]]; then - return 1 # Not a symlink - fi - - local current_target - current_target="$(readlink "$link")" - - if [[ "$current_target" != "$target" ]]; then - return 1 # Points to wrong target - fi - - return 0 # Symlink is correct -} - -# Check and update global configuration -GLOBAL_TARGET="$SHARED_CONFIGS_DIR/claude/global-CLAUDE.md" -GLOBAL_LINK="$CLAUDE_DIR/CLAUDE.md" - -if ! check_symlink "$GLOBAL_TARGET" "$GLOBAL_LINK"; then - step "Updating global CLAUDE.md configuration" - - # Backup existing file if it's not a symlink - if [[ -f "$GLOBAL_LINK" ]] && [[ ! -L "$GLOBAL_LINK" ]]; then - BACKUP_NAME="CLAUDE.md.backup-$(date +%Y%m%d-%H%M%S)" - warn "Backing up existing $GLOBAL_LINK to $BACKUP_NAME" - mv "$GLOBAL_LINK" "$CLAUDE_DIR/$BACKUP_NAME" - fi - - # Remove existing link if present - [[ -L "$GLOBAL_LINK" ]] && rm "$GLOBAL_LINK" - - # Create new symlink - ln -sf "$GLOBAL_TARGET" "$GLOBAL_LINK" - info "✓ Global configuration linked" -fi - -# Check and update project templates -TEMPLATES_TARGET="$SHARED_CONFIGS_DIR/claude/project-templates" -TEMPLATES_LINK="$CLAUDE_DIR/project-templates" - -if ! check_symlink "$TEMPLATES_TARGET" "$TEMPLATES_LINK"; then - step "Updating project templates" - - # Backup existing directory if it's not a symlink - if [[ -d "$TEMPLATES_LINK" ]] && [[ ! -L "$TEMPLATES_LINK" ]]; then - BACKUP_NAME="project-templates.backup-$(date +%Y%m%d-%H%M%S)" - warn "Backing up existing $TEMPLATES_LINK to $BACKUP_NAME" - mv "$TEMPLATES_LINK" "$CLAUDE_DIR/$BACKUP_NAME" - fi - - # Remove existing link if present - [[ -L "$TEMPLATES_LINK" ]] && rm "$TEMPLATES_LINK" - - # Create new symlink - ln -sf "$TEMPLATES_TARGET" "$TEMPLATES_LINK" - info "✓ Project templates linked" -fi - -# Verify installation -if [[ -L "$GLOBAL_LINK" ]] && [[ -L "$TEMPLATES_LINK" ]]; then - info "✓ vTeam configuration is active and up to date" -else - error "Configuration verification failed" - exit 1 -fi \ No newline at end of file diff --git a/vTeam/shared-configs/hooks/status-check.sh b/vTeam/shared-configs/hooks/status-check.sh deleted file mode 100755 index e38469e69..000000000 --- a/vTeam/shared-configs/hooks/status-check.sh +++ /dev/null @@ -1,76 +0,0 @@ -#!/bin/bash -set -euo pipefail - -# vTeam Configuration Status Check Script -# Displays current vTeam configuration status on Claude session start - -SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -SHARED_CONFIGS_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" -CLAUDE_DIR="$HOME/.claude" - -# Colors for output -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -BLUE='\033[0;34m' -NC='\033[0m' # No Color - -info() { - echo -e "${GREEN}[vTeam]${NC} $1" -} - -warn() { - echo -e "${YELLOW}[vTeam]${NC} $1" -} - -status() { - echo -e "${BLUE}[vTeam]${NC} $1" -} - -# Only show status if we're in a vTeam repository -if [[ ! -d "$SHARED_CONFIGS_DIR" ]]; then - exit 0 # Silent exit if not in vTeam repo -fi - -# Check configuration status -GLOBAL_LINK="$CLAUDE_DIR/CLAUDE.md" -TEMPLATES_LINK="$CLAUDE_DIR/project-templates" - -echo -status "=== vTeam Configuration Status ===" - -# Check global config -if [[ -L "$GLOBAL_LINK" ]]; then - TARGET=$(readlink "$GLOBAL_LINK") - if [[ "$TARGET" == "$SHARED_CONFIGS_DIR/claude/global-CLAUDE.md" ]]; then - info "✓ Global configuration: Active" - else - warn "⚠ Global configuration: Linked to different source" - fi -else - warn "⚠ Global configuration: Not linked (will be auto-configured on first Git operation)" -fi - -# Check project templates -if [[ -L "$TEMPLATES_LINK" ]]; then - TARGET=$(readlink "$TEMPLATES_LINK") - if [[ "$TARGET" == "$SHARED_CONFIGS_DIR/claude/project-templates" ]]; then - info "✓ Project templates: Active" - else - warn "⚠ Project templates: Linked to different source" - fi -else - warn "⚠ Project templates: Not linked (will be auto-configured on first Git operation)" -fi - -# Check for local overrides -LOCAL_SETTINGS=".claude/settings.local.json" -if [[ -f "$LOCAL_SETTINGS" ]]; then - info "✓ Local overrides: Present in $LOCAL_SETTINGS" -else - status "ℹ Local overrides: None (create $LOCAL_SETTINGS for personal customizations)" -fi - -echo -status "Team standards will be automatically enforced on Git operations" -status "Use '.claude/settings.local.json' for personal overrides" -echo \ No newline at end of file