Skip to content

AGENTS.md

Latest commit

 

History

History
184 lines (150 loc) · 7.2 KB

AGENTS.md

File metadata and controls

184 lines (150 loc) · 7.2 KB

AGENTS.md - CopilotAdventures Development Guide

Project Structure

CopilotAdventures is an educational repository featuring fantasy-themed coding challenges designed to teach GitHub Copilot's different interaction modes. The repository is organized as follows:

Directory Structure

CopilotAdventures/
├── Adventures/
│   ├── Agent/          # Autonomous AI agent mode challenges
│   └── Ask/            # Interactive chat mode challenges
├── Solutions/
│   ├── CSharp/         # C# solutions with centralized runner
│   ├── JavaScript/     # Standalone JavaScript solutions
│   └── Python/         # Standalone Python solutions
├── Data/
│   └── scrolls.txt     # Shared data for Eldoria adventure
├── Images/             # Adventure artwork (1456x832 landscape)
└── .github/
    └── copilot-instructions.md  # GitHub Copilot development guidelines

Adventure Organization

  • Agent Mode (Adventures/Agent/): Multi-file, autonomous project creation challenges
  • Ask Mode (Adventures/Ask/): Step-by-step collaborative learning challenges
  • Difficulty Levels: 1-Beginner/, 2-Intermediate/, 3-Advanced/
  • Parallel Variants: Each adventure has both -Agent.md and -Ask.md versions

Solutions Architecture

C# Centralized Pattern: Single Program.cs with switch-case adventure selector JavaScript/Python Standalone Pattern: Individual executable files per adventure

Coding Conventions

File Naming Standards

  • Adventure Files: The-[Name]-of-[Location]-[Mode].md
  • Solution Files: The-[Name]-of-[Location].[ext]
  • C# Classes: PascalCase matching adventure names (e.g., Tempora, Algora)
  • Fantasy Themes: Use mystical locations (Tempora, Algora, Lumoria, Eldoria)

Code Style Guidelines

  • Single-File Solutions: Complete adventure in one executable file
  • Console-Based I/O: All interaction through console for simplicity
  • Educational Comments: Include Copilot interaction patterns and prompts used
  • Fantasy Variable Naming: Align with adventure themes (clockTimes, scrollSecrets)
  • Self-Contained: Minimize external dependencies beyond standard libraries
  • Readability First: Prioritize educational value over optimization

Language-Specific Standards

C# Conventions

  • Use PascalCase for class names and public methods
  • Add new adventures to Program.cs switch statement
  • Implement mandatory Run() method for each adventure class
  • Use dotnet run [adventure-name] for execution

JavaScript/Python Conventions

  • Use camelCase for variables and functions
  • Direct execution: node filename.js or python filename.py
  • Include educational comments showing Copilot prompts
  • Handle console input/output consistently

Adventure Content Standards

  • Hero Images: Landscape format 1456x832 pixels
  • Structure: Background story → Objective → Prerequisites → Specifications → Tasks
  • Educational Focus: Demonstrate specific Copilot capabilities
  • Fantasy Theming: Maintain whimsical, adventure-based context
  • Learning Outcomes: Clear skill development goals

Testing Protocols

Solution Validation

  1. Functionality Testing: Verify each solution runs without errors
  2. Educational Value: Confirm adventure teaches intended Copilot skills
  3. Cross-Platform: Test solutions on multiple environments
  4. Documentation: Ensure clear instructions and expected outputs

Testing Commands

# C# Solutions
cd Solutions/CSharp
dotnet build
dotnet run [adventure-name]

# JavaScript Solutions  
cd Solutions/JavaScript
node The-[Adventure-Name].js

# Python Solutions
cd Solutions/Python
python The-[Adventure-Name].py

Quality Checklist

  • Solution executes successfully
  • Console output matches expected format
  • Educational comments are clear and helpful
  • Fantasy theme is consistent
  • Copilot interaction patterns are demonstrated
  • No external dependencies beyond standard libraries

Pull Request Guidelines

PR Title Format

Use: New Copilot Adventure: [Your Adventure Name] for new adventures

PR Content Requirements

  • Difficulty Level: Specify beginner, intermediate, or advanced
  • Adventure Template: Follow existing markdown structure in Adventures folder
  • Hero Image: Include landscape artwork (1456x832 pixels) using Microsoft Copilot Image Creator
  • Solution Code: Provide complete solution in single file within appropriate Solutions language folder
  • Educational Value: Demonstrate specific GitHub Copilot features or interaction modes

PR Description Template

## Adventure Details
- **Name**: [Adventure Name]
- **Difficulty**: [Beginner/Intermediate/Advanced]
- **Copilot Mode**: [Agent/Ask/Both]
- **Language**: [C#/JavaScript/Python]

## Learning Objectives
- [ ] Demonstrate [specific Copilot feature]
- [ ] Teach [programming concept]
- [ ] Practice [development skill]

## Files Included
- [ ] Adventure markdown file(s)
- [ ] Hero image (1456x832 landscape)
- [ ] Complete solution code
- [ ] Updated Program.cs (if C#)

## Testing Completed
- [ ] Solution builds and runs successfully
- [ ] Educational content is clear and engaging
- [ ] Fantasy theme is consistent
- [ ] Copilot interaction patterns are evident

Review Criteria

  1. Educational Value: Does the adventure effectively teach Copilot usage?
  2. Code Quality: Is the solution clean, well-commented, and functional?
  3. Template Compliance: Does it follow the established adventure structure?
  4. Fantasy Theme: Is the adventure content engaging and thematically consistent?
  5. Technical Requirements: Are all files properly formatted and executable?

Contribution Workflow

  1. Fork the repository
  2. Create adventure content following templates
  3. Test solution thoroughly
  4. Submit PR with complete documentation
  5. Address review feedback
  6. Merge after approval

GitHub Copilot Integration

Mode-Specific Development

  • Agent Mode: Use for autonomous project creation and multi-file coordination
  • Ask Mode: Use for step-by-step learning and explanation-driven development
  • Edit Mode: Use for iterative improvements and multi-file modifications

Best Practices

  • Include actual Copilot prompts used in solution comments
  • Demonstrate progressive enhancement with Copilot assistance
  • Show how different modes complement each other
  • Provide clear examples of effective Copilot interaction patterns

Common Adventure Patterns

Algorithm Categories

  • Time Synchronization: Parse time strings, calculate differences
  • Sequence Prediction: Pattern recognition in arrays
  • Data Filtering: Extract information using regex patterns
  • Grid Simulation: 2D array manipulation for game mechanics
  • Logic Implementation: Conditional rule systems

Data Processing Examples

  • Eldoria scrolls: Extract secrets using {*...*} pattern
  • Tempora clocks: Time arithmetic and synchronization
  • Mythos grids: 2D coordinate systems and pathfinding
  • Chamber echoes: Number sequence pattern recognition

This documentation ensures consistent, high-quality contributions that enhance the educational value of CopilotAdventures while maintaining its engaging fantasy theme.