Copilot instructions

1# Megarepo - AI Setup Repository
2 
3**ALWAYS follow these instructions first and only fallback to additional search and context gathering if the information here is incomplete or found to be in error.**
4 
5## Repository Overview
6 
7Megarepo is currently a minimal repository template designed for AI-related projects. The repository contains basic setup files and is configured for Node.js/Next.js development based on the .gitignore patterns.
8 
9## Current Repository State
10 
11**IMPORTANT**: This repository is currently in a minimal state with only basic setup files:
12- README.md (basic project description)
13- LICENSE (MIT license)
14- .gitignore (configured for Node.js/Next.js projects)
15 
16**DO NOT attempt to build, test, or run code** - there is no source code or build system present yet.
17 
18## Working Effectively
19 
20### Initial Repository Exploration
21```bash
22# Always start by understanding the current repository state
23ls -la
24git status
25find . -type f -name "*.json" -o -name "*.js" -o -name "*.ts" -o -name "*.md"
26```
27 
28### When Source Code is Added
29 
30The repository is pre-configured for Node.js/Next.js development. When source code is added, follow these patterns:
31 
32#### Node.js/Next.js Project Setup
33```bash
34# Check for package.json first
35ls package.json
36 
37# If package.json exists, install dependencies
38npm install
39# NEVER CANCEL: npm install typically takes 2-5 minutes. Set timeout to 10+ minutes.
40 
41# Common build commands (verify these exist in package.json first)
42npm run build
43# NEVER CANCEL: Build may take 5-45 minutes depending on project size. Set timeout to 60+ minutes.
44 
45# Common test commands
46npm test
47# NEVER CANCEL: Tests may take 5-15 minutes. Set timeout to 30+ minutes.
48 
49# Common development server
50npm run dev
51```
52 
53#### Pre-commit Validation
54When source code exists, always run these before committing:
55```bash
56# Check for linting configuration
57ls .eslintrc* eslint.config.* .prettierrc*
58 
59# Run linting if configured
60npm run lint
61 
62# Run formatting if configured  
63npm run format
64 
65# Run type checking if TypeScript
66npm run type-check
67```
68 
69## Repository Structure Expectations
70 
71Based on the .gitignore configuration, expect the following when the repository is populated:
72 
73```
74.
75├── README.md                 # Project documentation
76├── LICENSE                   # MIT license
77├── .gitignore               # Node.js/Next.js ignore patterns
78├── package.json             # Node.js dependencies and scripts
79├── package-lock.json        # Dependency lockfile
80├── next.config.js           # Next.js configuration (if Next.js)
81├── tsconfig.json            # TypeScript configuration (if TypeScript)
82├── .eslintrc.*              # ESLint configuration
83├── .prettierrc              # Prettier configuration
84├── src/                     # Source code directory
85│   ├── pages/               # Next.js pages (if Next.js)
86│   ├── components/          # React components
87│   └── utils/               # Utility functions
88├── public/                  # Static assets
89├── .next/                   # Next.js build output (ignored)
90├── build/                   # Build output (ignored)
91└── node_modules/            # Dependencies (ignored)
92```
93 
94## Validation Requirements
95 
96### Before Making Changes
971. **Always check current repository state first**:
98```bash
99   git status
100   ls -la
101   cat package.json  # Only if it exists
102```
103 
1042. **Verify build system exists before attempting builds**:
105```bash
106   # Check for package.json before running npm commands
107   test -f package.json && echo "Node.js project detected" || echo "No package.json found"
108```
109 
110### After Making Changes
1111. **When source code is present, always validate**:
112```bash
113   # Install dependencies if package.json exists
114   test -f package.json && npm install
115   
116   # Build if build script exists
117   test -f package.json && npm run build
118   
119   # Test if test script exists
120   test -f package.json && npm test
121   
122   # Lint if lint script exists
123   test -f package.json && npm run lint
124```
125 
1262. **Manual validation scenarios when application exists**:
127   - Start the development server and verify it loads
128   - Test basic functionality by navigating through the application
129   - Verify any API endpoints respond correctly
130   - Check console for errors
131 
132## Common Commands Reference
133 
134### Repository Information
135```bash
136# View current files
137ls -la
138 
139# Check git status
140git status
141 
142# View repository structure
143tree . -a -I 'node_modules|.git'  # If tree is available (use -a to show hidden files)
144find . -type f -not -path "./.git/*" -not -path "./node_modules/*" | sort
145```
146 
147### When Package.json Exists
148```bash
149# View available scripts
150cat package.json | grep -A 20 '"scripts"'
151 
152# Install dependencies
153npm install
154# TIMEOUT: 10+ minutes
155 
156# Common development commands (check package.json first)
157npm run dev        # Development server
158npm run build      # Production build
159npm run start      # Start production server
160npm run test       # Run tests
161npm run lint       # Run linter
162npm run format     # Format code
163```
164 
165## File Locations and Navigation
166 
167### Current Key Files
168- `/README.md` - Project overview and setup instructions
169- `/LICENSE` - MIT license terms
170- `/.gitignore` - Git ignore patterns (Node.js/Next.js focused)
171 
172### Expected Important Locations (when populated)
173- `/src/` - Main source code directory
174- `/src/pages/` - Next.js pages (if Next.js project)
175- `/src/components/` - React components
176- `/public/` - Static assets and files
177- `/package.json` - Project configuration and dependencies
178- `/next.config.js` - Next.js configuration
179- `/tsconfig.json` - TypeScript configuration
180 
181## AI Development Guidelines
182 
183Since this is an AI setup repository:
184 
1851. **Always verify AI-related dependencies** when they are added:
186```bash
187   # Common AI packages to look for
188   grep -E "(openai|langchain|tensorflow|pytorch|huggingface)" package.json
189```
190 
1912. **Environment variables for AI services**:
192```bash
193   # Check for environment configuration
194   ls .env* || echo "No environment files found"
195```
196 
1973. **API key management**:
198   - Never commit API keys
199   - Always use environment variables
200   - Check .env.example for required variables
201 
202## Troubleshooting
203 
204### Repository Appears Empty
205- This is expected in the current state
206- Check git branch: `git branch -a`
207- Look for other branches that might contain code
208 
209### Build Failures
210- First verify package.json exists: `ls package.json`
211- Clear dependencies and reinstall: `rm -rf node_modules package-lock.json && npm install`
212- Check Node.js version compatibility in package.json
213 
214### Development Server Issues
215- Verify port availability (typically 3000 for Next.js)
216- Check for environment variable requirements
217- Review console output for specific error messages
218 
219## Critical Reminders
220 
221- **NEVER CANCEL builds or long-running commands** - they may take 45+ minutes
222- **ALWAYS validate commands work** before assuming functionality exists
223- **CHECK for package.json** before running npm commands
224- **SET APPROPRIATE TIMEOUTS** - builds: 60+ minutes, tests: 30+ minutes
225- **VERIFY repository state** before attempting any operations