aiblueprint-cli 1.1.3 → 1.1.7

package/README.md

@@ -1,73 +1,457 @@
 # AIBlueprint CLI
 
-A CLI tool for setting up Claude Code configurations with AIBlueprint defaults.
+A comprehensive CLI tool for supercharging Claude Code with security, productivity, and workflow automation features. Transform your Claude Code experience with pre-configured commands, security hooks, intelligent status displays, and specialized AI agents.
 
-## Quick Start
+> [!NOTE]
+> If you encounter permission errors when running the commands below, add `sudo` before the command.
+
+## 🚀 Quick Start
 
 ```bash
 # Run immediately without installation
-bunx aiblueprint-cli claude-code setup
+bunx aiblueprint-cli@latest claude-code setup
+
+# Or install globally and use
+npm install -g aiblueprint-cli
+aiblueprint claude-code setup
 ```
 
-## Installation & Usage
+## 📋 Table of Contents
+
+- [Installation & Usage](#installation--usage)
+- [Command Reference](#command-reference)
+- [Available Features](#available-features)
+- [Configuration System](#configuration-system)
+- [Templates Catalog](#templates-catalog)
+- [Installation Targets](#installation-targets)
+- [Security Features](#security-features)
+- [Development](#development)
+
+## 💾 Installation & Usage
+
+### Installation Methods
 
 ```bash
-# Install globally
+# Global installation
 npm install -g aiblueprint-cli
+bun install -g aiblueprint-cli
+
+# Run without installation
+npx aiblueprint-cli@latest claude-code setup
+pnpm dlx aiblueprint-cli@latest claude-code setup
+bunx aiblueprint-cli@latest claude-code setup
+```
+
+### Basic Usage
+
+```bash
+# Interactive setup with feature selection
+bunx aiblueprint-cli@latest claude-code setup
+
+# Non-interactive setup (install all features)
+bunx aiblueprint-cli@latest claude-code setup --skip
+
+# Install to custom directory
+bunx aiblueprint-cli@latest claude-code setup --folder ./custom-claude-config
+
+# Install to project directory
+cd your-project
+bunx aiblueprint-cli@latest claude-code setup  # Creates .claude/ in project root
+```
+
+## 🎯 Command Reference
+
+### Main Commands
+
+| Command | Description | Options |
+|---------|-------------|---------|
+| `bunx aiblueprint-cli@latest claude-code setup` | Interactive setup with feature selection | `-f, --folder <path>` (alias for --claudeCodeFolder), `--claudeCodeFolder <path>`, `--codexFolder <path>`, `--openCodeFolder <path>`, `--factoryAiFolder <path>`, `-s, --skip` |
+| `bunx aiblueprint-cli@latest claude-code symlink` | Create symlinks between CLI tools (Codex, OpenCode, FactoryAI) | `--claudeCodeFolder <path>`, `--codexFolder <path>`, `--openCodeFolder <path>`, `--factoryAiFolder <path>` |
+| `bunx aiblueprint-cli@latest claude-code add hook <type>` | Install specific hook | `-f, --folder <path>` |
+| `bunx aiblueprint-cli@latest claude-code add commands [name]` | List or install commands | `-f, --folder <path>` |
+
+### Command Examples
+
+```bash
+# Setup with options
+bunx aiblueprint-cli@latest claude-code setup --skip                    # Install all features
+bunx aiblueprint-cli@latest claude-code setup --folder ~/.my-claude     # Custom location
+bunx aiblueprint-cli@latest claude-code setup --claudeCodeFolder ~/.claude --codexFolder ~/.codex  # Separate folders
+
+# Add specific hooks
+bunx aiblueprint-cli@latest claude-code add hook post-edit-typescript   # TypeScript processing hook
 
-# Or use with npx/pnpm dlx/bunx
-npx aiblueprint-cli claude-code setup
-pnpm dlx aiblueprint-cli claude-code setup
-bunx aiblueprint-cli claude-code setup
+# Manage commands
+bunx aiblueprint-cli@latest claude-code add commands                    # List all available commands
+bunx aiblueprint-cli@latest claude-code add commands commit             # Install commit command
+bunx aiblueprint-cli@latest claude-code add commands deep-code-analysis # Install analysis command
+
+# Create symlinks between CLI tools
+bunx aiblueprint-cli@latest claude-code symlink                         # Interactive symlink manager
+bunx aiblueprint-cli@latest claude-code symlink --factoryAiFolder ~/.factory  # With custom paths
 ```
 
-## What it does
+### Hook Types Available
+
+- `post-edit-typescript` - Automatic TypeScript file processing (Prettier + ESLint + type checking)
+
+### Installation Behavior
+
+The CLI intelligently determines where to install configurations:
+
+1. **Project Local** (`.claude/` in project root) - When run in a Git repository
+2. **Global** (`~/.claude/`) - When not in a Git repository or with custom folder
+3. **Custom Path** - When using `--folder` option
+
+## ✨ Available Features
+
+### 🛡️ Shell Shortcuts
+- **`cc`** - Claude Code with permissions skipped (`claude --dangerously-skip-permissions`)
+- **`ccc`** - Claude Code with continue mode (`claude --dangerously-skip-permissions -c`)
+- Platform support: macOS (`.zshenv`), Linux (`.bashrc`/`.zshrc`)
+
+### 🔒 Command Validation
+- **700+ line security system** protecting against dangerous bash commands
+- **Real-time validation** before command execution via PreToolUse hooks
+- **Smart detection** of privilege escalation, destructive operations, and command injection
+- **Comprehensive logging** to `~/.claude/security.log` with severity levels
+
+### 📊 Custom Statusline
+- **Git integration** - Branch status, changes, and repository info
+- **Cost tracking** - Session costs, daily limits, and token usage via ccusage
+- **Real-time updates** - Command-triggered statusline refresh
+- **Colored output** - Visual indicators for different status types
+
+### 🤖 AIBlueprint Commands (16 Available)
+
+**Development Workflow**
+- `commit` - Fast conventional commits with immediate push
+- `create-pull-request` - Auto-generated PR creation with templates
+- `fix-pr-comments` - Systematic PR review comment resolution
+- `run-tasks` - Execute GitHub issues with full EPCT workflow
+
+**Code Analysis & Research**
+- `deep-code-analysis` - Comprehensive codebase investigation with research
+- `explain-architecture` - Pattern analysis with ASCII diagrams
+- `cleanup-context` - Memory optimization and duplicate removal
+
+**Utilities & Automation**
+- `claude-memory` - Context management for long sessions
+- `watch-ci` - Automated CI/CD monitoring and failure fixing
+- `prompt-command` / `prompt-agent` - Template creation utilities
+- `epct` - Systematic Explore-Plan-Code-Test methodology
+
+### 🎭 AIBlueprint Agents (3 Specialized)
+
+- **explore-codebase** (yellow) - Comprehensive code discovery and analysis
+- **Snipper** (blue) - Rapid code modification specialist with minimal output
+- **websearch** (yellow) - Quick web research with authoritative sources
+
+### 🎨 Output Styles (3 Personalities)
+
+- **Assistant** - Professional "Bob" persona with honest, task-focused communication
+- **senior-dev** - Casual engineering teammate style, direct and conversational
+- **Honest Friend** - WhatsApp-style brutally honest feedback from a successful friend
+
+### 🔊 Notification Sounds
+- **Finish sound** - Audio alert for completed operations (macOS afplay)
+- **Need-human sound** - Audio alert for attention requests
+- **Volume control** - Configurable audio levels
+
+### 🔗 Symlink Management
+- **Multi-tool integration** - Create symlinks between Claude Code, Codex, OpenCode, and FactoryAI
+- **Interactive selection** - Choose source, content type (commands/agents), and destinations
+- **Smart validation** - Prevents overwriting non-symlink directories and validates paths
+- **Bidirectional sync** - Sync commands and agents in any direction
+- **Supported tools:**
+  - **Claude Code** - Commands + Agents (`~/.claude/`)
+  - **Codex** - Commands only (`~/.codex/prompts`)
+  - **OpenCode** - Commands only (`~/.config/opencode/command`)
+  - **FactoryAI** - Commands + Droids/Agents (`~/.factory/`)
+
+## ⚙️ Configuration System
+
+### Settings.json Structure
+
+The CLI automatically manages your `~/.claude/settings.json` with:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bash ~/.claude/scripts/statusline-ccusage.sh",
+    "padding": 0
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{"type": "command", "command": "bun ~/.claude/scripts/validate-command.js"}]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [{"type": "command", "command": "bun ~/.claude/hooks/hook-post-file.ts"}]
+      }
+    ]
+  }
+}
+```
+
+### GitHub Integration
+
+- **Remote-first approach** - Always downloads latest configurations from GitHub
+- **Automatic fallback** - Uses local files when GitHub is unavailable
+- **Version independence** - Get updates without CLI updates
+- **Rate limiting aware** - Handles GitHub API limitations gracefully
+
+## 📚 Templates Catalog
+
+### Commands by Category
+
+<details>
+<summary><strong>Development Workflow (4 commands)</strong></summary>
+
+| Command | Tools | Purpose |
+|---------|-------|---------|
+| `commit` | `Bash(git :*)` | Quick conventional commits with immediate push |
+| `create-pull-request` | `Bash(git :*)`, `Bash(gh :*)` | PR creation with auto-generated descriptions |
+| `fix-pr-comments` | `Bash(gh :*)`, `Read`, `Edit` | Systematic PR review resolution |
+| `run-tasks` | `Bash(gh :*)`, `Bash(git :*)` | GitHub issue execution with EPCT |
+
+</details>
+
+<details>
+<summary><strong>Analysis & Research (2 commands)</strong></summary>
+
+| Command | Tools | Purpose |
+|---------|-------|---------|
+| `deep-code-analysis` | `Task`, `WebSearch`, `mcp__context7__*` | Comprehensive codebase investigation |
+| `explain-architecture` | `Read`, `Glob`, `Grep`, `Task` | Architectural pattern analysis |
+
+</details>
+
+<details>
+<summary><strong>Maintenance & Optimization (2 commands)</strong></summary>
+
+| Command | Tools | Purpose |
+|---------|-------|---------|
+| `cleanup-context` | `TodoWrite`, `MultiEdit`, `Glob` | Memory bank optimization |
+| `watch-ci` | `Bash(gh :*)`, `Bash(sleep :*)` | Automated CI monitoring |
 
-The setup command will interactively configure your Claude Code environment with:
+</details>
 
-- **Shell shortcuts** - Add `cc` and `ccc` aliases for quick access
-- **Command validation** - Security hook for bash commands  
-- **Custom statusline** - Shows git, costs, tokens info
-- **AIBlueprint commands** - Pre-configured command templates
-- **AIBlueprint agents** - Specialized AI agents
-- **Output styles** - Custom output formatting
-- **Notification sounds** - Audio alerts for events
+<details>
+<summary><strong>Utilities (8 commands)</strong></summary>
 
-### Setup Process
+| Command | Tools | Purpose |
+|---------|-------|---------|
+| `claude-memory` | `Read`, `Write`, `Edit`, `Glob` | CLAUDE.md file management |
+| `epct` | `Task` | Explore-Plan-Code-Test methodology |
+| `prompt-command` | `Read`, `Write`, `Edit` | Command template creation |
+| `prompt-agent` | `Read`, `Write`, `Edit` | Agent template creation |
 
-1. Creates `~/.claude/` directory if it doesn't exist
-2. Copies selected configurations to your `.claude` folder
-3. Updates your `~/.claude/settings.json` with new configurations
-4. Installs required dependencies (`bun`, `ccusage`)
-5. Adds shell aliases to your shell configuration file
+</details>
 
-### Shell Shortcuts
+### Hooks Available
 
-After setup, you can use:
-- `cc` - Claude Code with permissions skipped
-- `ccc` - Claude Code with permissions skipped and continue mode
+| Hook | Language | Purpose | Triggers |
+|------|----------|---------|----------|
+| `post-edit-typescript` | TypeScript/Bun | File processing after edits | Edit, Write, MultiEdit on .ts/.tsx |
 
-## Requirements
+### Scripts & Utilities
 
-- Node.js 16+
-- macOS or Linux
-- Claude Code installed
+| Script | Language | Purpose |
+|--------|----------|---------|
+| `validate-command.js` | Bun/JavaScript | Security validation for bash commands |
+| `statusline-ccusage.sh` | Bash | Git status and usage tracking display |
 
-## Development
+## 🎯 Installation Targets
+
+### Local Project Installation (Recommended)
+
+When run in a Git repository, creates `.claude/` in your project root:
 
 ```bash
-# Install dependencies
-bun install
+cd your-project/
+bunx aiblueprint-cli@latest claude-code setup
+# Creates: your-project/.claude/
+```
 
-# Build and test locally
-bun run build
-npm link
-aiblueprint claude-code setup
+**Benefits:**
+- Project-specific configurations
+- Team collaboration ready
+- Version control friendly
+- Isolated environments
+
+### Global Installation
+
+When not in a Git repository, uses global directory:
+
+```bash
+cd ~/
+bunx aiblueprint-cli@latest claude-code setup
+# Creates: ~/.claude/
+```
+
+**Benefits:**
+- System-wide configurations
+- Works across all projects
+- Persistent settings
+
+### Custom Path Installation
+
+Use `--folder` for specific locations:
+
+```bash
+bunx aiblueprint-cli@latest claude-code setup --folder ./custom-config
+bunx aiblueprint-cli@latest claude-code setup --folder /opt/claude-config
+```
+
+## 🔐 Security Features
+
+### Command Validation System
+
+The security system protects against dangerous operations:
+
+**Critical Commands Blocked:**
+- `rm -rf` (with path validation)
+- `dd`, `mkfs`, `fdisk` (disk operations)
+- `chmod 777`, `chown -R` (permission changes)
+- `curl | bash`, `wget | sh` (remote execution)
+- `sudo` operations (privilege escalation)
+
+**Security Logging:**
+```json
+{
+  "timestamp": "2024-01-15T10:30:00.000Z",
+  "command": "rm -rf /",
+  "severity": "CRITICAL",
+  "action": "BLOCKED",
+  "reason": "Destructive command with critical path"
+}
+```
+
+**Safe Paths Allowed:**
+- `./`, `~/`, relative paths
+- `node_modules/`, `.git/`, common safe directories
+- Temporary directories (`/tmp/`, `/var/tmp/`)
+
+### Hook-Based Protection
+
+- **PreToolUse validation** - Commands checked before execution
+- **Real-time analysis** - Pattern matching and rule evaluation
+- **User confirmation** - Interactive prompts for questionable commands
+- **Comprehensive rules** - 50+ security patterns and checks
+
+## 🛠️ Development
+
+### Local Development Setup
+
+```bash
+# Clone and setup
+git clone <repository>
+cd aiblueprint-cli
+bun install
 
 # Development mode
 bun run dev claude-code setup
+bun run dev claude-code add commands
+
+# Testing
+bun run test:run                    # Run test suite
+bun run dev-test                    # Test with temporary config
+```
+
+### Build and Release
+
+```bash
+# Build for distribution
+bun run build                       # Compiles to dist/cli.js
+
+# Local testing
+bun run test-local                  # Creates npm link
+aiblueprint claude-code setup       # Test globally
+
+# Release (automated)
+bun run release                     # Version bump, build, tag, publish
 ```
 
-## License
+### Project Structure
+
+```
+src/
+├── cli.ts                          # Main CLI entry point
+├── commands/
+│   ├── setup.ts                    # Main setup command
+│   ├── addHook.ts                  # Hook installation
+│   └── addCommand.ts               # Command installation
+└── utils/
+    ├── claude-config.ts            # Configuration utilities
+    ├── file-installer.ts           # GitHub/local fallback
+    └── github.ts                   # GitHub API integration
+
+claude-code-config/                 # Template repository
+├── commands/                       # Command templates
+├── hooks/                          # Hook scripts
+├── agents/                         # Agent configurations
+├── scripts/                        # Utility scripts
+├── output-styles/                  # Style templates
+└── song/                           # Notification sounds
+```
+
+### Testing Commands
+
+```bash
+# Test all major workflows
+bun run dev claude-code setup --skip
+bun run dev claude-code add hook post-edit-typescript
+bun run dev claude-code add commands
+bun run dev claude-code add commands commit
+
+# Test with custom paths
+bun run dev claude-code setup --folder ./test-config
+```
+
+## 📋 Requirements
+
+### System Requirements
+- **Runtime**: Node.js 16+ or Bun
+- **Platform**: macOS (full support), Linux (partial), Windows (limited)
+- **Dependencies**: Git (for repository detection)
+
+### Claude Code Requirements
+- **Claude Code**: Latest version installed
+- **Permissions**: Ability to modify `~/.claude/settings.json`
+
+### Optional Dependencies
+- **bun**: Enhanced script execution and hooks
+- **ccusage**: Advanced statusline with cost tracking
+- **gh CLI**: GitHub integration for PR/issue commands
+- **prettier**, **eslint**: TypeScript hook functionality
+
+## 🤝 Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `bun run test:run`
+5. Submit a pull request
+
+### Adding New Templates
+
+1. Add template files to `claude-code-config/`
+2. Update metadata with YAML frontmatter
+3. Test installation: `bun run dev claude-code add commands <name>`
+4. Document in README
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+**Created by AIBlueprint** - Enhancing Claude Code for modern development workflows.
 
-MIT
+Need help? [Open an issue](https://github.com/aiblueprint/aiblueprint-cli/issues) or check our [documentation](https://docs.aiblueprint.dev).

package/claude-code-config/agents/explore-codebase.md

@@ -2,6 +2,7 @@
 name: explore-codebase
 description: Use this agent whenever you need to explore the codebase to realize a feature.
 color: yellow
+model: sonnet
 ---
 
 You are a codebase exploration specialist. Your only job is to find and present ALL relevant code and logic for the requested feature.

package/claude-code-config/agents/explore-docs.md

@@ -0,0 +1,88 @@
+---
+name: explore-docs
+description: Use this agent IMMEDIATELY when the user asks about library features, implementation methods, "how to do X with Y library", documentation searches, or ANY question about using/implementing specific libraries or frameworks (in any language) - launches Context7 and WebFetch for precise technical information with code examples
+color: yellow
+model: sonnet
+---
+
+You are a documentation exploration specialist. Your mission is to retrieve precise, actionable documentation with code examples while eliminating superficial content.
+
+## Search Strategy
+
+**Primary**: Use Context7 for library-specific documentation
+
+- Resolve library ID first with `mcp__context7__resolve-library-id`
+- Fetch targeted docs with `mcp__context7__get-library-docs`
+- Focus on specific topics when provided
+
+**Fallback**: Use WebSearch + WebFetch for official documentation
+
+- Search for official docs, API references, guides
+- Target authoritative sources (official websites, GitHub repos)
+- Fetch complete documentation pages
+
+## Data Processing
+
+**Filter for essentials**:
+
+- Code examples and usage patterns
+- API specifications and method signatures
+- Configuration options and parameters
+- Error handling patterns
+- Best practices and common pitfalls
+
+**Eliminate noise**:
+
+- Marketing content and introductions
+- Redundant explanations
+- Outdated or deprecated information
+
+## Output Format
+
+<output-format>
+
+### Library: [Name/Version]
+
+### Key Concepts
+
+- [Essential concept]: [Brief explanation]
+
+### Code Examples
+
+```language
+// [Practical example with context]
+```
+
+### API Re
+
+### Configuration
+
+````language
+// [Complete config example]
+```ference
+- `method(params)`: [Purpose and returns]
+- `property`: [Type and usage]
+
+
+### Common Patterns
+- [Pattern name]: [When to use + code]
+
+### URLs
+- Official docs: [url]
+- API reference: [url]
+- Examples: [url]
+
+## Execution Rules
+
+- **Precision over completeness** - focus on what's immediately useful
+- **Code-first approach** - every concept needs a working example
+- **No fluff** - skip introductions, marketing, basic explanations
+- **Verify recency** - prioritize current documentation versions
+- **Parallel searches** when exploring multiple aspects
+
+## Priority
+
+Actionable code examples > API specs > Configuration > Theory.
+
+</output-format>
+````

package/claude-code-config/agents/snipper.md

@@ -2,6 +2,7 @@
 name: Snipper
 description: Use this agent when you need to modify code. This agent is specialized to be fast. The output is small and optimized to code as fast as agent can.
 color: blue
+model: sonnet
 ---
 
 You are a rapid code modification specialist. No explanations, just execute.
@@ -19,6 +20,7 @@ You are a rapid code modification specialist. No explanations, just execute.
 - Make minimal changes to achieve the goal
 - Use `MultiEdit` for multiple changes in same file
 - Never add comments unless requested
+- DO NEVER RUN LINT CHECK. YOU CAN'T USE BASH.
 
 ## Output Format
 

package/claude-code-config/agents/websearch.md

@@ -3,6 +3,7 @@ name: websearch
 description: Use this agent when you need to make a quick web search.
 color: yellow
 tools: WebSearch, WebFetch
+model: sonnet
 ---
 
 You are a rapid web search specialist. Find accurate information fast.