GitHub Copilot Instructions

This repo contains structured instructions for GitHub Copilot to ensure consistent, high-quality development practices across all projects.

File Structure

Core Instructions

• .github/instructions/general.instructions.md - Core principles, error handling, implementation standards, and quality requirements
• .github/instructions/workflow.instructions.md - Git flow management, commit practices, and automated task sequences
• .github/instructions/best-practices.instructions.md - Customizable coding standards and domain-specific rules
• .github/copilot-instructions.md - Repo-specific operating rules for Copilot

Language-Specific Instructions

• .github/instructions/python.instructions.md - Python coding standards, testing, and environment automation
• .github/instructions/typescript.instructions.md - TypeScript/React component development with tool integration
• .github/instructions/pascal.instructions.md - Pascal/Delphi syntax and conventions with build automation

Maximum Autonomy Features

Complete Tool Integration

• Pre-work analysis using semantic_search, file_search, and list_dir
• Environment automation using Python environment management tools
• Continuous validation using get_errors and testing tools
• Automated documentation using apply_patch
• Git workflow automation using run_in_terminal and git tools

Autonomous Development Cycle

1. Context Gathering: Understand project structure and patterns
2. Environment Setup: Configure development environment automatically
3. Implementation: Create/modify files with continuous validation
4. Testing: Execute tests and validate results automatically
5. Documentation: Update all documentation automatically
6. Git Management: Handle all git operations through automated tasks

Tool Usage Priorities

• Information Gathering: semantic_search, file_search, list_dir
• Development: create_file, apply_patch, get_errors
• Validation: runTests, create_and_run_task, get_task_output, run_in_terminal
• Completion: get_changed_files, automated git tasks

Key Features

Customizable Best Practices

• best-practices.instructions.md - Separate, editable coding standards
• Domain-specific rules - GAAP for financial apps, performance for compilers, etc.
• Project-specific overrides - Copy and customize for each project type
• Environment-specific standards - Development, testing, production guidelines

Enhanced Error Handling

• CRITICAL: AI stops immediately on indentation errors and waits for help
• Maximum 3 debugging attempts before requesting assistance
• Comprehensive error logging and handling requirements

Full Implementation Standards

• When asked to implement something (e.g., "simulate a PID controller"), provide complete, production-ready implementations
• No simple examples or placeholder code
• Comprehensive solutions with error handling, testing, and documentation

Automated Workflow

• Structured git-flow process with feature branches
• Atomic changes with comprehensive testing
• Automated file management and commit processes
• Complete documentation requirements

Usage

These instruction files are automatically loaded by GitHub Copilot when working in the workspace. The applyTo directives ensure that language-specific instructions are applied to the appropriate file types.

Helper Commands

• Scaffold: Creates a new project with instructions, git setup, and sensible defaults.

  • Command: aicommands-scaffold (installed via installer) or run scaffold_project.sh directly.
  • Features: instruction pinning, safe fetch/backups, trimmed .gitignore, staged commits, optional install prompt.

• Install Toolset: Installs helper commands into your PATH.

  • Script: scripts/install_scaffold.sh
  • Examples:
    • Install all: scripts/install_scaffold.sh --all --force
    • Remote fetch latest by tag: scripts/install_scaffold.sh --all --from-remote --ref v0.1.1

• Update Instructions: Safely fetch and apply instruction updates pinned to a ref.

  • Script: scripts/update_instructions.sh
  • Behavior: verifies host, allowlists *.instructions.md, backs up differences to .github/instructions.backup/ and writes .new files, optional apply-all, updates .github/instructions.VERSION.

• Agent Mode Switcher: Curates active agents by mode using symlinks.

  • Script: scripts/agent_mode.sh
  • Modes: development, security, dba, all → links into .github/agents.active.

Typical Workflow

• Start a project: aicommands-scaffold MyProject → accept post-install to add commands.
• Pin instructions: Choose a tag/commit when prompted; confirm in .github/instructions.VERSION.
• Update later: Run scripts/update_instructions.sh to fetch from a newer ref; review/apply .new files.
• Switch agent views: Run scripts/agent_mode.sh and pick a mode (supports gum).

Notes

• Backups live in .github/instructions.backup and are ignored by git.
• If gum is installed, scripts offer interactive selection; otherwise they fall back to simple prompts.
• Use annotated tags (e.g., v0.1.1) to anchor changes before updating instructions.

Quality Assurance

All instructions emphasize:

• GAAP compliance for accounting-related code
• Comprehensive testing with edge case coverage
• Clear documentation written at a 3rd-grade level
• Professional coding standards and best practices
• Modular, reusable code architecture