diff --git a/.agentready-demo/demo-assessment-20251121-051257.json b/.agentready-demo/demo-assessment-20251121-051257.json new file mode 100644 index 0000000..8fa2ec9 --- /dev/null +++ b/.agentready-demo/demo-assessment-20251121-051257.json @@ -0,0 +1,620 @@ +{ + "repository": { + "path": "/var/folders/43/ffv83_l50cn2k0rzgxp63kyw0000gn/T/agentready-demo-zp8md4nd/demo-repo", + "name": "demo-repo", + "url": null, + "branch": "main", + "commit_hash": "8798997839b602cbb3f02073ca66ed95abc6cdda", + "languages": { + "Python": 4 + }, + "total_files": 7, + "total_lines": 100 + }, + "timestamp": "2025-11-21T05:12:57.860663", + "overall_score": 73.1, + "certification_level": "Silver", + "attributes_assessed": 10, + "attributes_skipped": 15, + "attributes_total": 25, + "findings": [ + { + "attribute": { + "id": "claude_md_file", + "name": "CLAUDE.md Configuration Files", + "category": "Context Window Optimization", + "tier": 1, + "description": "Project-specific configuration for Claude Code", + "criteria": "CLAUDE.md file exists in repository root", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "present", + "threshold": "present", + "evidence": [ + "CLAUDE.md found at /var/folders/43/ffv83_l50cn2k0rzgxp63kyw0000gn/T/agentready-demo-zp8md4nd/demo-repo/CLAUDE.md" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "readme_structure", + "name": "README Structure", + "category": "Documentation Standards", + "tier": 1, + "description": "Well-structured README with key sections", + "criteria": "README.md with installation, usage, and development sections", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "3/3 sections", + "threshold": "3/3 sections", + "evidence": [ + "Found 3/3 essential sections", + "Installation: \u2713", + "Usage: \u2713", + "Development: \u2713" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "type_annotations", + "name": "Type Annotations", + "category": "Code Quality", + "tier": 1, + "description": "Type hints in function signatures", + "criteria": ">80% of functions have type annotations", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "100.0%", + "threshold": "\u226580%", + "evidence": [ + "Typed functions: 5/5", + "Coverage: 100.0%" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "standard_layout", + "name": "Standard Project Layouts", + "category": "Repository Structure", + "tier": 1, + "description": "Follows standard project structure for language", + "criteria": "Standard directories (src/, tests/, docs/) present", + "default_weight": 0.1 + }, + "status": "pass", + "score": 100.0, + "measured_value": "2/2 directories", + "threshold": "2/2 directories", + "evidence": [ + "Found 2/2 standard directories", + "src/: \u2713", + "tests/: \u2713" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "lock_files", + "name": "Lock Files for Reproducibility", + "category": "Dependency Management", + "tier": 1, + "description": "Lock files present for dependency pinning", + "criteria": "package-lock.json, yarn.lock, poetry.lock, or requirements.txt with versions", + "default_weight": 0.1 + }, + "status": "fail", + "score": 0.0, + "measured_value": "none", + "threshold": "at least one lock file", + "evidence": [ + "No lock files found" + ], + "remediation": { + "summary": "Add lock file for dependency reproducibility", + "steps": [ + "Use npm install, poetry lock, or equivalent to generate lock file" + ], + "tools": [], + "commands": [ + "npm install # generates package-lock.json" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "test_coverage", + "name": "Test Coverage Requirements", + "category": "Testing & CI/CD", + "tier": 2, + "description": "Test coverage thresholds configured and enforced", + "criteria": ">80% code coverage", + "default_weight": 0.03 + }, + "status": "fail", + "score": 50.0, + "measured_value": "not configured", + "threshold": "configured with >80% threshold", + "evidence": [ + "Coverage config: \u2713", + "pytest-cov: \u2717" + ], + "remediation": { + "summary": "Configure test coverage with \u226580% threshold", + "steps": [ + "Install coverage tool (pytest-cov for Python, jest for JavaScript)", + "Configure coverage threshold in project config", + "Add coverage reporting to CI/CD pipeline", + "Run coverage locally before committing" + ], + "tools": [ + "pytest-cov", + "jest", + "vitest", + "coverage" + ], + "commands": [ + "# Python", + "pip install pytest-cov", + "pytest --cov=src --cov-report=term-missing --cov-fail-under=80", + "", + "# JavaScript", + "npm install --save-dev jest", + "npm test -- --coverage --coverageThreshold='{\\'global\\': {\\'lines\\': 80}}'" + ], + "examples": [ + "# Python - pyproject.toml\n[tool.pytest.ini_options]\naddopts = \"--cov=src --cov-report=term-missing\"\n\n[tool.coverage.report]\nfail_under = 80\n", + "// JavaScript - package.json\n{\n \"jest\": {\n \"coverageThreshold\": {\n \"global\": {\n \"lines\": 80,\n \"statements\": 80,\n \"functions\": 80,\n \"branches\": 80\n }\n }\n }\n}\n" + ], + "citations": [ + { + "source": "pytest-cov", + "title": "Coverage Configuration", + "url": "https://pytest-cov.readthedocs.io/", + "relevance": "pytest-cov configuration guide" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "precommit_hooks", + "name": "Pre-commit Hooks & CI/CD Linting", + "category": "Testing & CI/CD", + "tier": 2, + "description": "Pre-commit hooks configured for linting and formatting", + "criteria": ".pre-commit-config.yaml exists", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0.0, + "measured_value": "not configured", + "threshold": "configured", + "evidence": [ + ".pre-commit-config.yaml not found" + ], + "remediation": { + "summary": "Configure pre-commit hooks for automated code quality checks", + "steps": [ + "Install pre-commit framework", + "Create .pre-commit-config.yaml", + "Add hooks for linting and formatting", + "Install hooks: pre-commit install", + "Run on all files: pre-commit run --all-files" + ], + "tools": [ + "pre-commit" + ], + "commands": [ + "pip install pre-commit", + "pre-commit install", + "pre-commit run --all-files" + ], + "examples": [ + "# .pre-commit-config.yaml\nrepos:\n - repo: https://github.com/pre-commit/pre-commit-hooks\n rev: v4.4.0\n hooks:\n - id: trailing-whitespace\n - id: end-of-file-fixer\n - id: check-yaml\n - id: check-added-large-files\n\n - repo: https://github.com/psf/black\n rev: 23.3.0\n hooks:\n - id: black\n\n - repo: https://github.com/pycqa/isort\n rev: 5.12.0\n hooks:\n - id: isort\n" + ], + "citations": [ + { + "source": "pre-commit.com", + "title": "Pre-commit Framework", + "url": "https://pre-commit.com/", + "relevance": "Official pre-commit documentation" + } + ] + }, + "error_message": null + }, + { + "attribute": { + "id": "conventional_commits", + "name": "Conventional Commit Messages", + "category": "Git & Version Control", + "tier": 2, + "description": "Follows conventional commit format", + "criteria": "\u226580% of recent commits follow convention", + "default_weight": 0.03 + }, + "status": "fail", + "score": 0.0, + "measured_value": "not configured", + "threshold": "configured", + "evidence": [ + "No commitlint or husky configuration" + ], + "remediation": { + "summary": "Configure conventional commits with commitlint", + "steps": [ + "Install commitlint", + "Configure husky for commit-msg hook" + ], + "tools": [ + "commitlint", + "husky" + ], + "commands": [ + "npm install --save-dev @commitlint/cli @commitlint/config-conventional husky" + ], + "examples": [], + "citations": [] + }, + "error_message": null + }, + { + "attribute": { + "id": "gitignore_completeness", + "name": ".gitignore Completeness", + "category": "Git & Version Control", + "tier": 2, + "description": "Comprehensive .gitignore file", + "criteria": ".gitignore exists and covers common patterns", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "325 bytes", + "threshold": ">50 bytes", + "evidence": [ + ".gitignore found (325 bytes)" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "cyclomatic_complexity", + "name": "Cyclomatic Complexity Thresholds", + "category": "Code Quality", + "tier": 3, + "description": "Cyclomatic complexity thresholds enforced", + "criteria": "Average complexity <10, no functions >15", + "default_weight": 0.03 + }, + "status": "pass", + "score": 100.0, + "measured_value": "2.0", + "threshold": "<10.0", + "evidence": [ + "Average cyclomatic complexity: 2.0" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "one_command_setup", + "name": "One-Command Build/Setup", + "category": "Build & Development", + "tier": 2, + "description": "Assessment for One-Command Build/Setup", + "criteria": "To be implemented", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "One-Command Build/Setup assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "concise_documentation", + "name": "Concise Structured Documentation", + "category": "Context Window Optimization", + "tier": 2, + "description": "Assessment for Concise Structured Documentation", + "criteria": "To be implemented", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Concise Structured Documentation assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "inline_documentation", + "name": "Inline Documentation", + "category": "Documentation Standards", + "tier": 2, + "description": "Assessment for Inline Documentation", + "criteria": "To be implemented", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Inline Documentation assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "file_size_limits", + "name": "File Size Limits", + "category": "Context Window Optimization", + "tier": 2, + "description": "Assessment for File Size Limits", + "criteria": "To be implemented", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "File Size Limits assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "dependency_freshness", + "name": "Dependency Freshness & Security", + "category": "Dependency Management", + "tier": 2, + "description": "Assessment for Dependency Freshness & Security", + "criteria": "To be implemented", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Dependency Freshness & Security assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "separation_concerns", + "name": "Separation of Concerns", + "category": "Repository Structure", + "tier": 2, + "description": "Assessment for Separation of Concerns", + "criteria": "To be implemented", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Separation of Concerns assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "structured_logging", + "name": "Structured Logging", + "category": "Error Handling", + "tier": 3, + "description": "Assessment for Structured Logging", + "criteria": "To be implemented", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Structured Logging assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "openapi_specs", + "name": "OpenAPI/Swagger Specifications", + "category": "API Documentation", + "tier": 3, + "description": "Assessment for OpenAPI/Swagger Specifications", + "criteria": "To be implemented", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "OpenAPI/Swagger Specifications assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "architecture_decisions", + "name": "Architecture Decision Records", + "category": "Documentation Standards", + "tier": 3, + "description": "Assessment for Architecture Decision Records", + "criteria": "To be implemented", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Architecture Decision Records assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "semantic_naming", + "name": "Semantic File & Directory Naming", + "category": "Modularity", + "tier": 3, + "description": "Assessment for Semantic File & Directory Naming", + "criteria": "To be implemented", + "default_weight": 0.03 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Semantic File & Directory Naming assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "security_scanning", + "name": "Security Scanning Automation", + "category": "Security", + "tier": 4, + "description": "Assessment for Security Scanning Automation", + "criteria": "To be implemented", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Security Scanning Automation assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "performance_benchmarks", + "name": "Performance Benchmarks", + "category": "Performance", + "tier": 4, + "description": "Assessment for Performance Benchmarks", + "criteria": "To be implemented", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Performance Benchmarks assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "code_smells", + "name": "Code Smell Elimination", + "category": "Code Quality", + "tier": 4, + "description": "Assessment for Code Smell Elimination", + "criteria": "To be implemented", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Code Smell Elimination assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "issue_pr_templates", + "name": "Issue & Pull Request Templates", + "category": "Git & Version Control", + "tier": 4, + "description": "Assessment for Issue & Pull Request Templates", + "criteria": "To be implemented", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Issue & Pull Request Templates assessment not yet implemented" + ], + "remediation": null, + "error_message": null + }, + { + "attribute": { + "id": "container_setup", + "name": "Container/Virtualization Setup", + "category": "Build & Development", + "tier": 4, + "description": "Assessment for Container/Virtualization Setup", + "criteria": "To be implemented", + "default_weight": 0.01 + }, + "status": "not_applicable", + "score": null, + "measured_value": null, + "threshold": null, + "evidence": [ + "Container/Virtualization Setup assessment not yet implemented" + ], + "remediation": null, + "error_message": null + } + ], + "config": null, + "duration_seconds": 1.8 +} \ No newline at end of file diff --git a/.agentready-demo/demo-report-20251121-051257.html b/.agentready-demo/demo-report-20251121-051257.html new file mode 100644 index 0000000..bb4abc6 --- /dev/null +++ b/.agentready-demo/demo-report-20251121-051257.html @@ -0,0 +1,1890 @@ + + + + + + AgentReady Assessment - demo-repo + + + +
+
+

🤖 AgentReady Assessment Report

+

demo-repo â€ĸ November 21, 2025 at 05:12

+
+ + +
+
+

Overall Score

+
73.1
+
+
+

Certification

+
Silver
+
+
+

Assessed

+
10/25
+
+
+

Duration

+
1.8s
+
+
+ + +
+
+

💎 Platinum

+

90-100

+
+
+

đŸĨ‡ Gold

+

75-89

+
+
+

đŸĨˆ Silver

+

60-74

+
+
+

đŸĨ‰ Bronze

+

40-59

+
+
+

⚠ī¸ Needs Work

+

0-39

+
+
+ + +
+
+ + + + + +
+ +
+ + +
+ +
+ +
+
+ + +
+ +
+ +
+
+ + ✅ + + +
+

CLAUDE.md Configuration Files

+
+ Context Window Optimization â€ĸ + Tier 1 + â€ĸ present +
+
+
+ +
+ 100 +
+ +
+ +
+ +
+

Evidence

+
    + +
  • CLAUDE.md found at /var/folders/43/ffv83_l50cn2k0rzgxp63kyw0000gn/T/agentready-demo-zp8md4nd/demo-repo/CLAUDE.md
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ✅ + + +
+

README Structure

+
+ Documentation Standards â€ĸ + Tier 1 + â€ĸ 3/3 sections +
+
+
+ +
+ 100 +
+ +
+ +
+ +
+

Evidence

+
    + +
  • Found 3/3 essential sections
    • + +
  • Installation: ✓
    • + +
  • Usage: ✓
    • + +
  • Development: ✓
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ✅ + + +
+

Type Annotations

+
+ Code Quality â€ĸ + Tier 1 + â€ĸ 100.0% +
+
+
+ +
+ 100 +
+ +
+ +
+ +
+

Evidence

+
    + +
  • Typed functions: 5/5
    • + +
  • Coverage: 100.0%
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ✅ + + +
+

Standard Project Layouts

+
+ Repository Structure â€ĸ + Tier 1 + â€ĸ 2/2 directories +
+
+
+ +
+ 100 +
+ +
+ +
+ +
+

Evidence

+
    + +
  • Found 2/2 standard directories
    • + +
  • src/: ✓
    • + +
  • tests/: ✓
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ❌ + + +
+

Lock Files for Reproducibility

+
+ Dependency Management â€ĸ + Tier 1 + â€ĸ none +
+
+
+ +
+ 0 +
+ +
+ +
+ +
+

Evidence

+
    + +
  • No lock files found
    • + +
+
+ + + +
+

Remediation

+

Add lock file for dependency reproducibility

+ + +
    + +
  1. Use npm install, poetry lock, or equivalent to generate lock file
    2. + +
+ + + +

Commands

+ 
npm install  # generates package-lock.json
+ + + +
+ + + +
+
+ +
+ +
+
+ + ❌ + + +
+

Test Coverage Requirements

+
+ Testing & CI/CD â€ĸ + Tier 2 + â€ĸ not configured +
+
+
+ +
+ 50 +
+ +
+ +
+ +
+

Evidence

+
    + +
  • Coverage config: ✓
    • + +
  • pytest-cov: ✗
    • + +
+
+ + + +
+

Remediation

+

Configure test coverage with â‰Ĩ80% threshold

+ + +
    + +
  1. Install coverage tool (pytest-cov for Python, jest for JavaScript)
    2. + +
  2. Configure coverage threshold in project config
    3. + +
  3. Add coverage reporting to CI/CD pipeline
    4. + +
  4. Run coverage locally before committing
    5. + +
+ + + +

Commands

+ 
# Python
+pip install pytest-cov
+pytest --cov=src --cov-report=term-missing --cov-fail-under=80
+
+# JavaScript
+npm install --save-dev jest
+npm test -- --coverage --coverageThreshold='{\'global\': {\'lines\': 80}}'
+ + + +

Examples

+ + 
# Python - pyproject.toml
+[tool.pytest.ini_options]
+addopts = "--cov=src --cov-report=term-missing"
+
+[tool.coverage.report]
+fail_under = 80
+
+ + 
// JavaScript - package.json
+{
+  "jest": {
+    "coverageThreshold": {
+      "global": {
+        "lines": 80,
+        "statements": 80,
+        "functions": 80,
+        "branches": 80
+      }
+    }
+  }
+}
+
+ + +
+ + + +
+
+ +
+ +
+
+ + ❌ + + +
+

Pre-commit Hooks & CI/CD Linting

+
+ Testing & CI/CD â€ĸ + Tier 2 + â€ĸ not configured +
+
+
+ +
+ 0 +
+ +
+ +
+ +
+

Evidence

+
    + +
  • .pre-commit-config.yaml not found
    • + +
+
+ + + +
+

Remediation

+

Configure pre-commit hooks for automated code quality checks

+ + +
    + +
  1. Install pre-commit framework
    2. + +
  2. Create .pre-commit-config.yaml
    3. + +
  3. Add hooks for linting and formatting
    4. + +
  4. Install hooks: pre-commit install
    5. + +
  5. Run on all files: pre-commit run --all-files
    6. + +
+ + + +

Commands

+ 
pip install pre-commit
+pre-commit install
+pre-commit run --all-files
+ + + +

Examples

+ + 
# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  - repo: https://github.com/psf/black
+    rev: 23.3.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+
+ + +
+ + + +
+
+ +
+ +
+
+ + ❌ + + +
+

Conventional Commit Messages

+
+ Git & Version Control â€ĸ + Tier 2 + â€ĸ not configured +
+
+
+ +
+ 0 +
+ +
+ +
+ +
+

Evidence

+
    + +
  • No commitlint or husky configuration
    • + +
+
+ + + +
+

Remediation

+

Configure conventional commits with commitlint

+ + +
    + +
  1. Install commitlint
    2. + +
  2. Configure husky for commit-msg hook
    3. + +
+ + + +

Commands

+ 
npm install --save-dev @commitlint/cli @commitlint/config-conventional husky
+ + + +
+ + + +
+
+ +
+ +
+
+ + ✅ + + +
+

.gitignore Completeness

+
+ Git & Version Control â€ĸ + Tier 2 + â€ĸ 325 bytes +
+
+
+ +
+ 100 +
+ +
+ +
+ +
+

Evidence

+
    + +
  • .gitignore found (325 bytes)
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ✅ + + +
+

Cyclomatic Complexity Thresholds

+
+ Code Quality â€ĸ + Tier 3 + â€ĸ 2.0 +
+
+
+ +
+ 100 +
+ +
+ +
+ +
+

Evidence

+
    + +
  • Average cyclomatic complexity: 2.0
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

One-Command Build/Setup

+
+ Build & Development â€ĸ + Tier 2 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • One-Command Build/Setup assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

Concise Structured Documentation

+
+ Context Window Optimization â€ĸ + Tier 2 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • Concise Structured Documentation assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

Inline Documentation

+
+ Documentation Standards â€ĸ + Tier 2 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • Inline Documentation assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

File Size Limits

+
+ Context Window Optimization â€ĸ + Tier 2 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • File Size Limits assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

Dependency Freshness & Security

+
+ Dependency Management â€ĸ + Tier 2 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • Dependency Freshness & Security assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

Separation of Concerns

+
+ Repository Structure â€ĸ + Tier 2 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • Separation of Concerns assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

Structured Logging

+
+ Error Handling â€ĸ + Tier 3 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • Structured Logging assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

OpenAPI/Swagger Specifications

+
+ API Documentation â€ĸ + Tier 3 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • OpenAPI/Swagger Specifications assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

Architecture Decision Records

+
+ Documentation Standards â€ĸ + Tier 3 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • Architecture Decision Records assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

Semantic File & Directory Naming

+
+ Modularity â€ĸ + Tier 3 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • Semantic File & Directory Naming assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

Security Scanning Automation

+
+ Security â€ĸ + Tier 4 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • Security Scanning Automation assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

Performance Benchmarks

+
+ Performance â€ĸ + Tier 4 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • Performance Benchmarks assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

Code Smell Elimination

+
+ Code Quality â€ĸ + Tier 4 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • Code Smell Elimination assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

Issue & Pull Request Templates

+
+ Git & Version Control â€ĸ + Tier 4 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • Issue & Pull Request Templates assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ +
+
+ + ⊘ + + +
+

Container/Virtualization Setup

+
+ Build & Development â€ĸ + Tier 4 + +
+
+
+ +
—
+ +
+ +
+ +
+

Evidence

+
    + +
  • Container/Virtualization Setup assessment not yet implemented
    • + +
+
+ + + + + +
+
+ +
+ + +
+ + + + \ No newline at end of file diff --git a/.agentready-demo/demo-report-20251121-051257.md b/.agentready-demo/demo-report-20251121-051257.md new file mode 100644 index 0000000..0f10f4b --- /dev/null +++ b/.agentready-demo/demo-report-20251121-051257.md @@ -0,0 +1,308 @@ +# 🤖 AgentReady Assessment Report + +| Repository | Branch | Commit | Score | Level | Date | +|------------|--------|--------|-------|-------|------| +| **demo-repo** | main | `87989978` | **73.1/100** | **Silver** | 2025-11-21 05:12 | + +--- + +## 📊 Summary + +| Metric | Value | +|--------|-------| +| **Overall Score** | **73.1/100** | +| **Certification Level** | **Silver** | +| **Attributes Assessed** | 10/25 | +| **Attributes Skipped** | 15 | +| **Assessment Duration** | 1.8s | + +### Languages Detected + +- **Python**: 4 files + +### Repository Stats + +- **Total Files**: 7 +- **Total Lines**: 100 + +## 🎖ī¸ Certification Ladder + +- 💎 **Platinum** (90-100) +- đŸĨ‡ **Gold** (75-89) +- đŸĨˆ **Silver** (60-74) **→ YOUR LEVEL ←** +- đŸĨ‰ **Bronze** (40-59) +- ⚠ī¸ **Needs Improvement** (0-39) + +## 📋 Detailed Findings + +### API Documentation + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| OpenAPI/Swagger Specifications | T3 | ⊘ not_applicable | — | + +### Build & Development + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| One-Command Build/Setup | T2 | ⊘ not_applicable | — | +| Container/Virtualization Setup | T4 | ⊘ not_applicable | — | + +### Code Quality + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| Type Annotations | T1 | ✅ pass | 100 | +| Cyclomatic Complexity Thresholds | T3 | ✅ pass | 100 | +| Code Smell Elimination | T4 | ⊘ not_applicable | — | + +### Context Window Optimization + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| CLAUDE.md Configuration Files | T1 | ✅ pass | 100 | +| Concise Structured Documentation | T2 | ⊘ not_applicable | — | +| File Size Limits | T2 | ⊘ not_applicable | — | + +### Dependency Management + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| Lock Files for Reproducibility | T1 | ❌ fail | 0 | +| Dependency Freshness & Security | T2 | ⊘ not_applicable | — | + +#### ❌ Lock Files for Reproducibility + +**Measured**: none (Threshold: at least one lock file) + +**Evidence**: +- No lock files found + +
📝 Remediation Steps + + +Add lock file for dependency reproducibility + +1. Use npm install, poetry lock, or equivalent to generate lock file + +**Commands**: + +```bash +npm install # generates package-lock.json +``` + +
+ +### Documentation Standards + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| README Structure | T1 | ✅ pass | 100 | +| Inline Documentation | T2 | ⊘ not_applicable | — | +| Architecture Decision Records | T3 | ⊘ not_applicable | — | + +### Error Handling + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| Structured Logging | T3 | ⊘ not_applicable | — | + +### Git & Version Control + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| Conventional Commit Messages | T2 | ❌ fail | 0 | +| .gitignore Completeness | T2 | ✅ pass | 100 | +| Issue & Pull Request Templates | T4 | ⊘ not_applicable | — | + +#### ❌ Conventional Commit Messages + +**Measured**: not configured (Threshold: configured) + +**Evidence**: +- No commitlint or husky configuration + +
📝 Remediation Steps + + +Configure conventional commits with commitlint + +1. Install commitlint +2. Configure husky for commit-msg hook + +**Commands**: + +```bash +npm install --save-dev @commitlint/cli @commitlint/config-conventional husky +``` + +
+ +### Modularity + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| Semantic File & Directory Naming | T3 | ⊘ not_applicable | — | + +### Performance + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| Performance Benchmarks | T4 | ⊘ not_applicable | — | + +### Repository Structure + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| Standard Project Layouts | T1 | ✅ pass | 100 | +| Separation of Concerns | T2 | ⊘ not_applicable | — | + +### Security + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| Security Scanning Automation | T4 | ⊘ not_applicable | — | + +### Testing & CI/CD + +| Attribute | Tier | Status | Score | +|-----------|------|--------|-------| +| Test Coverage Requirements | T2 | ❌ fail | 50 | +| Pre-commit Hooks & CI/CD Linting | T2 | ❌ fail | 0 | + +#### ❌ Test Coverage Requirements + +**Measured**: not configured (Threshold: configured with >80% threshold) + +**Evidence**: +- Coverage config: ✓ +- pytest-cov: ✗ + +
📝 Remediation Steps + + +Configure test coverage with â‰Ĩ80% threshold + +1. Install coverage tool (pytest-cov for Python, jest for JavaScript) +2. Configure coverage threshold in project config +3. Add coverage reporting to CI/CD pipeline +4. Run coverage locally before committing + +**Commands**: + +```bash +# Python +pip install pytest-cov +pytest --cov=src --cov-report=term-missing --cov-fail-under=80 + +# JavaScript +npm install --save-dev jest +npm test -- --coverage --coverageThreshold='{\'global\': {\'lines\': 80}}' +``` + +**Examples**: + +``` +# Python - pyproject.toml +[tool.pytest.ini_options] +addopts = "--cov=src --cov-report=term-missing" + +[tool.coverage.report] +fail_under = 80 + +``` +``` +// JavaScript - package.json +{ + "jest": { + "coverageThreshold": { + "global": { + "lines": 80, + "statements": 80, + "functions": 80, + "branches": 80 + } + } + } +} + +``` + +
+ +#### ❌ Pre-commit Hooks & CI/CD Linting + +**Measured**: not configured (Threshold: configured) + +**Evidence**: +- .pre-commit-config.yaml not found + +
📝 Remediation Steps + + +Configure pre-commit hooks for automated code quality checks + +1. Install pre-commit framework +2. Create .pre-commit-config.yaml +3. Add hooks for linting and formatting +4. Install hooks: pre-commit install +5. Run on all files: pre-commit run --all-files + +**Commands**: + +```bash +pip install pre-commit +pre-commit install +pre-commit run --all-files +``` + +**Examples**: + +``` +# .pre-commit-config.yaml +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.4.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-yaml + - id: check-added-large-files + + - repo: https://github.com/psf/black + rev: 23.3.0 + hooks: + - id: black + + - repo: https://github.com/pycqa/isort + rev: 5.12.0 + hooks: + - id: isort + +``` + +
+ +## đŸŽ¯ Next Steps + +**Priority Improvements** (highest impact first): + +1. **Lock Files for Reproducibility** (Tier 1) - +10.0 points potential + - Add lock file for dependency reproducibility +2. **Pre-commit Hooks & CI/CD Linting** (Tier 2) - +3.0 points potential + - Configure pre-commit hooks for automated code quality checks +3. **Conventional Commit Messages** (Tier 2) - +3.0 points potential + - Configure conventional commits with commitlint +4. **Test Coverage Requirements** (Tier 2) - +3.0 points potential + - Configure test coverage with â‰Ĩ80% threshold + +--- + +## 📝 Assessment Metadata + +- **Tool Version**: AgentReady v1.0.0 +- **Research Report**: Bundled version +- **Repository Snapshot**: 8798997839b602cbb3f02073ca66ed95abc6cdda +- **Assessment Duration**: 1.8s + +🤖 Generated with [Claude Code](https://claude.com/claude-code) \ No newline at end of file diff --git a/.github/CLAUDE_INTEGRATION.md b/.github/CLAUDE_INTEGRATION.md new file mode 100644 index 0000000..091ebbd --- /dev/null +++ b/.github/CLAUDE_INTEGRATION.md @@ -0,0 +1,276 @@ +# Dual Claude Integration Guide + +This repository uses **two different Claude integrations** that work together for different use cases. + +## 🤖 Integration Overview + +| Integration | Trigger | Behavior | Use Case | +|------------|---------|----------|----------| +| **Claude Code Action** | Assign issue to `claude-bot` | Automated implementation in GitHub Actions | Autonomous feature development | +| **Direct @claude** | @mention claude in comments | Interactive conversation in comment thread | Discussion, guidance, code review | + +--- + +## 1. Automated Implementation (Claude Code Action) + +### How It Works + +When you **assign an issue to `claude-bot`**: +1. GitHub Actions workflow triggers +2. Claude Code CLI spins up in runner +3. Reads `CLAUDE.md` for project context +4. Implements the issue autonomously +5. Creates feature branch and commits +6. Opens PR for review + +### Configuration + +**Workflow**: `.github/workflows/claude-code-action.yml` +- Triggers only on `issues.assigned` events +- Checks `if: github.event.assignee.login == 'claude-bot'` +- Uses `ANTHROPIC_API_KEY` secret + +**System Prompts**: +- `CLAUDE.md` (project-level) - Automatically read +- `.github/claude-bot-prompt.md` (automation-specific) - Optional, currently commented out + +### Usage + +```bash +# Create issue on GitHub +# Assign to @claude-bot user +# Wait for PR to be created +``` + +### Example Workflow + +1. Create issue: "Implement dependency freshness assessor" +2. Assign to `claude-bot` +3. Wait 2-5 minutes +4. Review PR created by claude-bot +5. Merge or request changes + +--- + +## 2. Interactive Conversation (Direct @claude) + +### How It Works + +When you **@mention claude in any comment**: +1. Claude responds directly in the comment thread +2. No code is written automatically +3. Interactive back-and-forth discussion +4. You control when to apply suggestions + +### Setup Required + +**Install the Claude GitHub App**: +1. Navigate to https://github.com/apps/claude-ai +2. Click "Install" +3. Select `ambient-code/agentready` repository +4. Grant required permissions: + - Read access to code and issues + - Write access to comments +5. Complete installation + +**Connect Your Account**: +1. Go to https://claude.ai/settings +2. Navigate to "Integrations" +3. Connect your GitHub account +4. Authorize the app + +### Usage + +```markdown +@claude How should I structure the DependencyFreshnessAssessor? +``` + +Claude will respond with: +- Architecture suggestions +- Code examples +- Best practices +- Questions for clarification + +You then choose which suggestions to implement manually (or ask claude-bot to implement via assignment). + +--- + +## 3. When to Use Each Integration + +### Use Claude Code Action (assign to claude-bot) when: +- ✅ You want autonomous implementation +- ✅ The task is well-defined +- ✅ You're okay with reviewing a PR afterward +- ✅ You want to save development time + +### Use Direct @claude when: +- ✅ You need design discussion first +- ✅ You want to explore options interactively +- ✅ You need code review feedback +- ✅ You want to implement manually with guidance +- ✅ The task has ambiguity or trade-offs + +### Use Both Together: +1. Create issue with @claude mention +2. Discuss approach with interactive Claude +3. Once design is settled, assign to claude-bot +4. claude-bot implements the agreed-upon design + +--- + +## 4. Customizing Automation Behavior + +### Editing CLAUDE.md + +`CLAUDE.md` is the **main source of truth** for project context: +- Architecture overview +- Development workflow +- Code quality standards +- Testing requirements + +**Changes to CLAUDE.md affect both integrations.** + +### Editing .github/claude-bot-prompt.md + +This file provides **automation-specific instructions**: +- Feature branch naming conventions +- PR creation templates +- TDD requirements +- Commit message formats + +**To enable**: Uncomment the `claude_args` line in `claude-code-action.yml` + +### Example Customization + +```yaml +# In .github/workflows/claude-code-action.yml +claude_args: --append-system-prompt "$(cat .github/claude-bot-prompt.md)" +``` + +--- + +## 5. Troubleshooting + +### Claude Code Action Not Triggering + +**Check**: +- [ ] Issue is assigned to `claude-bot` user (exact spelling) +- [ ] GitHub Actions workflow is enabled in Settings > Actions +- [ ] `ANTHROPIC_API_KEY` secret is set in repository secrets +- [ ] Workflow file syntax is valid (no YAML errors) + +**View Logs**: +1. Go to Actions tab +2. Find the failed/running workflow +3. Click to view logs +4. Check "Claude Code Action" step for errors + +### Direct @claude Not Responding + +**Check**: +- [ ] Claude GitHub App is installed on repository +- [ ] Your GitHub account is connected at claude.ai +- [ ] You used `@claude` (not `@claude-bot`) +- [ ] Comment is on an issue or PR (not commit) + +**Note**: Direct @claude may take 30-60 seconds to respond initially. + +### Both Integrations Triggering + +**This shouldn't happen with current config**: +- Claude Code Action only triggers on assignment to `claude-bot` +- Direct @claude responds to @mentions +- These are mutually exclusive triggers + +If both respond, check that: +- Workflow file has correct `if:` condition +- You're not both assigning AND mentioning + +--- + +## 6. Security Considerations + +### API Keys +- `ANTHROPIC_API_KEY` stored as GitHub secret (encrypted) +- Never exposed in logs or PR comments +- Automatically rotated every 90 days + +### Permissions +- Claude Code Action has `write` access (needed for PRs) +- Direct @claude has `read` + `comment` access only +- Both run in isolated environments + +### Code Review +- **Always review PRs** created by claude-bot before merging +- Check for security issues (hardcoded secrets, injection vulnerabilities) +- Verify tests pass and coverage maintained +- Run local linters before merge + +--- + +## 7. Cost Management + +### Claude Code Action +- Uses Anthropic API (metered by tokens) +- Typical cost: $0.10-$0.50 per issue implementation +- Monitor usage in Anthropic Console + +### Direct @claude +- Free for individual use +- Subject to rate limits (TBD by Anthropic) + +### Best Practices +- Use claude-bot for well-defined tasks only +- Use direct @claude for exploration/discussion (cheaper) +- Review generated code before running (avoid wasted API calls) + +--- + +## 8. Examples + +### Example 1: Feature Discussion → Implementation +```markdown +# GitHub Issue #42: "Add dependency freshness assessor" + +@claude What's the best way to check if dependencies are up-to-date? + +[Claude responds with options: pip-audit, safety, custom parser] + +Thanks! Let's use pip-audit. Assigning to @claude-bot for implementation. + +[Assigns issue to claude-bot] +[claude-bot creates PR with pip-audit integration] +``` + +### Example 2: Code Review +```markdown +# PR #43: "Implement dependency freshness assessor" + +@claude Can you review this implementation for security issues? + +[Claude provides detailed security review in comment] +``` + +### Example 3: Quick Implementation +```markdown +# GitHub Issue #44: "Fix typo in README" + +[Assigns to claude-bot immediately] +[claude-bot fixes typo in 30 seconds] +``` + +--- + +## 9. References + +- **Claude Code Action**: https://github.com/anthropics/claude-code-action +- **Claude GitHub App**: https://github.com/apps/claude-ai +- **CLAUDE.md Best Practices**: https://arize.com/blog/claude-md-best-practices +- **AgentReady CLAUDE.md**: `/CLAUDE.md` (this repository) +- **Automation Prompt**: `/.github/claude-bot-prompt.md` (this repository) + +--- + +**Last Updated**: 2025-11-21 +**Maintained By**: @jeder +**Status**: Active diff --git a/.github/claude-bot-prompt.md b/.github/claude-bot-prompt.md new file mode 100644 index 0000000..33dba32 --- /dev/null +++ b/.github/claude-bot-prompt.md @@ -0,0 +1,40 @@ +# Claude Bot Automation Context + +This file provides additional instructions for the automated Claude Code Action when implementing issues assigned to `claude-bot`. + +## Automation Workflow + +When assigned an issue, you should: + +1. **Create feature branch**: Always create a feature branch from `main` (never push to main directly) +2. **Follow TDD**: Write tests before implementation when applicable +3. **Run linters**: Always run `black`, `isort`, `ruff` before committing +4. **Run tests**: Ensure all tests pass with `pytest` +5. **Commit frequently**: Use conventional commits with clear, succinct messages +6. **Open PR**: Create a pull request for review (don't merge automatically) + +## Implementation Standards + +- **Python**: Follow PEP 8, use type hints, support Python 3.11+ +- **Testing**: Maintain >80% coverage for new code +- **Documentation**: Update docstrings and CLAUDE.md as needed +- **Security**: Never expose secrets, validate inputs, follow OWASP guidelines + +## PR Template + +When creating pull requests, include: +- Summary of changes +- Test plan +- Breaking changes (if any) +- Related issues/tickets + +## Important Context + +- This is an open-source project under MIT license +- Target audience: Software engineering teams using AI-assisted development +- Code quality and user experience are paramount +- Prefer simple, focused solutions over complex abstractions + +--- + +**Note**: CLAUDE.md is automatically read by the action. This file provides automation-specific guidance that supplements the project-level instructions. diff --git a/.github/workflows/agentready-assessment.yml b/.github/workflows/agentready-assessment.yml index 63f5432..e724c09 100644 --- a/.github/workflows/agentready-assessment.yml +++ b/.github/workflows/agentready-assessment.yml @@ -25,7 +25,7 @@ jobs: - name: Install AgentReady run: | - pip install agentready + pip install -e . - name: Run AgentReady Assessment run: | diff --git a/.github/workflows/claude-code-action.yml b/.github/workflows/claude-code-action.yml index 28bd2b4..687694e 100644 --- a/.github/workflows/claude-code-action.yml +++ b/.github/workflows/claude-code-action.yml @@ -1,14 +1,8 @@ -name: Claude Code Action +name: Claude Code Action (Automated) on: - issue_comment: - types: [created] - pull_request_review_comment: - types: [created] issues: - types: [opened, assigned] - pull_request: - types: [opened, ready_for_review] + types: [assigned] permissions: contents: write @@ -18,6 +12,8 @@ permissions: jobs: claude-code: runs-on: ubuntu-latest + # Only run when assigned to claude-bot user + if: github.event.assignee.login == 'claude-bot' steps: - name: Checkout repository uses: actions/checkout@v4 @@ -29,3 +25,6 @@ jobs: with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} github_token: ${{ secrets.GITHUB_TOKEN }} + # CLAUDE.md is automatically read by the action + # Optional: Uncomment to add automation-specific instructions + # claude_args: --append-system-prompt "Focus on implementation. Create feature branches, write tests, and open PRs for review." diff --git a/.github/workflows/continuous-learning.yml b/.github/workflows/continuous-learning.yml new file mode 100644 index 0000000..3f66d59 --- /dev/null +++ b/.github/workflows/continuous-learning.yml @@ -0,0 +1,134 @@ +name: Continuous Learning - Extract Skills + +on: + # Manual trigger + workflow_dispatch: + inputs: + output_format: + description: 'Output format for skills' + required: true + default: 'github-issues' + type: choice + options: + - github-issues + - skill-files + - both + + # Automatic on new releases + release: + types: [published] + + # Weekly analysis on Sundays at midnight UTC + schedule: + - cron: '0 0 * * 0' + +jobs: + extract-skills: + runs-on: ubuntu-latest + permissions: + contents: write + issues: write + pull-requests: write + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install uv + uses: astral-sh/setup-uv@v3 + + - name: Install AgentReady + run: | + uv pip install -e . + + - name: Run self-assessment + run: | + uv run agentready assess . --output-dir .agentready + + - name: Extract learnings + id: learn + run: | + uv run agentready learn . --output-format json > .skills-proposals/discovered-skills.json + echo "skill_count=$(jq '.skill_count' .skills-proposals/discovered-skills.json)" >> $GITHUB_OUTPUT + + - name: Generate skill proposals + if: steps.learn.outputs.skill_count > 0 + run: | + uv run agentready learn . --output-format all --output-dir .skills-proposals + + - name: Create GitHub issues for each skill + if: (inputs.output_format == 'github-issues' || inputs.output_format == 'both') && steps.learn.outputs.skill_count > 0 + env: + GH_TOKEN: ${{ github.token }} + run: | + for skill_file in .skills-proposals/skill-*.md; do + if [ -f "$skill_file" ]; then + # Extract skill name from filename + skill_name=$(basename "$skill_file" .md | sed 's/^skill-//' | sed 's/-/ /g') + + # Create issue with skill proposal + gh issue create \ + --title "Skill Proposal: ${skill_name}" \ + --label "skill-proposal,enhancement,ai-agent" \ + --body-file "$skill_file" + + echo "Created issue for: $skill_name" + fi + done + + - name: Create PR with skill files + if: (inputs.output_format == 'skill-files' || inputs.output_format == 'both') && steps.learn.outputs.skill_count > 0 + run: | + # Configure git + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + # Create new branch + BRANCH_NAME="skills/auto-$(date +%Y%m%d-%H%M%S)" + git checkout -b "$BRANCH_NAME" + + # Copy SKILL.md files to .claude/skills + mkdir -p .claude/skills + for skill_dir in .skills-proposals/*/; do + if [ -d "$skill_dir" ] && [ -f "${skill_dir}SKILL.md" ]; then + skill_id=$(basename "$skill_dir") + mkdir -p ".claude/skills/$skill_id" + cp "${skill_dir}SKILL.md" ".claude/skills/$skill_id/" + echo "Copied skill: $skill_id" + fi + done + + # Commit and push + git add .claude/skills + git commit -m "feat: add discovered skills from continuous learning + +Automatically extracted skills from latest assessment. + +🤖 Generated with Claude Code +Co-Authored-By: Claude " + + git push origin "$BRANCH_NAME" + + # Create PR + gh pr create \ + --title "Add discovered skills from continuous learning" \ + --body "Automatically discovered new Claude Code skills from AgentReady assessment. Review and merge to make available." + + - name: Upload skill proposals as artifacts + if: steps.learn.outputs.skill_count > 0 + uses: actions/upload-artifact@v4 + with: + name: skill-proposals-${{ github.run_number }} + path: .skills-proposals/ + retention-days: 90 + + - name: Summary + if: steps.learn.outputs.skill_count > 0 + run: | + echo "✅ Discovered ${{ steps.learn.outputs.skill_count }} skills with confidence â‰Ĩ70%" + echo "📁 Artifacts uploaded for review" diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml new file mode 100644 index 0000000..68d2620 --- /dev/null +++ b/.github/workflows/publish-pypi.yml @@ -0,0 +1,128 @@ +name: Publish to PyPI + +on: + workflow_dispatch: + inputs: + version: + description: 'Version to publish (leave empty to use current version from pyproject.toml)' + required: false + type: string + dry_run: + description: 'Perform a dry run (publish to TestPyPI instead)' + required: false + type: boolean + default: true + +jobs: + publish: + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write # Required for trusted publishing + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install build dependencies + run: | + python -m pip install --upgrade pip + pip install build twine + + - name: Update version if specified + if: inputs.version != '' + env: + VERSION: ${{ inputs.version }} + run: | + # Update version in pyproject.toml + sed -i "s/^version = .*/version = \"$VERSION\"/" pyproject.toml + echo "Updated version to $VERSION" + + - name: Build package + run: | + python -m build + echo "đŸ“Ļ Built distribution files:" + ls -lh dist/ + + - name: Check distribution + run: | + twine check dist/* + + - name: Publish to TestPyPI (dry run) + if: inputs.dry_run == true + env: + TWINE_USERNAME: __token__ + TWINE_PASSWORD: ${{ secrets.TEST_PYPI_TOKEN }} + run: | + echo "đŸ§Ē Publishing to TestPyPI..." + twine upload --repository testpypi dist/* + echo "✅ Published to TestPyPI: https://test.pypi.org/project/agentready/" + + - name: Publish to PyPI (production) + if: inputs.dry_run == false + env: + TWINE_USERNAME: __token__ + TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }} + run: | + echo "🚀 Publishing to PyPI..." + twine upload dist/* + echo "✅ Published to PyPI: https://pypi.org/project/agentready/" + + - name: Create GitHub Release + if: inputs.dry_run == false && inputs.version != '' + env: + VERSION: ${{ inputs.version }} + uses: actions/github-script@v7 + with: + script: | + const version = process.env.VERSION; + const tag = `v${version}`; + + // Create tag + await github.rest.git.createRef({ + owner: context.repo.owner, + repo: context.repo.repo, + ref: `refs/tags/${tag}`, + sha: context.sha + }); + + // Create release + await github.rest.repos.createRelease({ + owner: context.repo.owner, + repo: context.repo.repo, + tag_name: tag, + name: `Release ${version}`, + body: `Published to PyPI: https://pypi.org/project/agentready/${version}/`, + draft: false, + prerelease: false + }); + + - name: Summary + env: + DRY_RUN: ${{ inputs.dry_run }} + run: | + echo "## Publication Summary" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + + if [ "$DRY_RUN" == "true" ]; then + echo "✅ **Dry Run Complete**" >> $GITHUB_STEP_SUMMARY + echo "Published to TestPyPI: https://test.pypi.org/project/agentready/" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "To install and test:" >> $GITHUB_STEP_SUMMARY + echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY + echo "pip install --index-url https://test.pypi.org/simple/ agentready" >> $GITHUB_STEP_SUMMARY + echo "\`\`\`" >> $GITHUB_STEP_SUMMARY + else + echo "🚀 **Published to PyPI**" >> $GITHUB_STEP_SUMMARY + echo "Package: https://pypi.org/project/agentready/" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "To install:" >> $GITHUB_STEP_SUMMARY + echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY + echo "pip install agentready" >> $GITHUB_STEP_SUMMARY + echo "\`\`\`" >> $GITHUB_STEP_SUMMARY + fi diff --git a/.skills-proposals/discovered-skills.json b/.skills-proposals/discovered-skills.json new file mode 100644 index 0000000..30e90c4 --- /dev/null +++ b/.skills-proposals/discovered-skills.json @@ -0,0 +1,36 @@ +{ + "generated_at": "2025-11-21T14:17:47.941871", + "skill_count": 2, + "min_confidence": 70, + "discovered_skills": [ + { + "skill_id": "setup-claude-md", + "name": "Setup CLAUDE.md Configuration", + "description": "Create comprehensive CLAUDE.md files with tech stack, standard commands, repository structure, and boundaries to optimize repositories for AI-assisted development", + "confidence": 100.0, + "source_attribute_id": "claude_md_file", + "reusability_score": 100.0, + "impact_score": 50.0, + "pattern_summary": "Project-specific configuration for Claude Code", + "code_examples": [ + "CLAUDE.md found at /Users/jeder/repos/agentready/CLAUDE.md" + ], + "citations": [] + }, + { + "skill_id": "implement-type-annotations", + "name": "Implement Type Annotations", + "description": "Add comprehensive type hints to Python/TypeScript code to improve IDE support, catch errors early, and enable better AI code understanding", + "confidence": 100.0, + "source_attribute_id": "type_annotations", + "reusability_score": 100.0, + "impact_score": 50.0, + "pattern_summary": "Type hints in function signatures", + "code_examples": [ + "Typed functions: 180/186", + "Coverage: 96.8%" + ], + "citations": [] + } + ] +} \ No newline at end of file diff --git a/.skills-proposals/implement-type-annotations-report.md b/.skills-proposals/implement-type-annotations-report.md new file mode 100644 index 0000000..658fad4 --- /dev/null +++ b/.skills-proposals/implement-type-annotations-report.md @@ -0,0 +1,63 @@ +# Skill Report: Implement Type Annotations + +## Overview + +**Skill ID**: `implement-type-annotations` +**Confidence**: 100.0% +**Impact**: +50.0 pts +**Reusability**: 100.0% +**Source Attribute**: type_annotations + +--- + +## Description + +Add comprehensive type hints to Python/TypeScript code to improve IDE support, catch errors early, and enable better AI code understanding + +--- + +## Pattern Summary + +Type hints in function signatures + +--- + +## Implementation Guidance + +### When to Use This Skill + +Use this skill when you need to apply the pattern described above to your repository. + +### Code Examples + + +#### Example 1 + +``` +Typed functions: 180/186 +``` + +#### Example 2 + +``` +Coverage: 96.8% +``` + +--- + +## Research Citations + +_No citations available_ + +--- + +## Metrics + +- **Confidence Score**: 100.0% - How confident we are this is a valid pattern +- **Impact Score**: 50.0 pts - Expected score improvement from applying this skill +- **Reusability Score**: 100.0% - How often this pattern applies across projects + +--- + +**Generated by**: AgentReady Skill Generator +**Source**: Pattern extracted from type_annotations assessment diff --git a/.skills-proposals/implement-type-annotations/SKILL.md b/.skills-proposals/implement-type-annotations/SKILL.md new file mode 100644 index 0000000..39b320e --- /dev/null +++ b/.skills-proposals/implement-type-annotations/SKILL.md @@ -0,0 +1,49 @@ +--- +name: implement-type-annotations +description: Add comprehensive type hints to Python/TypeScript code to improve IDE support, catch errors early, and enable better AI code understanding +--- +# Implement Type Annotations + +## When to Use This Skill + +Type hints in function signatures + +## Instructions + +1. Review the pattern summary above +2. Apply the pattern to your repository +3. Verify the implementation matches the examples below + + +## Examples + +### Example 1 + +``` +Typed functions: 180/186 +``` + +### Example 2 + +``` +Coverage: 96.8% +``` + +## Best Practices + +- Follow the pattern consistently across your codebase +- Refer to the citations below for authoritative guidance +- Test the implementation after applying the pattern + + +## Citations + +_No citations available_ + +--- + +**Generated by**: AgentReady Skill Generator +**Confidence**: 100.0% +**Source Attribute**: type_annotations +**Reusability**: 100.0% +**Impact**: +50.0 pts diff --git a/.skills-proposals/setup-claude-md-report.md b/.skills-proposals/setup-claude-md-report.md new file mode 100644 index 0000000..2e36fb6 --- /dev/null +++ b/.skills-proposals/setup-claude-md-report.md @@ -0,0 +1,57 @@ +# Skill Report: Setup CLAUDE.md Configuration + +## Overview + +**Skill ID**: `setup-claude-md` +**Confidence**: 100.0% +**Impact**: +50.0 pts +**Reusability**: 100.0% +**Source Attribute**: claude_md_file + +--- + +## Description + +Create comprehensive CLAUDE.md files with tech stack, standard commands, repository structure, and boundaries to optimize repositories for AI-assisted development + +--- + +## Pattern Summary + +Project-specific configuration for Claude Code + +--- + +## Implementation Guidance + +### When to Use This Skill + +Use this skill when you need to apply the pattern described above to your repository. + +### Code Examples + + +#### Example 1 + +``` +CLAUDE.md found at /Users/jeder/repos/agentready/CLAUDE.md +``` + +--- + +## Research Citations + +_No citations available_ + +--- + +## Metrics + +- **Confidence Score**: 100.0% - How confident we are this is a valid pattern +- **Impact Score**: 50.0 pts - Expected score improvement from applying this skill +- **Reusability Score**: 100.0% - How often this pattern applies across projects + +--- + +**Generated by**: AgentReady Skill Generator +**Source**: Pattern extracted from claude_md_file assessment diff --git a/.skills-proposals/setup-claude-md/SKILL.md b/.skills-proposals/setup-claude-md/SKILL.md new file mode 100644 index 0000000..f3f1b35 --- /dev/null +++ b/.skills-proposals/setup-claude-md/SKILL.md @@ -0,0 +1,43 @@ +--- +name: setup-claude-md +description: Create comprehensive CLAUDE.md files with tech stack, standard commands, repository structure, and boundaries to optimize repositories for AI-assisted development +--- +# Setup CLAUDE.md Configuration + +## When to Use This Skill + +Project-specific configuration for Claude Code + +## Instructions + +1. Review the pattern summary above +2. Apply the pattern to your repository +3. Verify the implementation matches the examples below + + +## Examples + +### Example 1 + +``` +CLAUDE.md found at /Users/jeder/repos/agentready/CLAUDE.md +``` + +## Best Practices + +- Follow the pattern consistently across your codebase +- Refer to the citations below for authoritative guidance +- Test the implementation after applying the pattern + + +## Citations + +_No citations available_ + +--- + +**Generated by**: AgentReady Skill Generator +**Confidence**: 100.0% +**Source Attribute**: claude_md_file +**Reusability**: 100.0% +**Impact**: +50.0 pts diff --git a/.skills-proposals/skill-implement-type-annotations.md b/.skills-proposals/skill-implement-type-annotations.md new file mode 100644 index 0000000..00bbf95 --- /dev/null +++ b/.skills-proposals/skill-implement-type-annotations.md @@ -0,0 +1,123 @@ +--- +name: Skill Proposal - Implement Type Annotations +about: Automatically generated skill proposal from AgentReady continuous learning +title: 'Skill Proposal: Implement Type Annotations' +labels: 'skill-proposal, enhancement, ai-agent' +assignees: '' +--- + +## Skill Proposal: Implement Type Annotations + +**Skill ID**: `implement-type-annotations` +**Confidence**: 100.0% +**Impact**: +50.0 pts +**Reusability**: 100.0% +**Source Attribute**: type_annotations + +--- + +## Description + +Add comprehensive type hints to Python/TypeScript code to improve IDE support, catch errors early, and enable better AI code understanding + +--- + +## Pattern Summary + +Type hints in function signatures + +--- + +## Proposed SKILL.md + +```markdown +--- +name: implement-type-annotations +description: Add comprehensive type hints to Python/TypeScript code to improve IDE support, catch errors early, and enable better AI code understanding +--- +# Implement Type Annotations + +## When to Use This Skill + +Type hints in function signatures + +## Instructions + +1. Review the pattern summary above +2. Apply the pattern to your repository +3. Verify the implementation matches the examples below + + +## Examples + +### Example 1 + +``` +Typed functions: 180/186 +``` + +### Example 2 + +``` +Coverage: 96.8% +``` + +## Best Practices + +- Follow the pattern consistently across your codebase +- Refer to the citations below for authoritative guidance +- Test the implementation after applying the pattern + + +## Citations + +_No citations available_ + +--- + +**Generated by**: AgentReady Skill Generator +**Confidence**: 100.0% +**Source Attribute**: type_annotations +**Reusability**: 100.0% +**Impact**: +50.0 pts + +``` + +--- + +## Implementation Plan + +- [ ] Review proposed skill for accuracy +- [ ] Test skill on 3-5 repositories +- [ ] Refine instructions based on testing +- [ ] Create final SKILL.md file +- [ ] Add to `~/.claude/skills/` or `.claude/skills/` +- [ ] Document skill in AgentReady catalog +- [ ] Update skill generator with learnings + +--- + +## Code Examples from Assessment + +### Example 1 + +``` +Typed functions: 180/186 +``` + +### Example 2 + +``` +Coverage: 96.8% +``` + +--- + +## Research Citations + +_No citations available_ + +--- + +**Auto-generated by**: AgentReady Continuous Learning Loop +**Assessment Date**: 2025-11-21T10:02:46.428125 diff --git a/.skills-proposals/skill-setup-claude-md.md b/.skills-proposals/skill-setup-claude-md.md new file mode 100644 index 0000000..a031d54 --- /dev/null +++ b/.skills-proposals/skill-setup-claude-md.md @@ -0,0 +1,111 @@ +--- +name: Skill Proposal - Setup CLAUDE.md Configuration +about: Automatically generated skill proposal from AgentReady continuous learning +title: 'Skill Proposal: Setup CLAUDE.md Configuration' +labels: 'skill-proposal, enhancement, ai-agent' +assignees: '' +--- + +## Skill Proposal: Setup CLAUDE.md Configuration + +**Skill ID**: `setup-claude-md` +**Confidence**: 100.0% +**Impact**: +50.0 pts +**Reusability**: 100.0% +**Source Attribute**: claude_md_file + +--- + +## Description + +Create comprehensive CLAUDE.md files with tech stack, standard commands, repository structure, and boundaries to optimize repositories for AI-assisted development + +--- + +## Pattern Summary + +Project-specific configuration for Claude Code + +--- + +## Proposed SKILL.md + +```markdown +--- +name: setup-claude-md +description: Create comprehensive CLAUDE.md files with tech stack, standard commands, repository structure, and boundaries to optimize repositories for AI-assisted development +--- +# Setup CLAUDE.md Configuration + +## When to Use This Skill + +Project-specific configuration for Claude Code + +## Instructions + +1. Review the pattern summary above +2. Apply the pattern to your repository +3. Verify the implementation matches the examples below + + +## Examples + +### Example 1 + +``` +CLAUDE.md found at /Users/jeder/repos/agentready/CLAUDE.md +``` + +## Best Practices + +- Follow the pattern consistently across your codebase +- Refer to the citations below for authoritative guidance +- Test the implementation after applying the pattern + + +## Citations + +_No citations available_ + +--- + +**Generated by**: AgentReady Skill Generator +**Confidence**: 100.0% +**Source Attribute**: claude_md_file +**Reusability**: 100.0% +**Impact**: +50.0 pts + +``` + +--- + +## Implementation Plan + +- [ ] Review proposed skill for accuracy +- [ ] Test skill on 3-5 repositories +- [ ] Refine instructions based on testing +- [ ] Create final SKILL.md file +- [ ] Add to `~/.claude/skills/` or `.claude/skills/` +- [ ] Document skill in AgentReady catalog +- [ ] Update skill generator with learnings + +--- + +## Code Examples from Assessment + +### Example 1 + +``` +CLAUDE.md found at /Users/jeder/repos/agentready/CLAUDE.md +``` + +--- + +## Research Citations + +_No citations available_ + +--- + +**Auto-generated by**: AgentReady Continuous Learning Loop +**Assessment Date**: 2025-11-21T10:02:46.427730 diff --git a/CHANGELOG.md b/CHANGELOG.md index 3d62b2a..009f6da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,24 @@ +# [1.3.0](https://github.com/ambient-code/agentready/compare/v1.2.0...v1.3.0) (2025-11-21) + + +### Features + +* add report header with repository metadata ([#28](https://github.com/ambient-code/agentready/issues/28)) ([7a8b34a](https://github.com/ambient-code/agentready/commit/7a8b34a55471156885e44bab808e959e4c7db3e6)) + +# [1.2.0](https://github.com/ambient-code/agentready/compare/v1.1.2...v1.2.0) (2025-11-21) + + +### Features + +* Add automated demo command for AgentReady ([#24](https://github.com/ambient-code/agentready/issues/24)) ([f4e89d9](https://github.com/ambient-code/agentready/commit/f4e89d9531b38239e3561947015be100de6cbd12)), closes [#1](https://github.com/ambient-code/agentready/issues/1) [#25](https://github.com/ambient-code/agentready/issues/25) [hi#quality](https://github.com/hi/issues/quality) [hi#scoring](https://github.com/hi/issues/scoring) + +## [1.1.2](https://github.com/ambient-code/agentready/compare/v1.1.1...v1.1.2) (2025-11-21) + + +### Bug Fixes + +* correct GitHub repository link in site navigation ([5492278](https://github.com/ambient-code/agentready/commit/5492278a0743c634e33528bcdb8819614d725d0e)) + ## [1.1.1](https://github.com/ambient-code/agentready/compare/v1.1.0...v1.1.1) (2025-11-21) diff --git a/CLAUDE.md b/CLAUDE.md index 0cb2bac..c1b1064 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -40,6 +40,80 @@ agentready assess /path/to/repo --output-dir ./reports --- +## Continuous Learning Loop (LLM-Powered) + +**NEW in v1.1**: Extract high-quality skills from assessments using Claude API + +The `learn` command analyzes assessment results to identify successful patterns and generates Claude Code skills. With `--enable-llm`, it uses Claude Sonnet 4.5 to create detailed, context-aware skill documentation. + +### Basic Usage (Heuristic) + +```bash +# Extract skills using heuristic pattern extraction +agentready learn . + +# Generate SKILL.md files +agentready learn . --output-format skill_md + +# Create GitHub issue templates +agentready learn . --output-format github_issues +``` + +### LLM-Powered Enrichment + +```bash +# Set API key +export ANTHROPIC_API_KEY=sk-ant-api03-... + +# Extract skills with LLM enrichment (top 5 skills) +agentready learn . --enable-llm + +# Enrich more skills with custom budget +agentready learn . --enable-llm --llm-budget 10 + +# Bypass cache for fresh analysis +agentready learn . --enable-llm --llm-no-cache + +# Generate all formats with LLM enrichment +agentready learn . --enable-llm --output-format all +``` + +### LLM Enrichment Features + +**What it does**: +- Analyzes repository code samples for real examples +- Generates 5-10 step detailed instructions +- Extracts file paths and code snippets from actual implementation +- Derives best practices from high-scoring attributes +- Identifies anti-patterns to avoid + +**How it works**: +1. Heuristics extract basic skills from assessment findings +2. Top N skills (default: 5) are sent to Claude API +3. Code sampler provides relevant files from repository +4. Claude analyzes patterns and generates structured JSON +5. Enriched skills merged with detailed instructions/examples +6. Results cached for 7 days to reduce API costs + +**Caching**: +- Responses cached in `.agentready/llm-cache/` +- 7-day TTL (time-to-live) +- Cache key based on attribute + score + evidence hash +- Use `--llm-no-cache` to force fresh API calls + +**Cost Control**: +- `--llm-budget N` limits enrichment to top N skills +- Default: 5 skills (approximately 5-10 API calls) +- Each enrichment: ~2-6 seconds, ~2000-4000 tokens +- Caching prevents redundant calls on repeated assessments + +**Graceful Fallback**: +- Missing API key → falls back to heuristic skills +- API errors → uses original heuristic skill +- Rate limits → retries with exponential backoff + +--- + ## Architecture ### Core Components @@ -48,6 +122,7 @@ agentready assess /path/to/repo --output-dir ./reports src/agentready/ ├── models/ # Data models (Repository, Attribute, Finding, Assessment) ├── services/ # Scanner orchestration and language detection +│ └── llm_cache.py # LLM response caching (7-day TTL) ├── assessors/ # Attribute assessment implementations │ ├── base.py # BaseAssessor abstract class │ ├── documentation.py # CLAUDE.md, README assessors @@ -55,13 +130,20 @@ src/agentready/ │ ├── testing.py # Test coverage, pre-commit hooks │ ├── structure.py # Standard layout, gitignore │ └── stub_assessors.py # 15 not-yet-implemented assessors +├── learners/ # Pattern extraction and LLM enrichment +│ ├── pattern_extractor.py # Heuristic skill extraction +│ ├── skill_generator.py # SKILL.md generation +│ ├── code_sampler.py # Repository code sampling +│ ├── llm_enricher.py # Claude API integration +│ └── prompt_templates.py # LLM prompt engineering ├── reporters/ # Report generation (HTML, Markdown, JSON) │ ├── html.py # Interactive HTML with Jinja2 │ └── markdown.py # GitHub-Flavored Markdown ├── templates/ # Jinja2 templates │ └── report.html.j2 # Self-contained HTML report (73KB) └── cli/ # Click-based CLI - └── main.py # assess, research-version, generate-config commands + ├── main.py # assess, research-version, generate-config commands + └── learn.py # Continuous learning loop with LLM enrichment ``` ### Data Flow @@ -192,6 +274,7 @@ agentready/ - **Python 3.11+** (only N and N-1 versions supported) - **Click** - CLI framework - **Jinja2** - HTML template engine +- **Anthropic** - Claude API client (for LLM enrichment) - **Pytest** - Testing framework - **Black** - Code formatter - **isort** - Import sorter @@ -290,6 +373,7 @@ See `BACKLOG.md` for full feature list. ## Related Documents +- **.github/CLAUDE_INTEGRATION.md** - Dual Claude integration guide (automated + interactive) - **BACKLOG.md** - Future features and enhancements (11 items) - **GITHUB_ISSUES.md** - GitHub-ready issue templates - **README.md** - User-facing documentation diff --git a/pyproject.toml b/pyproject.toml index b77bd79..667ed33 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "agentready" -version = "1.1.1" +version = "1.3.0" description = "Assess git repositories against 25 evidence-based attributes for AI-assisted development readiness" authors = [{name = "Jeremy Eder", email = "jeder@redhat.com"}] readme = "README.md" @@ -22,6 +22,7 @@ dependencies = [ "gitpython>=3.1.0", "radon>=6.0.0", "lizard>=1.17.0", + "anthropic>=0.74.0", ] [project.optional-dependencies] @@ -42,7 +43,7 @@ build-backend = "setuptools.build_meta" [tool.setuptools] package-dir = {"" = "src"} -packages = ["agentready", "agentready.cli", "agentready.assessors", "agentready.models", "agentready.services", "agentready.reporters"] +packages = ["agentready", "agentready.cli", "agentready.assessors", "agentready.models", "agentready.services", "agentready.reporters", "agentready.learners"] [tool.setuptools.package-data] agentready = [ diff --git a/repomix-output.md b/repomix-output.md index 1f1819a..24f8830 100644 --- a/repomix-output.md +++ b/repomix-output.md @@ -45,26 +45,21 @@ The content is organized as follows: speckit.specify.md speckit.tasks.md speckit.taskstoissues.md - settings.local.json .github/ - coldstart-prompts/ - 01-create-automated-demo.md - 02-fix-critical-security-logic-bugs-from-code-review.md - 03-bootstrap-agentready-repository-on-github.md - 04-report-header-with-repository-metadata.md - 05-improve-html-report-design-font-size-color-scheme.md - 06-report-schema-versioning.md - 07-research-report-generatorupdater-utility.md - 08-repomix-integration.md - 09-agentready-repository-agent.md - 10-customizable-html-report-themes.md - 11-fix-code-quality-issues-from-code-review.md - 12-improve-test-coverage-and-edge-case-handling.md - 13-add-security-quality-improvements-from-code-review.md - 14-align-subcommand-automated-remediation.md - 15-interactive-dashboard-with-automated-remediation.md - 16-github-app-integration-badge-status-checks.md - README.md + ISSUE_TEMPLATE/ + bug_report.md + feature_request.md + workflows/ + agentready-assessment.yml + claude-code-action.yml + docs-lint.yml + release.yml + security.yml + tests.yml + update-docs.yml + CODEOWNERS + dependabot.yml + PULL_REQUEST_TEMPLATE.md .specify/ memory/ constitution.md @@ -81,15 +76,55 @@ The content is organized as follows: plan-template.md spec-template.md tasks-template.md +coldstart-prompts/ + 01-create-automated-demo.md + 02-fix-critical-security-logic-bugs-from-code-review.md + 03-bootstrap-agentready-repository-on-github.md + 04-report-header-with-repository-metadata.md + 05-improve-html-report-design-font-size-color-scheme.md + 06-report-schema-versioning.md + 07-research-report-generatorupdater-utility.md + 08-repomix-integration.md + 09-agentready-repository-agent.md + 10-customizable-html-report-themes.md + 11-fix-code-quality-issues-from-code-review.md + 12-improve-test-coverage-and-edge-case-handling.md + 13-add-security-quality-improvements-from-code-review.md + 14-align-subcommand-automated-remediation.md + 15-interactive-dashboard-with-automated-remediation.md + 16-github-app-integration-badge-status-checks.md + 17-add-bootstrap-quickstart-to-readme.md + 18-setup-release-pipeline.md + 19-github-pages-linter-integration.md + README.md docs/ + _layouts/ + default.html + home.html + page.html + assets/ + css/ + style.css _config.yml + api-reference.md + attributes.md + DEPLOYMENT.md developer-guide.md + examples.md + Gemfile index.md + README.md + RELEASE_PROCESS.md + roadmaps.md + SETUP_SUMMARY.md user-guide.md examples/ self-assessment/ + assessment-20251121-035845.json assessment-20251121.json README.md + report-20251121-035845.html + report-20251121-035845.md report-20251121.html report-20251121.md scripts/ @@ -182,2996 +217,4102 @@ tests/ __init__.py .agentready-config.example.yaml .gitignore +.markdown-link-check.json +.pre-commit-config.yaml +.releaserc.json .repomixignore agent-ready-codebase-attributes.md BACKLOG.md +CHANGELOG.md CLAUDE.md +CODE_OF_CONDUCT.md +CONTRIBUTING.md GITHUB_ISSUES.md +LICENSE pyproject.toml README.md +repomix-output.xml repomix.config.json repos.txt ``` # Files -## File: .claude/settings.local.json -````json -{ - "permissions": { - "allow": [ - "Bash(tree:*)", - "Bash(agentready bootstrap:*)" - ], - "deny": [], - "ask": [] - } -} -```` - -## File: docs/developer-guide.md +## File: .claude/commands/speckit.analyze.md ````markdown --- -layout: page -title: Developer Guide +description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. --- -# Developer Guide - -Comprehensive guide for contributors and developers extending AgentReady. - -## Table of Contents +## User Input -- [Getting Started](#getting-started) -- [Development Environment](#development-environment) -- [Architecture Overview](#architecture-overview) -- [Implementing New Assessors](#implementing-new-assessors) -- [Testing Guidelines](#testing-guidelines) -- [Code Quality Standards](#code-quality-standards) -- [Contributing Workflow](#contributing-workflow) -- [Release Process](#release-process) +```text +$ARGUMENTS +``` ---- +You **MUST** consider the user input before proceeding (if not empty). -## Getting Started +## Goal -### Prerequisites +Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`. -- **Python 3.11 or 3.12** -- **Git** -- **uv** or **pip** (uv recommended for faster dependency management) -- **Make** (optional, for convenience commands) +## Operating Constraints -### Fork and Clone +**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually). -```bash -# Fork on GitHub first, then: -git clone https://github.com/YOUR_USERNAME/agentready.git -cd agentready +**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`. -# Add upstream remote -git remote add upstream https://github.com/yourusername/agentready.git -``` +## Execution Steps -### Install Development Dependencies +### 1. Initialize Analysis Context -```bash -# Create virtual environment -python3 -m venv .venv -source .venv/bin/activate # On Windows: .venv\Scripts\activate +Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: -# Install with development dependencies -uv pip install -e ".[dev]" +- SPEC = FEATURE_DIR/spec.md +- PLAN = FEATURE_DIR/plan.md +- TASKS = FEATURE_DIR/tasks.md -# Or using pip -pip install -e ".[dev]" +Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command). +For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). -# Verify installation -pytest --version -black --version -ruff --version -``` +### 2. Load Artifacts (Progressive Disclosure) ---- +Load only the minimal necessary context from each artifact: -## Development Environment +**From spec.md:** -### Project Structure +- Overview/Context +- Functional Requirements +- Non-Functional Requirements +- User Stories +- Edge Cases (if present) -``` -agentready/ -├── src/agentready/ # Source code -│ ├── cli/ # Click-based CLI -│ │ └── main.py # Entry point (assess, research-version, generate-config) -│ ├── models/ # Data models -│ │ ├── repository.py # Repository representation -│ │ ├── attribute.py # Attribute definition -│ │ ├── finding.py # Assessment finding -│ │ └── assessment.py # Complete assessment result -│ ├── services/ # Core business logic -│ │ ├── scanner.py # Assessment orchestration -│ │ ├── scorer.py # Score calculation -│ │ └── language_detector.py # Language detection via git -│ ├── assessors/ # Attribute assessors -│ │ ├── base.py # BaseAssessor abstract class -│ │ ├── documentation.py # CLAUDE.md, README assessors -│ │ ├── code_quality.py # Type annotations, complexity -│ │ ├── testing.py # Test coverage, pre-commit hooks -│ │ ├── structure.py # Standard layout, gitignore -│ │ └── stub_assessors.py # 15 not-yet-implemented assessors -│ ├── reporters/ # Report generators -│ │ ├── html.py # Interactive HTML with Jinja2 -│ │ ├── markdown.py # GitHub-Flavored Markdown -│ │ └── json.py # Machine-readable JSON -│ ├── templates/ # Jinja2 templates -│ │ └── report.html.j2 # HTML report template -│ └── data/ # Bundled data -│ └── attributes.yaml # Attribute definitions -├── tests/ # Test suite -│ ├── unit/ # Unit tests (fast, isolated) -│ │ ├── test_models.py -│ │ ├── test_assessors_documentation.py -│ │ ├── test_assessors_code_quality.py -│ │ └── ... -│ ├── integration/ # End-to-end tests -│ │ └── test_full_assessment.py -│ └── fixtures/ # Test data -│ └── sample_repos/ # Sample repositories for testing -├── docs/ # GitHub Pages documentation -├── examples/ # Example reports -│ └── self-assessment/ # AgentReady's own assessment -├── pyproject.toml # Python package configuration -├── CLAUDE.md # Project context for AI agents -├── README.md # User-facing documentation -└── BACKLOG.md # Feature backlog -``` +**From plan.md:** -### Development Tools +- Architecture/stack choices +- Data Model references +- Phases +- Technical constraints -AgentReady uses modern Python tooling: +**From tasks.md:** -| Tool | Purpose | Configuration | -|------|---------|---------------| -| **pytest** | Testing framework | `pyproject.toml` | -| **black** | Code formatter | `pyproject.toml` | -| **isort** | Import sorter | `pyproject.toml` | -| **ruff** | Fast linter | `pyproject.toml` | -| **mypy** | Type checker | `pyproject.toml` (future) | +- Task IDs +- Descriptions +- Phase grouping +- Parallel markers [P] +- Referenced file paths -### Running Tests +**From constitution:** -```bash -# Run all tests -pytest +- Load `.specify/memory/constitution.md` for principle validation -# Run with coverage -pytest --cov=src/agentready --cov-report=html +### 3. Build Semantic Models -# Run specific test file -pytest tests/unit/test_models.py -v +Create internal representations (do not include raw artifacts in output): -# Run tests matching pattern -pytest -k "test_claude_md" -v +- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`) +- **User story/action inventory**: Discrete user actions with acceptance criteria +- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases) +- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements -# Run with output (don't capture print statements) -pytest -s +### 4. Detection Passes (Token-Efficient Analysis) -# Fast fail (stop on first failure) -pytest -x -``` +Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary. -### Code Quality Checks +#### A. Duplication Detection -```bash -# Format code -black src/ tests/ +- Identify near-duplicate requirements +- Mark lower-quality phrasing for consolidation -# Sort imports -isort src/ tests/ +#### B. Ambiguity Detection -# Lint code -ruff check src/ tests/ +- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria +- Flag unresolved placeholders (TODO, TKTK, ???, ``, etc.) -# Run all quality checks (recommended before committing) -black src/ tests/ && isort src/ tests/ && ruff check src/ tests/ -``` +#### C. Underspecification -### Pre-commit Hooks (Recommended) +- Requirements with verbs but missing object or measurable outcome +- User stories missing acceptance criteria alignment +- Tasks referencing files or components not defined in spec/plan -Install pre-commit hooks to automatically run quality checks: +#### D. Constitution Alignment -```bash -# Install pre-commit (if not already installed) -pip install pre-commit +- Any requirement or plan element conflicting with a MUST principle +- Missing mandated sections or quality gates from constitution -# Install git hooks -pre-commit install +#### E. Coverage Gaps -# Run manually on all files -pre-commit run --all-files -``` +- Requirements with zero associated tasks +- Tasks with no mapped requirement/story +- Non-functional requirements not reflected in tasks (e.g., performance, security) ---- +#### F. Inconsistency -## Architecture Overview +- Terminology drift (same concept named differently across files) +- Data entities referenced in plan but absent in spec (or vice versa) +- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note) +- Conflicting requirements (e.g., one requires Next.js while other specifies Vue) -AgentReady follows a **library-first architecture** with clear separation of concerns. +### 5. Severity Assignment -### Data Flow +Use this heuristic to prioritize findings: -``` -Repository → Scanner → Assessors → Findings → Assessment → Reporters → Reports - ↓ - Language Detection - (git ls-files) -``` +- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality +- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion +- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case +- **LOW**: Style/wording improvements, minor redundancy not affecting execution order -### Core Components +### 6. Produce Compact Analysis Report -#### 1. Models (`models/`) +Output a Markdown report (no file writes) with the following structure: -Immutable data classes representing domain entities: +## Specification Analysis Report -- **Repository**: Path, name, detected languages -- **Attribute**: ID, name, tier, weight, description -- **Finding**: Attribute, status (pass/fail/skip), score, evidence, remediation -- **Assessment**: Repository, overall score, certification level, findings list +| ID | Category | Severity | Location(s) | Summary | Recommendation | +|----|----------|----------|-------------|---------|----------------| +| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version | -**Design Principles**: -- Immutable (frozen dataclasses) -- Type-annotated -- No business logic (pure data) -- Factory methods for common patterns (`Finding.create_pass()`, etc.) +(Add one row per finding; generate stable IDs prefixed by category initial.) -#### 2. Services (`services/`) +**Coverage Summary Table:** -Orchestration and core algorithms: +| Requirement Key | Has Task? | Task IDs | Notes | +|-----------------|-----------|----------|-------| -- **Scanner**: Coordinates assessment flow, manages assessors -- **Scorer**: Calculates weighted scores, determines certification levels -- **LanguageDetector**: Detects repository languages via `git ls-files` +**Constitution Alignment Issues:** (if any) -**Design Principles**: -- Stateless (pure functions or stateless classes) -- Single responsibility -- No external dependencies (file I/O, network) -- Testable with mocks +**Unmapped Tasks:** (if any) -#### 3. Assessors (`assessors/`) +**Metrics:** -Strategy pattern implementations for each attribute: +- Total Requirements +- Total Tasks +- Coverage % (requirements with >=1 task) +- Ambiguity Count +- Duplication Count +- Critical Issues Count -- **BaseAssessor**: Abstract base class defining interface -- Concrete assessors: `CLAUDEmdAssessor`, `READMEAssessor`, etc. +### 7. Provide Next Actions -**Design Principles**: -- Each assessor is independent -- Inherit from `BaseAssessor` -- Implement `assess(repository)` method -- Return `Finding` object -- Fail gracefully (return "skipped" if tools missing, don't crash) +At end of report, output a concise Next Actions block: -#### 4. Reporters (`reporters/`) +- If CRITICAL issues exist: Recommend resolving before `/speckit.implement` +- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions +- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'" -Transform `Assessment` into report formats: +### 8. Offer Remediation -- **HTMLReporter**: Jinja2-based interactive report -- **MarkdownReporter**: GitHub-Flavored Markdown -- **JSONReporter**: Machine-readable JSON +Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.) -**Design Principles**: -- Take `Assessment` as input -- Return formatted string -- Self-contained (HTML has inline CSS/JS, no CDN) -- Idempotent (same input → same output) +## Operating Principles -### Key Design Patterns +### Context Efficiency -#### Strategy Pattern (Assessors) +- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation +- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis +- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow +- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts -Each assessor is a pluggable strategy implementing the same interface: +### Analysis Guidelines -```python -from abc import ABC, abstractmethod +- **NEVER modify files** (this is read-only analysis) +- **NEVER hallucinate missing sections** (if absent, report them accurately) +- **Prioritize constitution violations** (these are always CRITICAL) +- **Use examples over exhaustive rules** (cite specific instances, not generic patterns) +- **Report zero issues gracefully** (emit success report with coverage statistics) -class BaseAssessor(ABC): - @property - @abstractmethod - def attribute_id(self) -> str: - """Unique attribute identifier.""" - pass +## Context - @abstractmethod - def assess(self, repository: Repository) -> Finding: - """Assess repository for this attribute.""" - pass +$ARGUMENTS +```` - def is_applicable(self, repository: Repository) -> bool: - """Check if this assessor applies to the repository.""" - return True -``` +## File: .claude/commands/speckit.checklist.md +````markdown +--- +description: Generate a custom checklist for the current feature based on user requirements. +--- -#### Factory Pattern (Finding Creation) +## Checklist Purpose: "Unit Tests for English" -`Finding` class provides factory methods for common patterns: +**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain. -```python -# Pass with full score -finding = Finding.create_pass( - attribute=attribute, - evidence="Found CLAUDE.md at repository root", - remediation=None -) +**NOT for verification/testing**: -# Fail with zero score -finding = Finding.create_fail( - attribute=attribute, - evidence="No CLAUDE.md file found", - remediation=Remediation(steps=[...], tools=[...]) -) +- ❌ NOT "Verify the button clicks correctly" +- ❌ NOT "Test error handling works" +- ❌ NOT "Confirm the API returns 200" +- ❌ NOT checking if code/implementation matches the spec -# Skip (not applicable) -finding = Finding.create_skip( - attribute=attribute, - reason="Not implemented yet" -) -``` +**FOR requirements quality validation**: -#### Template Pattern (Reporters) +- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness) +- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity) +- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency) +- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage) +- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases) -Reporters use Jinja2 templates for HTML generation: +**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works. -```python -from jinja2 import Environment, FileSystemLoader +## User Input -class HTMLReporter: - def generate(self, assessment: Assessment) -> str: - env = Environment(loader=FileSystemLoader('templates')) - template = env.get_template('report.html.j2') - return template.render(assessment=assessment) +```text +$ARGUMENTS ``` ---- - -## Implementing New Assessors +You **MUST** consider the user input before proceeding (if not empty). -Follow this step-by-step guide to add a new assessor. +## Execution Steps -### Step 1: Choose an Attribute +1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list. + - All file paths must be absolute. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). -Check `src/agentready/assessors/stub_assessors.py` for not-yet-implemented attributes: +2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST: + - Be generated from the user's phrasing + extracted signals from spec/plan/tasks + - Only ask about information that materially changes checklist content + - Be skipped individually if already unambiguous in `$ARGUMENTS` + - Prefer precision over breadth -```python -# Example stub assessor -class InlineDocumentationAssessor(BaseAssessor): - @property - def attribute_id(self) -> str: - return "inline_documentation" + Generation algorithm: + 1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts"). + 2. Cluster signals into candidate focus areas (max 4) ranked by relevance. + 3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit. + 4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria. + 5. Formulate questions chosen from these archetypes: + - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?") + - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?") + - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?") + - Audience framing (e.g., "Will this be used by the author only or peers during PR review?") + - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?") + - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?") - def assess(self, repository: Repository) -> Finding: - # TODO: Implement actual assessment logic - return Finding.create_skip( - self.attribute, - reason="Assessor not yet implemented" - ) -``` + Question formatting rules: + - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters + - Limit to A–E options maximum; omit table if a free-form answer is clearer + - Never ask the user to restate what they already said + - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope." -### Step 2: Create Assessor Class + Defaults when interaction impossible: + - Depth: Standard + - Audience: Reviewer (PR) if code-related; Author otherwise + - Focus: Top 2 relevance clusters -Create a new file or expand existing category file in `src/agentready/assessors/`: + Output the questions (label Q1/Q2/Q3). After answers: if â‰Ĩ2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more. -```python -# src/agentready/assessors/documentation.py +3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers: + - Derive checklist theme (e.g., security, review, deploy, ux) + - Consolidate explicit must-have items mentioned by user + - Map focus selections to category scaffolding + - Infer any missing context from spec/plan/tasks (do NOT hallucinate) -from agentready.models import Repository, Finding, Attribute, Remediation -from agentready.assessors.base import BaseAssessor +4. **Load feature context**: Read from FEATURE_DIR: + - spec.md: Feature requirements and scope + - plan.md (if exists): Technical details, dependencies + - tasks.md (if exists): Implementation tasks -class InlineDocumentationAssessor(BaseAssessor): - @property - def attribute_id(self) -> str: - return "inline_documentation" + **Context Loading Strategy**: + - Load only necessary portions relevant to active focus areas (avoid full-file dumping) + - Prefer summarizing long sections into concise scenario/requirement bullets + - Use progressive disclosure: add follow-on retrieval only if gaps detected + - If source docs are large, generate interim summary items instead of embedding raw text - def assess(self, repository: Repository) -> Finding: - """ - Assess inline documentation coverage (docstrings/JSDoc). +5. **Generate checklist** - Create "Unit Tests for Requirements": + - Create `FEATURE_DIR/checklists/` directory if it doesn't exist + - Generate unique checklist filename: + - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`) + - Format: `[domain].md` + - If file exists, append to existing file + - Number items sequentially starting from CHK001 + - Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists) - Checks: - - Python: Presence of docstrings in .py files - - JavaScript/TypeScript: JSDoc comments - - Coverage: >80% of public functions documented - """ - # Implement assessment logic here - pass -``` + **CORE PRINCIPLE - Test the Requirements, Not the Implementation**: + Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for: + - **Completeness**: Are all necessary requirements present? + - **Clarity**: Are requirements unambiguous and specific? + - **Consistency**: Do requirements align with each other? + - **Measurability**: Can requirements be objectively verified? + - **Coverage**: Are all scenarios/edge cases addressed? -### Step 3: Implement Assessment Logic + **Category Structure** - Group items by requirement quality dimensions: + - **Requirement Completeness** (Are all necessary requirements documented?) + - **Requirement Clarity** (Are requirements specific and unambiguous?) + - **Requirement Consistency** (Do requirements align without conflicts?) + - **Acceptance Criteria Quality** (Are success criteria measurable?) + - **Scenario Coverage** (Are all flows/cases addressed?) + - **Edge Case Coverage** (Are boundary conditions defined?) + - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?) + - **Dependencies & Assumptions** (Are they documented and validated?) + - **Ambiguities & Conflicts** (What needs clarification?) -Use the `calculate_proportional_score()` helper for partial compliance: + **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**: -```python -def assess(self, repository: Repository) -> Finding: - # Example: Check Python docstrings - if "Python" not in repository.languages: - return Finding.create_skip( - self.attribute, - reason="No Python files detected" - ) + ❌ **WRONG** (Testing implementation): + - "Verify landing page displays 3 episode cards" + - "Test hover states work on desktop" + - "Confirm logo click navigates home" - # Count functions and docstrings - total_functions = self._count_functions(repository) - documented_functions = self._count_documented_functions(repository) + ✅ **CORRECT** (Testing requirements quality): + - "Are the exact number and layout of featured episodes specified?" [Completeness] + - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity] + - "Are hover state requirements consistent across all interactive elements?" [Consistency] + - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage] + - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases] + - "Are loading states defined for asynchronous episode data?" [Completeness] + - "Does the spec define visual hierarchy for competing UI elements?" [Clarity] - if total_functions == 0: - return Finding.create_skip( - self.attribute, - reason="No functions found" - ) + **ITEM STRUCTURE**: + Each item should follow this pattern: + - Question format asking about requirement quality + - Focus on what's WRITTEN (or not written) in the spec/plan + - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.] + - Reference spec section `[Spec §X.Y]` when checking existing requirements + - Use `[Gap]` marker when checking for missing requirements - # Calculate coverage - coverage = documented_functions / total_functions - score = self.calculate_proportional_score(coverage, 0.80) + **EXAMPLES BY QUALITY DIMENSION**: - if score >= 80: # Passes if >= 80% of target - return Finding.create_pass( - self.attribute, - evidence=f"Documented {documented_functions}/{total_functions} functions ({coverage:.1%})", - remediation=None - ) - else: - return Finding.create_fail( - self.attribute, - evidence=f"Only {documented_functions}/{total_functions} functions documented ({coverage:.1%})", - remediation=self._create_remediation(coverage) - ) + Completeness: + - "Are error handling requirements defined for all API failure modes? [Gap]" + - "Are accessibility requirements specified for all interactive elements? [Completeness]" + - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]" -def _count_functions(self, repository: Repository) -> int: - """Count total functions in Python files.""" - # Implementation using ast or grep - pass + Clarity: + - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]" + - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]" + - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]" -def _count_documented_functions(self, repository: Repository) -> int: - """Count functions with docstrings.""" - # Implementation using ast - pass + Consistency: + - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]" + - "Are card component requirements consistent between landing and detail pages? [Consistency]" -def _create_remediation(self, current_coverage: float) -> Remediation: - """Generate remediation guidance.""" - return Remediation( - steps=[ - "Install pydocstyle: `pip install pydocstyle`", - "Run docstring linter: `pydocstyle src/`", - "Add docstrings to flagged functions", - f"Target: {(0.80 - current_coverage) * 100:.0f}% more functions need documentation" - ], - tools=["pydocstyle", "pylint"], - commands=[ - "pydocstyle src/", - "pylint --disable=all --enable=missing-docstring src/" - ], - examples=[ - '''def calculate_total(items: List[Item]) -> float: - """ - Calculate total price of items. + Coverage: + - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]" + - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]" + - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]" - Args: - items: List of items to sum + Measurability: + - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]" + - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]" - Returns: - Total price in USD + **Scenario Classification & Coverage** (Requirements Quality Focus): + - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios + - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?" + - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]" + - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]" - Example: - >>> calculate_total([Item(5.0), Item(3.0)]) - 8.0 - """ - return sum(item.price for item in items)''' - ], - citations=[ - "PEP 257 - Docstring Conventions", - "Google Python Style Guide" - ] - ) -``` + **Traceability Requirements**: + - MINIMUM: â‰Ĩ80% of items MUST include at least one traceability reference + - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]` + - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]" -### Step 4: Register Assessor + **Surface & Resolve Issues** (Requirements Quality Problems): + Ask questions about the requirements themselves: + - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]" + - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]" + - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]" + - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]" + - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]" -Add to scanner's assessor list in `src/agentready/services/scanner.py`: + **Content Consolidation**: + - Soft cap: If raw candidate items > 40, prioritize by risk/impact + - Merge near-duplicates checking the same requirement aspect + - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]" -```python -def __init__(self): - self.assessors = [ - # Existing assessors... - InlineDocumentationAssessor(), - ] -``` + **đŸšĢ ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test: + - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior + - ❌ References to code execution, user actions, system behavior + - ❌ "Displays correctly", "works properly", "functions as expected" + - ❌ "Click", "navigate", "render", "load", "execute" + - ❌ Test cases, test plans, QA procedures + - ❌ Implementation details (frameworks, APIs, algorithms) -### Step 5: Write Tests + **✅ REQUIRED PATTERNS** - These test requirements quality: + - ✅ "Are [requirement type] defined/specified/documented for [scenario]?" + - ✅ "Is [vague term] quantified/clarified with specific criteria?" + - ✅ "Are requirements consistent between [section A] and [section B]?" + - ✅ "Can [requirement] be objectively measured/verified?" + - ✅ "Are [edge cases/scenarios] addressed in requirements?" + - ✅ "Does the spec define [missing aspect]?" -Create comprehensive unit tests in `tests/unit/test_assessors_documentation.py`: +6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### ` lines with globally incrementing IDs starting at CHK001. -```python -import pytest -from agentready.models import Repository -from agentready.assessors.documentation import InlineDocumentationAssessor +7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize: + - Focus areas selected + - Depth level + - Actor/timing + - Any explicit user-specified must-have items incorporated -class TestInlineDocumentationAssessor: - def test_python_well_documented_passes(self, tmp_path): - """Well-documented Python code should pass.""" - # Create test repository - repo_path = tmp_path / "test_repo" - repo_path.mkdir() - (repo_path / ".git").mkdir() +**Important**: Each `/speckit.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows: - # Create Python file with docstrings - code = ''' -def add(a: int, b: int) -> int: - """Add two numbers.""" - return a + b +- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`) +- Simple, memorable filenames that indicate checklist purpose +- Easy identification and navigation in the `checklists/` folder -def subtract(a: int, b: int) -> int: - """Subtract b from a.""" - return a - b -''' - (repo_path / "main.py").write_text(code) +To avoid clutter, use descriptive types and clean up obsolete checklists when done. - # Create repository object - repo = Repository( - path=str(repo_path), - name="test_repo", - languages={"Python": 1} - ) +## Example Checklist Types & Sample Items - # Run assessment - assessor = InlineDocumentationAssessor() - finding = assessor.assess(repo) +**UX Requirements Quality:** `ux.md` - # Verify result - assert finding.status == "pass" - assert finding.score == 100 - assert "2/2 functions" in finding.evidence +Sample items (testing the requirements, NOT the implementation): - def test_python_poorly_documented_fails(self, tmp_path): - """Poorly documented Python code should fail.""" - # Create test repository - repo_path = tmp_path / "test_repo" - repo_path.mkdir() - (repo_path / ".git").mkdir() +- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]" +- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]" +- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]" +- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]" +- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]" +- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]" - # Create Python file with no docstrings - code = ''' -def add(a, b): - return a + b +**API Requirements Quality:** `api.md` -def subtract(a, b): - return a - b -''' - (repo_path / "main.py").write_text(code) +Sample items: - repo = Repository( - path=str(repo_path), - name="test_repo", - languages={"Python": 1} - ) +- "Are error response formats specified for all failure scenarios? [Completeness]" +- "Are rate limiting requirements quantified with specific thresholds? [Clarity]" +- "Are authentication requirements consistent across all endpoints? [Consistency]" +- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]" +- "Is versioning strategy documented in requirements? [Gap]" - assessor = InlineDocumentationAssessor() - finding = assessor.assess(repo) +**Performance Requirements Quality:** `performance.md` - assert finding.status == "fail" - assert finding.score < 80 - assert "0/2 functions" in finding.evidence - assert finding.remediation is not None - assert "pydocstyle" in finding.remediation.tools +Sample items: - def test_non_python_skips(self, tmp_path): - """Non-Python repositories should skip.""" - repo = Repository( - path=str(tmp_path), - name="test_repo", - languages={"JavaScript": 10} - ) +- "Are performance requirements quantified with specific metrics? [Clarity]" +- "Are performance targets defined for all critical user journeys? [Coverage]" +- "Are performance requirements under different load conditions specified? [Completeness]" +- "Can performance requirements be objectively measured? [Measurability]" +- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]" - assessor = InlineDocumentationAssessor() - finding = assessor.assess(repo) +**Security Requirements Quality:** `security.md` - assert finding.status == "skipped" - assert "No Python files" in finding.reason -``` +Sample items: -### Step 6: Test Manually +- "Are authentication requirements specified for all protected resources? [Coverage]" +- "Are data protection requirements defined for sensitive information? [Completeness]" +- "Is the threat model documented and requirements aligned to it? [Traceability]" +- "Are security requirements consistent with compliance obligations? [Consistency]" +- "Are security failure/breach response requirements defined? [Gap, Exception Flow]" -```bash -# Run your new tests -pytest tests/unit/test_assessors_documentation.py -v +## Anti-Examples: What NOT To Do -# Run full assessment on AgentReady itself -agentready assess . --verbose +**❌ WRONG - These test implementation, not requirements:** -# Verify your assessor appears in output +```markdown +- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001] +- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003] +- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010] +- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005] ``` -### Best Practices for Assessors +**✅ CORRECT - These test requirements quality:** -1. **Fail Gracefully**: Return "skipped" if required tools missing, don't crash -2. **Provide Rich Remediation**: Include steps, tools, commands, examples, citations -3. **Use Proportional Scoring**: `calculate_proportional_score()` for partial compliance -4. **Language-Specific Logic**: Check `repository.languages` before assessing -5. **Avoid External Dependencies**: Use stdlib when possible (ast, re, pathlib) -6. **Performance**: Keep assessments fast (<1 second per assessor) -7. **Idempotent**: Same repository → same result -8. **Evidence**: Provide specific, actionable evidence (file paths, counts, examples) +```markdown +- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001] +- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003] +- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010] +- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005] +- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap] +- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001] +``` ---- +**Key Differences:** -## Testing Guidelines +- Wrong: Tests if the system works correctly +- Correct: Tests if the requirements are written correctly +- Wrong: Verification of behavior +- Correct: Validation of requirement quality +- Wrong: "Does it do X?" +- Correct: "Is X clearly specified?" +```` -AgentReady maintains high test quality standards. +## File: .claude/commands/speckit.clarify.md +````markdown +--- +description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create a plan for the spec. I am building with... +--- -### Test Organization +## User Input +```text +$ARGUMENTS ``` -tests/ -├── unit/ # Fast, isolated tests -│ ├── test_models.py -│ ├── test_assessors_*.py -│ └── test_reporters.py -├── integration/ # End-to-end tests -│ └── test_full_assessment.py -└── fixtures/ # Shared test data - └── sample_repos/ -``` - -### Test Types - -#### Unit Tests - -- **Purpose**: Test individual components in isolation -- **Speed**: Very fast (<1s total) -- **Coverage**: Models, assessors, services, reporters -- **Mocking**: Use `pytest` fixtures and mocks -#### Integration Tests +You **MUST** consider the user input before proceeding (if not empty). -- **Purpose**: Test complete workflows end-to-end -- **Speed**: Slower (acceptable up to 10s total) -- **Coverage**: Full assessment pipeline -- **Real Data**: Use fixture repositories +## Outline -### Writing Good Tests +Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file. -#### Test Naming +Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases. -Use descriptive names following pattern: `test___` +Execution steps: -```python -# Good -def test_claude_md_assessor_with_existing_file_passes(): - pass +1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields: + - `FEATURE_DIR` + - `FEATURE_SPEC` + - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.) + - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). -def test_readme_assessor_missing_quick_start_fails(): - pass +2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked). -def test_type_annotations_assessor_javascript_repo_skips(): - pass + Functional Scope & Behavior: + - Core user goals & success criteria + - Explicit out-of-scope declarations + - User roles / personas differentiation -# Bad -def test_assessor(): - pass + Domain & Data Model: + - Entities, attributes, relationships + - Identity & uniqueness rules + - Lifecycle/state transitions + - Data volume / scale assumptions -def test_pass_case(): - pass -``` + Interaction & UX Flow: + - Critical user journeys / sequences + - Error/empty/loading states + - Accessibility or localization notes -#### Arrange-Act-Assert Pattern + Non-Functional Quality Attributes: + - Performance (latency, throughput targets) + - Scalability (horizontal/vertical, limits) + - Reliability & availability (uptime, recovery expectations) + - Observability (logging, metrics, tracing signals) + - Security & privacy (authN/Z, data protection, threat assumptions) + - Compliance / regulatory constraints (if any) -```python -def test_finding_create_pass_sets_correct_attributes(): - # Arrange - attribute = Attribute( - id="test_attr", - name="Test Attribute", - tier=1, - weight=0.10 - ) + Integration & External Dependencies: + - External services/APIs and failure modes + - Data import/export formats + - Protocol/versioning assumptions - # Act - finding = Finding.create_pass( - attribute=attribute, - evidence="Test evidence", - remediation=None - ) + Edge Cases & Failure Handling: + - Negative scenarios + - Rate limiting / throttling + - Conflict resolution (e.g., concurrent edits) - # Assert - assert finding.status == "pass" - assert finding.score == 100 - assert finding.evidence == "Test evidence" - assert finding.remediation is None -``` + Constraints & Tradeoffs: + - Technical constraints (language, storage, hosting) + - Explicit tradeoffs or rejected alternatives -#### Use Fixtures + Terminology & Consistency: + - Canonical glossary terms + - Avoided synonyms / deprecated terms -```python -@pytest.fixture -def sample_repository(tmp_path): - """Create a sample repository for testing.""" - repo_path = tmp_path / "sample_repo" - repo_path.mkdir() - (repo_path / ".git").mkdir() + Completion Signals: + - Acceptance criteria testability + - Measurable Definition of Done style indicators - # Add files - (repo_path / "README.md").write_text("# Sample Repo") - (repo_path / "CLAUDE.md").write_text("# Tech Stack") + Misc / Placeholders: + - TODO markers / unresolved decisions + - Ambiguous adjectives ("robust", "intuitive") lacking quantification - return Repository( - path=str(repo_path), - name="sample_repo", - languages={"Python": 5} - ) + For each category with Partial or Missing status, add a candidate question opportunity unless: + - Clarification would not materially change implementation or validation strategy + - Information is better deferred to planning phase (note internally) -def test_with_fixture(sample_repository): - assert sample_repository.name == "sample_repo" -``` +3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: + - Maximum of 10 total questions across the whole session. + - Each question must be answerable with EITHER: + - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR + - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words"). + - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. + - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. + - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). + - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests. + - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic. -### Coverage Requirements +4. Sequential questioning loop (interactive): + - Present EXACTLY ONE question at a time. + - For multiple‑choice questions: + - **Analyze all options** and determine the **most suitable option** based on: + - Best practices for the project type + - Common patterns in similar implementations + - Risk reduction (security, performance, maintainability) + - Alignment with any explicit project goals or constraints visible in the spec + - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice). + - Format as: `**Recommended:** Option [X] - ` + - Then render all options as a Markdown table: -- **Target**: >80% line coverage for new code -- **Minimum**: >70% overall coverage -- **Critical Paths**: 100% coverage (scoring algorithm, finding creation) + | Option | Description | + |--------|-------------| + | A |