{"id":43646982,"url":"https://github.com/ambient-code/agentready","last_synced_at":"2026-04-02T13:55:11.092Z","repository":{"id":325430710,"uuid":"1101139767","full_name":"ambient-code/agentready","owner":"ambient-code","description":"Repo Optimizer: Assess git repositories for AI-assisted development readiness. Submit your score!","archived":false,"fork":false,"pushed_at":"2026-03-26T03:32:29.000Z","size":4713,"stargazers_count":117,"open_issues_count":11,"forks_count":39,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T23:56:59.292Z","etag":null,"topics":["ai-assisted-development","assessment-tool","code-quality","python"],"latest_commit_sha":null,"homepage":"https://ambient-code.github.io/agentready/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ambient-code.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmaps.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-21T08:51:33.000Z","updated_at":"2026-03-26T12:47:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ambient-code/agentready","commit_stats":null,"previous_names":["ambient-code/agentready"],"tags_count":111,"template":false,"template_full_name":null,"purl":"pkg:github/ambient-code/agentready","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fagentready","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fagentready/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fagentready/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fagentready/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ambient-code","download_url":"https://codeload.github.com/ambient-code/agentready/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ambient-code%2Fagentready/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31307351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assisted-development","assessment-tool","code-quality","python"],"created_at":"2026-02-04T19:01:44.880Z","updated_at":"2026-04-02T13:55:11.087Z","avatar_url":"https://github.com/ambient-code.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AgentReady Repository Scorer\n\n[![codecov](https://codecov.io/gh/ambient-code/agentready/branch/main/graph/badge.svg)](https://codecov.io/gh/ambient-code/agentready)\n[![Tests](https://github.com/ambient-code/agentready/actions/workflows/ci.yml/badge.svg)](https://github.com/ambient-code/agentready/actions/workflows/ci.yml)\n\nAssess git repositories against evidence-based attributes for AI-assisted development readiness.\n\n\u003e **📚 Research-Based Assessment**: AgentReady's attributes are derived from [comprehensive research](RESEARCH_REPORT.md) analyzing 50+ authoritative sources including **Anthropic**, **Microsoft**, **Google**, **ArXiv**, and **IEEE/ACM**. Each attribute is backed by peer-reviewed research and industry best practices. [View full research report →](RESEARCH_REPORT.md)\n\n## Overview\n\nAgentReady evaluates your repository across multiple dimensions of code quality, documentation, testing, and infrastructure to determine how well-suited it is for AI-assisted development workflows. The tool generates comprehensive reports with:\n\n- **Overall Score \u0026 Certification**: Platinum/Gold/Silver/Bronze based on comprehensive attribute assessment\n- **Interactive HTML Reports**: Filter, sort, and explore findings with embedded guidance\n- **Version-Control-Friendly Markdown**: Track progress over time with git-diffable reports\n- **Actionable Remediation**: Specific tools, commands, and examples to improve each attribute\n- **Schema Versioning**: Backwards-compatible report format with validation and migration tools\n\n## Quick Start\n\n### Container (Recommended)\n\n```bash\n# Login to GitHub Container Registry (required for private image)\npodman login ghcr.io\n\n# Pull container\npodman pull ghcr.io/ambient-code/agentready:latest\n\n# Create output directory\nmkdir -p ~/agentready-reports\n\n# Assess AgentReady itself\ngit clone https://github.com/ambient-code/agentready /tmp/agentready\npodman run --rm \\\n  -v /tmp/agentready:/repo:ro \\\n  -v ~/agentready-reports:/reports \\\n  ghcr.io/ambient-code/agentready:latest \\\n  assess /repo --output-dir /reports\n\n# Assess your repository\n# For large repos, add -i flag to confirm the size warning\npodman run --rm \\\n  -v /path/to/your/repo:/repo:ro \\\n  -v ~/agentready-reports:/reports \\\n  ghcr.io/ambient-code/agentready:latest \\\n  assess /repo --output-dir /reports\n\n# Open reports\nopen ~/agentready-reports/report-latest.html\n```\n\n[See full container documentation →](CONTAINER.md)\n\n### Python Package\n\n```bash\n# Install\npip install agentready\n\n# Assess AgentReady itself\ngit clone https://github.com/ambient-code/agentready /tmp/agentready\nagentready assess /tmp/agentready\n\n# Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n\n# Install dependencies\npip install -e \".[dev]\"\n```\n### Run Directly via uv (Optional, No Install Required)\n\nIf you use **uv**, you can run AgentReady directly from GitHub without cloning or installing:\n\n```bash\nuvx --from git+https://github.com/ambient-code/agentready agentready -- assess .\n```\n\nTo install it as a reusable global tool:\n\n```bash\nuv tool install --from git+https://github.com/ambient-code/agentready agentready\n```\n\nAfter installing globally:\n\n```bash\nagentready assess .\n```\n\n### Harbor CLI (for Benchmarks)\n\nHarbor is required for running Terminal-Bench evaluations:\n\n```bash\n# AgentReady will prompt to install automatically, or install manually:\nuv tool install harbor\n\n# Alternative: Use pip if uv is not available\npip install harbor\n\n# Verify installation\nharbor --version\n```\n\n**Skip automatic checks**: If you prefer to skip the automatic Harbor check (for advanced users):\n\n```bash\nagentready benchmark --skip-preflight --subset smoketest\n```\n\n### Assessment Only\n\nFor one-time analysis without infrastructure changes:\n\n```bash\n# Assess current repository\nagentready assess .\n\n# Assess another repository\nagentready assess /path/to/your/repo\n\n# Specify custom configuration\nagentready assess /path/to/repo --config my-config.yaml\n\n# Custom output directory\nagentready assess /path/to/repo --output-dir ./reports\n```\n\n### Example Output\n\n```\nAssessing repository: myproject\nRepository: /Users/username/myproject\nLanguages detected: Python (42 files), JavaScript (18 files)\n\nEvaluating attributes...\n[████████████████████████░░░░░░░░] 23/25 (2 skipped)\n\nOverall Score: 72.5/100 (Silver)\nAttributes Assessed: 23/25\nDuration: 2m 7s\n\nReports generated:\n  HTML: .agentready/report-latest.html\n  Markdown: .agentready/report-latest.md\n```\n\n## Features\n\n### Evidence-Based Attributes\n\nEvaluated across 13 categories:\n\n1. **Context Window Optimization**: CLAUDE.md files, concise docs, file size limits\n2. **Documentation Standards**: README structure, inline docs, ADRs\n3. **Code Quality**: Cyclomatic complexity, file length, type annotations, code smells\n4. **Repository Structure**: Standard layouts, separation of concerns\n5. **Testing \u0026 CI/CD**: Coverage, test naming, pre-commit hooks\n6. **Dependency Management**: Lock files, freshness, security\n7. **Git \u0026 Version Control**: Conventional commits, gitignore, templates\n8. **Build \u0026 Development**: One-command setup, dev docs, containers\n9. **Error Handling**: Clear messages, structured logging\n10. **API Documentation**: OpenAPI/Swagger specs\n11. **Modularity**: DRY principle, naming conventions\n12. **CI/CD Integration**: Pipeline visibility, branch protection\n13. **Security**: Scanning automation, secrets management\n\n### Tier-Based Scoring\n\nAttributes are weighted by importance:\n\n- **Tier 1 (Essential)**: 50% of total score - CLAUDE.md, README, types, layouts, lock files\n- **Tier 2 (Critical)**: 30% of total score - Tests, commits, build setup\n- **Tier 3 (Important)**: 15% of total score - Complexity, logging, API docs\n- **Tier 4 (Advanced)**: 5% of total score - Security scanning, performance benchmarks\n\nMissing essential attributes (especially CLAUDE.md at 10% weight) has 10x the impact of missing advanced features.\n\n### Interactive HTML Reports\n\n- Filter by status (Pass/Fail/Skipped)\n- Sort by score, tier, or category\n- Search attributes by name\n- Collapsible sections with detailed evidence\n- Color-coded score indicators\n- Certification ladder visualization\n- Works offline (no CDN dependencies)\n\n### Customization\n\nCreate `.agentready-config.yaml` to customize weights:\n\n```yaml\nweights:\n  claude_md_file: 0.15      # Increase importance (default: 0.10)\n  test_coverage: 0.05       # Increase importance (default: 0.03)\n  conventional_commits: 0.01  # Decrease importance (default: 0.03)\n  # Other attributes use defaults, rescaled to sum to 1.0\n\nexcluded_attributes:\n  - performance_benchmarks  # Skip this attribute\n\noutput_dir: ./custom-reports\n```\n\n## CLI Reference\n\n```bash\n# Assessment commands\nagentready assess PATH                   # Assess repository at PATH\nagentready assess PATH --verbose         # Show detailed progress\nagentready assess PATH --config FILE     # Use custom configuration\nagentready assess PATH --output-dir DIR  # Custom report location\n\n# Configuration commands\nagentready --validate-config FILE        # Validate configuration\nagentready generate-config               # Create example config\n\n# Research report management\nagentready research-version              # Show bundled research version\nagentready research validate FILE        # Validate research report\nagentready research init                 # Generate new research report\nagentready research add-attribute FILE   # Add attribute to report\nagentready research bump-version FILE    # Update version\nagentready research format FILE          # Format research report\n\n# Utility commands\nagentready --version                     # Show tool version\nagentready --help                        # Show help message\n```\n\n## Architecture\n\nAgentReady follows a library-first design:\n\n- **Models**: Data entities (Repository, Assessment, Finding, Attribute)\n- **Assessors**: Independent evaluators for each attribute category\n- **Services**: Scanner (orchestration), Scorer (calculation), LanguageDetector\n- **Reporters**: HTML and Markdown report generators\n- **CLI**: Thin wrapper orchestrating assessment workflow\n\n## Development\n\n### Run Tests\n\n```bash\n# Run all tests with coverage\npytest\n\n# Run specific test suite\npytest tests/unit/\npytest tests/integration/\npytest tests/contract/\n\n# Run with verbose output\npytest -v -s\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/ tests/\n\n# Sort imports\nisort src/ tests/\n\n# Lint code\nflake8 src/ tests/ --ignore=E501\n\n# Run all checks\nblack . \u0026\u0026 isort . \u0026\u0026 flake8 .\n```\n\n### Project Structure\n\n```\nsrc/agentready/\n├── cli/              # Click-based CLI entry point\n├── assessors/        # Attribute evaluators (13 categories)\n├── models/           # Data entities\n├── services/         # Core logic (Scanner, Scorer)\n├── reporters/        # HTML and Markdown generators\n├── templates/        # Jinja2 HTML template\n└── data/             # Bundled research report and defaults\n\ntests/\n├── unit/             # Unit tests for individual components\n├── integration/      # End-to-end workflow tests\n├── contract/         # Schema validation tests\n└── fixtures/         # Test repositories\n```\n\n## Research Foundation\n\nAll attributes are derived from evidence-based research with 50+ citations from:\n\n- Anthropic (Claude Code documentation, engineering blog)\n- Microsoft (Code metrics, Azure DevOps best practices)\n- Google (SRE handbook, style guides)\n- ArXiv (Software engineering research papers)\n- IEEE/ACM (Academic publications on code quality)\n\nSee `src/agentready/data/RESEARCH_REPORT.md` for complete research report.\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions welcome! Please ensure:\n\n- All tests pass (`pytest`)\n- Code is formatted (`black`, `isort`)\n- Linting passes (`flake8`)\n- Test coverage \u003e80%\n\n## Support\n\n- Documentation: See `/docs` directory\n- Issues: Report at GitHub Issues\n- Questions: Open a discussion on GitHub\n\n---\n\n**Quick Start**: `pip install -e \".[dev]\" \u0026\u0026 agentready assess .` - Ready in \u003c5 minutes!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fambient-code%2Fagentready","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fambient-code%2Fagentready","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fambient-code%2Fagentready/lists"}