This PR adds a comprehensive AGENTS.md file that provides GitHub Copilot coding agents with detailed instructions on how to work effectively in the BigCommerce documentation repository.

What's Included

The instructions file provides:

• Complete setup workflow with validated commands and timing expectations
• Repository structure guide covering all key directories (docs/, reference/, assets/, etc.)
• Validation requirements for both MDX documentation and OpenAPI specification changes
• Development workflow from setup through validation to deployment
• Troubleshooting guide for common issues like linting errors and setup problems
• Explicit timeout recommendations with "NEVER CANCEL" warnings for all operations

Key Features

Exhaustively Validated Commands:

• npm ci - dependency installation (~1-30 seconds)
• npm run lint - MDX validation for 392+ files (~12 seconds)
• spectral lint - OpenAPI validation for 70+ YAML files (~32 seconds)

Repository-Specific Guidance:

• No traditional build process (documentation source files only)
• Production deployment via CircleCI integration
• Custom style guide linting and spell checking
• BigCommerce-specific terminology and glossary management

Comprehensive Coverage:

• Prerequisites (Node.js 18+, npm)
• File structure and navigation
• Validation scenarios for different change types
• External dependencies and tools
• Performance expectations and timing

File Location

The instructions are located in AGENTS.md in the repository root, following the open standard for AI coding agent instructions.

Validation Process

All commands and workflows in the instructions have been thoroughly tested:

• Fresh repository setup from scratch
• Complete validation workflow execution
• Test changes to verify linting catches issues
• Timing measurements for accurate timeout recommendations

The instructions follow the imperative tone requirement ("Run this command", "Do not do this") and include explicit warnings about not canceling long-running operations.

Fixes #1060.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.