daffy0208__ai-dev-standards/docs/INSTALLATION-AND-UPDATES.md

Installation and Update Guide

Complete guide for installing, updating, and maintaining ai-dev-standards in your projects.

Quick Start

# Clone ai-dev-standards
cd ~
git clone https://github.com/your-org/ai-dev-standards.git

# Initialize a project
cd /path/to/your/project
bash ~/ai-dev-standards/setup-project.sh

Installation Features

1. Version Tracking ✅

Every installation now tracks:

• ai-dev-standards version
• Installation path
• Last sync date

Location: .ai-dev.json

{
  "version": "3.0.0",
  "aiDevStandardsRoot": "/home/user/ai-dev-standards",
  "lastSync": "2025-01-04T12:00:00Z",
  "installed": {
    "skills": [...],
    "mcps": [...],
    "tools": [...]
  }
}

2. Automatic Hooks Installation ✅

Setup automatically installs:

• .claude/hooks/ - Skill activation hooks
• .claude/skills/skill-rules.json - 64 skill activation rules
• .claude/settings.json - Hook configuration
• Hook dependencies (npm install)

Result: Skills activate automatically with 95%+ accuracy

3. Health Check System ✅

Run ai-dev doctor to check:

• Node.js version (>=18)
• Dependencies status
• ai-dev-standards installation
• Hooks configuration
• Skill activation rules
• Git status
• Environment variables

Auto-fix: ai-dev doctor --fix-all

4. Flexible Installation Paths ✅

No longer requires ~/ai-dev-standards:

• Stores actual path in .ai-dev.json
• Resolves paths dynamically
• Supports multiple installations
• Works with any location

5. Post-Install Verification ✅

After setup completes:

• Health check runs automatically
• Displays installation summary
• Shows skill count and hooks status
• Lists helpful commands

Commands

Check for Updates

ai-dev check-updates

Shows:

• Current version vs remote version
• Commits behind
• Recent changes
• Update recommendation

Example output:

🔍 Checking for updates...

📊 Version Info:
  Local version:  3.0.0 (abc1234)
  Remote version: 3.1.0 (def5678)

⚠️  You are 5 commits behind

💡 Run ai-dev self-update to update

📝 Recent changes:
  • Added specialized agents
  • Optimized skill activation
  • Fixed registry issues

Update ai-dev-standards

ai-dev self-update

What it does:

1. Checks for local changes
2. Stashes changes if --force
3. Pulls latest from Git
4. Re-installs CLI
5. Updates hooks
6. Shows what's new

Options:

• --force - Update even with local changes

Example:

# Safe update (fails if local changes)
ai-dev self-update

# Force update (stashes local changes)
ai-dev self-update --force

Health Check

ai-dev doctor

Checks 11 areas:

1. Node.js version
2. Package manager (npm)
3. package.json validity
4. Dependencies status
5. Git status
6. Environment variables
7. TypeScript config
8. Linting setup
9. ai-dev-standards installation
10. Hooks configuration
11. Skill activation rules

Auto-fix issues:

ai-dev doctor --fix-all

Verbose output:

ai-dev doctor --verbose

Project Sync

ai-dev sync

Updates:

• Latest skills list
• MCP configurations
• Registry updates
• Documentation sync

Installation Paths

Flexible Locations

ai-dev-standards can be installed anywhere:

# Standard location
~/ai-dev-standards/

# Custom location
/opt/ai-dev-standards/

# Project-specific
./vendor/ai-dev-standards/

How it works:

1. setup-project.sh detects installation path
2. Saves to .ai-dev.json as aiDevStandardsRoot
3. Commands resolve paths dynamically

Finding Installation

# Check .ai-dev.json
cat .ai-dev.json | grep aiDevStandardsRoot

# Or use jq
jq -r '.aiDevStandardsRoot' .ai-dev.json

Upgrade from Old Installation

If you have an old installation without version tracking:

# 1. Re-run setup
bash ~/ai-dev-standards/setup-project.sh

# 2. Verify upgrade
ai-dev doctor

# 3. Check version
jq -r '.version' .ai-dev.json

What gets upgraded:

• Adds version to .ai-dev.json
• Adds installation path tracking
• Installs hooks if missing
• Updates to latest patterns

Hooks Installation

Automatic Installation

setup-project.sh now installs hooks automatically:

.claude/
├── hooks/
│   ├── skill-activation-prompt.ts
│   ├── skill-activation-prompt.sh
│   ├── generate-skill-rules.cjs
│   ├── package.json
│   ├── tsconfig.json
│   └── node_modules/
├── skills/
│   └── skill-rules.json (64 skills)
└── settings.json

Manual Installation

If hooks aren't installed:

# Copy hooks
mkdir -p .claude/hooks .claude/skills
cp -r ~/ai-dev-standards/.claude/hooks/* .claude/hooks/
cp ~/ai-dev-standards/.claude/skills/skill-rules.json .claude/skills/
cp ~/ai-dev-standards/.claude/settings.json .claude/

# Install dependencies
cd .claude/hooks
npm install

# Make executable
chmod +x *.sh

Verify Hooks

# Check installation
ai-dev doctor

# Test skill activation
ls .claude/skills/skill-rules.json

# Verify executable
ls -la .claude/hooks/*.sh

Troubleshooting

Issue: "ai-dev command not found"

Solution:

cd ~/ai-dev-standards/CLI
npm install
npm link

Issue: "Version not tracked"

Solution:

# Add version manually
jq '. + {version: "3.0.0", aiDevStandardsRoot: "'$HOME'/ai-dev-standards"}' \
  .ai-dev.json > .ai-dev.json.tmp && mv .ai-dev.json.tmp .ai-dev.json

Issue: "Hooks not working"

Solution:

# Re-install hooks
bash ~/ai-dev-standards/setup-project.sh

# Or manually
cd .claude/hooks
npm install
chmod +x *.sh

Issue: "Local changes prevent update"

Solution:

# Option 1: Commit changes
cd ~/ai-dev-standards
git add .
git commit -m "Local changes"
ai-dev self-update

# Option 2: Force update (stashes changes)
ai-dev self-update --force

# Option 3: Reset to remote
cd ~/ai-dev-standards
git reset --hard origin/main

Issue: "skill-rules.json missing"

Solution:

# Regenerate
cd .claude/hooks
node generate-skill-rules.cjs

# Or copy from ai-dev-standards
cp ~/ai-dev-standards/.claude/skills/skill-rules.json .claude/skills/

Best Practices

Regular Updates

# Weekly check
ai-dev check-updates

# Monthly update
ai-dev self-update
ai-dev sync

Before Important Work

# Health check
ai-dev doctor

# Update if needed
ai-dev self-update

# Sync resources
ai-dev sync

After Cloning Project

# Check installation
ai-dev doctor

# Install if missing
bash ~/ai-dev-standards/setup-project.sh

Multiple Projects

Each project tracks its own version:

# Project A
cd ~/projects/project-a
jq -r '.version' .ai-dev.json  # 3.0.0

# Project B
cd ~/projects/project-b
jq -r '.version' .ai-dev.json  # 3.1.0

# Update all
for dir in ~/projects/*/; do
  cd "$dir"
  ai-dev sync
done

Migration Guide

From v2.x to v3.x

What's new:

• Version tracking
• Automatic hooks installation
• Health check system
• Flexible paths
• Self-update command

Migration steps:

# 1. Update ai-dev-standards
cd ~/ai-dev-standards
git pull origin main

# 2. Re-install CLI
cd CLI
npm install
npm link

# 3. Update projects
cd /path/to/project
bash ~/ai-dev-standards/setup-project.sh

# 4. Verify
ai-dev doctor

Performance

All operations are optimized:

Check Updates

• < 2 seconds
• Only fetches Git metadata
• Minimal network usage

Self Update

• < 10 seconds (typical)
• Parallel operations
• Incremental updates only

Health Check

• < 3 seconds
• Cached checks
• Parallel validation

Hooks Installation

• < 5 seconds
• Minimal dependencies
• Silent npm install

Security

Update Safety

ai-dev self-update is safe:

• Checks for local changes first
• Creates backup with --force
• Pulls from trusted Git remote
• No arbitrary code execution

Installation Verification

setup-project.sh is transparent:

• All paths are visible
• No hidden operations
• Standard npm/git commands
• Open source and auditable

Advanced Usage

Custom Installation Location

# Install to custom location
git clone https://github.com/your-org/ai-dev-standards.git /opt/ai-dev-standards

# Setup project
cd /path/to/project
bash /opt/ai-dev-standards/setup-project.sh

# Verify path
jq -r '.aiDevStandardsRoot' .ai-dev.json
# Output: /opt/ai-dev-standards

CI/CD Integration

# .github/workflows/setup.yml
- name: Setup ai-dev-standards
  run: |
    git clone https://github.com/your-org/ai-dev-standards.git ~/ai-dev-standards
    bash ~/ai-dev-standards/setup-project.sh
    ai-dev doctor

- name: Check for updates
  run: ai-dev check-updates --silent

Docker Integration

# Dockerfile
FROM node:18

# Install ai-dev-standards
RUN git clone https://github.com/your-org/ai-dev-standards.git /opt/ai-dev-standards

# Setup in project
WORKDIR /app
COPY . .
RUN bash /opt/ai-dev-standards/setup-project.sh

# Health check
RUN ai-dev doctor --fix-all

Support

Issues:

• Run ai-dev doctor --verbose
• Check .ai-dev.json for configuration
• Verify hooks with ls -la .claude/hooks/*.sh

Questions:

• See docs/INDEX.md
• Check README.md
• Review SKILL-AUTO-ACTIVATION.md

Updates:

• Check CHANGELOG.md
• Run ai-dev check-updates
• Follow repository releases

---

Summary

5 Major Improvements:

1. ✅ Version Tracking - Always know what version you have
2. ✅ Auto Hooks Install - Skills activate automatically (95%+ accuracy)
3. ✅ Health Check - ai-dev doctor verifies everything
4. ✅ Flexible Paths - Install anywhere, no hardcoded paths
5. ✅ Post-Install Verification - Automatic health check after setup

Key Commands:

• ai-dev check-updates - Check for updates
• ai-dev self-update - Update to latest
• ai-dev doctor - Health check
• ai-dev sync - Sync resources
• bash setup-project.sh - Initial setup

Result: Easy installation, simple updates, always healthy!