|
1 | | -# AgentReady |
2 | | - |
3 | | -Assess repositories against evidence-based attributes for AI-assisted development readiness. |
4 | | - |
5 | | -## Quick Reference |
6 | | - |
7 | | -| Item | Value | |
8 | | -|------|-------| |
9 | | -| **Python** | >=3.12 | |
10 | | -| **Entry Point** | `agentready.cli.main:cli` (or `python -m agentready`) | |
11 | | -| **Self-Score** | 80.0/100 (Silver) | |
12 | | -| **Test Coverage** | 37% (target: >80%) | |
13 | | - |
14 | | -## Commands |
15 | | - |
16 | | -```bash |
17 | | -# Core |
18 | | -agentready assess <repo> # Assess repository |
19 | | -agentready bootstrap <repo> # Setup agent-ready infrastructure |
20 | | -agentready align <repo> # Automated remediation |
21 | | - |
22 | | -# Development |
23 | | -pytest # Run tests |
24 | | -pytest --cov=src/agentready # With coverage |
25 | | -black . && isort . && ruff check . # Lint |
26 | | - |
27 | | -# Local development (uses this checkout, not the installed package) |
28 | | -PYTHONPATH=src python -m agentready assess <repo> |
29 | | - |
30 | | -# Benchmarks (requires: uv tool install harbor) |
31 | | -agentready harbor compare -t task1 -t task2 |
32 | | -``` |
33 | | - |
34 | | -## Architecture |
35 | | - |
36 | | -``` |
37 | | -src/agentready/ |
38 | | -├── assessors/ # 25 attribute evaluators (see assessors/__init__.py) |
39 | | -├── cli/ # Click commands with LazyGroup optimization |
40 | | -├── data/ # default-weights.yaml, RESEARCH_REPORT.md |
41 | | -├── fixers/ # Automated remediation strategies |
42 | | -├── github/ # PR review formatting |
43 | | -├── learners/ # LLM-powered pattern extraction |
44 | | -├── models/ # Repository, Assessment, Finding, Attribute |
45 | | -├── prompts/ # LLM prompt templates |
46 | | -├── reporters/ # HTML, Markdown, JSON output |
47 | | -├── services/ # Scanner orchestration, scoring, caching |
48 | | -├── templates/ # Jinja2 HTML templates |
49 | | -└── utils/ # preflight, privacy, security, subprocess |
50 | | -``` |
51 | | - |
52 | | -**Data Flow**: Repository -> Scanner -> Assessors -> Findings -> Scorer -> Reporters |
53 | | - |
54 | | -## Scoring |
55 | | - |
56 | | -**Tier weights** (from `data/default-weights.yaml:6-9`): |
57 | | -- Tier 1 (Essential): 55% |
58 | | -- Tier 2 (Critical): 27% |
59 | | -- Tier 3 (Important): 15% |
60 | | -- Tier 4 (Advanced): 3% |
61 | | - |
62 | | -**Certification**: Platinum (90+), Gold (75-89), Silver (60-74), Bronze (40-59) |
63 | | - |
64 | | -## Adding Assessors |
65 | | - |
66 | | -1. Create class inheriting `BaseAssessor` (`assessors/base.py`) |
67 | | -2. Implement `attribute_id` property and `assess(repository)` method |
68 | | -3. Register in `assessors/__init__.py:create_all_assessors()` |
69 | | -4. Add tests in `tests/unit/test_assessors_*.py` |
70 | | - |
71 | | -**Reference implementations**: |
72 | | -- Simple: `AgentInstructionsAssessor` at `assessors/documentation.py` |
73 | | -- Complex: `TypeAnnotationsAssessor` at `assessors/code_quality.py` |
74 | | -- Conditional: `ContainerSetupAssessor` at `assessors/containers.py` |
75 | | - |
76 | | -## Key Patterns |
77 | | - |
78 | | -**Proportional scoring**: Use `calculate_proportional_score()` for partial compliance |
79 | | - |
80 | | -**Graceful degradation**: Return "skipped" if tools missing, never crash |
81 | | - |
82 | | -**Finding creation**: |
83 | | -```python |
84 | | -Finding.create_pass(self.attribute, evidence="...", details="...") |
85 | | -Finding.create_fail(self.attribute, evidence="...", remediation="...") |
86 | | -``` |
87 | | - |
88 | | -## CI/CD |
89 | | - |
90 | | -16 GitHub Actions workflows in `.github/workflows/`: |
91 | | -- `ci.yml` - Tests (Py 3.12/3.13), linting, coverage |
92 | | -- `release.yml` - Semantic versioning, PyPI publish |
93 | | -- `agentready-assessment.yml` - Self-assessment on commits |
94 | | -- `pr-review.yml` - Automated PR review |
95 | | - |
96 | | -**Note for agents**: Always run `actionlint` before pushing workflow changes. |
97 | | - |
98 | | -## Conventions |
99 | | - |
100 | | -**Commits**: `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, `chore:` |
101 | | - |
102 | | -**Tests**: All new assessors require unit tests. Maintain >80% coverage for new code. |
103 | | - |
104 | | -**Linting**: Run `black . && isort . && ruff check .` before commits |
105 | | - |
106 | | -## Key Files |
107 | | - |
108 | | -| Purpose | Location | |
109 | | -|---------|----------| |
110 | | -| Weight config | `src/agentready/data/default-weights.yaml` | |
111 | | -| Research report | `src/agentready/data/RESEARCH_REPORT.md` | |
112 | | -| HTML template | `src/agentready/templates/report.html.j2` | |
113 | | -| Schemas | `specs/001-agentready-scorer/contracts/` | |
114 | | -| Issue templates | `.github/ISSUE_TEMPLATE/` | |
115 | | - |
116 | | -## Agent Guidelines |
117 | | - |
118 | | -1. **Read before modifying** - Understand existing assessors first |
119 | | -2. **Follow patterns** - Use reference implementations above |
120 | | -3. **Test thoroughly** - Unit tests required for all assessors |
121 | | -4. **Backwards compatibility** - Schema version bump for model changes |
122 | | -5. **Rich remediation** - Actionable steps with tools, commands, examples |
123 | | -6. **Self-assign issues** - Before starting work on a GitHub issue, check if it is already assigned. If it is, warn the user and ask for confirmation before continuing. If unassigned (or the user confirms), self-assign it immediately to prevent duplicate effort from other contributors |
124 | | -7. **Keep docs/attributes.md in sync** - When changing how an assessor scores (thresholds, partial credit rules, recognized paths, pass/fail conditions), update the corresponding entry in `docs/attributes.md` in the same PR |
125 | | - |
126 | | -## Related Docs |
127 | | - |
128 | | -See `BOOKMARKS.md` for navigation to: |
129 | | -- Harbor benchmarks guide |
130 | | -- SWE-bench experiments |
131 | | -- Research report schema |
132 | | -- Feature specifications |
133 | | -- API reference (docs/) |
134 | | - |
135 | | ---- |
136 | | - |
| 1 | +@AGENTS.md |
0 commit comments