@stillrivercode/agentic-workflow-template/docs/idk-stillriver-integration.md

NPM package to create AI-powered GitHub workflow automation projects

# IDK + stillriver-ai-workflows Integration

This document describes the integration between Information Dense Keywords (IDK) and stillriver-ai-workflows for enhanced PR automation.

## Overview

The integration combines:

- **IDK (Information Dense Keywords)**: Standardized AI command vocabulary for development tasks
- **stillriver-ai-workflows**: GitHub Action for automated AI code reviews on pull requests

## Integration Architecture

### IDK Dictionary Location

- **Path**: `docs/dictionary/` and `docs/AI.md`
- **Access**: Via `npx @stillrivercode/information-dense-keywords docs`
- **Purpose**: Provides standardized command vocabulary for AI assistants

### stillriver-ai-workflows Integration

- **Workflow**: `.github/workflows/ai-pr-review.yml`
- **Action**: `stillrivercode/stillriver-ai-workflows@v1`
- **Purpose**: Automated AI code reviews using OpenRouter API

## Enhanced PR Workflow

### 1. PR Creation with IDK Commands

Users can create PRs using IDK command vocabulary:

```bash
# Example IDK commands for PR operations
npx @stillrivercode/information-dense-keywords "pr create this feature with comprehensive review"
npx @stillrivercode/information-dense-keywords "review this pull request for security concerns"
```

### 2. Automated AI Review

When a PR is opened or labeled with `ai-review-needed`:

1. **Test Validation**: Ensures tests are passing before review
2. **AI Review**: Uses stillriver-ai-workflows for comprehensive analysis
3. **Label Management**: Adds appropriate labels based on review outcomes
4. **Comment Posting**: Automated AI review comments on the PR

### 3. Integration Features

#### Enhanced Review Prompts

- The AI review system leverages IDK vocabulary for structured analysis
- Reviews follow IDK patterns for consistency and clarity
- AI assistants understand IDK command context when reviewing code

#### Workflow Configuration

```yaml
- name: Run AI Review via stillriver-ai-workflows
  uses: stillrivercode/stillriver-ai-workflows@v1
  with:
    github_token: ${{ github.token }}
    openrouter_api_key: ${{ secrets.OPENROUTER_API_KEY }}
    model: ${{ vars.AI_MODEL || 'anthropic/claude-sonnet-4' }}
    review_type: 'full'
    max_tokens: 4000
    temperature: 0.3
```

#### Supported Models

- **anthropic/claude-sonnet-4** (default)
- **anthropic/claude-3.5-sonnet**
- **openai/gpt-4-turbo**
- **google/gemini-pro**

## IDK Command Categories for PR Operations

### Core Commands

- **CREATE** - Generate new PR with comprehensive description
- **SELECT** - Choose specific files or changes for review
- **FIX** - Address issues identified in PR review
- **DELETE** - Remove unnecessary changes from PR

### Development Commands

- **analyze this** - Examine PR changes for patterns and issues
- **debug this** - Investigate issues found in PR review
- **optimize this** - Improve performance of PR changes

### Quality Assurance Commands

- **review this** - Perform comprehensive PR code review
- **test this** - Generate or validate tests for PR changes

### Git Operations

- **pr** - Pull request operations (create, merge, review)
- **commit** - Create well-formatted commits for PR
- **push** - Push PR changes to remote repository

## Usage Examples

### 1. Creating a PR with IDK

```bash
# Plan the feature first
npx @stillrivercode/information-dense-keywords "plan this user authentication feature"

# Create specification
npx @stillrivercode/information-dense-keywords "spec this OAuth2 implementation"

# Create PR with comprehensive description
gh pr create --title "feat: add OAuth2 authentication" --body "Implements user authentication as planned in spec"
```

### 2. Requesting AI Review

```bash
# Add label to trigger AI review
gh pr edit --add-label "ai-review-needed"

# Or use IDK command for review request
npx @stillrivercode/information-dense-keywords "review this pull request for security and performance"
```

### 3. Following Up on Review

```bash
# Address security concerns identified
npx @stillrivercode/information-dense-keywords "fix security vulnerabilities identified in PR review"

# Optimize performance issues
npx @stillrivercode/information-dense-keywords "optimize this database query performance"
```

## Configuration

### Required Secrets

- `OPENROUTER_API_KEY`: API key for OpenRouter service
- `GH_PAT`: GitHub Personal Access Token (repo scope)

### Optional Variables

- `AI_MODEL`: Specify which AI model to use for reviews
- `AI_DEBUG_MODE`: Enable debug logging for troubleshooting

### Labels

- `ai-review-needed`: Triggers AI review workflow
- `ai-reviewed`: Added after successful AI review
- `ai-review-failed`: Added when AI review fails

## Benefits

### For Developers

- **Standardized Commands**: Consistent vocabulary across all AI interactions
- **Automated Reviews**: Comprehensive code analysis without manual effort
- **Multi-Model Support**: Choice of AI models via OpenRouter
- **Cost Efficient**: Built-in usage controls and monitoring

### For Teams

- **Consistent Quality**: Standardized review patterns across all PRs
- **Faster Feedback**: Immediate AI insights on code changes
- **Security Focus**: Automated security concern identification
- **Documentation**: Clear command vocabulary for all team members

## Best Practices

### 1. IDK Command Usage

- Use precise IDK keywords for consistent results
- Chain commands for complex workflows: "analyze this then review this then optimize this"
- Follow IDK expected output formats for structured feedback

### 2. PR Review Process

- Ensure tests pass before requesting AI review
- Address AI feedback systematically using IDK commands
- Use specific review types (security, performance) when appropriate

### 3. Workflow Optimization

- Set appropriate model for task complexity
- Monitor API usage to control costs
- Use debug mode for troubleshooting workflow issues

## Troubleshooting

### Common Issues

1. **AI Review Not Triggering**
   - Check that `ai-review-needed` label is applied
   - Verify tests are passing
   - Ensure OpenRouter API key is configured

2. **Review Quality Issues**
   - Try different AI models via `AI_MODEL` variable
   - Adjust temperature and max_tokens parameters
   - Use specific review types for focused analysis

3. **IDK Command Issues**
   - Ensure IDK is installed in `docs/` directory
   - Check that `docs/AI.md` exists and is properly formatted
   - Verify command syntax matches IDK dictionary patterns

## Related Documentation

- [IDK Dictionary](information-dense-keywords.md) - Complete command vocabulary
- [AI Workflow Guide](ai-workflow-guide.md) - Comprehensive workflow instructions
- [stillriver-ai-workflows](https://github.com/stillrivercode/stillriver-ai-workflows) - GitHub Action documentation
- [OpenRouter API](https://openrouter.ai) - Multi-model AI API service