Copilot Instructions Builder CLI

A powerful CLI application for building GitHub Copilot instruction files from modular, hierarchical components. Create sophisticated instruction sets using a three-tier architecture: Base Instructions → Domain-Specific Layers → Task-Specific Modules.

🚀 Features

• Hierarchical Module System: Compose instructions from base, domain, and task-specific modules
• Smart Dependency Resolution: Automatic dependency management with cycle detection
• Intelligent Conflict Resolution: Handle module conflicts with multiple resolution strategies
• Advanced Merging: Smart content merging with semantic understanding
• Template Variables: Dynamic content generation with variable substitution
• Conditional Instructions: Include/exclude sections based on context and conditions
• Priority-Based Ordering: Sophisticated priority calculation for optimal instruction ordering
• Interactive CLI: Both command-driven and configuration-driven workflows
• Performance Optimized: Caching, lazy loading, and parallel processing

📋 Quick Start

Installation

npm install -g copilot-instructions

Initialize a New Project

copilot-instructions init

Quick Build with Modules

# Build with specific modules
copilot-instructions build --base programming-fundamentals --domain frontend/react --task ui-components

# Build from configuration file
copilot-instructions build

# Build specific profile
copilot-instructions build --profile production

List Available Modules

# List all modules
copilot-instructions list

# Filter by type and tags
copilot-instructions list --type domain --tags react,frontend

🏗️ Architecture Overview

Hierarchical Instruction System

Base Instructions (Foundation)
    ↓
Domain Layers (Technology-specific)
    ↓
Task Modules (Use case-specific)
    ↓
.copilot-instructions.md (Output)

Module Types

• Base Instructions: General programming principles, code quality, documentation standards
• Domain Layers: Technology-specific guidance (React, Node.js, Python, etc.)
• Task Modules: Specific use cases (API development, UI components, testing, etc.)

📁 Project Structure

copilot-instructions-builder/
├── src/
│   ├── core/                    # Core composition engine
│   │   ├── composer.js          # Main instruction composition
│   │   ├── resolver.js          # Dependency resolution
│   │   ├── conflict-resolver.js # Conflict handling
│   │   └── ...
│   ├── modules/                 # Module management
│   ├── commands/                # CLI commands
│   └── utils/                   # Utilities and helpers
├── modules/                     # Built-in instruction modules
│   ├── base/                    # Foundation modules
│   ├── domains/                 # Technology-specific modules
│   └── tasks/                   # Use case modules
└── templates/                   # Output templates

🔧 CLI Commands

Core Operations

# Initialize project configuration
copilot-instructions init

# List available modules
copilot-instructions list [--type base|domain|task] [--tags react,frontend]

# Build instructions from modules
copilot-instructions build --base programming-fundamentals --domain frontend/react --task ui-components

# Add module to existing config
copilot-instructions add frontend/vue

# Validate configuration
copilot-instructions validate

# Show module dependencies
copilot-instructions deps frontend/react

# Search modules
copilot-instructions search "api development"

Configuration-Driven Operations

# Build from configuration file
copilot-instructions build

# Build specific profile
copilot-instructions build --profile production

# Use custom config file
copilot-instructions build --config ./configs/backend.config.js

# Build all profiles
copilot-instructions build --all-profiles

📝 Module Structure

Each instruction module follows a standardized JSON format:

{
  "id": "module-identifier",
  "name": "Module Display Name",
  "type": "base|domain|task",
  "version": "1.0.0",
  "dependencies": ["required-module-ids"],
  "conflicts": ["conflicting-module-ids"],
  "tags": ["react", "frontend", "ui"],
  "priority": 100,
  "metadata": {
    "description": "Module description",
    "author": "author-name",
    "category": "frontend|backend|testing|devops|general"
  },
  "instructions": {
    "sections": [
      {
        "id": "section-identifier",
        "title": "Section Title",
        "priority": 100,
        "merge_strategy": "replace|append|prepend|smart_merge",
        "content": ["instruction 1", "instruction 2"],
        "conditions": {
          "include_if": ["tag1", "tag2"],
          "exclude_if": ["tag3"],
          "require_modules": ["module-id"]
        }
      }
    ]
  },
  "variables": {
    "projectName": "{{PROJECT_NAME}}",
    "framework": "{{FRAMEWORK}}"
  }
}

🎯 Key Features

Smart Dependency Resolution

• Cycle Detection: Prevents circular dependencies with detailed error reporting
• Topological Sorting: Ensures correct module loading order
• Conflict Detection: Identifies and resolves module conflicts automatically

Intelligent Merging

• Content-Aware: Understands different types of content (rules, examples, guidelines)
• Deduplication: Removes duplicate instructions automatically
• Priority-Based: Respects module and section priorities during merging

Template Variables

{
  "variables": {
    "projectName": "{{PROJECT_NAME}}",
    "framework": "{{FRAMEWORK || 'React'}}"
  }
}

Supports:

• Simple variables: {{VAR}}
• Default values: {{VAR || 'default'}}
• Function calls: {{func(args)}}

Conditional Instructions

{
  "conditions": {
    "include_if": ["react", "frontend"],
    "exclude_if": ["vue"],
    "require_modules": ["base-frontend"],
    "conflict_with": ["legacy-module"]
  }
}

⚙️ Configuration

Project Configuration File

Create a copilot-instructions.config.js file:

module.exports = {
  profiles: {
    development: {
      modules: [
        'programming-fundamentals',
        'frontend/react',
        'ui-components'
      ],
      variables: {
        PROJECT_NAME: 'My App',
        FRAMEWORK: 'React'
      }
    },
    production: {
      modules: [
        'programming-fundamentals',
        'frontend/react',
        'ui-components',
        'performance-optimization'
      ]
    }
  },
  output: {
    file: '.copilot-instructions.md',
    template: 'default'
  }
};

🔍 Examples

Building a React Frontend Project

# Quick command approach
copilot-instructions build \
  --base programming-fundamentals,code-quality \
  --domain frontend/react \
  --task ui-components,performance-optimization

# Configuration approach
copilot-instructions init
# Edit copilot-instructions.config.js
copilot-instructions build --profile frontend

Building a Node.js API

copilot-instructions build \
  --base programming-fundamentals,documentation \
  --domain backend/nodejs \
  --task api-development,database-design

Custom Module Discovery

# Search for modules
copilot-instructions search "testing"
copilot-instructions search "performance"

# List modules by category
copilot-instructions list --type task --tags api,backend

🛠️ Development

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes
4. Add tests for new functionality
5. Run tests: npm test
6. Submit a pull request

Adding Custom Modules

Create new modules in the modules/ directory following the module structure. See our architecture documentation for detailed guidelines.

Testing

# Run all tests
npm test

# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:performance

🔧 Advanced Features

Error Handling

The CLI provides detailed error messages and recovery suggestions:

• Circular Dependencies: Suggests breaking changes
• Module Conflicts: Offers interactive resolution
• Invalid Configuration: Provides schema validation help
• Template Errors: Includes variable debugging information

Performance Optimizations

• Lazy Loading: Modules loaded only when needed
• Incremental Builds: Only rebuild changed dependencies
• Parallel Processing: Concurrent resolution of independent modules
• Multi-level Caching: Optimized module and result caching

📚 Documentation

• Architecture Plan - Detailed technical architecture
• Configuration Guide - Configuration options and examples
• Module Development - Creating custom modules
• API Reference - Programmatic usage

🤝 Support

• 📧 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Wiki: Project Wiki

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• GitHub Copilot team for the inspiration
• Contributors and community members
• Open source projects that made this possible

---

Built with ❤️ for better AI-assisted development