Agent Readiness Dashboard

Steps

• For Python: Add type hints to function parameters and return types
• For TypeScript: Enable strict mode in tsconfig.json
• Use mypy or pyright for Python type checking
• Use tsc --strict for TypeScript
• 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

Steps

• Enable Dependabot alerts in GitHub repository settings (or configure Renovate: add renovate.json to repository root)
• Add CodeQL scanning workflow for SAST
• Configure secret detection (detect-secrets, gitleaks)
• Set up language-specific scanners (pip-audit, npm audit, Snyk)

Commands

gh repo edit --enable-security pip install detect-secrets # Python secret detection npm audit # JavaScript dependency audit

Steps

• Identify files >1000 lines
• Split into logical submodules
• Extract classes/functions into separate files
• Maintain single responsibility principle

Steps

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

Commands

# Check README length wc -l README.md # Count headings grep -c '^#' README.md

Steps

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

Commands

# 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

Steps

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

Commands

# Install structlog pip install structlog # Configure structlog # See examples for configuration

Steps

• Create a source directory for your code
• Option A: Use src/ layout (recommended for packages)
• Option B: Use project-named directory (e.g., mypackage/)
• Ensure your package has __init__.py
• Create tests/ directory for test files
• Add at least one test file

Commands

# Option A: src layout mkdir -p src/mypackage touch src/mypackage/__init__.py # --- # Option B: flat layout (project-named) mkdir -p mypackage touch mypackage/__init__.py # Create tests directory mkdir -p tests touch tests/__init__.py touch tests/test_example.py

Steps

• Enable Dependabot in GitHub repository settings
• Add .github/dependabot.yml configuration file
• Or configure Renovate: add renovate.json to repository root
• Set up CodeQL scanning for SAST
• Add secret detection to pre-commit hooks
• Configure language-specific security scanners

Commands

gh repo edit --enable-security pip install pre-commit detect-secrets pre-commit install

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

Commands

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

Steps

• Option A (Python/pre-commit): Add conventional-pre-commit to .pre-commit-config.yaml
• Option B (JS/commitlint): Install commitlint and configure husky for commit-msg hook

Commands

# Python (pre-commit): pip install pre-commit && pre-commit install --hook-type commit-msg # JS (commitlint + husky): npm install --save-dev @commitlint/cli @commitlint/config-conventional husky

Steps

• Choose setup automation tool (Makefile, setup script, or package manager)
• Create setup command that handles all dependencies
• Document setup command prominently in README (Quick Start section)
• Ensure setup is idempotent (safe to run multiple times)
• Test setup on fresh clone to verify it works

Commands

# Example Makefile cat > Makefile << 'EOF' .PHONY: setup setup: python -m venv venv . venv/bin/activate && pip install -r requirements.txt pre-commit install cp .env.example .env @echo 'Setup complete! Run make test to verify.' EOF

Steps

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

Commands

# Check README length wc -l README.md # Count headings grep -c '^#' README.md

Steps

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

Commands

# 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

Steps

• Create .github/ directory if it doesn't exist
• Add PULL_REQUEST_TEMPLATE.md for PRs
• Create .github/ISSUE_TEMPLATE/ directory
• Add bug_report.md for bug reports
• Add feature_request.md for feature requests
• Optionally add config.yml to configure template chooser

Commands

# Create directories mkdir -p .github/ISSUE_TEMPLATE # Create PR template cat > .github/PULL_REQUEST_TEMPLATE.md << 'EOF' ## Summary <!-- Describe the changes in this PR --> ## Related Issues Fixes # ## Testing - [ ] Tests added/updated - [ ] All tests pass ## Checklist - [ ] Documentation updated - [ ] CHANGELOG.md updated EOF

Steps

• Create CI config for your platform (GitHub Actions, GitLab CI, etc.)
• Define jobs: lint, test, build
• Use descriptive job and step names
• Configure dependency caching
• Enable parallel job execution
• Upload artifacts: test results, coverage reports
• Add status badge to README

Commands

# Create GitHub Actions workflow mkdir -p .github/workflows touch .github/workflows/ci.yml # Validate workflow gh workflow view ci.yml

Steps

• Add actionlint for GitHub Actions workflow validation
• Configure markdownlint for documentation quality

Commands

npm install --save-dev markdownlint-cli && touch .markdownlint.json