docs: expand AGENTS.md with actionable contributor guidance

[Tyler-R-Kendrick]

Overview

Optimized AGENTS.md from a minimal 21-line document into a comprehensive, actionable guide for contributors. The original document was terse and left many implementation details ambiguous.

Target File

• Path: AGENTS.md (repository root)
• Original size: 21 lines, 4 sections
• Optimized size: 362 lines, 6 sections (added TOC and Visual Validation)
• Selection reason: No existing trainer workspace; prioritized for fresh optimization

Workspace

• Local workspace: .trainer-workspace/AGENTS/
• Iteration: iteration-1
• Datasets created: 3 training cases, 2 validation cases covering contributor workflows

Key Improvements

1. Git Usage Section

• Added: Explanation of why git mv preserves file history
• Added: What breaks if you don't (git blame, history tracking)
• Added: Concrete bash command examples
• Benefit: Contributors understand the WHY behind the convention

2. Agent-Skills Workflow (NEW comprehensive section)

• Added: Full directory structure explanation
• Added: 6-step setup guide with exact paths and commands
• Added: Symlink rationale and cross-platform instructions
• Benefit: New contributors can complete setup without confusion

3. Code Development & Testing (EXPANDED)

• Added: Explicit definition of "100% coverage"
• Added: pytest-cov tool specification and invocation
• Added: Pre-commit checklist for code review
• Added: Python example testing edge cases
• Benefit: Contributors know exactly which tool and how to verify coverage

4. Scaffolding (EXPANDED)

• Added: Project-type-specific subsections (Python/uv, Node/npm, .NET/dotnet, Skills)
• Added: Real command examples for each
• Added: "What NOT to do" warning list
• Benefit: Contributors select the right tool with concrete examples

5. Visual Validation (NEW section)

• Added: Playwright introduction and benefits
• Added: Python and Node.js example code (fully working)
• Added: Step-by-step PR integration instructions
• Added: Best practices for visual testing
• Benefit: New capability now documented with working examples

Validation

• ✅ All 856 tests pass (baseline maintained)
• ✅ Markdown valid (no syntax errors)
• ✅ Five test scenarios covered: Each scenario addressing common contributor friction points now has clear, actionable answers
• ✅ Tone preserved: Maintains professional, friendly voice while being more instructional

Test Scenarios Addressed

1. New contributor setup: Complete paths and step-by-step instructions
2. Git workflow: Understanding why git mv is required
3. Test coverage: Explicit tool (pytest-cov) and verification steps
4. Scaffolding tool selection: 4 concrete examples with real commands
5. Visual validation: New section with Playwright examples and PR steps

Files Modified

• AGENTS.md: Expanded from 21 to 362 lines

Artifacts in Workspace

• Engineer prompt review: .trainer-workspace/AGENTS/engineer-prompt/review.md
• Training/validation datasets: .trainer-workspace/AGENTS/iterations/iteration-1/synthesize/{train,val}.jsonl
• Optimized candidate: .trainer-workspace/AGENTS/iterations/iteration-1/optimize/optimized-prompt.md
• Decision summary: .trainer-workspace/AGENTS/decision.md
• Validation log: .trainer-workspace/AGENTS/iterations/iteration-1/validation/pytest.txt

Why This Optimization

The expanded AGENTS.md directly addresses the most common contributor friction points identified in the engineer-prompt review. Each section now includes rationale, concrete examples, and step-by-step instructions that remove ambiguity.

Generated by Train Prompt · ● 1.3M · ◷

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: a38e0035-ab0e-4ee9-b390-a3240a8c6020

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch optimize-agents-md-f3a78466667ae2c9

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}