From 1980a14a6ba64bb919b10aa6535b4ecfe92098cc Mon Sep 17 00:00:00 2001 From: "actual-ai-analyzer[bot]" <163927646+actual-ai-analyzer[bot]@users.noreply.github.com> Date: Thu, 11 Dec 2025 21:43:07 +0000 Subject: [PATCH] Sync rule files with ADRs - Update CLAUDE.md (claude) - Update .cursor/rules/adr-001.mdc (cursor) - Update .cursor/rules/adr-002.mdc (cursor) - Update .cursor/rules/adr-003.mdc (cursor) - Update .cursor/rules/adr-004.mdc (cursor) - Update .cursor/rules/adr-005.mdc (cursor) - Update .clinerules (cline) - Update .gemini/adr-001.md (gemini) - Update .gemini/adr-002.md (gemini) - Update .gemini/adr-003.md (gemini) - Update .gemini/adr-004.md (gemini) - Update .gemini/adr-005.md (gemini) - Update .gemini/GEMINI.md (gemini) - Update .kiro/steering/architectural-decisions.md (kiro) - Update AGENTS.md (agents) --- .clinerules | 52 +++++++++++++++++ .cursor/rules/adr-001.mdc | 16 ++++++ .cursor/rules/adr-002.mdc | 16 ++++++ .cursor/rules/adr-003.mdc | 16 ++++++ .cursor/rules/adr-004.mdc | 16 ++++++ .cursor/rules/adr-005.mdc | 10 ++++ .gemini/GEMINI.md | 7 +++ .gemini/adr-001.md | 11 ++++ .gemini/adr-002.md | 11 ++++ .gemini/adr-003.md | 11 ++++ .gemini/adr-004.md | 11 ++++ .gemini/adr-005.md | 5 ++ .kiro/steering/architectural-decisions.md | 61 ++++++++++++++++++++ AGENTS.md | 70 +++++++++++++++++++++++ CLAUDE.md | 51 +++++++++++++++++ 15 files changed, 364 insertions(+) create mode 100644 .clinerules create mode 100644 .cursor/rules/adr-001.mdc create mode 100644 .cursor/rules/adr-002.mdc create mode 100644 .cursor/rules/adr-003.mdc create mode 100644 .cursor/rules/adr-004.mdc create mode 100644 .cursor/rules/adr-005.mdc create mode 100644 .gemini/GEMINI.md create mode 100644 .gemini/adr-001.md create mode 100644 .gemini/adr-002.md create mode 100644 .gemini/adr-003.md create mode 100644 .gemini/adr-004.md create mode 100644 .gemini/adr-005.md create mode 100644 .kiro/steering/architectural-decisions.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/.clinerules b/.clinerules new file mode 100644 index 0000000..cb4f046 --- /dev/null +++ b/.clinerules @@ -0,0 +1,52 @@ +--- +description: Architectural decisions for Python development +globs: ["**/*.py", "**"] +--- + +# Global ADRs (All Files) + +## ADR: Use Python For All Development Purposes + +1. use python for everything, and use python 3+ + +# Python File ADRs (*.py) + +## ADR: Git Repository Integration for Provenance Tracking + +1. Use subprocess module with git commands for all Git repository operations in Python applications +2. Validate Git repository existence before performing any git operations using subprocess.run(['git', 'rev-parse', '--git-dir']) +3. Integrate gitignore patterns for file filtering using pathspec module with 'gitwildmatch' pattern type +4. Implement git blame analysis to track file provenance including author, date, and commit metadata +5. Detect repository main branch dynamically by checking for 'main', 'master', or current branch +6. Use Path.resolve() for absolute path resolution when working with Git repository paths +7. Extract git metadata (commit hash, author, email, date) for all analyzed files to support provenance tracking + +## ADR: Asynchronous Programming with Asyncio for Concurrent Operations + +1. Use async/await pattern for all I/O-bound operations including API calls and file processing in Python modules +2. Import asyncio module for event loop management and concurrency primitives +3. Define async functions with 'async def' for any operation that performs network requests or file I/O +4. Use 'await' keyword for all async function calls and use asyncio.sleep() instead of time.sleep() in async contexts +5. Implement async context managers for resource management in asynchronous code +6. Use asyncio.gather() or asyncio.create_task() for concurrent execution of multiple async operations +7. Call asyncio.run() at the entry point to execute async main functions from synchronous code + +## ADR: Click Framework for CLI Application Architecture + +1. Use Click framework (click>=8.0.0) for all command-line interface implementation in Python applications +2. Structure CLI with @click.group() decorator at the top level and @click.command() for subcommands +3. Define command-line options using @click.option() with type hints, help text, and default values +4. Use @click.argument() for required positional arguments with click.Choice() for enumerated values +5. Include colorama>=0.4.6 for cross-platform colored terminal output in all CLI applications +6. Implement --verbose/-v flag for debug output and --force/-f flag to skip confirmation prompts +7. Provide clear help text for all commands and options using the help parameter + +## ADR: Anthropic Claude AI Integration for Code Analysis + +1. Use Anthropic Claude API (via BAML client) for all AI-powered code analysis in Python files +2. Default to 'claude-sonnet-4-20250514' model for analysis tasks unless specific model requirements dictate otherwise +3. Store Anthropic API keys in environment variables (ANTHROPIC_API_KEY) and never hardcode credentials in Python source files +4. Validate BAML client initialization before performing any AI operations using check_baml_client() validation +5. Import AI functionality from baml_client.async_client module for all async AI operations +6. Track token usage for all Claude API calls to monitor costs and usage patterns +7. Set BAML_LOG environment variable to 'OFF' to disable verbose logging in production \ No newline at end of file diff --git a/.cursor/rules/adr-001.mdc b/.cursor/rules/adr-001.mdc new file mode 100644 index 0000000..0eff4e5 --- /dev/null +++ b/.cursor/rules/adr-001.mdc @@ -0,0 +1,16 @@ +--- +globs: ["**/*.py"] +alwaysApply: false +--- + +# Git Repository Integration for Provenance Tracking + +## Policies + +1. Use subprocess module with git commands for all Git repository operations in Python applications +2. Validate Git repository existence before performing any git operations using subprocess.run(['git', 'rev-parse', '--git-dir']) +3. Integrate gitignore patterns for file filtering using pathspec module with 'gitwildmatch' pattern type +4. Implement git blame analysis to track file provenance including author, date, and commit metadata +5. Detect repository main branch dynamically by checking for 'main', 'master', or current branch +6. Use Path.resolve() for absolute path resolution when working with Git repository paths +7. Extract git metadata (commit hash, author, email, date) for all analyzed files to support provenance tracking \ No newline at end of file diff --git a/.cursor/rules/adr-002.mdc b/.cursor/rules/adr-002.mdc new file mode 100644 index 0000000..1f2d70f --- /dev/null +++ b/.cursor/rules/adr-002.mdc @@ -0,0 +1,16 @@ +--- +globs: ["**/*.py"] +alwaysApply: false +--- + +# Asynchronous Programming with Asyncio for Concurrent Operations + +## Policies + +1. Use async/await pattern for all I/O-bound operations including API calls and file processing in Python modules +2. Import asyncio module for event loop management and concurrency primitives +3. Define async functions with 'async def' for any operation that performs network requests or file I/O +4. Use 'await' keyword for all async function calls and use asyncio.sleep() instead of time.sleep() in async contexts +5. Implement async context managers for resource management in asynchronous code +6. Use asyncio.gather() or asyncio.create_task() for concurrent execution of multiple async operations +7. Call asyncio.run() at the entry point to execute async main functions from synchronous code \ No newline at end of file diff --git a/.cursor/rules/adr-003.mdc b/.cursor/rules/adr-003.mdc new file mode 100644 index 0000000..a7b3453 --- /dev/null +++ b/.cursor/rules/adr-003.mdc @@ -0,0 +1,16 @@ +--- +globs: ["**/*.py"] +alwaysApply: false +--- + +# Click Framework for CLI Application Architecture + +## Policies + +1. Use Click framework (click>=8.0.0) for all command-line interface implementation in Python applications +2. Structure CLI with @click.group() decorator at the top level and @click.command() for subcommands +3. Define command-line options using @click.option() with type hints, help text, and default values +4. Use @click.argument() for required positional arguments with click.Choice() for enumerated values +5. Include colorama>=0.4.6 for cross-platform colored terminal output in all CLI applications +6. Implement --verbose/-v flag for debug output and --force/-f flag to skip confirmation prompts +7. Provide clear help text for all commands and options using the help parameter \ No newline at end of file diff --git a/.cursor/rules/adr-004.mdc b/.cursor/rules/adr-004.mdc new file mode 100644 index 0000000..9accd4f --- /dev/null +++ b/.cursor/rules/adr-004.mdc @@ -0,0 +1,16 @@ +--- +globs: ["**/*.py"] +alwaysApply: false +--- + +# Anthropic Claude AI Integration for Code Analysis + +## Policies + +1. Use Anthropic Claude API (via BAML client) for all AI-powered code analysis in Python files +2. Default to 'claude-sonnet-4-20250514' model for analysis tasks unless specific model requirements dictate otherwise +3. Store Anthropic API keys in environment variables (ANTHROPIC_API_KEY) and never hardcode credentials in Python source files +4. Validate BAML client initialization before performing any AI operations using check_baml_client() validation +5. Import AI functionality from baml_client.async_client module for all async AI operations +6. Track token usage for all Claude API calls to monitor costs and usage patterns +7. Set BAML_LOG environment variable to 'OFF' to disable verbose logging in production \ No newline at end of file diff --git a/.cursor/rules/adr-005.mdc b/.cursor/rules/adr-005.mdc new file mode 100644 index 0000000..f920f8e --- /dev/null +++ b/.cursor/rules/adr-005.mdc @@ -0,0 +1,10 @@ +--- +globs: ["**"] +alwaysApply: false +--- + +# Use Python For All Development Purposes + +## Policies + +1. use python for everything, and use python 3+ \ No newline at end of file diff --git a/.gemini/GEMINI.md b/.gemini/GEMINI.md new file mode 100644 index 0000000..292d7f3 --- /dev/null +++ b/.gemini/GEMINI.md @@ -0,0 +1,7 @@ +Development standards and architectural decision records are stored individually below and are important to development. + +@adr-001.md +@adr-002.md +@adr-003.md +@adr-004.md +@adr-005.md \ No newline at end of file diff --git a/.gemini/adr-001.md b/.gemini/adr-001.md new file mode 100644 index 0000000..75b3960 --- /dev/null +++ b/.gemini/adr-001.md @@ -0,0 +1,11 @@ +# Git Repository Integration for Provenance Tracking + +## Policies + +1. Use subprocess module with git commands for all Git repository operations in Python applications +2. Validate Git repository existence before performing any git operations using subprocess.run(['git', 'rev-parse', '--git-dir']) +3. Integrate gitignore patterns for file filtering using pathspec module with 'gitwildmatch' pattern type +4. Implement git blame analysis to track file provenance including author, date, and commit metadata +5. Detect repository main branch dynamically by checking for 'main', 'master', or current branch +6. Use Path.resolve() for absolute path resolution when working with Git repository paths +7. Extract git metadata (commit hash, author, email, date) for all analyzed files to support provenance tracking \ No newline at end of file diff --git a/.gemini/adr-002.md b/.gemini/adr-002.md new file mode 100644 index 0000000..3a8a4ca --- /dev/null +++ b/.gemini/adr-002.md @@ -0,0 +1,11 @@ +# Asynchronous Programming with Asyncio for Concurrent Operations + +## Policies + +1. Use async/await pattern for all I/O-bound operations including API calls and file processing in Python modules +2. Import asyncio module for event loop management and concurrency primitives +3. Define async functions with 'async def' for any operation that performs network requests or file I/O +4. Use 'await' keyword for all async function calls and use asyncio.sleep() instead of time.sleep() in async contexts +5. Implement async context managers for resource management in asynchronous code +6. Use asyncio.gather() or asyncio.create_task() for concurrent execution of multiple async operations +7. Call asyncio.run() at the entry point to execute async main functions from synchronous code \ No newline at end of file diff --git a/.gemini/adr-003.md b/.gemini/adr-003.md new file mode 100644 index 0000000..229b8d7 --- /dev/null +++ b/.gemini/adr-003.md @@ -0,0 +1,11 @@ +# Click Framework for CLI Application Architecture + +## Policies + +1. Use Click framework (click>=8.0.0) for all command-line interface implementation in Python applications +2. Structure CLI with @click.group() decorator at the top level and @click.command() for subcommands +3. Define command-line options using @click.option() with type hints, help text, and default values +4. Use @click.argument() for required positional arguments with click.Choice() for enumerated values +5. Include colorama>=0.4.6 for cross-platform colored terminal output in all CLI applications +6. Implement --verbose/-v flag for debug output and --force/-f flag to skip confirmation prompts +7. Provide clear help text for all commands and options using the help parameter \ No newline at end of file diff --git a/.gemini/adr-004.md b/.gemini/adr-004.md new file mode 100644 index 0000000..5bce035 --- /dev/null +++ b/.gemini/adr-004.md @@ -0,0 +1,11 @@ +# Anthropic Claude AI Integration for Code Analysis + +## Policies + +1. Use Anthropic Claude API (via BAML client) for all AI-powered code analysis in Python files +2. Default to 'claude-sonnet-4-20250514' model for analysis tasks unless specific model requirements dictate otherwise +3. Store Anthropic API keys in environment variables (ANTHROPIC_API_KEY) and never hardcode credentials in Python source files +4. Validate BAML client initialization before performing any AI operations using check_baml_client() validation +5. Import AI functionality from baml_client.async_client module for all async AI operations +6. Track token usage for all Claude API calls to monitor costs and usage patterns +7. Set BAML_LOG environment variable to 'OFF' to disable verbose logging in production \ No newline at end of file diff --git a/.gemini/adr-005.md b/.gemini/adr-005.md new file mode 100644 index 0000000..08d615e --- /dev/null +++ b/.gemini/adr-005.md @@ -0,0 +1,5 @@ +# Use Python For All Development Purposes + +## Policies + +1. use python for everything, and use python 3+ \ No newline at end of file diff --git a/.kiro/steering/architectural-decisions.md b/.kiro/steering/architectural-decisions.md new file mode 100644 index 0000000..a388af7 --- /dev/null +++ b/.kiro/steering/architectural-decisions.md @@ -0,0 +1,61 @@ +--- +title: Architectural Decisions +type: steering +inclusion: always +--- + +# Repository-Wide ADRs (All Files) + +## ADR: Use Python For All Development Purposes + +1. use python for everything, and use python 3+ + +--- + +# Python File ADRs (*.py) + +## ADR: Git Repository Integration for Provenance Tracking + +1. Use subprocess module with git commands for all Git repository operations in Python applications +2. Validate Git repository existence before performing any git operations using subprocess.run(['git', 'rev-parse', '--git-dir']) +3. Integrate gitignore patterns for file filtering using pathspec module with 'gitwildmatch' pattern type +4. Implement git blame analysis to track file provenance including author, date, and commit metadata +5. Detect repository main branch dynamically by checking for 'main', 'master', or current branch +6. Use Path.resolve() for absolute path resolution when working with Git repository paths +7. Extract git metadata (commit hash, author, email, date) for all analyzed files to support provenance tracking + +--- + +## ADR: Asynchronous Programming with Asyncio for Concurrent Operations + +1. Use async/await pattern for all I/O-bound operations including API calls and file processing in Python modules +2. Import asyncio module for event loop management and concurrency primitives +3. Define async functions with 'async def' for any operation that performs network requests or file I/O +4. Use 'await' keyword for all async function calls and use asyncio.sleep() instead of time.sleep() in async contexts +5. Implement async context managers for resource management in asynchronous code +6. Use asyncio.gather() or asyncio.create_task() for concurrent execution of multiple async operations +7. Call asyncio.run() at the entry point to execute async main functions from synchronous code + +--- + +## ADR: Click Framework for CLI Application Architecture + +1. Use Click framework (click>=8.0.0) for all command-line interface implementation in Python applications +2. Structure CLI with @click.group() decorator at the top level and @click.command() for subcommands +3. Define command-line options using @click.option() with type hints, help text, and default values +4. Use @click.argument() for required positional arguments with click.Choice() for enumerated values +5. Include colorama>=0.4.6 for cross-platform colored terminal output in all CLI applications +6. Implement --verbose/-v flag for debug output and --force/-f flag to skip confirmation prompts +7. Provide clear help text for all commands and options using the help parameter + +--- + +## ADR: Anthropic Claude AI Integration for Code Analysis + +1. Use Anthropic Claude API (via BAML client) for all AI-powered code analysis in Python files +2. Default to 'claude-sonnet-4-20250514' model for analysis tasks unless specific model requirements dictate otherwise +3. Store Anthropic API keys in environment variables (ANTHROPIC_API_KEY) and never hardcode credentials in Python source files +4. Validate BAML client initialization before performing any AI operations using check_baml_client() validation +5. Import AI functionality from baml_client.async_client module for all async AI operations +6. Track token usage for all Claude API calls to monitor costs and usage patterns +7. Set BAML_LOG environment variable to 'OFF' to disable verbose logging in production \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..139eb77 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,70 @@ +# Development Guidelines + +This document provides comprehensive development guidelines and policies for the rulectl repository. + +## Project Structure & Module Organization + +The repository follows Python best practices for project organization. + +## Build, Test, and Development Commands + +Standard Python development commands apply for building, testing, and running the application. + +## Coding Style & Naming Conventions + +### Python Programming + +1. use python for everything, and use python 3+ + +### Git Repository Integration + +1. Use subprocess module with git commands for all Git repository operations in Python applications +2. Validate Git repository existence before performing any git operations using subprocess.run(['git', 'rev-parse', '--git-dir']) +3. Integrate gitignore patterns for file filtering using pathspec module with 'gitwildmatch' pattern type +4. Implement git blame analysis to track file provenance including author, date, and commit metadata +5. Detect repository main branch dynamically by checking for 'main', 'master', or current branch +6. Use Path.resolve() for absolute path resolution when working with Git repository paths +7. Extract git metadata (commit hash, author, email, date) for all analyzed files to support provenance tracking + +### Asynchronous Programming + +1. Use async/await pattern for all I/O-bound operations including API calls and file processing in Python modules +2. Import asyncio module for event loop management and concurrency primitives +3. Define async functions with 'async def' for any operation that performs network requests or file I/O +4. Use 'await' keyword for all async function calls and use asyncio.sleep() instead of time.sleep() in async contexts +5. Implement async context managers for resource management in asynchronous code +6. Use asyncio.gather() or asyncio.create_task() for concurrent execution of multiple async operations +7. Call asyncio.run() at the entry point to execute async main functions from synchronous code + +### CLI Architecture + +1. Use Click framework (click>=8.0.0) for all command-line interface implementation in Python applications +2. Structure CLI with @click.group() decorator at the top level and @click.command() for subcommands +3. Define command-line options using @click.option() with type hints, help text, and default values +4. Use @click.argument() for required positional arguments with click.Choice() for enumerated values +5. Include colorama>=0.4.6 for cross-platform colored terminal output in all CLI applications +6. Implement --verbose/-v flag for debug output and --force/-f flag to skip confirmation prompts +7. Provide clear help text for all commands and options using the help parameter + +### AI Integration + +1. Use Anthropic Claude API (via BAML client) for all AI-powered code analysis in Python files +2. Default to 'claude-sonnet-4-20250514' model for analysis tasks unless specific model requirements dictate otherwise +3. Store Anthropic API keys in environment variables (ANTHROPIC_API_KEY) and never hardcode credentials in Python source files +4. Validate BAML client initialization before performing any AI operations using check_baml_client() validation +5. Import AI functionality from baml_client.async_client module for all async AI operations +6. Track token usage for all Claude API calls to monitor costs and usage patterns +7. Set BAML_LOG environment variable to 'OFF' to disable verbose logging in production + +## Testing Guidelines + +Follow Python testing best practices for unit and integration testing. + +## Commit & Pull Request Guidelines + +Follow standard Git workflow practices for commits and pull requests. + +## Security & Configuration Tips + +1. Store API keys and sensitive credentials in environment variables, never hardcode in source files +2. Validate all external inputs and Git repository operations before execution \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..2dc50bf --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,51 @@ +## ADR 1: Git Repository Integration for Provenance Tracking + +1. Use subprocess module with git commands for all Git repository operations in Python applications +2. Validate Git repository existence before performing any git operations using subprocess.run(['git', 'rev-parse', '--git-dir']) +3. Integrate gitignore patterns for file filtering using pathspec module with 'gitwildmatch' pattern type +4. Implement git blame analysis to track file provenance including author, date, and commit metadata +5. Detect repository main branch dynamically by checking for 'main', 'master', or current branch +6. Use Path.resolve() for absolute path resolution when working with Git repository paths +7. Extract git metadata (commit hash, author, email, date) for all analyzed files to support provenance tracking + +--- + +## ADR 2: Asynchronous Programming with Asyncio for Concurrent Operations + +1. Use async/await pattern for all I/O-bound operations including API calls and file processing in Python modules +2. Import asyncio module for event loop management and concurrency primitives +3. Define async functions with 'async def' for any operation that performs network requests or file I/O +4. Use 'await' keyword for all async function calls and use asyncio.sleep() instead of time.sleep() in async contexts +5. Implement async context managers for resource management in asynchronous code +6. Use asyncio.gather() or asyncio.create_task() for concurrent execution of multiple async operations +7. Call asyncio.run() at the entry point to execute async main functions from synchronous code + +--- + +## ADR 3: Click Framework for CLI Application Architecture + +1. Use Click framework (click>=8.0.0) for all command-line interface implementation in Python applications +2. Structure CLI with @click.group() decorator at the top level and @click.command() for subcommands +3. Define command-line options using @click.option() with type hints, help text, and default values +4. Use @click.argument() for required positional arguments with click.Choice() for enumerated values +5. Include colorama>=0.4.6 for cross-platform colored terminal output in all CLI applications +6. Implement --verbose/-v flag for debug output and --force/-f flag to skip confirmation prompts +7. Provide clear help text for all commands and options using the help parameter + +--- + +## ADR 4: Anthropic Claude AI Integration for Code Analysis + +1. Use Anthropic Claude API (via BAML client) for all AI-powered code analysis in Python files +2. Default to 'claude-sonnet-4-20250514' model for analysis tasks unless specific model requirements dictate otherwise +3. Store Anthropic API keys in environment variables (ANTHROPIC_API_KEY) and never hardcode credentials in Python source files +4. Validate BAML client initialization before performing any AI operations using check_baml_client() validation +5. Import AI functionality from baml_client.async_client module for all async AI operations +6. Track token usage for all Claude API calls to monitor costs and usage patterns +7. Set BAML_LOG environment variable to 'OFF' to disable verbose logging in production + +--- + +## ADR 5: Use Python For All Development Purposes + +1. use python for everything, and use python 3+ \ No newline at end of file