Skip to content

Conversation

@jeremyeder
Copy link
Contributor

Summary

  • Merged analyze_github_org.py and analyze_github_org_rest.py into a single unified script
  • Added automatic fallback from GraphQL (gh CLI) to REST API for better reliability
  • Included utility scripts for filtering and querying cached repository data
  • Updated .gitignore to exclude generated cache files and temporary repository lists

Changes

Consolidated Script Features

  • Dual API support: Primary GraphQL via gh CLI with automatic REST API fallback
  • Comprehensive data: Fetches organization repos with activity metrics, languages, stars, forks
  • Smart caching: Saves results to .cache/github-org-analysis/ for efficient querying
  • Rich reporting: Activity-sorted repository lists with summary statistics

New Utility Scripts

  • filter_active_originals.py: Filter to original (non-fork) repos with recent activity
  • query_github_cache.py: Query cached data by language, activity, stars, etc.

Gitignore Updates

  • Added .cache/ directory (generated analysis data)
  • Added repository list patterns (*-repos.txt, test-repos.txt, etc.)

Test plan

  • Ran black, isort, ruff on all modified scripts
  • Verified consolidated script maintains all features from both original versions
  • Updated error messages to reference correct script name
  • Confirmed all generated files are properly excluded by gitignore

🤖 Generated with Claude Code

Consolidated analyze_github_org.py and analyze_github_org_rest.py into a
single script with automatic fallback from GraphQL to REST API. Added
supporting utility scripts for filtering and querying cached data.

Updated .gitignore to exclude generated cache files and temporary repo lists.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@github-actions
Copy link
Contributor

🤖 AgentReady Assessment Report

Repository: agentready
Path: /home/runner/work/agentready/agentready
Branch: HEAD | Commit: cc75fef0
Assessed: November 25, 2025 at 2:19 PM
AgentReady Version: 2.7.1
Run by: runner@runnervmg1sw1


📊 Summary

Metric Value
Overall Score 70.4/100
Certification Level Silver
Attributes Assessed 19/31
Attributes Not Assessed 12
Assessment Duration 1.3s

Languages Detected

  • Python: 137 files
  • Markdown: 98 files
  • YAML: 20 files
  • JSON: 9 files
  • Shell: 6 files

Repository Stats

  • Total Files: 315
  • Total Lines: 174,816

🎖️ 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 ✅ pass 100
One-Command Build/Setup T2 ⊘ not_applicable
Container/Virtualization Setup T4 ⊘ not_applicable

Code Organization

Attribute Tier Status Score
Separation of Concerns T2 ✅ pass 98

Code Quality

Attribute Tier Status Score
Type Annotations T1 ❌ fail 41
Cyclomatic Complexity Thresholds T3 ✅ pass 100
Semantic Naming T3 ✅ pass 100
Structured Logging T3 ❌ fail 0
Code Smell Elimination T4 ⊘ not_applicable

❌ Type Annotations

Measured: 32.6% (Threshold: ≥80%)

Evidence:

  • Typed functions: 445/1365
  • Coverage: 32.6%
📝 Remediation Steps

Add type annotations to function signatures

  1. For Python: Add type hints to function parameters and return types
  2. For TypeScript: Enable strict mode in tsconfig.json
  3. Use mypy or pyright for Python type checking
  4. Use tsc --strict for TypeScript
  5. Add type annotations gradually to existing code

Commands:

# Python
pip install mypy
mypy --strict src/

# TypeScript
npm install --save-dev typescript
echo '{"compilerOptions": {"strict": true}}' > tsconfig.json

Examples:

# Python - Before
def calculate(x, y):
    return x + y

# Python - After
def calculate(x: float, y: float) -> float:
    return x + y

// TypeScript - tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

❌ Structured Logging

Measured: not configured (Threshold: structured logging library)

Evidence:

  • No structured logging library found
  • Checked files: pyproject.toml
  • Using built-in logging module (unstructured)
📝 Remediation Steps

Add structured logging library for machine-parseable logs

  1. Choose structured logging library (structlog for Python, winston for Node.js)
  2. Install library and configure JSON formatter
  3. Add standard fields: timestamp, level, message, context
  4. Include request context: request_id, user_id, session_id
  5. Use consistent field naming (snake_case for Python)
  6. Never log sensitive data (passwords, tokens, PII)
  7. Configure different formats for dev (pretty) and prod (JSON)

Commands:

# Install structlog
pip install structlog

# Configure structlog
# See examples for configuration

Examples:

# Python with structlog
import structlog

# Configure structlog
structlog.configure(
    processors=[
        structlog.stdlib.add_log_level,
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.JSONRenderer()
    ]
)

logger = structlog.get_logger()

# Good: Structured logging
logger.info(
    "user_login",
    user_id="123",
    email="user@example.com",
    ip_address="192.168.1.1"
)

# Bad: Unstructured logging
logger.info(f"User {user_id} logged in from {ip}")

Context Window Optimization

Attribute Tier Status Score
CLAUDE.md Configuration Files T1 ✅ pass 100
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:

npm install  # generates package-lock.json

Documentation

Attribute Tier Status Score
Concise Documentation T2 ❌ fail 70
Inline Documentation T2 ✅ pass 100

❌ Concise Documentation

Measured: 276 lines, 40 headings, 38 bullets (Threshold: <500 lines, structured format)

Evidence:

  • README length: 276 lines (excellent)
  • Heading density: 14.5 per 100 lines (target: 3-5)
  • 1 paragraphs exceed 10 lines (walls of text)
📝 Remediation Steps

Make documentation more concise and structured

  1. Break long README into multiple documents (docs/ directory)
  2. Add clear Markdown headings (##, ###) for structure
  3. Convert prose paragraphs to bullet points where possible
  4. Add table of contents for documents >100 lines
  5. Use code blocks instead of describing commands in prose
  6. Move detailed content to wiki or docs/, keep README focused

Commands:

# Check README length
wc -l README.md

# Count headings
grep -c '^#' README.md

Examples:

# Good: Concise with structure

## Quick Start
```bash
pip install -e .
agentready assess .

Features

  • Fast repository scanning
  • HTML and Markdown reports
  • 25 agent-ready attributes

Documentation

See docs/ for detailed guides.

Bad: Verbose prose

This project is a tool that helps you assess your repository
against best practices for AI-assisted development. It works by
scanning your codebase and checking for various attributes that
make repositories more effective when working with AI coding
assistants like Claude Code...

[Many more paragraphs of prose...]


</details>

### Documentation Standards

| Attribute | Tier | Status | Score |
|-----------|------|--------|-------|
| README Structure | T1 | ✅ pass | 100 |
| Architecture Decision Records (ADRs) | T3 | ❌ fail | 0 |
| Architecture Decision Records | T3 | ⊘ not_applicable | — |

#### ❌ Architecture Decision Records (ADRs)

**Measured**: no ADR directory (Threshold: ADR directory with decisions)

**Evidence**:
- No ADR directory found (checked docs/adr/, .adr/, adr/, docs/decisions/)

<details><summary><strong>📝 Remediation Steps</strong></summary>


Create Architecture Decision Records (ADRs) directory and document key decisions

1. Create docs/adr/ directory in repository root
2. Use Michael Nygard ADR template or MADR format
3. Document each significant architectural decision
4. Number ADRs sequentially (0001-*.md, 0002-*.md)
5. Include Status, Context, Decision, and Consequences sections
6. Update ADR status when decisions are revised (Superseded, Deprecated)

**Commands**:

```bash
# Create ADR directory
mkdir -p docs/adr

# Create first ADR using template
cat > docs/adr/0001-use-architecture-decision-records.md << 'EOF'
# 1. Use Architecture Decision Records

Date: 2025-11-22

## Status
Accepted

## Context
We need to record architectural decisions made in this project.

## Decision
We will use Architecture Decision Records (ADRs) as described by Michael Nygard.

## Consequences
- Decisions are documented with context
- Future contributors understand rationale
- ADRs are lightweight and version-controlled
EOF

Examples:

# Example ADR Structure

```markdown
# 2. Use PostgreSQL for Database

Date: 2025-11-22

## Status
Accepted

## Context
We need a relational database for complex queries and ACID transactions.
Team has PostgreSQL experience. Need full-text search capabilities.

## Decision
Use PostgreSQL 15+ as primary database.

## Consequences
- Positive: Robust ACID, full-text search, team familiarity
- Negative: Higher resource usage than SQLite
- Neutral: Need to manage migrations, backups

</details>

### Git & Version Control

| Attribute | Tier | Status | Score |
|-----------|------|--------|-------|
| Conventional Commit Messages | T2 | ❌ fail | 0 |
| .gitignore Completeness | T2 | ✅ pass | 100 |
| Branch Protection Rules | T4 | ⊘ not_applicable | — |
| Issue & Pull Request Templates | T4 | ⊘ not_applicable | — |

#### ❌ Conventional Commit Messages

**Measured**: not configured (Threshold: configured)

**Evidence**:
- No commitlint or husky configuration

<details><summary><strong>📝 Remediation Steps</strong></summary>


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

Performance

Attribute Tier Status Score
Performance Benchmarks T4 ⊘ not_applicable

Repository Structure

Attribute Tier Status Score
Standard Project Layouts T1 ✅ pass 100
Issue & Pull Request Templates T3 ✅ 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 ✅ pass 100
Pre-commit Hooks & CI/CD Linting T2 ✅ pass 100
CI/CD Pipeline Visibility T3 ✅ pass 80

🎯 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. Type Annotations (Tier 1) - +10.0 points potential
    • Add type annotations to function signatures
  3. Conventional Commit Messages (Tier 2) - +3.0 points potential
    • Configure conventional commits with commitlint
  4. Concise Documentation (Tier 2) - +3.0 points potential
    • Make documentation more concise and structured
  5. Architecture Decision Records (ADRs) (Tier 3) - +1.5 points potential
    • Create Architecture Decision Records (ADRs) directory and document key decisions

📝 Assessment Metadata

  • Tool Version: AgentReady v1.0.0
  • Research Report: Bundled version
  • Repository Snapshot: cc75fef
  • Assessment Duration: 1.3s

🤖 Generated with Claude Code

Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +30 to +31
return [
r for r in repos if r.get("primaryLanguageName", "").lower() == language.lower()

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Guard language filter against missing values

The language filter assumes every repo has a primaryLanguageName string and calls .lower() on it. Cached data from analyze_github_org.py sets this field to None for repos without a detected language, so running query_github_cache.py --language … will raise AttributeError as soon as such a repo is encountered, preventing any filtered output. Use a safe default (e.g., (value or '').lower()) before comparing to avoid crashing when repos lack a primary language.

Useful? React with 👍 / 👎.

Configure CodeRabbit with aggressive noise reduction:
- Disable checks already handled locally (black, ruff, isort)
- Set confidence threshold to 0.75 (only comment when certain)
- Focus on security, bugs, breaking changes, performance
- Ignore style preferences and trivial suggestions
- Path-specific instructions for different code areas
- Teach CodeRabbit about AgentReady patterns and conventions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@github-actions
Copy link
Contributor

🤖 AgentReady Assessment Report

Repository: agentready
Path: /home/runner/work/agentready/agentready
Branch: HEAD | Commit: bb9650bb
Assessed: November 25, 2025 at 2:22 PM
AgentReady Version: 2.7.1
Run by: runner@runnervmg1sw1


📊 Summary

Metric Value
Overall Score 70.4/100
Certification Level Silver
Attributes Assessed 19/31
Attributes Not Assessed 12
Assessment Duration 1.5s

Languages Detected

  • Python: 137 files
  • Markdown: 98 files
  • YAML: 21 files
  • JSON: 9 files
  • Shell: 6 files

Repository Stats

  • Total Files: 316
  • Total Lines: 175,015

🎖️ 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 ✅ pass 100
One-Command Build/Setup T2 ⊘ not_applicable
Container/Virtualization Setup T4 ⊘ not_applicable

Code Organization

Attribute Tier Status Score
Separation of Concerns T2 ✅ pass 98

Code Quality

Attribute Tier Status Score
Type Annotations T1 ❌ fail 41
Cyclomatic Complexity Thresholds T3 ✅ pass 100
Semantic Naming T3 ✅ pass 100
Structured Logging T3 ❌ fail 0
Code Smell Elimination T4 ⊘ not_applicable

❌ Type Annotations

Measured: 32.6% (Threshold: ≥80%)

Evidence:

  • Typed functions: 445/1365
  • Coverage: 32.6%
📝 Remediation Steps

Add type annotations to function signatures

  1. For Python: Add type hints to function parameters and return types
  2. For TypeScript: Enable strict mode in tsconfig.json
  3. Use mypy or pyright for Python type checking
  4. Use tsc --strict for TypeScript
  5. Add type annotations gradually to existing code

Commands:

# Python
pip install mypy
mypy --strict src/

# TypeScript
npm install --save-dev typescript
echo '{"compilerOptions": {"strict": true}}' > tsconfig.json

Examples:

# Python - Before
def calculate(x, y):
    return x + y

# Python - After
def calculate(x: float, y: float) -> float:
    return x + y

// TypeScript - tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

❌ Structured Logging

Measured: not configured (Threshold: structured logging library)

Evidence:

  • No structured logging library found
  • Checked files: pyproject.toml
  • Using built-in logging module (unstructured)
📝 Remediation Steps

Add structured logging library for machine-parseable logs

  1. Choose structured logging library (structlog for Python, winston for Node.js)
  2. Install library and configure JSON formatter
  3. Add standard fields: timestamp, level, message, context
  4. Include request context: request_id, user_id, session_id
  5. Use consistent field naming (snake_case for Python)
  6. Never log sensitive data (passwords, tokens, PII)
  7. Configure different formats for dev (pretty) and prod (JSON)

Commands:

# Install structlog
pip install structlog

# Configure structlog
# See examples for configuration

Examples:

# Python with structlog
import structlog

# Configure structlog
structlog.configure(
    processors=[
        structlog.stdlib.add_log_level,
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.JSONRenderer()
    ]
)

logger = structlog.get_logger()

# Good: Structured logging
logger.info(
    "user_login",
    user_id="123",
    email="user@example.com",
    ip_address="192.168.1.1"
)

# Bad: Unstructured logging
logger.info(f"User {user_id} logged in from {ip}")

Context Window Optimization

Attribute Tier Status Score
CLAUDE.md Configuration Files T1 ✅ pass 100
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:

npm install  # generates package-lock.json

Documentation

Attribute Tier Status Score
Concise Documentation T2 ❌ fail 70
Inline Documentation T2 ✅ pass 100

❌ Concise Documentation

Measured: 276 lines, 40 headings, 38 bullets (Threshold: <500 lines, structured format)

Evidence:

  • README length: 276 lines (excellent)
  • Heading density: 14.5 per 100 lines (target: 3-5)
  • 1 paragraphs exceed 10 lines (walls of text)
📝 Remediation Steps

Make documentation more concise and structured

  1. Break long README into multiple documents (docs/ directory)
  2. Add clear Markdown headings (##, ###) for structure
  3. Convert prose paragraphs to bullet points where possible
  4. Add table of contents for documents >100 lines
  5. Use code blocks instead of describing commands in prose
  6. Move detailed content to wiki or docs/, keep README focused

Commands:

# Check README length
wc -l README.md

# Count headings
grep -c '^#' README.md

Examples:

# Good: Concise with structure

## Quick Start
```bash
pip install -e .
agentready assess .

Features

  • Fast repository scanning
  • HTML and Markdown reports
  • 25 agent-ready attributes

Documentation

See docs/ for detailed guides.

Bad: Verbose prose

This project is a tool that helps you assess your repository
against best practices for AI-assisted development. It works by
scanning your codebase and checking for various attributes that
make repositories more effective when working with AI coding
assistants like Claude Code...

[Many more paragraphs of prose...]


</details>

### Documentation Standards

| Attribute | Tier | Status | Score |
|-----------|------|--------|-------|
| README Structure | T1 | ✅ pass | 100 |
| Architecture Decision Records (ADRs) | T3 | ❌ fail | 0 |
| Architecture Decision Records | T3 | ⊘ not_applicable | — |

#### ❌ Architecture Decision Records (ADRs)

**Measured**: no ADR directory (Threshold: ADR directory with decisions)

**Evidence**:
- No ADR directory found (checked docs/adr/, .adr/, adr/, docs/decisions/)

<details><summary><strong>📝 Remediation Steps</strong></summary>


Create Architecture Decision Records (ADRs) directory and document key decisions

1. Create docs/adr/ directory in repository root
2. Use Michael Nygard ADR template or MADR format
3. Document each significant architectural decision
4. Number ADRs sequentially (0001-*.md, 0002-*.md)
5. Include Status, Context, Decision, and Consequences sections
6. Update ADR status when decisions are revised (Superseded, Deprecated)

**Commands**:

```bash
# Create ADR directory
mkdir -p docs/adr

# Create first ADR using template
cat > docs/adr/0001-use-architecture-decision-records.md << 'EOF'
# 1. Use Architecture Decision Records

Date: 2025-11-22

## Status
Accepted

## Context
We need to record architectural decisions made in this project.

## Decision
We will use Architecture Decision Records (ADRs) as described by Michael Nygard.

## Consequences
- Decisions are documented with context
- Future contributors understand rationale
- ADRs are lightweight and version-controlled
EOF

Examples:

# Example ADR Structure

```markdown
# 2. Use PostgreSQL for Database

Date: 2025-11-22

## Status
Accepted

## Context
We need a relational database for complex queries and ACID transactions.
Team has PostgreSQL experience. Need full-text search capabilities.

## Decision
Use PostgreSQL 15+ as primary database.

## Consequences
- Positive: Robust ACID, full-text search, team familiarity
- Negative: Higher resource usage than SQLite
- Neutral: Need to manage migrations, backups

</details>

### Git & Version Control

| Attribute | Tier | Status | Score |
|-----------|------|--------|-------|
| Conventional Commit Messages | T2 | ❌ fail | 0 |
| .gitignore Completeness | T2 | ✅ pass | 100 |
| Branch Protection Rules | T4 | ⊘ not_applicable | — |
| Issue & Pull Request Templates | T4 | ⊘ not_applicable | — |

#### ❌ Conventional Commit Messages

**Measured**: not configured (Threshold: configured)

**Evidence**:
- No commitlint or husky configuration

<details><summary><strong>📝 Remediation Steps</strong></summary>


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

Performance

Attribute Tier Status Score
Performance Benchmarks T4 ⊘ not_applicable

Repository Structure

Attribute Tier Status Score
Standard Project Layouts T1 ✅ pass 100
Issue & Pull Request Templates T3 ✅ 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 ✅ pass 100
Pre-commit Hooks & CI/CD Linting T2 ✅ pass 100
CI/CD Pipeline Visibility T3 ✅ pass 80

🎯 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. Type Annotations (Tier 1) - +10.0 points potential
    • Add type annotations to function signatures
  3. Conventional Commit Messages (Tier 2) - +3.0 points potential
    • Configure conventional commits with commitlint
  4. Concise Documentation (Tier 2) - +3.0 points potential
    • Make documentation more concise and structured
  5. Architecture Decision Records (ADRs) (Tier 3) - +1.5 points potential
    • Create Architecture Decision Records (ADRs) directory and document key decisions

📝 Assessment Metadata

  • Tool Version: AgentReady v1.0.0
  • Research Report: Bundled version
  • Repository Snapshot: bb9650b
  • Assessment Duration: 1.5s

🤖 Generated with Claude Code

@jeremyeder jeremyeder merged commit 244ba8b into main Nov 25, 2025
7 of 9 checks passed
@github-actions
Copy link
Contributor

🎉 This PR is included in version 2.8.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants