Angular AI Instructions - GitHub Copilot Enhancement

Overview

The angular-ai-instructions package is a comprehensive CLI tool and npm package that automatically manages GitHub Copilot instruction files for Angular projects. It provides a seamless way to enhance your GitHub Copilot Chat experience by organizing and syncing Angular-specific development instructions directly into your workspace.

Core Capabilities

🤖 AI-Powered Development Enhancement

• Automatic GitHub Copilot Integration: Seamlessly integrates with GitHub Copilot Chat
• Angular-Specific Instructions: Curated Angular development best practices and patterns
• Multi-Category Organization: Instructions organized by development areas (Components, CLS, Documentation, etc.)
• Automatic File Synchronization: Syncs instructions on package installation and updates
• VS Code Configuration: Automatically configures Copilot instructions in VS Code settings
• CLI Tool Support: Manual sync commands for development workflows

🔧 Features

✅ Post-Install Sync - Automatically syncs instructions after npm install
✅ Update Hooks - Syncs updated instructions with npm update
✅ VS Code Integration - Configures .vscode/settings.json automatically
✅ CLI Commands - Manual sync capabilities via npx angular-ai
✅ Category-Based Organization - Structured instruction files by topic
✅ Root + Categorized Instructions - Global and specific guidance
✅ Customizable Structure - Support for custom instruction categories
✅ GitHub Actions Ready - Works with CI/CD workflows

Key Benefits

| Feature | Description | |---------|-------------| | Enhanced AI Assistance | Provides contextual Angular guidance to GitHub Copilot | | Development Standards | Enforces consistent Angular development practices | | Team Collaboration | Shared development guidelines across team members | | Automatic Updates | Instructions update automatically with package updates | | Flexible Organization | Category-based structure for different development areas |

Quick Start Guide

Installation & Setup (2 minutes)

1. Install the Package

# Install angular-ai-instructions in your Angular project
npm install angular-ai

# Or install globally for CLI access
npm install -g angular-ai-instructions

2. Automatic Setup

The package automatically:

• Copies instruction files to .github/copilot-instructions/
• Updates .vscode/settings.json with instruction paths
• Creates necessary directory structure
• Configures GitHub Copilot Chat integration

3. Manual Sync (if needed)

# Manually sync instructions
npx angular-ai sync

# Show available commands
npx angular-ai help

Usage Examples

Example 1: Automatic Installation

# In your Angular project directory
npm install angular-ai

# Package automatically:
# 1. Creates .github/copilot-instructions/ directory
# 2. Copies instruction files
# 3. Updates .vscode/settings.json
# 4. Configures GitHub Copilot Chat

Example 2: Development Workflow

# During development
npx angular-ai sync

# After updating the package
npm update angular-ai
npx angular-ai sync  # Manual sync for immediate updates

Example 3: Team Setup

# Team member clones repository
git clone <your-angular-project>
cd <your-angular-project>
npm install  # Instructions auto-sync

# Team now has consistent Copilot instructions

Example 4: CI/CD Integration

# In your CI/CD pipeline
npm install
npx angular-ai sync
npm run build

Package Structure

What Gets Installed

The package creates a structured set of instruction files and configurations:

project-root/
├── .github/
│   └── copilot-instructions/
│       ├── ROOT.md                          # Core Angular principles
│       ├── DOCUMENTATION.md                 # Documentation standards
│       ├── CLS/                             # Component Layout Structure
│       │   ├── routing.md                   # Routing guidelines
│       │   └── structure.md                 # Component organization
│       ├── components/                      # Component guidance
│       │   ├── best-practices.md            # Component best practices
│       │   └── testing.md                   # Component testing strategies
│       └── [additional categories...]       # Custom categories
│
└── .vscode/
    └── settings.json
        └── "github.copilot.chat.instructions": [
              ".github/copilot-instructions/ROOT.md",
              ".github/copilot-instructions/DOCUMENTATION.md",
              ".github/copilot-instructions/CLS/*.md",
              ".github/copilot-instructions/components/*.md"
              // ... additional category patterns
            ]

CLI Commands

Available Commands

npx angular-ai sync

Purpose: Manually synchronize instruction files to your project.

Usage:

npx angular-ai sync

What it does:

• Reads instruction files from the package
• Copies them to .github/copilot-instructions/
• Generates instruction paths based on folder structure
• Updates .vscode/settings.json with these paths
• Creates necessary directories if they don't exist

npx angular-ai help

Purpose: Display available commands and options.

Usage:

npx angular-ai help

Output:

Angular AI Instructions - GitHub Copilot Enhancement
Usage: angular-ai [command]

Commands:
  sync    Synchronize instruction files to your project
  help    Display this help message

Examples:
  npx angular-ai sync    # Sync instructions
  npx angular-ai help    # Show this help

Instruction Categories

Available Categories

1. ROOT.md

• Purpose: Core Angular development principles and guidelines
• Content: Fundamental Angular patterns, architecture decisions, best practices
• Usage: Global guidance for all Angular development

2. CLS/ (Component Layout Structure)

• routing.md: Angular routing guidelines and patterns
• structure.md: Component organization and structure best practices
• Purpose: Layout and structural guidance for Angular applications

3. components/

• best-practices.md: Component development best practices
• testing.md: Component testing strategies and patterns
• Purpose: Specific guidance for Angular component development

4. DOCUMENTATION.md

• Purpose: Documentation standards and guidelines
• Content: Code documentation, API documentation, inline comments

Custom Categories

You can extend the instruction set by:

1. Modifying the package: Add new categories to instructions/ directory
2. Creating your own fork: Customize instructions for your team's needs
3. Adding custom files: Include additional markdown files in existing categories

Configuration Details

VS Code Settings Integration

The package automatically updates your .vscode/settings.json:

{
  "github.copilot.chat.instructions": [
    ".github/copilot-instructions/ROOT.md",
    ".github/copilot-instructions/DOCUMENTATION.md",
    ".github/copilot-instructions/CLS/*.md",
    ".github/copilot-instructions/components/*.md"
  ]
}

Path Generation Rules

The package uses intelligent path generation:

• Root Files: Files in the root of instructions/ → Direct paths
• Category Files: Files in subdirectories → Wildcard patterns
• Dynamic Generation: Automatically handles new categories and files

Settings.json Backup

Before updating, the package:

1. Creates a backup of your existing settings.json
2. Merges new settings with existing ones
3. Preserves your custom settings

Package Scripts

Automatic Scripts

The package includes automatic execution scripts:

postinstall

npm run postinstall
# Automatically runs after: npm install angular-ai

prepare

npm run prepare
# Automatically runs after: npm install
# Also runs during: npm pack, npm publish

Manual Execution

# Run installation script manually
node bin/install.js

# Run CLI commands
node bin/cli.js sync
node bin/cli.js help

Customization and Development

Creating Custom Instructions

1. Fork the Package

git clone <repository-url>
cd angular-ai-instructions
npm install

2. Modify Instructions

Edit or add files in the instructions/ directory:

instructions/
├── ROOT.md                    # Edit existing
├── components/
│   ├── new-guide.md           # Add new files
│   └── custom-patterns.md     # Custom patterns
├── cls/
│   └── performance.md         # Add performance guidance
└── testing/
    ├── e2e-testing.md         # Add e2e guidance
    └── unit-testing.md        # Customize testing

3. Update Version

# Update package.json version
npm version patch  # or minor, major

4. Test Changes

# Test locally
npm install
npx angular-ai sync

# Test CLI commands
npx angular-ai help
npx angular-ai sync

5. Publish

# Publish to npm
npm publish

Adding New Categories

1. Create Directory Structure

mkdir instructions/new-category
touch instructions/new-category/new-guide.md

2. Update CLI Logic (if needed)

Edit src/index.js to handle new category structure:

// Add category handling logic
const categories = {
  'new-category': 'New Category Description'
};

Integration Examples

With Angular CLI Projects

# Create new Angular project
ng new my-angular-app
cd my-angular-app

# Install angular-ai-instructions
npm install angular-ai

# Instructions automatically sync
# GitHub Copilot Chat now has Angular guidance

With Existing Projects

# Navigate to existing project
cd my-existing-angular-app

# Install instructions
npm install angular-ai

# Sync immediately
npx angular-ai sync

# Verify integration
cat .vscode/settings.json

With Monorepo Projects

# In monorepo root
npm install angular-ai-instructions

# Install in specific workspace
npm install angular-ai-instructions --workspace=apps/web-app

# Sync instructions
npx angular-ai sync

With CI/CD Pipelines

# .github/workflows/ci.yml
name: CI
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'
      - run: npm install
      - run: npx angular-ai sync  # Ensure instructions are synced
      - run: npm run build

Troubleshooting

Common Issues

1. Instructions Not Syncing

Symptoms: No instruction files in .github/copilot-instructions/

Solutions:

# Check Node.js version (requires 14+)
node --version

# Manually run sync
npx angular-ai sync

# Check permissions
ls -la .vscode/
chmod 755 .vscode/

# Reinstall package
npm uninstall angular-ai
npm install angular-ai

2. VS Code Settings Not Updating

Symptoms: .vscode/settings.json not updated

Solutions:

# Backup and check settings.json
cp .vscode/settings.json .vscode/settings.json.backup
cat .vscode/settings.json

# Ensure valid JSON
# Manually sync if needed
npx angular-ai sync

# Check file permissions
chmod 644 .vscode/settings.json

3. CLI Commands Not Working

Symptoms: npx angular-ai command not found

Solutions:

# Clear npm cache
npm cache clean --force

# Reinstall package
npm uninstall angular-ai-instructions
npm install angular-ai-instructions

# Try with full path
node node_modules/.bin/angular-ai sync

4. GitHub Copilot Chat Not Loading Instructions

Symptoms: Copilot Chat doesn't show Angular-specific guidance

Solutions:

1. Restart VS Code after syncing instructions
2. Check VS Code settings for correct instruction paths
3. Verify GitHub Copilot Chat extension is installed and enabled
4. Reload VS Code window (Ctrl/Cmd + Shift + P → "Developer: Reload Window")

Debug Mode

Enable Debug Logging

# Add debug flag to see detailed output
DEBUG=angular-ai:* npx angular-ai sync

Check Package Contents

# List installed files
npm list angular-ai-instructions

# Check package contents
tar -tzf $(npm pack angular-ai-instructions.tgz)

Requirements and Dependencies

System Requirements

• Node.js: Version 14.0.0 or higher
• npm: Version 6.0.0 or higher
• GitHub Copilot Chat: VS Code extension required
• VS Code: For Copilot Chat integration

Package Dependencies

• fs-extra: File system operations
• path: Path manipulation utilities
• fs: Core file system operations

Verification Commands

# Check Node.js version
node --version

# Check npm version
npm --version

# Verify GitHub Copilot Chat
# (Check VS Code extensions)

# Test package installation
npm list angular-ai-instructions

Performance and Optimization

Installation Performance

• Fast Sync: Optimized file copying and minimal operations
• Incremental Updates: Only copies changed files
• Batch Processing: Processes multiple instruction files efficiently

Memory Usage

• Low Memory Footprint: Efficient file reading and processing
• Stream Processing: Handles large instruction files gracefully
• Cleanup: Automatically cleans temporary files

Best Practices

1. Run sync in CI/CD: Ensure consistent team instructions
2. Update regularly: Keep instructions current with Angular updates
3. Customize for team: Fork and customize for your team's needs
4. Monitor GitHub Copilot: Ensure extension is active and updated

License and Support

License

MIT License - See LICENSE file for details

Support

• GitHub Issues: Report bugs and feature requests
• Documentation: Check README and inline documentation
• Community: Engage with the Angular community

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Version History

• v1.0.4: Current version with enhanced CLI support
• v1.0.3: Added additional instruction categories
• v1.0.2: Improved VS Code integration
• v1.0.1: Initial release with basic instruction sync
• v1.0.0: Package creation and initial structure

Additional Resources

Related Tools

• GitHub Copilot: AI pair programmer for code completion
• Angular CLI: Command-line interface for Angular projects
• VS Code: Recommended IDE for Angular development
• Angular DevTools: Browser extension for Angular debugging

Documentation

• Angular Style Guide
• GitHub Copilot Documentation
• VS Code Settings Documentation

Community

• Angular Community: Join Angular Discord and forums
• GitHub Discussions: Participate in package discussions
• Stack Overflow: Ask questions with Angular and Copilot tags