awesome-copilot/CONFIG.md

# Configuration File System

The Awesome Copilot repository supports a configuration file system that allows you to easily manage which prompts, instructions, chat modes, and collections are included in your project.

## Installation

### Via Git Clone (Required)
```bash
# Clone the repository
git clone https://github.com/AstroSteveo/awesome-copilot
cd awesome-copilot

# Install dependencies
npm install

# Now you can use the CLI tool
node awesome-copilot.js help
```

**Note:** The `awesome-copilot` package is not yet published to npm, so you must clone the repository to use the CLI tool.

## Quick Start

### 1. Initialize Your Project

Navigate to your project directory where you want to add awesome-copilot customizations, then run:

```bash
# Initialize with default configuration
node /path/to/awesome-copilot/awesome-copilot.js init

# Or initialize with a specific name
node /path/to/awesome-copilot/awesome-copilot.js init my-project.config.yml
```

**Tip:** You can create an alias or add the awesome-copilot directory to your PATH for easier access:
```bash
# Add to your ~/.bashrc or ~/.zshrc
alias awesome-copilot="node /path/to/awesome-copilot/awesome-copilot.js"
```

This creates:
- Configuration file (`awesome-copilot.config.yml`)
- `.github/` directory structure
- VS Code settings pointing to `.github/` directories
- No changes to `.gitignore` (files in `.github/` are typically tracked)

### 2. Enable Desired Items

You can enable items either by editing the YAML file directly or by using the CLI helpers that toggle entries for you.

#### Option A: Edit the configuration file manually

Set items to `true` in the configuration file to include them:

```yaml
version: "1.0"
project:
  name: "My Project"
  description: "A project using awesome-copilot customizations"
  output_directory: ".github"
  # Recommended default is .github; explicit output_directory will be respected
prompts:
  create-readme: true
  editorconfig: true
  generate-tests: false
instructions:
  typescript-best-practices: true
  testing-standards: true
  react: false
chatmodes:
  architect: true
  dba: false
  specification: true
collections:
  frontend-web-dev: true
  csharp-dotnet-development: false
```

#### Option B: Manage items from the CLI (recommended for quick toggles)

```bash
# Inspect what is enabled in the default configuration file
node /path/to/awesome-copilot/awesome-copilot.js list instructions

# Enable a single prompt
node /path/to/awesome-copilot/awesome-copilot.js toggle prompts create-readme on

# Disable everything in a section
node /path/to/awesome-copilot/awesome-copilot.js toggle instructions all off

# Work with a named configuration file
node /path/to/awesome-copilot/awesome-copilot.js list prompts --config team.config.yml
```

The CLI prints the number of enabled items and estimates the combined size of their instructions/prompts so you can avoid exceeding Copilot Agent's context window. If the total size approaches a risky threshold, you'll see a warning.

### 3. Apply Configuration

```bash
# Apply default configuration file
node /path/to/awesome-copilot/awesome-copilot.js apply

# Or apply specific configuration file  
node /path/to/awesome-copilot/awesome-copilot.js apply my-project.config.yml
```

This will copy the enabled files to your project's `.github` directory (or the directory specified in the config).

## Configuration File Format

### Top-level Structure

```yaml
version: "1.0"                    # Required: Config format version
project:                          # Optional: Project metadata
  name: "My Project"              # Project name
  description: "Project desc"     # Project description  
  output_directory: ".github"     # Where to copy files (default: .github)
prompts: {}                       # Enable/disable prompts
instructions: {}                  # Enable/disable instructions
chatmodes: {}                     # Enable/disable chat modes
collections: {}                   # Enable/disable collections
```

### Individual Items

Set any item to `true` to include it, `false` to exclude it:

```yaml
prompts:
  create-readme: true             # Include this prompt
  generate-tests: false           # Exclude this prompt
```

### Collections

Collections are special - when you enable a collection, it automatically includes all items in that collection:

```yaml
collections:
  frontend-web-dev: true          # Includes all prompts, instructions, and chat modes in this collection
```

## Output Structure

When you apply a configuration, files are organized as follows:

```
.github/
├── prompts/
│   └── *.prompt.md             # Prompts for /awesome-copilot commands
├── chatmodes/
│   └── *.chatmode.md           # Chat modes for VS Code
└── instructions/
    └── *.instructions.md       # Instructions that auto-apply to coding
```

VS Code automatically detects these files through the generated `.vscode/settings.json` configuration.

## NPM Scripts

If you've cloned the repository locally, you can also use npm scripts:

```bash
# Initialize configuration
npm run config:init

# Apply configuration
npm run config:apply

# Access CLI help
npm run config help
```

## VS Code Integration

The `node awesome-copilot.js init` command automatically configures VS Code to detect your customizations:

- Creates `.vscode/settings.json` with proper file locations
- Points to `.github/` directories instead of framework directories
- Maintains separation between your project and the awesome-copilot framework

No manual VS Code configuration needed!

## GitHub Copilot Repository Instructions

Awesome Copilot can generate a `.github/copilot-instructions.md` file that provides repository-level instructions to GitHub Copilot. This feature supports GitHub's native repository instructions capability, which automatically applies instructions to all Copilot interactions within your repository.

### Generating Repository Instructions

```bash
# Generate basic repository instructions file
node /path/to/awesome-copilot/awesome-copilot.js generate-repo-instructions

# Generate with full instruction content included
node /path/to/awesome-copilot/awesome-copilot.js generate-repo-instructions --consolidated

# Custom output location
node /path/to/awesome-copilot/awesome-copilot.js generate-repo-instructions --output=.copilot/instructions.md

# Generate without header
node /path/to/awesome-copilot/awesome-copilot.js generate-repo-instructions --no-header
```

### Template Options

- **`repository` (default)**: Lists enabled instructions with references to individual files
- **`consolidated`**: Includes full content from all enabled instruction files
- **`basic`**: Simple list without detailed formatting

### Benefits of Repository Instructions

- **Automatic Application**: Instructions apply to all team members without manual configuration
- **Version Control**: Instructions are tracked with your code and evolve with your project
- **IDE Agnostic**: Works across VS Code, Visual Studio, GitHub Copilot CLI, and web interfaces
- **Consistency**: Ensures all team members get the same Copilot behavior
- **No Setup Required**: New team members automatically get proper instructions

### Integration with Configuration

The repository instructions are generated based on your enabled instructions in the configuration file:

```yaml
instructions:
  csharp: true       # Included in repository instructions
  python: true       # Included in repository instructions
  java: false        # Excluded from repository instructions
  
collections:
  testing-automation: true  # All instructions in this collection included
```

### Workflow Integration

Repository instructions work seamlessly with the existing workflow:

1. **Configure**: Enable instructions in your config file
2. **Apply**: Run `awesome-copilot apply` to copy files to your project
3. **Generate**: Run `generate-repo-instructions` to create the repository instructions file
4. **Commit**: Add the generated file to version control
5. **Collaborate**: Team members automatically get consistent Copilot behavior

## Examples

### Frontend React Project

```yaml
version: "1.0"
project:
  name: "React Frontend"
  output_directory: ".github"
collections:
  frontend-web-dev: true
prompts:
  create-readme: true
  editorconfig: true
chatmodes:
  specification: true
```

### Backend .NET Project

```yaml
version: "1.0"
project:
  name: ".NET API"
  output_directory: ".github"
collections:
  csharp-dotnet-development: true
instructions:
  testing-standards: true
prompts:
  create-specification: true
```

### Full Stack Project

```yaml
version: "1.0"
project:
  name: "Full Stack App"
  output_directory: ".github"
collections:
  frontend-web-dev: true
  csharp-dotnet-development: true
  database-data-management: true
chatmodes:
  architect: true
  specification: true
```

## Migration from Manual Approach

If you were previously copying files manually or using an older version:

1. Remove manually copied files from your `.github` directory
2. Clone awesome-copilot repository: `git clone https://github.com/AstroSteveo/awesome-copilot`
3. Run `node /path/to/awesome-copilot/awesome-copilot.js init` to create a clean setup
4. Edit the config to enable the same items you were using manually
5. Run `node /path/to/awesome-copilot/awesome-copilot.js apply` to get a clean, managed setup

The approach uses the standard `.github/` directory for Copilot customizations. If you previously used `.awesome-copilot/`, set `project.output_directory: ".awesome-copilot"` to keep that structure.

## Benefits

- **Centralized Management**: One file controls all your Copilot customizations
- **VS Code Integration**: Automatic configuration, no manual setup required
- **Clear Separation**: Framework files separated from your project files
- **Version Control Friendly**: Config file tracks what's enabled, generated files are ignored
- **Easy Updates**: Re-run apply command after awesome-copilot updates
- **Collection Support**: Enable entire curated sets with one setting
- **Minimal Footprint**: Only enabled files are copied to your project