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

Environment Variables

This project uses .env files to manage environment-specific variables.

• .env.development: This file is for your local development environment. It should contain your actual secret keys, database URLs, etc. This file is included in .gitignore and should not be committed to the repository. To get started, you can copy the example file:

  cp .env.example .env.development

  Then, edit .env.development with your specific settings.

• .env.example: This file serves as a template for .env.development. It lists all the environment variables that the project expects, along with placeholder values. You can use this file as a reference to create your own .env.development file. This file should be committed to the repository.

Debugging with VS Code

This project includes pre-configured VS Code launch configurations in .vscode/launch.json to facilitate debugging.

• Debugging the CLI: To debug the main CLI application (src/cli.ts), open the "Run and Debug" view in VS Code (usually accessible via the bug icon in the activity bar or Ctrl+Shift+D / Cmd+Shift+D). Select the "Debug CLI" configuration from the dropdown and click the play button (Start Debugging). This will launch the CLI with the debugger attached, allowing you to set breakpoints, inspect variables, and step through the code.

• Debugging Tests: To debug Jest tests, select the "Debug Tests" configuration from the "Run and Debug" view. This configuration runs Jest with the --runInBand option, which is crucial for the debugger to correctly attach to the test processes. You can set breakpoints directly in your test files (*.test.ts) or in the source code being tested.

🔧 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