build: Bootstrap agent-ready infrastructure

[dahlem]

Summary

• Bootstrap agent-ready infrastructure via agentready bootstrap
• Add assessment report from agentready assess
• Add CI workflows, issue/PR templates, pre-commit config, and other repo hygiene files

Files added/modified

• .agentready/ — assessment reports and configuration
• .github/workflows/ — CI workflows (agentready assessment, security, tests)
• .github/ISSUE_TEMPLATE/ — issue templates
• .github/PULL_REQUEST_TEMPLATE.md — PR template
• .github/CODEOWNERS — code ownership
• .github/dependabot.yml — dependency update config
• .pre-commit-config.yaml — pre-commit hooks
• CODE_OF_CONDUCT.md — code of conduct (if added)

Test plan

• Verify CI workflows pass on the PR
• Review agentready assessment report
• Confirm no unintended file changes

🤖 Generated with Claude Code

[github-actions]

🤖 AgentReady Assessment Report

Repository: trustyai-service-operator
Path: /home/runner/work/trustyai-service-operator/trustyai-service-operator
Branch: HEAD | Commit: e3d90762
Assessed: February 12, 2026 at 4:10 PM
AgentReady Version: 2.27.0
Run by: runner@runnervmwffz4

---

📊 Summary

Metric	Value
Overall Score	57.4/100 🥉 Bronze (Tier Definitions)
Attributes Assessed	18/25
Attributes Not Assessed	7
Assessment Duration	0.1s

Languages Detected

• Go: 134 files
• YAML: 102 files
• Markdown: 11 files
• JSON: 3 files

Repository Stats

• Total Files: 277
• Total Lines: 62,857

🎯 Priority Improvements

Focus on these high-impact fixes first:

1. CLAUDE.md Configuration Files (Tier 1) - +10.0 points potential
   • Create CLAUDE.md or AGENTS.md with project-specific configuration for AI coding assistants
2. Standard Project Layouts (Tier 1) - +10.0 points potential
   • Organize code into standard directories (src/, tests/, docs/)
3. Conventional Commit Messages (Tier 2) - +3.0 points potential
   • Configure conventional commits with commitlint
4. File Size Limits (Tier 2) - +3.0 points potential
   • Refactor large files into smaller, focused modules
5. Concise Documentation (Tier 2) - +3.0 points potential
   • Make documentation more concise and structured

📋 Detailed Findings

Findings sorted by priority (Tier 1 failures first, then Tier 2, etc.)

CLAUDE.md Configuration Files ❌ 0/100

📝 Remediation Steps

Measured: missing (Threshold: present)

Evidence:

• CLAUDE.md not found in repository root
• AGENTS.md not found (alternative)

Create CLAUDE.md or AGENTS.md with project-specific configuration for AI coding assistants

1. Choose one of three approaches:
2. Option 1: Create standalone CLAUDE.md (>50 bytes) with project context
3. Option 2: Create AGENTS.md and symlink CLAUDE.md to it (cross-tool compatibility)
4. Option 3: Create AGENTS.md and reference it with @AGENTS.md in minimal CLAUDE.md
5. Add project overview and purpose
6. Document key architectural patterns
7. Specify coding standards and conventions
8. Include build/test/deployment commands
9. Add any project-specific context that helps AI assistants

Commands:

# Option 1: Standalone CLAUDE.md
touch CLAUDE.md
# Add content describing your project

# Option 2: Symlink CLAUDE.md to AGENTS.md
touch AGENTS.md
# Add content to AGENTS.md
ln -s AGENTS.md CLAUDE.md

# Option 3: @ reference in CLAUDE.md
echo '@AGENTS.md' > CLAUDE.md
touch AGENTS.md
# Add content to AGENTS.md

Examples:

# Standalone CLAUDE.md (Option 1)

## Overview
Brief description of what this project does.

## Architecture
Key patterns and structure.

## Development
```bash
# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

Coding Standards

• Use TypeScript strict mode
• Follow ESLint configuration
• Write tests for new features

CLAUDE.md with @ reference (Option 3)

@AGENTS.md

AGENTS.md (shared by multiple tools)

Project Overview

This project implements a REST API for user management.

Architecture

• Layered architecture: controllers, services, repositories
• PostgreSQL database with SQLAlchemy ORM
• FastAPI web framework

Development Workflow

# Setup
python -m venv .venv
source .venv/bin/activate
pip install -e .

# Run tests
pytest

# Start server
uvicorn app.main:app --reload

Code Conventions

• Use type hints for all functions
• Follow PEP 8 style guide
• Write docstrings for public APIs
• Maintain >80% test coverage

</details>

![T1](https://img.shields.io/badge/T1-Standard_Project_Layouts_50--100-red) **Standard Project Layouts** ❌ 50/100
<details>
<summary>📝 Remediation Steps</summary>

**Measured**: 1/2 directories (Threshold: 2/2 directories)

**Evidence**:
- Found 1/2 standard directories
- src/: ✗
- tests/: ✓

Organize code into standard directories (src/, tests/, docs/)

1. Create src/ directory for source code
2. Create tests/ directory for test files
3. Create docs/ directory for documentation
4. Move source code into src/
5. Move tests into tests/

**Commands**:
```bash
mkdir -p src tests docs
# Move source files to src/
# Move test files to tests/

Dependency Security & Vulnerability Scanning ✅ 35/100

README Structure ✅ 100/100

Dependency Pinning for Reproducibility ✅ 100/100

Type Annotations ⊘

Conventional Commit Messages ❌ 0/100

📝 Remediation Steps

Measured: not configured (Threshold: configured)

Evidence:

• No commitlint or husky configuration

Configure conventional commits with commitlint

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

Commands:

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

File Size Limits ❌ 40/100

📝 Remediation Steps

Measured: 4 huge, 12 large out of 134 (Threshold: <5% files >500 lines, 0 files >1000 lines)

Evidence:

• Found 4 files >1000 lines (3.0% of 134 files)
• Largest: controllers/evalhub/unit_test.go (1065 lines)

Refactor large files into smaller, focused modules

1. Identify files >1000 lines
2. Split into logical submodules
3. Extract classes/functions into separate files
4. Maintain single responsibility principle

Examples:

# Split large file:
# models.py (1500 lines) → models/user.py, models/product.py, models/order.py

Concise Documentation ❌ 64/100

📝 Remediation Steps

Measured: 50 lines, 7 headings, 6 bullets (Threshold: <500 lines, structured format)

Evidence:

• README length: 50 lines (excellent)
• Heading density: 14.0 per 100 lines (target: 3-5)
• Only 6 bullet points (prefer bullets over prose)

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>

![T2](https://img.shields.io/badge/T2-.gitignore_Completeness_78--100-green) **.gitignore Completeness** ✅ 78/100

![T2](https://img.shields.io/badge/T2-Separation_of_Concerns_94--100-green) **Separation of Concerns** ✅ 94/100

![T2](https://img.shields.io/badge/T2-Pre-commit_Hooks_%26_CI%2FCD_Linting_100--100-green) **Pre-commit Hooks & CI/CD Linting** ✅ 100/100

![T2](https://img.shields.io/badge/T2-One-Command_Build%2FSetup_100--100-green) **One-Command Build/Setup** ✅ 100/100

![T2](https://img.shields.io/badge/T2-Test_Coverage_Requirements_N--A-lightgray) **Test Coverage Requirements** ⊘ 

![T2](https://img.shields.io/badge/T2-Inline_Documentation_N--A-lightgray) **Inline Documentation** ⊘ 

![T3](https://img.shields.io/badge/T3-Architecture_Decision_Records_%28ADRs%29_0--100-red) **Architecture Decision Records (ADRs)** ❌ 0/100
<details>
<summary>📝 Remediation Steps</summary>

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

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

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>

![T3](https://img.shields.io/badge/T3-OpenAPI%2FSwagger_Specifications_0--100-red) **OpenAPI/Swagger Specifications** ❌ 0/100
<details>
<summary>📝 Remediation Steps</summary>

**Measured**: no OpenAPI spec (Threshold: OpenAPI 3.x spec present)

**Evidence**:
- No OpenAPI specification found
- Searched recursively for: openapi.yaml, openapi.yml, openapi.json, swagger.yaml, swagger.yml, swagger.json

Create OpenAPI specification for API endpoints

1. Create openapi.yaml in repository root
2. Define OpenAPI version 3.x
3. Document all API endpoints with full schemas
4. Add request/response examples
5. Define security schemes (API keys, OAuth, etc.)
6. Validate spec with Swagger Editor or Spectral
7. Generate API documentation with Swagger UI or ReDoc

**Commands**:
```bash
# Install OpenAPI validator
npm install -g @stoplight/spectral-cli

# Validate spec
spectral lint openapi.yaml

# Generate client SDK
npx @openapitools/openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o client/

Examples:

# openapi.yaml - Minimal example
openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
  description: API for managing users

servers:
  - url: https://api.example.com/v1

paths:
  /users/{userId}:
    get:
      summary: Get user by ID
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found

components:
  schemas:
    User:
      type: object
      required:
        - id
        - email
      properties:
        id:
          type: string
          example: "user_123"
        email:
          type: string
          format: email
          example: "[email protected]"
        name:
          type: string
          example: "John Doe"

CI/CD Pipeline Visibility ✅ 80/100

Issue & Pull Request Templates ✅ 100/100

Cyclomatic Complexity Thresholds ⊘

Semantic Naming ⊘

Structured Logging ⊘

Code Smell Elimination ❌ 0/100

📝 Remediation Steps

Measured: none (Threshold: ≥60% of applicable linters configured)

Evidence:

• No linters configured

Configure 3 missing linter(s)

1. Configure golangci-lint for Go
2. Add actionlint for GitHub Actions workflow validation
3. Configure markdownlint for documentation quality

Commands:

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
npm install --save-dev markdownlint-cli && touch .markdownlint.json

Examples:

# .pylintrc example
[MASTER]
max-line-length=100

[MESSAGES CONTROL]
disable=C0111

# .eslintrc.json example
{
  "extends": "eslint:recommended",
  "rules": {
    "no-console": "warn"
  }
}

Container/Virtualization Setup ✅ 70/100

Branch Protection Rules ⊘

---

📝 Assessment Metadata

• AgentReady Version: v2.27.0
• Research Version: v1.0.1
• Repository Snapshot: e3d9076
• Assessment Duration: 0.1s
• Assessed By: runner@runnervmwffz4
• Assessment Date: February 12, 2026 at 4:10 PM

🤖 Generated with Claude Code