docs: improve documentation and add AI slop terminology for SEO

- Complete AGENTS.md with comprehensive development guide
- Add "AI slop" and "slop code" terminology to README for better SEO
- Update action.yml description to include slop code reference
- Add development workflow, testing guide, and troubleshooting sections

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: jdiegosierra

AGENTS.md

@@ -1,12 +1,14 @@
-# AGENTS.md
-
-TODO
+# Development Guide
 
 ## Project Overview
 
-GitHub Action that evaluates PR contributor quality using objective GitHub metrics to combat AI-generated spam. Analyzes
-user's contribution history and calculates a score (0-1000) based on PR merge rate, contributions to quality repos,
-community engagement, and more.
+**Contributor Report** is a GitHub Action that evaluates PR contributor quality using objective GitHub metrics to combat
+AI-generated spam PRs (also known as "AI slop" or "slop code"). It analyzes a contributor's GitHub activity history and
+calculates scores based on PR merge rate, contributions to quality repositories, community engagement, and behavioral
+patterns.
+
+The goal is to help open source maintainers identify low-quality, spam, or AI-generated contributions that waste
+maintainer time and resources, while being fair to legitimate contributors, especially newcomers.
 
 ## Common Commands
 
@@ -92,3 +94,50 @@ const { myFunction } = await import('../src/module.js')
 - Use `.js` extensions in imports (ESM requirement)
 - Document functions with JSDoc comments
 - Weights must sum to 1.0 for proper normalization
+- Always run tests before committing: `pnpm test`
+- Keep test coverage above 80%
+
+## Development Workflow
+
+1. Create a feature branch: `git checkout -b feature/your-feature`
+2. Make your changes in `src/`
+3. Add/update tests in `__tests__/`
+4. Run the full test suite: `pnpm run all`
+5. Bundle for distribution: `pnpm bundle`
+6. Commit changes (including `dist/` updates)
+7. Open a PR against `main`
+
+## Testing Locally
+
+To test the action locally with real GitHub data:
+
+1. Copy `.env.example` to `.env`
+2. Add your GitHub token and test repository details
+3. Run: `pnpm local-action`
+
+## Adding New Metrics
+
+1. Create new file in `src/metrics/your-metric.ts`
+2. Export a function that returns a `MetricResult`
+3. Add it to `src/metrics/index.ts`
+4. Add corresponding tests in `__tests__/metrics/`
+5. Update the scoring engine in `src/scoring/engine.ts`
+6. Document the metric in README.md
+
+## Troubleshooting
+
+**Tests failing with ESM errors?**
+
+- Ensure imports use `.js` extensions
+- Use `jest.unstable_mockModule()` for mocking
+- Import modules after mocking is set up
+
+**dist/ out of sync?**
+
+- Run `pnpm bundle` after any `src/` changes
+- The CI will fail if `dist/` is not up to date
+
+**Rate limits?**
+
+- Use a personal access token with higher limits
+- The action includes automatic rate limit handling

README.md

@@ -5,13 +5,14 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 A GitHub Action that evaluates contributor quality using objective GitHub metrics to help combat AI-generated spam PRs
-in open source projects.
+(AI slop) in open source projects.
 
 ## The Problem
 
-Open source maintainers are increasingly facing a flood of low-quality, AI-generated pull requests. These spam PRs waste
-maintainer time and resources. This action helps by analyzing the PR author's contribution history using objective
-metrics.
+Open source maintainers are increasingly facing a flood of low-quality, AI-generated pull requests (commonly known as
+"AI slop" or "slop code"). These spam PRs waste maintainer time and resources, cluttering repositories with
+minimal-value contributions. This action helps by analyzing the PR author's contribution history using objective metrics
+to identify potential spam or low-effort AI-generated contributions.
 
 ## How It Works
 

action.yml

@@ -1,5 +1,5 @@
 name: 'Contributor Report'
-description: 'Evaluate PR contributor quality using objective GitHub metrics to combat AI-generated spam'
+description: 'Evaluate PR contributor quality using objective GitHub metrics to combat AI-generated spam and slop code'
 author: 'jdiegosierra'
 
 branding: