ai-playbook 1.0.0

package/bin/cli.js

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const playbookDir = path.join(__dirname, '..');
+const homeDir = process.env.HOME || process.env.USERPROFILE;
+
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  cyan: '\x1b[36m',
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+function getFolderSize(dir) {
+  try {
+    const result = execSync(`du -sh "${dir}" 2>/dev/null | cut -f1`, { encoding: 'utf-8' });
+    return result.trim();
+  } catch {
+    return 'N/A';
+  }
+}
+
+function countFiles(dir, extension = null) {
+  try {
+    let cmd = `find "${dir}" -type f`;
+    if (extension) {
+      cmd += ` -name "*.${extension}"`;
+    }
+    cmd += ' | wc -l';
+    const result = execSync(cmd, { encoding: 'utf-8' });
+    return parseInt(result.trim());
+  } catch {
+    return 0;
+  }
+}
+
+function printHeader() {
+  log('', 'cyan');
+  log('╔════════════════════════════════════════╗', 'cyan');
+  log('║      AI PLAYBOOK - CLI TOOL            ║', 'cyan');
+  log('╚════════════════════════════════════════╝', 'cyan');
+  log('', 'cyan');
+}
+
+function setupCommand() {
+  log('Setting up AI Playbook...', 'yellow');
+  log('', 'yellow');
+
+  try {
+    execSync(`bash "${playbookDir}/setup.sh"`, { stdio: 'inherit' });
+    log('\nSetup complete!', 'green');
+  } catch (error) {
+    log(`Setup failed: ${error.message}`, 'red');
+    process.exit(1);
+  }
+}
+
+function listCommand() {
+  printHeader();
+
+  const folders = [
+    { name: 'agents', desc: 'Specialized AI agents (15 agents)' },
+    { name: 'commands', desc: 'Development commands (16 commands)' },
+    { name: 'hooks', desc: 'Automation hooks (15+ hooks)' },
+    { name: 'prompts', desc: 'Prompt templates (12 prompts)' },
+    { name: 'skills', desc: 'Domain expertise and skills' },
+    { name: 'patterns', desc: 'Reusable solution patterns' },
+    { name: 'roles', desc: 'Engineering role definitions' },
+    { name: 'context', desc: 'Communication context' },
+    { name: 'knowledge', desc: 'Reference knowledge' },
+  ];
+
+  log('📁 Available Folders:\n', 'blue');
+
+  folders.forEach((folder) => {
+    const dir = path.join(playbookDir, folder.name);
+    const exists = fs.existsSync(dir);
+    const size = exists ? getFolderSize(dir) : 'N/A';
+    const files = exists ? countFiles(dir, 'md') : 0;
+
+    if (exists) {
+      log(`  ✓ ${folder.name.padEnd(15)} - ${folder.desc.padEnd(35)} (${size}, ${files} files)`, 'green');
+    } else {
+      log(`  ✗ ${folder.name.padEnd(15)} - ${folder.desc}`, 'yellow');
+    }
+  });
+
+  log('\n📦 Sync Locations:\n', 'blue');
+
+  const locations = [
+    { name: 'Claude Code', path: `${homeDir}/.claude/playbook` },
+    { name: 'GitHub CLI (Codex)', path: `${homeDir}/.config/gh/extensions/playbook` },
+    { name: 'Warp Terminal', path: `${homeDir}/Library/Application Support/Warp/playbook` },
+    { name: 'Cursor Editor', path: `${homeDir}/.config/Cursor/playbook` },
+    { name: 'VS Code', path: `${homeDir}/.vscode-playbook` },
+    { name: 'Aider CLI', path: `${homeDir}/.aider/playbook` },
+    { name: 'Continue IDE', path: `${homeDir}/.continue/playbook` },
+    { name: 'Ollama', path: `${homeDir}/.ollama/playbook` },
+    { name: 'Generic Location', path: `${homeDir}/.ai-playbook` },
+  ];
+
+  locations.forEach((loc) => {
+    const exists = fs.existsSync(loc.path);
+    if (exists) {
+      log(`  ✓ ${loc.name.padEnd(20)} → ${loc.path}`, 'green');
+    } else {
+      log(`  ○ ${loc.name.padEnd(20)} → ${loc.path}`, 'yellow');
+    }
+  });
+
+  log('', 'cyan');
+}
+
+function helpCommand() {
+  printHeader();
+
+  log('Usage: ai-playbook [command]\n', 'cyan');
+
+  log('Commands:\n', 'blue');
+  log('  setup           Sync playbook to all AI tool directories', 'cyan');
+  log('  list            Show playbook contents and sync locations', 'cyan');
+  log('  help            Show this help message', 'cyan');
+
+  log('\nInstallation:\n', 'blue');
+  log('  npm install -g ai-playbook', 'cyan');
+  log('  ai-playbook setup\n', 'cyan');
+
+  log('Usage in Tools:\n', 'blue');
+  log('  • Claude Code: Reference ~/.claude/playbook', 'cyan');
+  log('  • VS Code: Reference ~/.vscode-playbook', 'cyan');
+  log('  • Cursor: Reference ~/.config/Cursor/playbook', 'cyan');
+  log('  • Warp: Reference ~/Library/Application Support/Warp/playbook', 'cyan');
+  log('  • Generic: Reference ~/.ai-playbook\n', 'cyan');
+
+  log('Examples:\n', 'blue');
+  log('  ai-playbook setup    # Sync to all tools', 'cyan');
+  log('  ai-playbook list     # Show structure', 'cyan');
+  log('  ai-playbook help     # Show this message\n', 'cyan');
+
+  log('Documentation:\n', 'blue');
+  log('  README: ', 'cyan');
+  log('    https://github.com/srikanthkanteti/ai-playbook', 'cyan');
+  log('  Playbook Location: ', 'cyan');
+  log(`    ${playbookDir}\n`, 'cyan');
+}
+
+function versionCommand() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(playbookDir, 'package.json'), 'utf-8'));
+  log(`AI Playbook v${pkg.version}`, 'cyan');
+}
+
+const command = process.argv[2] || 'help';
+
+switch (command) {
+  case 'setup':
+    setupCommand();
+    break;
+  case 'list':
+    listCommand();
+    break;
+  case 'help':
+  case '-h':
+  case '--help':
+    helpCommand();
+    break;
+  case 'version':
+  case '-v':
+  case '--version':
+    versionCommand();
+    break;
+  default:
+    log(`Unknown command: ${command}`, 'yellow');
+    log('Run "ai-playbook help" for usage information\n', 'yellow');
+    process.exit(1);
+}

package/commands/README.md

@@ -0,0 +1,266 @@
+# Commands
+
+Reusable command recipes and workflow definitions for development, validation, and operations.
+
+## Overview
+
+Commands are automation patterns for common development tasks. Each command is self-contained and can be:
+- Invoked individually
+- Chained together
+- Integrated into CI/CD
+- Run locally or in automation
+
+## Command Categories
+
+### Development Commands
+
+Local development setup and iteration:
+- `setup` - Initialize development environment
+- `dev` - Start development server
+- `build` - Build project artifacts
+- `watch` - Watch files and rebuild on change
+- `clean` - Clean build artifacts
+
+### Testing Commands
+
+Quality validation:
+- `test` - Run all tests
+- `test-unit` - Run unit tests only
+- `test-integration` - Run integration tests
+- `test-coverage` - Run tests with coverage report
+- `test-watch` - Watch and run tests on file change
+
+### Code Quality Commands
+
+Code standards and analysis:
+- `lint` - Run linters
+- `format` - Format code
+- `type-check` - Run type checker
+- `analyze` - Static analysis
+- `audit` - Dependency audit
+
+### Validation Commands
+
+Pre-commit and pre-push validation:
+- `validate` - Run all validation checks
+- `validate-security` - Security checks
+- `validate-performance` - Performance checks
+- `validate-types` - Type checking
+
+### Deployment Commands
+
+Release and deployment:
+- `release` - Create release
+- `deploy-staging` - Deploy to staging
+- `deploy-prod` - Deploy to production
+- `rollback` - Rollback deployment
+
+### Utility Commands
+
+Helper tasks:
+- `deps` - Check and update dependencies
+- `migrate` - Run database migrations
+- `seed` - Seed database
+- `reset` - Reset environment
+
+## Command Format
+
+Each command file contains:
+
+```
+# Command Name
+
+## Purpose
+What this command does and when to use it
+
+## Usage
+How to invoke the command
+
+## Prerequisites
+What needs to be installed/configured
+
+## Steps
+Step-by-step what the command does
+
+## Outputs
+What the command produces
+
+## Examples
+Examples of using the command
+
+## Troubleshooting
+Common issues and solutions
+```
+
+## Using Commands
+
+### Run a Single Command
+
+```bash
+source commands/[command-name].sh
+```
+
+### Chain Commands
+
+```bash
+source commands/setup.sh && source commands/dev.sh
+```
+
+### In CI/CD
+
+```yaml
+- name: Run validation
+  run: source commands/validate.sh
+```
+
+## Command Dependencies
+
+Some commands depend on others:
+
+```
+setup
+  ├─ dev (requires setup)
+  ├─ build (requires setup)
+  └─ test (requires setup)
+
+validate
+  ├─ lint (requires setup)
+  ├─ type-check (requires setup)
+  └─ test (requires setup)
+
+release
+  ├─ validate
+  ├─ build
+  └─ deploy-staging
+```
+
+## Creating New Commands
+
+### Command Template
+
+```bash
+#!/bin/bash
+# [command-name].sh
+# Purpose: [describe what this does]
+
+set -e  # Exit on error
+
+# Validate prerequisites
+if ! command -v [tool] &> /dev/null; then
+    echo "Error: [tool] not found"
+    exit 1
+fi
+
+# Main command steps
+echo "Starting [command-name]..."
+
+# Step 1
+echo "Step 1: ..."
+
+# Step 2
+echo "Step 2: ..."
+
+echo "[command-name] complete!"
+```
+
+### Best Practices
+
+- ✅ Use `set -e` to exit on error
+- ✅ Validate prerequisites exist
+- ✅ Provide clear progress messages
+- ✅ Return meaningful exit codes
+- ✅ Clean up on failure
+- ✅ Support dry-run mode
+- ✅ Document prerequisites
+- ✅ Keep commands focused
+
+## Common Patterns
+
+### Error Handling
+
+```bash
+if ! [command]; then
+    echo "Error: [message]" >&2
+    exit 1
+fi
+```
+
+### Conditional Steps
+
+```bash
+if [ "$SKIP_TESTS" != "true" ]; then
+    echo "Running tests..."
+    # run tests
+fi
+```
+
+### Dry Run Support
+
+```bash
+if [ "$DRY_RUN" = "true" ]; then
+    echo "[Would execute: command]"
+else
+    command
+fi
+```
+
+### Progress Output
+
+```bash
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Step: [description]"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+```
+
+## Environment Variables
+
+Common variables for commands:
+
+- `DRY_RUN=true` - Show what would run without executing
+- `SKIP_TESTS=true` - Skip test steps
+- `VERBOSE=true` - Show more output
+- `CI=true` - Running in CI environment
+- `ENVIRONMENT=staging|prod` - Target environment
+
+## Integration with Tools
+
+### With Make
+
+```makefile
+.PHONY: setup
+setup:
+	source commands/setup.sh
+
+.PHONY: validate
+validate:
+	source commands/validate.sh
+```
+
+### With npm/package.json
+
+```json
+{
+  "scripts": {
+    "setup": "source commands/setup.sh",
+    "dev": "source commands/dev.sh",
+    "test": "source commands/test.sh",
+    "validate": "source commands/validate.sh"
+  }
+}
+```
+
+### With GitHub Actions
+
+```yaml
+- name: Setup
+  run: source commands/setup.sh
+
+- name: Validate
+  run: source commands/validate.sh
+```
+
+## Version
+
+**Version:** 1.0
+
+Commands are templates for common workflows. Customize for your project's specific needs.

package/commands/build.md

@@ -0,0 +1,135 @@
+# build Command
+
+**Purpose:** Build project artifacts for production  
+**Usage:** `npm run build`  
+**Trigger:** Release preparation
+
+## Description
+
+Compiles and optimizes code for production deployment. Validates quality and tests before building.
+
+## Build Process
+
+1. Validate code quality
+2. Run tests
+3. Compile/transpile code
+4. Optimize assets
+5. Generate build artifacts
+6. Verify build size
+
+## Success Criteria
+
+✓ Lint passes  
+✓ Tests pass  
+✓ Build compiles  
+✓ Assets optimized  
+✓ No errors  
+✓ Output generated  
+
+## Build Artifacts
+
+| Framework | Output |
+|---|---|
+| Next.js | `.next/` directory |
+| React | `build/` directory |
+| Vue | `dist/` directory |
+| Node | `dist/` or `build/` |
+
+## Configuration
+
+- `webpack.config.js` - Webpack config
+- `.babelrc` - Babel config
+- `tsconfig.json` - TypeScript config
+- `vite.config.js` - Vite config (if used)
+
+## Running Build
+
+```bash
+# Production build
+npm run build
+
+# Development build
+npm run build:dev
+
+# With analysis
+npm run build:analyze
+
+# Watch mode
+npm run build:watch
+```
+
+## Build Verification
+
+After build, check:
+- **Size:** artifacts/.size file
+- **Output:** dist/ or build/ exists
+- **Errors:** None in logs
+- **Assets:** CSS, JS minified
+
+## Performance
+
+Typical build times:
+- Small project: 10-30 seconds
+- Medium project: 30-60 seconds
+- Large project: 1-3 minutes
+
+## Optimization
+
+Build includes:
+- Code minification
+- Tree shaking
+- Code splitting
+- Asset compression
+- Sourcemap generation
+
+## Failure Handling
+
+| Error | Solution |
+|---|---|
+| Compilation error | Fix TypeScript/Babel errors |
+| Missing file | Check imports, paths |
+| Build too large | Enable code splitting |
+| Memory exceeded | Increase Node memory |
+
+## Environment Variables
+
+- `CI=true` - CI mode (stricter)
+- `ANALYZE=true` - Bundle analysis
+- `SKIP_TESTS=true` - Skip tests (not recommended)
+
+## Docker Build
+
+If using Docker:
+```bash
+docker build -t myapp:latest .
+```
+
+## Deployment After Build
+
+1. Run build successfully
+2. Commit if needed (or use CI artifact)
+3. Deploy build artifact
+4. Verify in staging
+5. Deploy to production
+
+## Related Commands
+
+- `dev` - Development server
+- `test` - Run tests
+- `validate` - All checks
+- `deploy-staging` - Deploy build
+
+## CI/CD Integration
+
+- Build triggered on commit
+- Artifact stored in CI
+- Deploy pulls from artifact
+- Build cached for performance
+
+## Notes
+
+- Always build before deploying
+- Test build locally first
+- Build artifacts are not source code
+- Keep build artifacts (.gitignore)
+- Production build is immutable

package/commands/clean.md

@@ -0,0 +1,126 @@
+# clean Command
+
+**Purpose:** Clean build artifacts and temporary files  
+**Usage:** `npm run clean`  
+**Trigger:** Reset environment, free disk space
+
+## Description
+
+Removes generated files and temporary directories, resetting project to clean state.
+
+## Directories Removed
+
+| Directory | Contents |
+|---|---|
+| `dist/` | Compiled output |
+| `build/` | Build artifacts |
+| `.next/` | Next.js cache |
+| `.cache/` | Build cache |
+| `node_modules/` | (optional) Dependencies |
+| `coverage/` | Test reports |
+| `__pycache__/` | Python cache |
+
+## Files Removed
+
+- Compiled files (`.js` from `.ts`)
+- Cache files (`.swp`, `.swo`)
+- OS files (`.DS_Store`)
+- Log files (`*.log`)
+- Temporary files
+
+## Success Criteria
+
+✓ Build artifacts deleted  
+✓ Cache cleared  
+✓ Logs removed  
+✓ Disk space freed  
+
+## Running Clean
+
+```bash
+# Interactive (asks for confirmation)
+npm run clean
+
+# Force without prompt
+FORCE=true npm run clean
+
+# Only specific directories
+rm -rf dist/
+rm -rf coverage/
+
+# With Docker
+docker system prune -f
+```
+
+## What's Safe to Delete
+
+✓ `dist/` - Always safe
+✓ `build/` - Always safe
+✓ `coverage/` - Always safe
+✓ `.cache/` - Always safe
+✓ `__pycache__/` - Always safe
+
+## What's Dangerous
+
+✗ `node_modules/` - Need reinstall
+✗ `.env` - Configuration lost
+✗ `src/` - Source code!
+✗ `.git/` - Repository!
+
+## Disk Space Impact
+
+Typical sizes freed:
+- `node_modules/`: 200-500MB
+- `dist/`: 10-50MB
+- `.cache/`: 10-100MB
+- `coverage/`: 1-10MB
+
+## After Clean
+
+After cleaning, you need to:
+1. Reinstall dependencies: `npm install`
+2. Rebuild: `npm run build`
+3. Restart dev server: `npm run dev`
+
+## When to Clean
+
+- Disk space needed
+- Mysterious build errors
+- Switching git branches
+- Large files accumulating
+- Performance issues
+
+## Related Commands
+
+- `setup` - Reinitialize environment
+- `build` - Rebuild artifacts
+- `dev` - Restart dev server
+
+## Safety
+
+- Confirmation required (interactive)
+- Safe to run multiple times
+- Doesn't delete source code
+- Doesn't delete configuration
+- Can use `git clean` for git files
+
+## Advanced Cleaning
+
+```bash
+# Remove untracked files
+git clean -fd
+
+# Remove node_modules only
+rm -rf node_modules/ && npm install
+
+# Docker cleanup
+docker system prune -a --volumes
+```
+
+## Notes
+
+- Always ask before deleting
+- Build fresh after clean
+- May take time to reinstall
+- Network required for reinstall
+- IDE may need restart