npm package: @llms-sdk/iap
Description: 🔮 Supercharge your GitHub workflow with Claude AI. Transform 'fix stuff' commits into professional messages, generate intelligent changelogs, create comprehensive docs, and get AI code reviews that actually understand your codebase. One command replaces 
Author: lennylmiller
Latest version: 1.0.3

# IAP

[![npm version](https://badge.fury.io/js/%40llms-sdk%2Fiap.svg)](https://badge.fury.io/js/%40llms-sdk%2Fiap)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

🔮 **Supercharge your GitHub workflow with Claude AI.** Transform your development process with AI-powered commit messages, intelligent changelogs, automated documentation, and code reviews that actually understand your codebase.

## Quick Install

```bash
npm install -g @llms-sdk/iap
```

**Prerequisites:** Node.js 18+, Git, [Claude Code](https://www.anthropic.com/claude-code), and optionally [GitHub CLI](https://cli.github.com/).

## Quick Start

```bash
cd your-project
iap --verify        # Check system dependencies and authentication
iap commit          # AI generates perfect commit messages
iap changelog       # Creates intelligent project history
iap readme          # Writes comprehensive documentation
```

## Commands

### 🔧 `iap --verify`
**Smart dependency and authentication checking.**

Validates your system setup and authentication status with intelligent caching to avoid repeated checks. Ensures Claude, Git, and GitHub authentication are properly configured.

```bash
iap --verify                  # Force full dependency check
```

**How it works:**
- Validates Claude Code installation and authentication
- Checks Git configuration and user setup
- Verifies GitHub authentication (SSH keys or GitHub CLI)
- Uses intelligent 24-hour caching to avoid repeated checks
- Provides detailed feedback on any missing dependencies

### 🤖 `iap commit`
**AI-powered commits that actually make sense.**

Analyzes your git changes, understands the context, and generates conventional commit messages. No more "fix stuff" or "update files" - get meaningful commits that tell the story of your code.

```bash
iap commit                    # Quick AI commit
iap commit --interactive      # Review before committing  
iap commit --verbose          # See the AI thinking process
iap commit "Add user context" # Include additional context
```

**How it works:**
- Scans all changed files and understands the modifications
- Analyzes code patterns to determine commit type (feat/fix/refactor/etc.)
- Generates conventional commit format with clear descriptions
- Supports additional context to guide commit message generation
- Enhanced authentication validation for seamless push operations
- Automatically stages, commits, and pushes to your current branch

### 📅 `iap changelog`
**Turn raw commit history into readable project stories.**

Creates human-readable changelogs that focus on user impact, not technical noise. Generates daily, weekly, and monthly summaries that actually make sense to stakeholders.

```bash
iap changelog                 # Generate intelligent changelog
iap changelog --verbose       # See detailed analysis process
```

**How it works:**
- Analyzes entire commit history with AI understanding
- Filters out trivial changes, focuses on meaningful updates  
- Groups changes by time periods and impact
- Creates multiple changelog formats (daily/weekly/monthly)
- Writes in clear, non-technical language

### 📖 `iap readme`
**Professional documentation that writes itself.**

Analyzes your codebase architecture and creates comprehensive README files with installation guides, usage examples, and feature descriptions.

```bash
iap readme                    # Generate project README
```

**How it works:**
- Scans project structure and identifies key technologies
- Analyzes package.json and dependencies
- Understands code patterns and project purpose
- Creates professional documentation with examples
- Includes installation, usage, and contribution guides

### 🔍 `iap review`
**Code reviews that catch what humans miss.**

Performs deep code analysis for security vulnerabilities, performance issues, and maintainability problems. Provides actionable recommendations for improvement.

```bash
iap review                    # Comprehensive code analysis
iap review --verbose          # Detailed security assessment
```

**How it works:**
- Analyzes entire codebase for patterns and anti-patterns
- Identifies security vulnerabilities and performance bottlenecks
- Evaluates code quality and maintainability metrics
- Provides specific, actionable improvement recommendations
- Saves detailed review to `docs/code-review.md`

### 📚 `iap docs`
**Technical documentation that developers actually read.**

Creates comprehensive technical guides covering architecture, components, deployment, and troubleshooting.

```bash
iap docs                      # Generate technical documentation
```

**How it works:**
- Maps project architecture and component relationships
- Documents data flow and system interactions
- Creates deployment and configuration guides
- Includes troubleshooting and debugging information
- Saves to `docs/technical-docs.md`

### 💡 `iap brainstorm`
**AI-powered feature ideation and improvement suggestions.**

Analyzes your codebase capabilities and suggests new features, optimizations, and architectural improvements.

```bash
iap brainstorm                # Get improvement ideas
```

**How it works:**
- Evaluates current codebase capabilities and patterns
- Identifies optimization opportunities and technical debt
- Suggests new features based on project direction
- Recommends architecture evolution strategies
- Saves ideas to `docs/ideas.md`

### 📝 `iap annotate`
**Add intelligent context to your entire git history.**

Analyzes every commit in your repository and adds AI-generated notes that explain what each change actually accomplished.

```bash
iap annotate                  # Add AI notes to all commits
iap annotate --verbose        # See annotation process
```

**How it works:**
- Processes each commit's diff and understands changes
- Generates detailed technical explanations
- Adds git notes with context and purpose
- Creates searchable commit history
- View with `git log --show-notes`

## Project Integration

Add to your `package.json` for team workflows:

```json
{
  "scripts": {
    "commit": "iap commit --interactive",
    "release:prep": "iap changelog && iap readme",
    "code:review": "iap review --verbose",
    "docs:update": "iap docs"
  }
}
```

## Why IAP?

### 🎯 **Intelligent, Not Automated**
Unlike simple automation tools, IAP understands your code context. It reads your entire codebase, understands patterns, and generates content that makes sense for your specific project.

### 🚀 **GitHub + Claude = Superpowers** 
Combines Claude's deep reasoning with GitHub workflows. Get AI that understands not just syntax, but intent, architecture, and user impact.

### ⚡ **Saves Hours, Not Minutes**
- **Commit messages**: From 30 seconds to instant, every time
- **Changelogs**: From hours of manual work to 2 minutes
- **Documentation**: From days of writing to comprehensive docs in minutes
- **Code reviews**: Catch issues before they become problems

### 🧠 **Context-Aware AI**
- Understands your project's tech stack and patterns
- Maintains consistency with your existing code style
- Focuses on user impact, not just technical changes
- Learns from your codebase structure and conventions

## Examples

### Daily Workflow
```bash
# Make some changes
echo "new feature" >> src/feature.js

# AI commit with perfect message
iap commit
# ✅ Output: "feat: add user authentication with JWT tokens"

# Update documentation automatically  
iap readme
# ✅ Creates professional README with new feature documented

# Prepare for release
iap changelog
# ✅ Generates release notes that stakeholders actually understand
```

### Team Workflow
```bash
# Before standups - get project insights
iap brainstorm
# ✅ "Here are 8 improvement opportunities based on your codebase..."

# Before releases - comprehensive preparation
yarn release:prep
# ✅ Updated changelog + README + documentation

# Before code reviews - AI pre-screening
iap review
# ✅ "Found 3 security issues and 5 performance optimizations..."
```

## Installation Details

### Prerequisites
Install these first:
```bash
# Required
npm install -g @anthropic-ai/claude-code
# Then run: claude (and complete authentication)

# Recommended  
brew install gh          # GitHub CLI for enhanced workflows
gh auth login           # Authenticate with GitHub
```

**System Requirements:** Node.js 18+, Git configured with user info.

### GitHub Authentication Setup

IAP uses intelligent global authentication detection that works across all your repositories. The system automatically validates your GitHub access using either SSH keys or GitHub CLI authentication:

#### 🔐 **SSH Authentication (Recommended)**
If your remote uses `git@github.com:...` format:
```bash
# Generate SSH key (if you don't have one)
ssh-keygen -t ed25519 -C "your@email.com"

# Add public key to GitHub
cat ~/.ssh/id_ed25519.pub
# Copy the output and add it at: https://github.com/settings/keys

# Test SSH connection
ssh -T git@github.com
```

#### 🌐 **HTTPS Authentication**
If your remote uses `https://github.com/...` format, you have three options:

**Option 1: GitHub CLI (Recommended)**
```bash
brew install gh
gh auth login  # Choose SSH when prompted
```

**Option 2: Switch to SSH**
```bash
git remote set-url origin git@github.com:USERNAME/REPOSITORY.git
```

**Option 3: Personal Access Token**
- Create token at [GitHub Settings](https://github.com/settings/tokens)
- Use token as password when git prompts for credentials

> 💡 **Why SSH is Better:** SSH eliminates password prompts, is more secure, and provides seamless authentication. IAP will automatically detect your setup and guide you through any authentication issues.

## Troubleshooting

### Common Issues

**Command not found**
```bash
npm install -g iap
# Ensure npm global bin is in your PATH
```

**Claude Code not authenticated**
```bash
claude
# Follow authentication prompts (Console/Pro/Enterprise)
```

**Git not configured**
```bash
git config --global user.name "Your Name"
git config --global user.email "your@email.com"
```

**GitHub CLI issues (optional)**
```bash
brew install gh         # macOS recommended
gh auth login          # Authenticate with GitHub
```

### Debug Mode
Use `--verbose` for detailed output and `--verify` for dependency checking:
```bash
iap commit --verbose          # Shows step-by-step AI reasoning
iap --verify                  # Force full system verification
iap --verify --verbose        # Detailed dependency diagnostics
```

### Getting Help
- Run `iap help` for command reference
- Check [Claude Code docs](https://www.anthropic.com/claude-code)
- Open issues on [GitHub](https://github.com/lennylmiller/iap)

## Contributing

1. Fork the repository
2. Make your changes  
3. Use IAP to commit: `iap commit --interactive`
4. Submit a pull request

## License

MIT License - see LICENSE file.

---

**Made with ❤️ and AI** - IAP transforms your development workflow by giving Claude deep understanding of your GitHub projects.