Add AGENTS.md and AI-CONTRIBUTIONS.md documentation#67
Merged
Conversation
Creates two complementary documentation files: AGENTS.md - Instructions FOR AI agents on how to work on this codebase: - Project overview and tech stack - Setup and testing commands - Project structure and development workflow - Code style and conventions - CI/CD configuration details - Comprehensive dos and don'ts - Git commit and PR guidelines - Security considerations - Debugging tips and common issues - Links to external resources AI-CONTRIBUTIONS.md - Historical record OF AI agent contributions: - Overview of 11 PRs merged with AI assistance - Detailed breakdown by category (bugs, performance, testing) - Before/after metrics showing impact - Technology stack updates - Methodology and best practices - Links to all pull requests This follows the standard AGENTS.md format (instructions for future AI work) while preserving transparency about past AI contributions in a separate file. Benefits: - Future AI agents have clear guidance on project conventions - Reduces iteration cycles and improves AI code quality - Maintains transparency about AI collaboration - Provides debugging resources and common patterns - Documents security considerations and best practices Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
chorrell
force-pushed
the
add-agents-documentation
branch
from
5a36a89 to
89bad1f
Compare
chorrell
changed the title
Adds markdownlint enforcement and documentation standards to the project. Changes: .markdownlint.json - Configuration for markdown linting: - Line length: 120 chars (excludes code blocks and tables) - Enforces blank lines around headings and lists - Requires language specs for fenced code blocks - Standard markdown best practices AGENTS.md - Updated with markdown requirements: - Added "Documentation Standards" section - Instructions for running markdownlint - Added to DO list: lint markdown files before commit - Fixed all linting issues: - Split long lines - Added language specs to code blocks (text, bash) - Converted bold text to proper headings (####) - Proper blank lines around lists and headings AI-CONTRIBUTIONS.md - Fixed all linting issues: - Split long lines for readability - Converted PR titles from bold to proper headings (####) - Added blank lines around sections - Improved document structure All *.md files now pass: npx markdownlint-cli *.md Benefits: - Consistent markdown formatting across the project - Better readability and maintainability - Catches common markdown issues automatically - Standard enforced for human and AI contributors Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Creates two complementary documentation files following best practices:
AGENTS.md - Instructions for AI Coding Agents
A comprehensive guide telling future AI agents HOW to work on this codebase:
Key Sections
📋 Project Overview
⚡ Setup & Commands
📝 Documentation Standards (NEW!)
🗂️ Project Structure
🔧 Development Workflow
📝 Code Style & Conventions
🧪 Testing Instructions
✅ Dos and Don'ts
📋 Git & PR Guidelines
🔒 Security Considerations
🐛 Debugging
AI-CONTRIBUTIONS.md - Historical Record
Documents the 11 PRs that transformed this project with AI assistance:
.markdownlint.json - Quality Standards
Configuration for markdown linting:
Why These Files?
AGENTS.md (Standard):
AI-CONTRIBUTIONS.md (Transparency):
.markdownlint.json (Quality):
Comparison
Changes Made
✅ Created AGENTS.md with comprehensive AI agent instructions
✅ Created AI-CONTRIBUTIONS.md documenting 11 PRs
✅ Added .markdownlint.json configuration
✅ Fixed all linting issues in all markdown files
✅ Added Documentation Standards section to AGENTS.md
✅ All *.md files now pass:
npx markdownlint-cli *.mdBenefits
✅ Better AI Collaboration - Clear instructions reduce mistakes
✅ Faster Development - AI agents understand conventions immediately
✅ Quality Enforcement - Markdown linting catches issues early
✅ Transparency - Clear record of AI contributions
✅ Onboarding - New contributors (human or AI) get up to speed quickly
✅ Standards Compliance - Follows emerging AGENTS.md best practices
This provides operational guidance, transparency, AND quality enforcement! 📚✨