Coding Open Agent Tools - Roadmap

Current Version: v0.4.1

This document outlines the planned development roadmap for the Coding Open Agent Tools project. All milestones are sequenced by priority and dependency order, not time-based estimates.

🎯 Core Philosophy: Token Efficiency

This project focuses on deterministic operations that save agent tokens:

✅ Parsers - Convert unstructured → structured (saves parsing tokens)
✅ Validators - Catch errors before execution (prevents retry loops)
✅ Extractors - Pull specific data from complex sources
✅ Formatters - Apply deterministic rules (escaping, quoting)
✅ Scanners - Rule-based pattern detection (security, anti-patterns)

We avoid building what agents already do well:

❌ Full code generation (agents excel at creative logic)
❌ Architecture decisions (requires judgment and context)
❌ Code refactoring (agents reason through transformations)
❌ Project scaffolding (agents handle with examples)

📊 Current Status (v0.4.1)

✅ Completed Features

Core Infrastructure (v0.1.0-beta & v0.1.1)

154 total developer tools across 7 modules
PyPI publishing with trusted publishing
Complete GitHub infrastructure (templates, workflows, automation)
Comprehensive documentation (README, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT)

Analysis Module (14 functions) - ✅ Released (v0.1.0)

AST parsing and code structure analysis
Cyclomatic complexity calculation
Import management and organization
Secret detection and security scanning (basic regex patterns, stdlib only)

Git Module (79 functions) - ✅ Released (v0.4.1)

Original 9 functions (v0.1.0): Repository status, diff operations, commit history, blame analysis, branch management, file history tracking
Enhanced with 70 new functions (v0.4.1): Commit message validation, git hooks management, configuration analysis, repository health checks, merge conflict detection, security auditing, submodule management, workflow validation, remote analysis, tags & versioning, diff analysis
Conventional commits validation, git hooks security, repository size analysis, secret scanning in history

Profiling Module (8 functions) - ✅ Released (v0.1.0)

Performance profiling and benchmarking
Memory usage analysis
Memory leak detection
Implementation comparison

Quality Module (7 functions) - ✅ Released (v0.1.0)

Static analysis tool output parsers (ruff, mypy, pytest)
Issue filtering and prioritization
Code quality summarization

Shell Validation Module (13 functions) - ✅ Released (v0.2.0)

Shell syntax validation, dependency checking, ShellCheck integration
Security analysis and injection risk detection
Argument escaping and shebang normalization
Shell script parsing, function/variable extraction
Unquoted variable detection, dangerous command identification
Enhanced secret scanning with optional detect-secrets integration

Python Validation Module (15 functions) - ✅ Released (v0.2.0)

Python syntax and type hint validation
Import order validation and ADK compliance checking
Function signature and docstring parsing
Type annotation extraction and dependency tracking
Docstring formatting and import sorting
Circular import detection, unused import identification
Anti-pattern detection and test coverage gap analysis

Database Operations Module (18 functions) - ✅ Released (v0.3.0)

SQLite database operations (create, execute, fetch)
Schema management and inspection
Safe query building (prevents SQL injection)
JSON import/export and database backup
Pure stdlib implementation (zero dependencies)

📈 Project Health Metrics

Test Coverage: 50%
Code Quality: 100% ruff, 100% mypy --strict
Tests: 570 passing
PyPI: Published and available
GitHub: Full automation and community features
Total Functions: 154 across 7 modules
Decorator Pattern: @strands_tool only (Google ADK compatible)

🗺️ Development Milestones

v0.2.0 - Shell Validation & Security Module

Priority: High Status: ✅ Released (2025-10-15)

Focus: Validation and security analysis (NOT full script generation)

Features (~13 functions):

Validators: validate_shell_syntax(), check_shell_dependencies()
Security Scanners: analyze_shell_security(), detect_shell_injection_risks(), scan_for_secrets_enhanced()
Formatters: escape_shell_argument(), normalize_shebang()
Parsers: parse_shell_script(), extract_shell_functions(), extract_shell_variables()
Analyzers: detect_unquoted_variables(), find_dangerous_commands(), check_error_handling()
Enhanced Secret Detection: Optional detect-secrets integration for comprehensive scanning

Rationale:

Agents waste many tokens getting shell escaping/quoting right
Security issues (unquoted vars, eval, injection) are deterministic to detect
Syntax validation prevents failed executions (saves retry loops)
Parsing shell scripts to extract structure is tedious for agents

Success Criteria:

All 13 functions implemented and tested
80%+ test coverage
Security analysis catches OWASP shell injection patterns
Enhanced secret detection with detect-secrets (optional dependency)
Validation prevents 95%+ of syntax errors
100% ruff and mypy compliance

Example Usage:

import coding_open_agent_tools as coat

# Agent writes a shell script (they're good at this)
script = """#!/bin/bash
APP_DIR=/app
cd $APP_DIR  # Unquoted variable!
eval "$USER_INPUT"  # Dangerous!
"""

# Validate syntax (prevents execution failure)
validation = coat.validate_shell_syntax(script, "bash")
# {'is_valid': 'true', 'errors': ''}

# Security analysis (deterministic rule checking)
issues = coat.analyze_shell_security(script)
# [
#   {'severity': 'high', 'line': 3, 'issue': 'Unquoted variable expansion', ...},
#   {'severity': 'critical', 'line': 4, 'issue': 'Use of eval with user input', ...}
# ]

# Fix escaping (deterministic formatting)
safe_arg = coat.escape_shell_argument(user_input, quote_style="single")

# Enhanced secret detection (optional detect-secrets integration)
secrets = coat.scan_for_secrets_enhanced(script, use_detect_secrets=True)
# Falls back to stdlib regex if detect-secrets not installed

Dependencies:

Python stdlib: re, subprocess, shlex
Optional: detect-secrets>=1.5.0 (pip installable Python library for enhanced secret scanning)
Optional: shellcheck (external tool) for enhanced syntax validation

What We're NOT Building:

❌ Full script generators (agents write scripts well with prompting)
❌ Template systems (agents use examples effectively)
❌ Systemd/cron generators (agents handle these with docs)

v0.3.0 - Python Validation & Analysis Module

Priority: High Status: ✅ Released (2025-10-15)

Focus: Validation, parsing, and formatting (NOT full code generation)

Features (~15 functions):

Validators: validate_python_syntax(), validate_type_hints(), validate_import_order(), check_adk_compliance()
Extractors: parse_function_signature(), extract_docstring_info(), extract_type_annotations(), get_function_dependencies()
Formatters: format_docstring(), sort_imports(), normalize_type_hints()
Analyzers: detect_circular_imports(), find_unused_imports(), identify_anti_patterns(), check_test_coverage_gaps()

Rationale:

Validation prevents syntax/type errors (saves retry loops and tokens)
Parsing function signatures/docstrings is tedious and error-prone for agents
Import sorting and docstring formatting are purely deterministic
ADK compliance checking catches issues before runtime
Agents already write excellent Python code—they just need validation

Success Criteria:

All 15 functions implemented and tested
80%+ test coverage
Validation catches 95%+ of syntax/type errors
Support all 3 docstring styles (Google, NumPy, Sphinx)
100% Google ADK compliance
Parsers handle complex Python 3.9-3.12 syntax

Example Usage:

import coding_open_agent_tools as coat

# Agent writes Python code (they're excellent at this)
code = '''
def process_data(data: list[dict], operation: str) -> dict:
    """Process data with operation."""
    return {"result": "done"}
'''

# Validate syntax (catches errors before execution)
validation = coat.validate_python_syntax(code)
# {'is_valid': 'true', 'error_message': '', 'line_number': '0'}

# Extract signature (tedious parsing for agents)
sig = coat.parse_function_signature(code)
# {'name': 'process_data', 'parameters': '[{"name":"data", "type":"list[dict]"}, ...]', ...}

# Check ADK compliance (deterministic rules)
compliance = coat.check_adk_compliance(code)
# {'is_compliant': 'false', 'issues': ['Missing return type in docstring', ...]}

# Format docstring (deterministic formatting)
formatted = coat.format_docstring(
    description="Process data with operation",
    parameters=[{"name": "data", "type": "list[dict]", "description": "Input data"}],
    return_description="Processing result",
    style="google"
)

Dependencies:

Python stdlib: ast, inspect, textwrap, typing
Optional: mypy, ruff for enhanced validation

What We're NOT Building:

❌ Full function/class generators (agents write excellent code)
❌ Test generators (agents create comprehensive tests)
❌ Project scaffolding (agents use cookiecutter/examples)
❌ Documentation generators (agents write clear docs)

v0.3.5 - SQLite Database Operations Module

Priority: High Status: ✅ Released (2025-10-15)

Focus: Local data storage and structured data management (pure stdlib)

Features (18 functions):

Database Operations: create_sqlite_database(), execute_query(), execute_many(), fetch_all(), fetch_one()
Schema Management: inspect_schema(), create_table_from_dict(), add_column(), create_index()
Safe Query Building: build_select_query(), build_insert_query(), build_update_query(), build_delete_query(), escape_sql_identifier(), validate_sql_query()
Migration Helpers: export_to_json(), import_from_json(), backup_database()
Query Validation: validate_parameterized_query(), check_sql_injection_patterns()

Rationale:

Local data storage is essential for agent memory and state
SQLite is pure stdlib (no dependencies)
Agents waste tokens on SQL syntax and escaping
Safe query building prevents SQL injection
Schema inspection saves repetitive queries

Success Criteria:

All 10 functions implemented and tested
80%+ test coverage
Zero dependencies (pure stdlib sqlite3)
SQL injection prevention through parameterization
100% ruff and mypy compliance

Example Usage:

import coding_open_agent_tools as coat

# Create and populate database
db_path = coat.create_sqlite_database("/tmp/agent_memory.db")

# Safe query building (prevents SQL injection)
query = coat.build_insert_query(
    table="tasks",
    columns=["id", "description", "status"],
    values=[(1, "Analyze code", "done"), (2, "Write tests", "pending")]
)

# Execute safely
coat.execute_many(db_path, query)

# Inspect schema (tedious for agents)
schema = coat.inspect_schema(db_path)
# {'tasks': {'columns': [{'name': 'id', 'type': 'INTEGER'}, ...], 'indexes': [...]}}

# Fetch results
results = coat.fetch_all(db_path, "SELECT * FROM tasks WHERE status = ?", ["pending"])

Use Cases:

Agent Memory: Persist conversation context, learned patterns, user preferences
Structured Data: Store code metrics, test results, profiling data
Cache Layer: Cache expensive analysis results, API responses
State Management: Track multi-step agent workflows

Dependencies:

Python stdlib: sqlite3 only (no external dependencies)

v0.4.0 - Git Enhancement Module (Released as v0.4.1)

Priority: High Status: ✅ Released (2025-10-15)

Focus: Comprehensive git operations beyond basic status/diff (validation, security, analysis)

Original Git Module (9 functions - from v0.1.0):

Status: get_git_status(), get_current_branch(), get_git_diff()
History: get_git_log(), get_git_blame(), get_file_history(), get_file_at_commit()
Branches: list_branches(), get_branch_info()

Enhanced Features (70 new functions across 11 subcategories):

1. Commit Message Validation (8 functions)

Validators: validate_commit_message(), validate_conventional_commits(), validate_commit_signature(), validate_commit_message_length()
Parsers: parse_commit_message(), parse_conventional_commit(), extract_commit_type_scope()
Analyzers: analyze_commit_message_quality(), check_commit_message_links()

2. Git Hooks Management (9 functions)

Validators: validate_git_hook_syntax(), check_hook_permissions(), validate_hook_configuration(), validate_hook_compatibility()
Parsers: parse_git_hook_config(), extract_hook_dependencies()
Security: analyze_hook_security(), check_hook_execution_safety()
Testers: test_hook_execution()

3. Git Configuration Analysis (6 functions)

Validators: validate_git_config(), validate_gitignore_coverage(), validate_gitattributes()
Parsers: parse_gitconfig(), parse_gitignore(), parse_gitattributes()
Detectors: detect_gitignore_conflicts()

4. Repository Health Checks (8 functions)

Analyzers: detect_large_files(), analyze_branch_staleness(), check_repository_size(), analyze_commit_frequency()
Detectors: detect_binary_files(), check_lfs_usage(), detect_repo_bloat(), analyze_clone_performance()

5. Merge Conflict Analysis (6 functions)

Detectors: detect_merge_conflicts(), predict_merge_conflicts(), detect_conflicting_branches()
Parsers: parse_conflict_markers(), extract_conflict_sections()
Analyzers: analyze_conflict_complexity(), suggest_conflict_resolution_strategy()

6. Git Security Auditing (8 functions)

Scanners: scan_commit_history_for_secrets(), validate_commit_signatures(), detect_force_push_history(), audit_repository_permissions()
Validators: check_author_verification(), validate_gpg_signatures(), check_ssh_key_usage()
Analyzers: analyze_permission_changes(), detect_suspicious_commits()

7. Submodule Management (5 functions)

Parsers: parse_gitmodules(), extract_submodule_config()
Validators: validate_submodule_urls(), check_submodule_versions()
Analyzers: analyze_submodule_dependencies(), detect_submodule_drift()

8. Git Workflow Validation (6 functions)

Validators: validate_gitflow_compliance(), validate_trunk_based_workflow(), check_branch_naming_conventions(), validate_merge_strategy()
Analyzers: analyze_branching_model(), check_pr_readiness()

9. Remote Repository Analysis (5 functions)

Parsers: parse_remote_info(), extract_remote_urls(), parse_fetch_refspec()
Validators: check_remote_accessibility(), validate_push_permissions()

10. Tag & Version Management (5 functions)

Validators: validate_semantic_version_tags(), check_tag_format(), validate_version_progression()
Parsers: parse_tag_annotations(), extract_version_info()
Detectors: detect_tag_conflicts()

11. Diff Analysis Enhancement (4 functions)

Parsers: parse_diff_hunks(), extract_diff_statistics()
Analyzers: calculate_diff_complexity(), detect_whitespace_only_changes(), analyze_code_churn()

Rationale:

Git operations are ubiquitous in agent workflows
Commit message validation prevents CI failures (conventional commits, issue linking)
Merge conflict detection saves significant resolution time
Security scanning prevents credential leaks and unauthorized changes
Repository health checks prevent bloat and performance issues
Agents waste many tokens on git output parsing and validation
All operations are deterministic rule-based checks

Success Criteria: ✅ All Met

✅ All 70 functions implemented and tested
✅ Test coverage maintained
✅ Commit message validation (conventional commits support)
✅ Security scanning (secrets in history)
✅ Conflict detection and analysis
✅ 100% ruff and mypy --strict compliance
✅ Zero external dependencies (pure stdlib + subprocess for git commands)

Example Usage:

import coding_open_agent_tools as coat

# Validate commit message (prevents CI failures)
validation = coat.validate_conventional_commits(
    message="feat(api): add user authentication endpoint\n\nImplements JWT-based authentication",
    require_body=True
)
# {'is_valid': 'true', 'type': 'feat', 'scope': 'api', 'breaking': 'false'}

# Security audit (scan entire history for secrets)
secrets = coat.scan_commit_history_for_secrets(
    repo_path="/path/to/repo",
    scan_depth=100
)
# [{'commit': 'abc123', 'file': 'config.py', 'line': 5, 'type': 'api_key', ...}]

# Detect merge conflicts before attempting merge
conflicts = coat.predict_merge_conflicts(
    repo_path="/path/to/repo",
    source_branch="feature/new-api",
    target_branch="main"
)
# {'has_conflicts': 'true', 'conflicting_files': ['src/api.py', 'tests/test_api.py']}

# Repository health check
health = coat.check_repository_size(repo_path="/path/to/repo")
# {'total_size_mb': '150', 'large_files': [...], 'recommendations': [...]}

# Validate git hooks before commit
hook_check = coat.validate_git_hook_syntax(
    hook_path=".git/hooks/pre-commit",
    shell_type="bash"
)
# {'is_valid': 'true', 'security_issues': [], 'permissions_ok': 'true'}

Dependencies:

Python stdlib: subprocess, re, pathlib, json
Git binary (must be installed and in PATH)

What We're NOT Building:

❌ Full git GUI/TUI (use existing tools)
❌ Git workflow automation (agents handle this)
❌ Repository hosting features (use GitHub/GitLab)
❌ Advanced git operations (rebase interactive, cherry-pick) - agents do these well

v0.5.0 - Configuration Validation Module

Priority: High (Next milestone after v0.4.1) Status: 🚧 Planned

Focus: Config validation and security scanning (NOT generation)

Features (~10 functions):

Validators: validate_yaml_syntax(), validate_toml_syntax(), validate_json_schema(), check_ci_config_validity()
Security Scanners: scan_config_for_secrets() (uses detect-secrets), detect_insecure_settings(), check_exposed_ports()
Analyzers: detect_dependency_conflicts(), validate_version_constraints(), check_compatibility()

Rationale:

Config syntax validation prevents deployment failures
Security scanning is deterministic (exposed secrets, insecure defaults)
Dependency conflict detection saves debugging time
Agents already write good configs when given examples/docs

Success Criteria:

All 10 functions implemented and tested
80%+ test coverage
Catches common CI/CD misconfigurations
Detects 95%+ of exposed secrets in configs
Schema validation for major platforms (GitHub Actions, GitLab CI)

Example Usage:

# Validate YAML syntax
validation = coat.validate_yaml_syntax(config_content)

# Security scan (uses detect-secrets under the hood)
issues = coat.scan_config_for_secrets(dockerfile_content)
# [{'severity': 'critical', 'line': 5, 'issue': 'Hardcoded API key', ...}]

# Dependency conflicts
conflicts = coat.detect_dependency_conflicts(requirements_txt)

Dependencies:

Python stdlib: json, re, pathlib
Optional: detect-secrets>=1.5.0 (for secret scanning)
Optional: pyyaml, toml (for enhanced parsing)

What We're NOT Building:

❌ Config generators (agents write configs well with examples)

v0.6.0 - Enhanced Code Analysis Module

Priority: Medium (Follows v0.5.0) Status: 📋 Future

Focus: Advanced deterministic analysis (double down on what works)

Features (~12 functions):

Dependency Analyzers: detect_circular_imports(), find_unused_dependencies(), analyze_import_cycles()
Security Scanners: detect_sql_injection_patterns(), find_xss_vulnerabilities(), scan_for_hardcoded_credentials()
Performance Detectors: identify_n_squared_loops(), detect_memory_leak_patterns(), find_blocking_io()
Compliance Checkers: check_gdpr_compliance(), validate_accessibility(), detect_license_violations()

Rationale:

These are all rule-based, deterministic checks
Agents struggle with complex static analysis
Prevents security and performance issues early
Builds on the project's core strengths

Success Criteria:

All 12 functions implemented
80%+ test coverage
Catches common security vulnerabilities (OWASP Top 10)
Performance checks detect major anti-patterns

What We're NOT Building:

❌ Multi-language code generation (low priority, agents handle well)
❌ Language conversion tools (requires complex transformations)

v0.7.0 - HTTP/API Validation Module

Priority: Medium (Expansion phase after core modules) Status: 📋 Future

Focus: Validate API requests/responses (NOT build clients)

Features (~12 functions):

Validators: validate_json_schema(), check_rest_api_compliance(), validate_http_headers(), validate_http_method()
Parsers: parse_openapi_spec(), extract_api_endpoints(), parse_http_request(), parse_http_response()
Security Scanners: detect_api_security_issues(), check_cors_configuration(), validate_auth_headers()
Analyzers: check_rate_limit_headers(), analyze_api_versioning()

Rationale: Agents waste tokens on API validation logic. Parsing OpenAPI specs is tedious. Security checks are deterministic.

v0.8.0 - Regex Validation & Testing Module

Priority: Medium (Expansion phase) Status: 📋 Future

Focus: Validate and test regex patterns (NOT generate them)

Features (~8 functions):

Validators: validate_regex_syntax(), check_regex_compatibility()
Testers: test_regex_matches(), benchmark_regex_performance()
Security Scanners: detect_catastrophic_backtracking(), check_regex_security()
Parsers: explain_regex_pattern(), extract_regex_groups()

Rationale: Agents write regexes but miss edge cases. Testing and validation is deterministic.

v0.9.0 - Documentation Validation Module

Priority: Medium (Expansion phase) Status: 📋 Future

Focus: Validate and parse docs (NOT generate them)

Features (~10 functions):

Validators: validate_markdown_syntax(), validate_frontmatter(), check_accessibility()
Link Checkers: check_broken_links(), validate_anchor_links(), check_external_links()
Parsers: extract_code_blocks(), parse_table_of_contents(), parse_metadata()
Analyzers: check_heading_hierarchy(), analyze_readability()

Rationale: Agents write good docs. Validation catches broken links and accessibility issues.

v0.10.0 - Dependency Analysis Module

Priority: High (Universal need, high token savings) Status: 📋 Future

Focus: Analyze dependencies and detect conflicts

Features (~12 functions):

Parsers: parse_requirements_txt(), parse_package_json(), parse_poetry_lock(), parse_cargo_toml()
Validators: detect_version_conflicts(), check_security_advisories(), validate_semver()
Analyzers: identify_circular_dependencies(), calculate_dependency_tree(), find_unused_dependencies()
Scanners: check_outdated_dependencies(), detect_license_conflicts()

Rationale: Dependency resolution is deterministic. Agents struggle with complex graphs.

v0.11.0 - Environment Variable Validation Module

Priority: Medium (Expansion phase) Status: 📋 Future

Focus: Validate env vars and .env files

Features (~8 functions):

Validators: validate_env_file_syntax(), check_required_variables(), validate_env_var_types()
Security Scanners: detect_env_var_conflicts(), scan_env_for_secrets()
Parsers: parse_env_file(), extract_env_var_references(), resolve_env_var_substitutions()

Rationale: Agents write .env files but miss validation. Security scanning is deterministic.