Research-Informed AI Workflow Module

A comprehensive, reusable system for AI-assisted software development and analysis workflows. This module provides structured, research-backed approaches to codebase analysis, optimization, and development assistance.

🎯 Overview

The Research-Informed AI Workflow is a systematic approach to software development that combines:

• Structured Code Analysis - 9 specialized analysis tasks covering security, performance, testing, and more
• Research Integration - External AI research to ensure best practices and modern approaches
• Automated Bundle Generation - Intelligent code bundling for optimal AI context
• Development Workflow Integration - Seamless integration with existing development processes

📦 What's Included

Core Components

.workflow-module/
├── bundles.json                    # Task configurations and metadata
├── Generate.ps1                   # PowerShell script for bundle generation
├── Validate-Setup.ps1             # Validation script for setup verification
├── setup.ps1                      # Setup script for initial configuration
├── README.md                      # This documentation
├── CONTRIBUTING.md                # Contribution guidelines
├── task_creation_template.md      # Template for creating new analysis tasks
├── .gitignore                    # Git ignore rules for the module
├── examples/                     # Example configurations for different project types
│   ├── README.md                 # Examples overview
│   ├── README.python.md          # Python project example
│   ├── bundles.example.nodejs.json
│   ├── bundles.example.python.json
│   ├── repomix.config.example.nodejs.json
│   └── repomix.config.example.python.json
└── tasks/                        # Analysis task instruction files
    ├── 01_comprehensive_analysis.md
    ├── 02_security_vulnerability_analysis.md
    ├── 03_testing_system_analysis.md
    ├── 04_performance_scalability_analysis.md
    ├── 05_dependency_management_analysis.md
    ├── 06_code_modernization_analysis.md
    ├── 07_error_handling_resilience_analysis.md
    ├── 08_documentation_quality_analysis.md
    └── 09_copilot_instructions_optimization.md

Analysis Tasks Available

1. Comprehensive Project Analysis - High-level architecture and improvement overview
2. Security Vulnerability Analysis - OWASP-based security audit
3. Testing System Analysis - Test coverage and quality assessment
4. Performance & Scalability Analysis - Bottleneck identification and optimization
5. Dependency Management Analysis - Security and maintenance of third-party packages
6. Code Modernization & Refactoring - Technical debt and modernization opportunities
7. Error Handling & Resilience Analysis - Fault tolerance and stability assessment
8. Documentation Quality Analysis - Documentation completeness and accuracy
9. Copilot Instructions Optimization - AI assistance context and workflow optimization

🚀 Quick Start

Prerequisites

• Node.js and npm (for Repomix bundle generation)
• PowerShell (for running the generation script)
• Repomix (npm install -g repomix)
• Access to Google AI Studio (Gemini) or similar AI platform
• External AI platform with web search capabilities (Claude, Gemini Web, etc.)

Basic Usage

1. Copy the module to your project:

   cp -r .workflow-module /path/to/your/project/
   cd /path/to/your/project/.workflow-module

2. Generate an analysis bundle:

   .\Generate.ps1 -TaskID "comprehensive-analysis"

3. Use the generated context:

   • Copy the contents of output/comprehensive-analysis/context.xml
   • Paste into Google AI Studio (Gemini)
   • Follow the AI-generated research plan
   • Implement the recommended improvements

✅ Validation & Setup Verification

Before using the module, validate your setup:

# Run comprehensive validation
.\Validate-Setup.ps1

# Validate specific task
.\Validate-Setup.ps1 -TaskID "comprehensive-analysis"

# Quick validation (syntax only)
.\Validate-Setup.ps1 -Quick

The validation script checks:

• ✅ PowerShell script syntax
• ✅ JSON configuration files
• ✅ Task instruction files
• ✅ Bundle patterns
• ✅ Dependencies (Node.js, Repomix)
• ✅ Integration between components

📚 Examples & Templates

The module includes example configurations for different project types:

Node.js Projects

# Copy Node.js example configuration
Copy-Item "examples\bundles.example.nodejs.json" ".\bundles.json"
Copy-Item "examples\repomix.config.example.nodejs.json" ".\repomix.config.json"

Python Projects

# Copy Python example configuration
Copy-Item "examples\bundles.example.python.json" ".\bundles.json"
Copy-Item "examples\repomix.config.example.python.json" ".\repomix.config.json"

See examples/README.md for detailed usage instructions for each project type.

📋 Workflow Process

Phase 1: Bundle Generation

# Generate a focused code bundle for analysis
.\Generate.ps1 -TaskID "[task-id]"

Phase 2: Research Plan Generation

• Paste the generated context.xml into Google AI Studio
• Gemini analyzes the bundle and generates targeted research prompts
• Research prompts are designed for external AI platforms

Phase 3: Research Execution

• Execute research prompts using AI platforms with web search
• Compile findings into comprehensive research reports
• Focus on modern best practices and current standards

Phase 4: Enhanced Analysis & Implementation

• Return to Gemini with research findings
• Generate enhanced analysis reports and TODO checklists
• Implement prioritized improvements using git workflows

⚙️ Configuration

Customizing Analysis Tasks

Edit bundles.json to modify existing tasks or add new ones:

{
  "id": "your-custom-analysis",
  "name": "Your Custom Analysis",
  "tags": ["custom", "analysis"],
  "instructionsFile": "tasks/10_your_custom_analysis.md",
  "bundle": [
    "src/",
    "custom-files/",
    "*.config"
  ]
}

Bundle Configuration

Each task in bundles.json includes:

• id: Unique identifier for the task
• name: Human-readable task name
• tags: Categorization tags for filtering
• instructionsFile: Path to task-specific instructions
• bundle: Array of file/directory patterns to include

Creating Custom Analysis Tasks

Use the provided template to create new analysis tasks:

1. Copy the template:

   Copy-Item "task_creation_template.md" "tasks\10_your_custom_analysis.md"

2. Edit the task file following the template structure

3. Add to bundles.json:

   {
     "id": "your-custom-analysis",
     "name": "Your Custom Analysis",
     "instructionsFile": "tasks/10_your_custom_analysis.md",
     "bundle": [
       "src/",
       "custom-files/",
       "*.config"
     ]
   }

4. Validate the new task:

   .\Validate-Setup.ps1 -TaskID "your-custom-analysis"

🔧 Integration Examples

Integrating with Existing Projects

1. Copy the module:

   cp -r .workflow-module /path/to/your/project/

2. Customize for your project:

   • Update bundle patterns in bundles.json
   • Modify task instructions as needed
   • Adjust file paths for your project structure

3. Set up project-specific configuration:

   # Create project-specific repomix config
   cp repomix.config.json repomix.config.project.json
   # Edit include/exclude patterns for your project

CI/CD Integration

Add to your CI/CD pipeline:

# .github/workflows/ai-analysis.yml
name: AI Analysis Workflow
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  ai-analysis:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install Repomix
        run: npm install -g repomix
      - name: Run AI Analysis
        run: |
          cd .workflow-module
          .\Generate.ps1 -TaskID "comprehensive-analysis"

🎨 Customization

Adding New Analysis Tasks

1. Create instruction file:

   cp tasks/01_comprehensive_analysis.md tasks/10_your_analysis.md
   # Edit the new file with your specific requirements

2. Update bundles.json:

   {
     "id": "your-analysis",
     "name": "Your Custom Analysis",
     "tags": ["custom"],
     "instructionsFile": "tasks/10_your_analysis.md",
     "bundle": ["your", "files", "here"]
   }

3. Test the new task:

   .\Generate.ps1 -TaskID "your-analysis"

Modifying Bundle Patterns

Update the bundle array in bundles.json to include/exclude files:

"bundle": [
  "src/**/*.py",        # Include all Python files in src/
  "tests/**/*.py",      # Include test files
  "!src/legacy/",       # Exclude legacy code
  "docs/**/*.md",       # Include documentation
  "pyproject.toml"      # Include project config
]

📊 Analysis Task Details

Comprehensive Project Analysis

• Files: 196 files, ~300K tokens
• Focus: Architecture, design patterns, scalability
• Use Case: New projects, team onboarding, major refactoring

Security Vulnerability Analysis

• Files: 124 files, ~180K tokens
• Focus: OWASP Top 10, secure coding practices
• Use Case: Security audits, compliance reviews

Performance & Scalability Analysis

• Files: 80 files, ~90K tokens
• Focus: Bottlenecks, async patterns, database optimization
• Use Case: Performance issues, scaling requirements

Testing System Analysis

• Files: 175 files, ~266K tokens
• Focus: Test coverage, mocking strategies, CI/CD integration
• Use Case: Test strategy planning, quality assurance

🔍 Troubleshooting

Common Issues

Repomix not found:

npm install -g repomix
repomix --version

Bundle generation fails:

• Check file paths in bundles.json
• Ensure Repomix has proper permissions
• Verify Node.js version compatibility

Large bundle sizes:

• Review and optimize include patterns
• Use more specific file patterns
• Exclude unnecessary directories

AI analysis issues:

• Ensure context.xml is complete
• Check for special characters in file paths
• Verify AI platform context limits

🤝 Contributing

Improving the Module

1. Fork and clone:

   git clone https://github.com/yourusername/ai-workflow-module.git
   cd ai-workflow-module

2. Create feature branch:

   git checkout -b feature/new-analysis-task

3. Make changes:

   • Add new task instructions
   • Update bundle configurations
   • Improve documentation

4. Test changes:

   .\Generate.ps1 -TaskID "your-new-task"

5. Submit pull request:

   • Ensure all tests pass
   • Update documentation
   • Provide usage examples

Reporting Issues

• Use GitHub Issues for bug reports
• Include error messages and reproduction steps
• Specify your environment (OS, Node.js version, etc.)

🤝 Community & Contributions

We welcome contributions from the community! See CONTRIBUTING.md for detailed guidelines on:

• Task Development - Creating new analysis tasks
• Code Contributions - Improving scripts and tooling
• Documentation - Enhancing examples and guides
• Testing - Adding validation and test cases

Getting Started with Contributions

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make your changes
4. Validate your changes: .\Validate-Setup.ps1
5. Submit a pull request

Areas for Contribution

• New Analysis Tasks - Specialized analysis for specific domains
• Language Support - Examples for additional programming languages
• Tool Integration - Integration with other AI platforms or tools
• Performance Optimization - Improving bundle generation speed
• Documentation - More examples and use cases

📄 License

This module is provided as-is for educational and development purposes. Feel free to modify and distribute according to your needs.

🙏 Acknowledgments

• Repomix - For intelligent code bundling
• Google AI Studio (Gemini) - For advanced code analysis
• PowerShell - For cross-platform automation
• Open source community - For inspiration and best practices

Ready to supercharge your development workflow with AI assistance? 🚀

Start with: .\Generate.ps1 -TaskID "comprehensive-analysis"

Running an Analysis

1. Open PowerShell in VS Code:

   # Navigate to the project root
   cd /path/to/your/project

2. Run the generation script with a task ID:

   .\Generate.ps1 -TaskID "comprehensive-analysis"

3. Copy the generated context.xml:

   • The script will create .workflow-module/output/comprehensive-analysis/context.xml
   • Copy the entire contents of this file

4. Paste into Google AI Studio:

   • Start a new chat with Gemini
   • Paste the context.xml content
   • Gemini will generate a research plan as its first output

5. Execute research prompts:

   • Use an external AI platform to execute each research prompt
   • Compile all research findings into a single document

6. Generate enhanced analysis:

   • Return to the original Gemini chat
   • Provide the research findings
   • Request the final enhanced analysis and TODO checklist

Output Structure

Generated bundles are stored in:

.workflow-module/output/
└── [task-id]/
    └── context.xml    # Self-contained analysis bundle

Configuration

The bundles.json file defines:

• Task IDs and names
• Associated instruction files
• Code bundles to include for each analysis
• Task metadata and tags

Integration with Development Workflow

The workflow generates:

• Enhanced Analysis Reports - Detailed findings with research-backed recommendations
• GitHub Copilot TODO Checklists - Step-by-step implementation guides
• Git commands - Branch creation and commit guidance
• Testing commands - Validation steps for changes

Best Practices

• Always run the research phase before implementing changes
• Use the generated TODO checklists to track progress
• Validate changes with the provided testing commands
• Keep research findings for future reference

Troubleshooting

• Ensure Repomix is installed: npm install -g repomix
• Verify all task instruction files exist in the tasks/ directory
• Check that the bundles.json configuration matches your file structure
• Ensure you have write permissions for the .workflow-module/output directory

Contributing

When adding new analysis tasks:

1. Create a new instruction file in the tasks/ directory
2. Add an entry to bundles.json with appropriate configuration
3. Test the bundle generation with the Generate.ps1 script
4. Update this README with the new task description