Add AGENTS.md

.claude/skills/exercise-development/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: exercise-development
+description: Guidelines for creating and modifying Git-Mastery exercises. Use when developing new exercises, understanding exercise types, or following exercise patterns.
+---
+
+# Exercise Development
+
+## Quick Guide
+
+### Two Types of Content
+
+**Standard Exercises**: Structured learning with validation (1-2 hours to create)
+- Complete directory with download, verify, test, README
+- Automated validation using git-autograder
+- Comprehensive testing required
+
+**Hands-On Scripts**: Quick demonstrations without validation (5-10 min to create)
+- Single Python file in `hands_on/`
+- No validation, tests, or README
+- Focus on demonstration
+
+## When to Use Each Type
+
+| Use Standard Exercise When... | Use Hands-On Script When... |
+|------------------------------|----------------------------|
+| Need to assess understanding | Just demonstrating a concept |
+| Have specific success criteria | Exploring open-ended scenarios |
+| Want automated grading | Showing command effects |
+| Building structured curriculum | Quick experimentation |
+
+## Detailed Guides
+
+### Standard Exercises
+**[standard-exercises.md](standard-exercises.md)** - Complete guide to creating exercises with validation
+- Proposal and approval process
+- Scaffolding with `./new.sh`
+- Implementing download.py, verify.py, test_verify.py, README.md
+- Testing and troubleshooting
+
+### Hands-On Scripts
+**[hands-on-scripts.md](hands-on-scripts.md)** - Quick guide to creating demonstration scripts
+- When and why to create
+- Implementation steps
+- Common patterns
+- Examples
+
+## Quick Start
+
+### Create Standard Exercise
+```bash
+# 1. Get approval (create GitHub issue)
+# 2. Generate scaffolding
+./new.sh
+
+# 3. Implement required files:
+#    - download.py
+#    - verify.py
+#    - test_verify.py
+#    - README.md
+
+# 4. Test
+./test.sh <exercise-name>
+
+# 5. Quality check
+ruff format . && ruff check . && mypy <exercise-name>/
+```
+
+### Create Hands-On Script
+```bash
+# Use scaffolding
+./new.sh
+# Choose "hands-on"
+
+# Implement download(verbose: bool) function
+# Test manually
+python hands_on/<script_name>.py
+```
+
+## Exercise Conventions
+
+### Naming
+- **Directories**: kebab-case (`branch-forward`, `conflict-mediator`)
+- **Files**: snake_case (`download.py`, `test_verify.py`)
+- **Constants**: UPPER_SNAKE_CASE (`QUESTION_ONE`, `REPOSITORY_NAME`)
+
+### Required Elements (Standard Exercises)
+- `__init__.py` - Package marker
+- `.gitmastery-exercise.json` - Configuration
+- `download.py` - `setup(verbose: bool = False)`
+- `verify.py` - With `verify()` function
+- `test_verify.py` - With `REPOSITORY_NAME` and test functions
+- `README.md` - With scenario, task, hints
+
+### Required Elements (Hands-On)
+- `__requires_git__` and `__requires_github__` variables
+- `download(verbose: bool)` function
+
+## Examples
+
+### Standard Exercise Examples
+- **Simple**: `amateur_detective/` - Answer validation
+- **Branching**: `branch_bender/` - Branch operations
+- **Remote**: `remote_control/` - GitHub integration
+- **Complex**: `conflict_mediator/` - Merge conflicts
+
+### Hands-On Examples
+- `hands_on/add_files.py` - Staging demonstration
+- `hands_on/branch_delete.py` - Branch deletion
+- `hands_on/remote_branch_pull.py` - Remote operations
+
+## Related Skills
+
+- **[exercise-utils](../exercise-utils/SKILL.md)** - Utility functions reference

.claude/skills/exercise-development/hands-on-scripts.md

@@ -0,0 +1,96 @@
+# Creating Hands-On Scripts
+
+Hands-on scripts are simple demonstration scripts that show Git operations without validation or testing.
+
+## When to Create Hands-On Scripts
+
+Use hands-on scripts when:
+- Demonstrating how a Git command works
+- Showing effects of operations (e.g., what happens when you delete a branch)
+- Exploratory learning without right/wrong answers
+- Quick demonstrations that don't need validation
+- Teaching through observation rather than assessment
+
+## Implementation Steps
+
+### 1. Create Script File
+
+Use the scaffolding script:
+
+```bash
+./new.sh
+# Choose "hands-on" or "h"
+```
+
+**Prompts:**
+1. **Hands-on name**: Enter name after "hp-" prefix (e.g., entering "branch-demo" creates "hp-branch-demo")
+2. **Requires Git?**: Default yes (if script uses Git commands)
+3. **Requires GitHub?**: Default yes (set to no if script doesn't need GitHub CLI)
+
+**Generated file**: `hands_on/<name>.py` with `__requires_git__`, `__requires_github__`, and `download(verbose: bool)` function
+
+**Manual creation** (if needed):
+```bash
+touch hands_on/my_demo.py
+```
+
+### 2. Implement Required Variables
+
+`__requires_git__` and `__requires_github__` flags at top of file.
+
+### 3. Implement download() Function
+
+This is the only required function - it performs the demonstration.
+
+**Examples**: See [hands_on/branch_delete.py](../../../hands_on/branch_delete.py) or [hands_on/add_files.py](../../../hands_on/add_files.py).
+
+### 4. Focus on Demonstration
+
+Key principles:
+- **Use verbose output** to show what's happening
+- **Add print statements** to guide understanding
+- **Leave repository** in an interesting state for exploration
+- **Suggest commands** for users to run next
+
+## Common Patterns
+
+See examples in [hands_on/](../../../hands_on/) directory:
+- Simple Git operations: [branch_delete.py](../../../hands_on/branch_delete.py)
+- Branch operations: [create_branch.py](../../../hands_on/create_branch.py)
+- GitHub operations: [remote_branch_pull.py](../../../hands_on/remote_branch_pull.py)
+- Merge operations: Any merge-related script in hands_on/
+
+## Best Practices
+
+- Use helpful print statements with verbose flag
+- Leave repository in explorable state (multiple branches, commits)
+- Guide without prescribing (suggest commands, don't require)
+
+## Hands-On vs Standard Exercise
+
+| Aspect | Hands-On Script | Standard Exercise |
+|--------|----------------|-------------------|
+| **Purpose** | Demonstrate & explore | Teach & validate |
+| **Structure** | Single `.py` file | Complete directory |
+| **Files** | Just the script | download, verify, test, README |
+| **Validation** | None | Required |
+| **Testing** | Manual only | Automated with pytest |
+| **Instructions** | Optional comments | Required README.md |
+| **Success Criteria** | None | Defined rules |
+| **User Action** | Run and observe | Complete and verify |
+| **Creation Time** | 5-10 minutes | 1-2 hours |
+| **Use Case** | Demos, exploration | Structured learning |
+
+## Testing Hands-On Scripts
+
+No formal tests required, but manually verify by running the script and checking the created state.
+
+## Pre-Commit Checklist
+
+- ✓ Has `__requires_git__` and `__requires_github__`
+- ✓ Has `download(verbose: bool)` function
+- ✓ Uses utility functions (not raw subprocess)
+- ✓ Includes helpful verbose output
+- ✓ Creates interesting state to explore
+- ✓ Tested manually
+- ✓ Follows naming conventions (snake_case)