@grunnverk/kodrdriv 1.3.0

package/guide/index.md

@@ -0,0 +1,224 @@
+# KodrDriv AI Guide
+
+This directory contains comprehensive documentation designed to help developers and AI assistants understand, integrate, debug, and extend kodrdriv - an AI-powered Git workflow automation tool.
+
+## What is KodrDriv?
+
+KodrDriv automates Git workflows by using AI to generate intelligent commit messages and release notes. It analyzes your code changes, Git history, and project context to create meaningful documentation while automating the entire release process.
+
+**Core Value**: Solves the "context switch" problem - when you're deep in code and Git asks you to summarize what you've done, kodrdriv analyzes your changes and writes documentation that reflects your actual work.
+
+### MCP Integration
+
+KodrDriv supports the **Model Context Protocol (MCP)**, allowing AI assistants like Cursor to directly invoke all kodrdriv commands:
+- **14 Tools**: commit, release, publish, development, precommit, tree operations, and more
+- **8 Resources**: Access config, status, and workspace data via `kodrdriv://` URIs
+- **6 Prompts**: Guided workflows for common operations
+
+See [`MCP_INTEGRATION.md`](../MCP_INTEGRATION.md) for details.
+
+## Guide Contents
+
+### Getting Started
+- [**Quick Start**](./quickstart.md): Get kodrdriv working in 5 minutes
+- [**Usage**](./usage.md): Common workflows and command examples
+- [**Integration**](./integration.md): How to integrate kodrdriv into your project
+
+### Understanding KodrDriv
+- [**Architecture**](./architecture.md): System design, packages, and data flow
+- [**Commands**](./commands.md): Complete command reference with examples
+- [**Configuration**](./configuration.md): All configuration options and patterns
+
+### Development & Debugging
+- [**Development**](./development.md): Building, testing, and extending kodrdriv
+- [**Debugging**](./debugging.md): Common issues and troubleshooting strategies
+- [**Testing**](./testing.md): Test structure and how to run tests
+
+### Advanced Topics
+- [**AI System**](./ai-system.md): How AI analysis works (agentic mode, tools, prompts)
+- [**Tree Operations**](./tree-operations.md): Multi-package workflow automation
+- [**Monorepo Guide**](./monorepo.md): Using kodrdriv in monorepos
+
+## Project Structure
+
+```
+kodrdriv/                   - Main CLI tool
+├── src/
+│   ├── commands/          - Command implementations
+│   ├── util/              - Utility functions
+│   ├── content/           - Content generation (diffs, logs)
+│   └── types.ts           - TypeScript types
+├── tests/                 - Test suite
+└── docs/                  - Detailed documentation
+
+ai-service/                - AI integration package
+├── src/
+│   ├── agentic/          - Tool-calling AI agents
+│   ├── prompts/          - Prompt engineering
+│   └── tools/            - AI tools for analysis
+└── tests/                - AI service tests
+
+tree-core/                 - Dependency graph analysis
+tree-execution/            - Parallel execution engine
+shared/                    - Shared utilities
+git-tools/                 - Git operations
+github-tools/              - GitHub API integration
+audio-tools/               - Audio recording & transcription
+```
+
+## Key Capabilities
+
+### 1. Intelligent Commit Messages
+Uses AI to analyze your code changes and generate meaningful commit messages:
+- Investigates file relationships and dependencies
+- Reviews recent commit history to avoid duplicates
+- Checks related tests to understand behavior changes
+- Suggests splitting unrelated changes into multiple commits
+
+### 2. Comprehensive Release Notes
+Generates detailed release notes from Git history:
+- Analyzes commits and identifies patterns
+- Detects breaking changes automatically
+- Integrates with GitHub issues and milestones
+- Provides context about how changes relate
+
+### 3. Automated Publishing
+Complete release workflow automation:
+- Generates release notes
+- Creates pull request
+- Waits for CI checks
+- Merges to main
+- Creates GitHub release
+- Bumps to next dev version
+
+### 4. Multi-Package Support
+Manages monorepos with complex dependencies:
+- Analyzes dependency graphs
+- Executes commands in correct order
+- Parallel execution where possible
+- Recovery from failures
+
+### 5. Audio-Driven Workflows
+Voice-powered development:
+- Record audio for commit context
+- Transcribe review notes
+- Voice-driven issue creation
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# Generate commit message
+kodrdriv commit --sendit
+
+# Generate release notes
+kodrdriv release
+
+# Publish a release
+kodrdriv publish
+
+# Multi-package operations
+kodrdriv tree publish --parallel
+
+# With context files
+kodrdriv release --context-files IMPLEMENTATION.md
+
+# With self-reflection
+kodrdriv commit --self-reflection
+```
+
+### Essential Configuration
+
+```json
+{
+  "model": "gpt-4o",
+  "outputDirectory": "output",
+  "commit": {
+    "selfReflection": true,
+    "maxAgenticIterations": 10
+  },
+  "release": {
+    "selfReflection": true,
+    "maxAgenticIterations": 30
+  }
+}
+```
+
+### Environment Variables
+
+```bash
+export OPENAI_API_KEY="your-key"      # Required
+export GITHUB_TOKEN="your-token"      # For publish
+```
+
+## Key Features
+
+- **AI Analysis (Always On)**: Uses tool-calling to investigate changes before generating content
+- **Context Files**: Pass documentation files as context (`--context-files`)
+- **Self-Reflection**: Generate reports showing tool effectiveness and analysis quality
+- **GitHub Integration**: Issues, milestones, pull requests, releases
+- **Flexible Configuration**: Hierarchical config with command-line overrides
+- **Stop-Context Filtering**: Automatically remove sensitive information
+- **Dry Run Mode**: Preview everything before execution
+
+## Implementation Guides in Root Directory
+
+The `/Users/tobrien/gitw/grunnverk/` directory contains extensive implementation documentation:
+
+### Recent Improvements
+- `SELF-REFLECTION-IMPROVEMENTS.md` - File location and prompt improvements
+- `CONTEXT-FILES-AND-HUMAN-PROMPTS.md` - Context files and anti-slop prompts
+- `AGENTIC-ONLY-SIMPLIFICATION.md` - Simplified to always use AI analysis
+- `SESSION-SUMMARY-DEC-31.md` - Complete overview of recent changes
+
+### AI System
+- `AI-SERVICE-INTEGRATION-COMPLETE.md` - AI service extraction and integration
+- `AGENTIC-RELEASE-NOTES-COMPLETE.md` - Agentic release notes implementation
+- `AGENTIC-COMMIT-IMPROVEMENTS.md` - Commit generation improvements
+- `AI-FRIENDLY-LOGGING-GUIDE.md` - Logging best practices
+
+### Architecture & Features
+- `TREE-TOOLKIT-COMPLETE.md` - Tree operations extraction
+- `PARALLEL-PUBLISH-QUICK-REFERENCE.md` - Parallel execution guide
+- `RIOTPROMPT-COMPLETE-SUMMARY.md` - Prompt engineering system
+- `MONOREPO-PUBLISH-IMPROVEMENTS.md` - Monorepo workflows
+
+### Debugging & Fixes
+- `PARALLEL-PUBLISH-DEBUGGING-GUIDE.md` - Troubleshooting parallel execution
+- `RECOVERY-FIXES.md` - Error recovery mechanisms
+- `CHECKPOINT-RECOVERY-FIX.md` - Checkpoint system details
+
+## For AI Assistants
+
+If you're an AI helping someone use kodrdriv:
+
+1. **Start with** [`quickstart.md`](./quickstart.md) to get the basics
+2. **Read** [`integration.md`](./integration.md) to understand how to integrate into projects
+3. **Reference** [`commands.md`](./commands.md) for specific command details
+4. **Check** [`debugging.md`](./debugging.md) when troubleshooting
+5. **Review** root directory `.md` files for implementation details
+
+## For Developers
+
+If you're integrating kodrdriv:
+
+1. **Install**: `npm install -g @grunnverk/kodrdriv`
+2. **Configure**: `kodrdriv --init-config`
+3. **Try it**: `kodrdriv commit --dry-run`
+4. **Customize**: Edit `.kodrdriv/config.yaml`
+5. **Automate**: Add to your CI/CD pipeline
+
+## Next Steps
+
+- 🚀 [Get started in 5 minutes](./quickstart.md)
+- 📖 [Learn common workflows](./usage.md)
+- 🔧 [Integrate into your project](./integration.md)
+- 🐛 [Troubleshoot issues](./debugging.md)
+- 🧠 [Understand the AI system](./ai-system.md)
+
+**Need help?** Start with the guide that matches your goal, and refer to the implementation documents in the root directory for detailed technical information.
+
+
+
+

package/guide/integration.md

@@ -0,0 +1,510 @@
+# Integration Guide
+
+How to integrate kodrdriv into your project.
+
+## Integration Patterns
+
+### 1. Basic Git Workflow Integration
+
+Replace manual commit messages with AI-generated ones:
+
+**Before**:
+```bash
+git add .
+git commit -m "fix: update user auth"
+```
+
+**After**:
+```bash
+git add .
+kodrdriv commit --sendit
+```
+
+### 2. CI/CD Integration
+
+#### GitHub Actions Example
+
+```yaml
+name: Release
+on:
+  push:
+    branches: [main]
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install kodrdriv
+        run: npm install -g @grunnverk/kodrdriv
+
+      - name: Generate Release Notes
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          kodrdriv release --context-files CHANGELOG.md
+
+      - name: Create Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # Release notes are in output/RELEASE_NOTES.md
+          gh release create v$(node -p "require('./package.json').version") \
+            --notes-file output/RELEASE_NOTES.md
+```
+
+#### GitLab CI Example
+
+```yaml
+release:
+  stage: deploy
+  script:
+    - npm install -g @grunnverk/kodrdriv
+    - kodrdriv release
+    - # Use generated notes in output/RELEASE_NOTES.md
+  only:
+    - main
+```
+
+### 3. Pre-Commit Hook Integration
+
+Automatically generate commit messages:
+
+**.git/hooks/prepare-commit-msg**:
+```bash
+#!/bin/bash
+# Generate commit message with kodrdriv
+if [ -z "$2" ]; then
+  # Only for new commits (not amend)
+  kodrdriv commit --cached > "$1"
+fi
+```
+
+Make it executable:
+```bash
+chmod +x .git/hooks/prepare-commit-msg
+```
+
+### 4. npm Scripts Integration
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "commit": "kodrdriv commit --sendit",
+    "release:notes": "kodrdriv release",
+    "release:publish": "kodrdriv publish",
+    "precommit": "kodrdriv precommit"
+  }
+}
+```
+
+Usage:
+```bash
+npm run commit
+npm run release:publish
+```
+
+## Project Setup
+
+### For Single Package Projects
+
+1. **Install kodrdriv**:
+```bash
+npm install --save-dev @grunnverk/kodrdriv
+# or globally
+npm install -g @grunnverk/kodrdriv
+```
+
+2. **Initialize configuration**:
+```bash
+kodrdriv --init-config
+```
+
+3. **Configure for your project**:
+```yaml
+# .kodrdriv/config.yaml
+model: gpt-4o
+outputDirectory: output
+
+commit:
+  sendit: false          # Require manual confirmation
+  selfReflection: true   # Generate analysis reports
+
+release:
+  focus: "user-facing changes and breaking changes"
+  maxAgenticIterations: 30
+```
+
+4. **Test it**:
+```bash
+kodrdriv commit --dry-run
+kodrdriv release --dry-run
+```
+
+### For Monorepo Projects
+
+1. **Install in root**:
+```bash
+cd /path/to/monorepo
+npm install -g @grunnverk/kodrdriv
+```
+
+2. **Configure tree operations**:
+```yaml
+# .kodrdriv/config.yaml
+tree:
+  directories:
+    - packages/core
+    - packages/ui
+    - packages/utils
+  parallel: true
+  maxConcurrency: 4
+```
+
+3. **Use tree commands**:
+```bash
+# Commit across all packages
+kodrdriv tree commit
+
+# Publish all in correct order
+kodrdriv tree publish --parallel
+
+# Link packages for development
+kodrdriv tree link
+```
+
+## Integration with Existing Tools
+
+### With Conventional Commits
+
+Kodrdriv generates conventional commit format by default:
+
+```bash
+# Output follows conventional format
+kodrdriv commit
+# → feat: add user authentication
+# → fix: resolve memory leak in cache
+# → chore: update dependencies
+```
+
+### With Semantic Release
+
+Use kodrdriv to generate release notes, then use semantic-release for publishing:
+
+```json
+{
+  "scripts": {
+    "release:notes": "kodrdriv release",
+    "release:semantic": "semantic-release"
+  }
+}
+```
+
+### With Changesets
+
+Generate release notes that complement changesets:
+
+```bash
+# Generate comprehensive notes
+kodrdriv release --context-files .changeset/*.md
+
+# Use alongside changesets
+npx changeset version
+kodrdriv release
+npx changeset publish
+```
+
+### With Lerna/nx
+
+Use kodrdriv's tree operations:
+
+```bash
+# Instead of lerna run
+kodrdriv tree --cmd "npm test"
+
+# Instead of lerna publish
+kodrdriv tree publish --parallel
+```
+
+## Configuration Patterns
+
+### Minimal Configuration
+
+```yaml
+model: gpt-4o-mini
+outputDirectory: output
+```
+
+### Standard Configuration
+
+```yaml
+model: gpt-4o
+outputDirectory: output
+
+commit:
+  selfReflection: true
+  add: false
+
+release:
+  focus: "breaking changes and new features"
+  selfReflection: true
+
+publish:
+  sendit: false
+  targetBranch: main
+```
+
+### Advanced Configuration
+
+```yaml
+model: gpt-4o
+openaiReasoning: medium
+outputDirectory: output
+
+contextDirectories:
+  - docs
+  - .github
+
+commit:
+  selfReflection: true
+  maxAgenticIterations: 15
+  allowCommitSplitting: true
+  contextFiles:
+    - docs/ARCHITECTURE.md
+
+release:
+  selfReflection: true
+  maxAgenticIterations: 40
+  focus: |
+    Emphasize breaking changes and migration steps.
+    Target audience: developers using this library.
+
+publish:
+  targetBranch: main
+  mergeMethod: squash
+  checksTimeout: 3600000
+  waitForReleaseWorkflows: true
+
+tree:
+  parallel: true
+  maxConcurrency: 4
+  directories:
+    - packages/core
+    - packages/ui
+```
+
+## Team Workflows
+
+### Small Team (1-5 developers)
+
+```bash
+# Each developer runs locally
+kodrdriv commit --sendit
+
+# Releases done by maintainer
+kodrdriv publish --interactive
+```
+
+### Medium Team (5-20 developers)
+
+```yaml
+# .kodrdriv/config.yaml
+commit:
+  sendit: false           # Require review
+  interactive: true       # Allow editing
+
+release:
+  interactive: true       # Team review before publish
+  noMilestones: false     # Use GitHub milestones
+```
+
+### Large Team (20+ developers)
+
+```yaml
+# Stricter controls
+commit:
+  sendit: false
+  skipFileCheck: false    # Prevent accidental commits
+
+publish:
+  sendit: false           # Manual approval required
+  requireEnvVars:
+    - GITHUB_TOKEN
+    - OPENAI_API_KEY
+    - RELEASE_APPROVER     # Custom check
+```
+
+## Environment-Specific Configuration
+
+### Development
+
+```yaml
+# .kodrdriv/config.dev.yaml
+dryRun: true
+verbose: true
+model: gpt-4o-mini
+```
+
+### Production
+
+```yaml
+# .kodrdriv/config.prod.yaml
+dryRun: false
+model: gpt-4o
+release:
+  selfReflection: true
+publish:
+  sendit: true
+  skipUserConfirmation: true
+```
+
+Load with:
+```bash
+kodrdriv commit --config-dir .kodrdriv/config.prod.yaml
+```
+
+## Migration from Other Tools
+
+### From semantic-release
+
+**Before**:
+```json
+{
+  "release": {
+    "plugins": ["@semantic-release/commit-analyzer"]
+  }
+}
+```
+
+**After**: Remove semantic-release config, use kodrdriv:
+```bash
+kodrdriv publish
+```
+
+### From conventional-changelog
+
+**Before**:
+```bash
+conventional-changelog -p angular -i CHANGELOG.md -s
+```
+
+**After**:
+```bash
+kodrdriv release
+# Notes in output/RELEASE_NOTES.md
+```
+
+### From manual process
+
+**Before**:
+```bash
+git log --oneline > notes.txt
+# Manually write release notes
+gh release create v1.0.0 --notes "..."
+```
+
+**After**:
+```bash
+kodrdriv publish  # Does everything
+```
+
+## Verification
+
+### Test Your Integration
+
+1. **Dry Run Test**:
+```bash
+kodrdriv commit --dry-run
+kodrdriv release --dry-run
+kodrdriv publish --dry-run
+```
+
+2. **Check Output**:
+```bash
+ls output/
+# Should see timestamped files
+```
+
+3. **Verify Configuration**:
+```bash
+kodrdriv --check-config
+```
+
+4. **Test with Real Changes**:
+```bash
+echo "test" >> test.txt
+git add test.txt
+kodrdriv commit --verbose
+git reset HEAD test.txt
+rm test.txt
+```
+
+## Common Integration Patterns
+
+### Pattern 1: Manual Commit, Auto Release
+
+```yaml
+commit:
+  sendit: false           # Review commits manually
+
+release:
+  interactive: false      # Auto-generate notes
+
+publish:
+  sendit: true           # Fully automated
+```
+
+### Pattern 2: Auto Commit, Manual Release
+
+```yaml
+commit:
+  sendit: true           # Auto-commit
+
+release:
+  interactive: true      # Review release notes
+
+publish:
+  sendit: false          # Manual approval
+```
+
+### Pattern 3: Full Automation
+
+```yaml
+commit:
+  sendit: true
+
+release:
+  interactive: false
+
+publish:
+  sendit: true
+  skipUserConfirmation: true
+```
+
+## Next Steps
+
+- **[Usage Guide](./usage.md)** - Learn common workflows
+- **[Commands Reference](./commands.md)** - All available commands
+- **[Configuration Guide](./configuration.md)** - Advanced configuration options
+- **[Debugging Guide](./debugging.md)** - Troubleshooting help
+
+## Quick Tips
+
+1. **Always start with --dry-run** to preview
+2. **Use --verbose** to see what's happening
+3. **Enable selfReflection** to improve quality
+4. **Pass --context-files** for better context
+5. **Check output/** directory for generated files
+
+Your kodrdriv integration is complete! 🎉
+
+
+
+