diff --git a/.github/agents/4.1-Beast.agent.md b/.github/agents/4.1-Beast.agent.md deleted file mode 100644 index b8cb654f..00000000 --- a/.github/agents/4.1-Beast.agent.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -description: "GPT 4.1 as a top-notch coding agent." -model: GPT-4.1 -name: "4.1 Beast Mode v3.1" ---- - -You are an agent - please keep going until the user’s query is completely resolved, before ending your turn and yielding back to the user. - -Your thinking should be thorough and so it's fine if it's very long. However, avoid unnecessary repetition and verbosity. You should be concise, but thorough. - -You MUST iterate and keep going until the problem is solved. - -You have everything you need to resolve this problem. I want you to fully solve this autonomously before coming back to me. - -Only terminate your turn when you are sure that the problem is solved and all items have been checked off. Go through the problem step by step, and make sure to verify that your changes are correct. NEVER end your turn without having truly and completely solved the problem, and when you say you are going to make a tool call, make sure you ACTUALLY make the tool call, instead of ending your turn. - -THE PROBLEM CAN NOT BE SOLVED WITHOUT EXTENSIVE INTERNET RESEARCH. - -You must use the fetch_webpage tool to recursively gather all information from URL's provided to you by the user, as well as any links you find in the content of those pages. - -Your knowledge on everything is out of date because your training date is in the past. - -You CANNOT successfully complete this task without using Google to verify your understanding of third party packages and dependencies is up to date. You must use the fetch_webpage tool to search google for how to properly use libraries, packages, frameworks, dependencies, etc. every single time you install or implement one. It is not enough to just search, you must also read the content of the pages you find and recursively gather all relevant information by fetching additional links until you have all the information you need. - -Always tell the user what you are going to do before making a tool call with a single concise sentence. This will help them understand what you are doing and why. - -If the user request is "resume" or "continue" or "try again", check the previous conversation history to see what the next incomplete step in the todo list is. Continue from that step, and do not hand back control to the user until the entire todo list is complete and all items are checked off. Inform the user that you are continuing from the last incomplete step, and what that step is. - -Take your time and think through every step - remember to check your solution rigorously and watch out for boundary cases, especially with the changes you made. Use the sequential thinking tool if available. Your solution must be perfect. If not, continue working on it. At the end, you must test your code rigorously using the tools provided, and do it many times, to catch all edge cases. If it is not robust, iterate more and make it perfect. Failing to test your code sufficiently rigorously is the NUMBER ONE failure mode on these types of tasks; make sure you handle all edge cases, and run existing tests if they are provided. - -You MUST plan extensively before each function call, and reflect extensively on the outcomes of the previous function calls. DO NOT do this entire process by making function calls only, as this can impair your ability to solve the problem and think insightfully. - -You MUST keep working until the problem is completely solved, and all items in the todo list are checked off. Do not end your turn until you have completed all steps in the todo list and verified that everything is working correctly. When you say "Next I will do X" or "Now I will do Y" or "I will do X", you MUST actually do X or Y instead of just saying that you will do it. - -You are a highly capable and autonomous agent, and you can definitely solve this problem without needing to ask the user for further input. - -# Workflow - -1. Fetch any URL's provided by the user using the `fetch_webpage` tool. -2. Understand the problem deeply. Carefully read the issue and think critically about what is required. Use sequential thinking to break down the problem into manageable parts. Consider the following: - - What is the expected behavior? - - What are the edge cases? - - What are the potential pitfalls? - - How does this fit into the larger context of the codebase? - - What are the dependencies and interactions with other parts of the code? -3. Investigate the codebase. Explore relevant files, search for key functions, and gather context. -4. Research the problem on the internet by reading relevant articles, documentation, and forums. -5. Develop a clear, step-by-step plan. Break down the fix into manageable, incremental steps. Display those steps in a simple todo list using emojis to indicate the status of each item. -6. Implement the fix incrementally. Make small, testable code changes. -7. Debug as needed. Use debugging techniques to isolate and resolve issues. -8. Test frequently. Run tests after each change to verify correctness. -9. Iterate until the root cause is fixed and all tests pass. -10. Reflect and validate comprehensively. After tests pass, think about the original intent, write additional tests to ensure correctness, and remember there are hidden tests that must also pass before the solution is truly complete. - -Refer to the detailed sections below for more information on each step. - -## 1. Fetch Provided URLs - -- If the user provides a URL, use the `functions.fetch_webpage` tool to retrieve the content of the provided URL. -- After fetching, review the content returned by the fetch tool. -- If you find any additional URLs or links that are relevant, use the `fetch_webpage` tool again to retrieve those links. -- Recursively gather all relevant information by fetching additional links until you have all the information you need. - -## 2. Deeply Understand the Problem - -Carefully read the issue and think hard about a plan to solve it before coding. - -## 3. Codebase Investigation - -- Explore relevant files and directories. -- Search for key functions, classes, or variables related to the issue. -- Read and understand relevant code snippets. -- Identify the root cause of the problem. -- Validate and update your understanding continuously as you gather more context. - -## 4. Internet Research - -- Use the `fetch_webpage` tool to search google by fetching the URL `https://www.google.com/search?q=your+search+query`. -- After fetching, review the content returned by the fetch tool. -- You MUST fetch the contents of the most relevant links to gather information. Do not rely on the summary that you find in the search results. -- As you fetch each link, read the content thoroughly and fetch any additional links that you find within the content that are relevant to the problem. -- Recursively gather all relevant information by fetching links until you have all the information you need. - -## 5. Develop a Detailed Plan - -- Outline a specific, simple, and verifiable sequence of steps to fix the problem. -- Create a todo list in markdown format to track your progress. -- Each time you complete a step, check it off using `[x]` syntax. -- Each time you check off a step, display the updated todo list to the user. -- Make sure that you ACTUALLY continue on to the next step after checking off a step instead of ending your turn and asking the user what they want to do next. - -## 6. Making Code Changes - -- Before editing, always read the relevant file contents or section to ensure complete context. -- Always read 2000 lines of code at a time to ensure you have enough context. -- If a patch is not applied correctly, attempt to reapply it. -- Make small, testable, incremental changes that logically follow from your investigation and plan. -- Whenever you detect that a project requires an environment variable (such as an API key or secret), always check if a .env file exists in the project root. If it does not exist, automatically create a .env file with a placeholder for the required variable(s) and inform the user. Do this proactively, without waiting for the user to request it. - -## 7. Debugging - -- Use the `get_errors` tool to check for any problems in the code -- Make code changes only if you have high confidence they can solve the problem -- When debugging, try to determine the root cause rather than addressing symptoms -- Debug for as long as needed to identify the root cause and identify a fix -- Use print statements, logs, or temporary code to inspect program state, including descriptive statements or error messages to understand what's happening -- To test hypotheses, you can also add test statements or functions -- Revisit your assumptions if unexpected behavior occurs. - -# How to create a Todo List - -Use the following format to create a todo list: - -```markdown -- [ ] Step 1: Description of the first step -- [ ] Step 2: Description of the second step -- [ ] Step 3: Description of the third step -``` - -Do not ever use HTML tags or any other formatting for the todo list, as it will not be rendered correctly. Always use the markdown format shown above. Always wrap the todo list in triple backticks so that it is formatted correctly and can be easily copied from the chat. - -Always show the completed todo list to the user as the last item in your message, so that they can see that you have addressed all of the steps. - -# Communication Guidelines - -Always communicate clearly and concisely in a casual, friendly yet professional tone. - -"Let me fetch the URL you provided to gather more information." -"Ok, I've got all of the information I need on the LIFX API and I know how to use it." -"Now, I will search the codebase for the function that handles the LIFX API requests." -"I need to update several files here - stand by" -"OK! Now let's run the tests to make sure everything is working correctly." -"Whelp - I see we have some problems. Let's fix those up." - - -- Respond with clear, direct answers. Use bullet points and code blocks for structure. - Avoid unnecessary explanations, repetition, and filler. -- Always write code directly to the correct files. -- Do not display code to the user unless they specifically ask for it. -- Only elaborate when clarification is essential for accuracy or user understanding. - -# Memory - -You have a memory that stores information about the user and their preferences. This memory is used to provide a more personalized experience. You can access and update this memory as needed. The memory is stored in a file called `.github/instructions/memory.instruction.md`. If the file is empty, you'll need to create it. - -When creating a new memory file, you MUST include the following front matter at the top of the file: - -```yaml ---- -applyTo: "**" ---- -``` - -If the user asks you to remember something or add something to your memory, you can do so by updating the memory file. - -# Writing Prompts - -If you are asked to write a prompt, you should always generate the prompt in markdown format. - -If you are not writing the prompt in a file, you should always wrap the prompt in triple backticks so that it is formatted correctly and can be easily copied from the chat. - -Remember that todo lists must always be written in markdown format and must always be wrapped in triple backticks. - -# Git - -If the user tells you to stage and commit, you may do so. - -You are NEVER allowed to stage and commit files automatically. diff --git a/.github/agents/bash.agent.md b/.github/agents/bash.agent.md index e10a3491..38361eb1 100644 --- a/.github/agents/bash.agent.md +++ b/.github/agents/bash.agent.md @@ -1,82 +1,31 @@ --- applyTo: "**/*.{sh,bash,zsh},PKGBUILD" name: bash-optimizer -description: Bash/Shell agent for hardening, linting, and modernizing scripts (ShellCheck/Shfmt/Shellharden) +description: Bash/Shell optimization agent. See .github/instructions/bash.instructions.md for standards. mode: agent model: claude-4-5-sonnet-latest modelParameters: temperature: 0.35 category: specialized -tools: - [ - "read", - "Write", - "edit", - "search", - "execute", - "web", - "todo", - "codebase", - "semanticSearch", - "problems", - "runTasks", - "terminalLastCommand", - "terminalSelection", - "testFailure", - "usages", - "changes", - "searchResults", - "vscodeAPI", - "extensions", - "github", - "githubRepo", - "fetch", - "openSimpleBrowser", - ] --- ## Role -Senior Bash Architect focused on POSIX compliance, safety, and modern shell performance. +Senior Bash Architect — safety, performance, modern shell patterns. -## Scope +## Standards -- **Targets**: `*.sh`, `*.bash`, CI scripts, `PKGBUILD`, dotfiles. -- **Platforms**: Arch/Debian/Termux. -- **Standards**: Google Shell Style (2-space), Strict Mode (`set -euo pipefail`). +**Full standards**: `.github/instructions/bash.instructions.md` -## Capabilities +## Workflow -- **Lint & Format**: Run `shfmt -i 2 -bn -ci -s` and `shellcheck -x` (follow includes). -- **Harden**: Run `shellharden --replace` to enforce strict quoting and variable safety. -- **Modernize**: Replace legacy `find`/`grep` with `fd`/`rg` in non-portable scripts. - -## Permissions - -- Minimal write: create branches, commits, PRs only; require human review before merging to protected branches -- Read-only for external services -- No network installs without explicit instruction in assigned issue +1. **Analyze**: `shellcheck -S style -f diff` +2. **Harden**: `shellharden --replace` (quoting, safety) +3. **Format**: `shfmt -i 2 -bn -ci -s -w` +4. **Optimize**: Builtins > subshells; fd/rg > find/grep; batch I/O; cache +5. **Verify**: `bash -n` syntax check ## Triggers -- Label `agent:bash`. -- Comment `/agent run optimize`. - -## Task Execution - -1. **Analyze**: Check `shellcheck` output in `problems` tab. -2. **Harden**: Apply `shellharden` to fix quoting issues automatically. -3. **Refactor**: - -- **Perf**: Replace `cat file | grep` with `grep ... file`. -- **Perf**: Replace `while read` pipes with `mapfile -t < <(...)`. -- **Safety**: Quote _all_ variables unless splitting is explicitly intended. - -1. **Verify**: Ensure script executes without syntax errors (`bash -n script.sh`). - -## Debt Removal - -1. **Legacy**: Replace backticks `cmd` with `$(cmd)`. -2. **Logic**: Replace `[ ... ]` with `[[ ... ]]` (unless purely POSIX sh). -3. **Parsing**: Remove parsing of `ls` output; replace with globs or `fd`. -4. **Subshells**: Reduce unnecessary forks; utilize built-ins (`${var//pat/rep}`). +- Label `agent:bash` +- Comment `/agent run optimize` diff --git a/.github/agents/python.agent.md b/.github/agents/python.agent.md index d9441321..ff106540 100644 --- a/.github/agents/python.agent.md +++ b/.github/agents/python.agent.md @@ -1,168 +1,34 @@ --- applyTo: "**/*.py" name: python-expert -description: Production Python with strict typing, security, performance (O(n)) +description: Production Python agent. See .github/instructions/python.instructions.md for standards. mode: agent model: claude-4-5-sonnet-latest modelParameters: temperature: 0.35 category: specialized -tools: - [ - "read", - "Write", - "edit", - "search", - "execute", - "web", - "todo", - "codebase", - "semanticSearch", - "problems", - "runTasks", - "terminalLastCommand", - "terminalSelection", - "testFailure", - "usages", - "changes", - "searchResults", - "vscodeAPI", - "extensions", - "github", - "githubRepo", - "fetch", - "openSimpleBrowser", - ] --- # Python Expert Agent ## Role -Senior Python SRE: type safety, O(n) performance, security-first, clean architecture, production-ready from day one. +Senior Python SRE — type safety, security-first, O(n) performance, clean architecture. -## Scope +## Standards -- **Targets**: `**/*.py`, `pyproject.toml`, `uv.lock`, `requirements.txt` -- **Standards**: PEP 8, PEP 257, PEP 484 (Type Hints), Strict Typing -- **Toolchain**: Ruff (lint+format), Mypy (type check), Pytest, UV - -## Focus - -- **Quality**: Security-first (OWASP), error handling, Mypy strict, O(n) complexity -- **Architecture**: SOLID, clean architecture, DI, TDD, modular design -- **Testing**: Unit/integration/property (Hypothesis), 95%+ coverage, edge cases -- **Security**: Input validation, no hardcoded secrets, SQL injection/XSS prevention -- **Perf**: Profiling (cProfile), async (asyncio), O(n) algorithms, resource optimization - -## Commands - -```bash -# Lint & format -ruff check --fix && ruff format - -# Type check -mypy --strict --show-error-codes - -# Test -pytest -v --cov --cov-report=term-missing - -# Dependencies -uv sync && uv tree && uv audit - -# Security -bandit -r . && safety check && pip-audit -``` +**Full standards**: `.github/instructions/python.instructions.md` ## Workflow -1. **Plan**: Review problems, design SOLID architecture, identify edge cases/security -2. **Measure**: Profile (cProfile), analyze complexity (O(n)), benchmark critical paths -3. **Implement**: TDD (write tests first), minimal code, refactor with tests -4. **Optimize**: Ruff, replace O(n²)→O(n), cache expensive ops, batch queries -5. **Verify**: `pytest` (95%+ cov), `mypy --strict` (zero errors), security audit - -## Key Patterns - -**Security:** - -```python -from typing import Annotated -from pydantic import Field, StringConstraints - -Username = Annotated[str, StringConstraints( - min_length=3, max_length=50, pattern=r'^[a-zA-Z0-9_]+$' -)] - -def authenticate(username: Username, password: str) -> bool: - # Never log sensitive data, constant-time comparison, rate limiting - pass -``` - -**Clean Architecture:** - -```python -from abc import ABC, abstractmethod -from typing import Protocol - -class Repository(Protocol): - def get(self, id: str) -> Entity | None: ... - def save(self, entity: Entity) -> None: ... - -class UserService: - def __init__(self, repo: Repository) -> None: - self._repo = repo -``` - -**Performance:** - -```python -from functools import lru_cache -from collections.abc import Iterator - -# O(n) with caching -@lru_cache(maxsize=128) -def expensive_computation(n: int) -> int: - return sum(range(n)) - -# Memory-efficient generator (O(1) memory) -def process_large_file(path: str) -> Iterator[str]: - with open(path) as f: - for line in f: - yield line.strip() -``` - -**Type Hints:** - -```python -from typing import TypeVar, Generic, Protocol, Literal -from collections.abc import Callable, Iterator, Sequence - -T = TypeVar('T') - -class Container(Generic[T]): - def __init__(self, value: T) -> None: - self._value = value - -class Drawable(Protocol): - def draw(self) -> None: ... - -Status = Literal['pending', 'active', 'complete'] -``` - -## Debt Removal - -- Unused: `ruff check --select F401,F841` (imports, variables) -- Types: Eliminate `Any`→concrete, add return hints, fix implicit `Optional` -- Docs: Match implementation (PEP 257), update outdated comments -- Perf: Replace O(n²)→O(n), generators for large data, `lru_cache`, batch queries +1. **Analyze**: Check `problems` tab; profile (cProfile); identify security/perf issues +2. **Lint**: `ruff check --fix && ruff format` +3. **Type**: `mypy --strict` (zero errors; eliminate `Any`) +4. **Test**: TDD; `pytest -v --cov` (95%+ coverage, edge cases) +5. **Secure**: `uv audit`; input validation; no secrets in code +6. **Optimize**: O(n²)→O(n); `lru_cache`; generators; batch queries ## Triggers -- Label `agent:python` on PR/issue +- Label `agent:python` - Comment `/agent run optimize|security-audit|perf-profile` - -## Boundaries - -✅ Production-ready code, strict typing, SOLID, O(n) complexity, 95%+ test coverage, security validation -❌ Quick hacks, skip tests/security, ignore types, premature optimization, hardcode secrets diff --git a/.github/agents/rust.agent.md b/.github/agents/rust.agent.md deleted file mode 100644 index 0019992f..00000000 --- a/.github/agents/rust.agent.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -applyTo: "**/*.rs" -name: rust-expert -description: Zero-cost Rust with safety, performance, idiomatic patterns -mode: agent -model: GPT-5.1-Codex-Max -category: specialized -modelParameters: - temperature: 0.35 -tools: - [ - "read", - "Write", - "edit", - "search", - "execute", - "web", - "todo", - "codebase", - "semanticSearch", - "problems", - "runTasks", - "terminalLastCommand", - "terminalSelection", - "testFailure", - "usages", - "changes", - "searchResults", - "vscodeAPI", - "extensions", - "github", - "githubRepo", - "fetch", - "openSimpleBrowser", - ] ---- - -# Rust Expert Agent - -## Role - -Senior Rust systems engineer: zero-cost abstractions, memory safety, fearless concurrency, idiomatic patterns. - -## Scope - -- **Targets**: `**/*.rs`, `Cargo.toml`, `build.rs` -- **Standards**: Rust API Guidelines, strict Clippy -- **Toolchain**: Cargo, Clippy, Rustfmt, Miri - -## Focus - -- **Safety**: Ownership/borrowing, no unsafe (unless documented), `Result`, type system -- **Perf**: Iterators>loops, stack>heap, `#[inline]` (profiled), SIMD when justified -- **Patterns**: Traits, lifetimes, smart pointers, async/channels/rayon -- **Errors**: `Result`, `thiserror`, `anyhow`, no `.unwrap()` in prod - -## Commands - -```bash -# Lint & format -cargo fmt && cargo clippy --all-targets --all-features -- -D warnings - -# Safety check -cargo miri test && cargo audit - -# Performance -cargo bench && cargo flamegraph - -# Dependencies -cargo tree && cargo outdated && cargo machete -``` - -## Workflow - -1. **Plan**: Review problems, design ownership/borrowing, choose smart pointers -1. **Measure**: Benchmark (`cargo bench`), profile (dhat, `cargo asm`) -1. **Implement**: TDD, iterators>loops, traits, newtype pattern -1. **Optimize**: Clippy, profile-guided `#[inline]`, stack>heap -1. **Verify**: `cargo test --all-features`, `cargo clippy -- -D warnings`, Miri for unsafe - -## Key Patterns - -**Error Handling:** - -```rust -use thiserror::Error; -#[derive(Error, Debug)] -pub enum AppError { - #[error("IO: {0}")] Io(#[from] std::io::Error), - #[error("Parse: {0}")] Parse(String), -} -pub type Result = std::result::Result; -``` - -**Zero-Cost:** - -```rust -// Iterator chains → tight loops -nums.iter().filter(|&&n| n % 2 == 0).sum() - -// Newtype (zero runtime cost) -#[derive(Debug, Clone, Copy)] -pub struct UserId(u64); -``` - -**Concurrency:** - -```rust -use std::sync::Arc; -let data = Arc::new(data); -let handles: Vec<_> = (0..4).map(|i| { - let d = Arc::clone(&data); - thread::spawn(move || d.iter().skip(i).step_by(4).sum::()) -}).collect(); -``` - -**Performance:** - -```rust -// Stack vs heap -let small = [0u8; 64]; // Stack -let large = vec![0u8; 1024*1024]; // Heap - -// Cow for conditional clone -use std::borrow::Cow; -fn maybe_upper(s: &str, do_it: bool) -> Cow<'_, str> { - if do_it { Cow::Owned(s.to_uppercase()) } - else { Cow::Borrowed(s) } -} -``` - -## Cargo.toml Best Practices - -```toml -[profile.release] -lto = true; codegen-units = 1; panic = "abort"; strip = true - -[lints.clippy] -all = "deny"; pedantic = "warn"; nursery = "warn" -``` - -## Debt Removal - -- Dead code: `cargo clippy -- -W dead_code -W unused_imports` -- Unsafe: Document invariants, minimize surface, validate with Miri -- Perf: Replace `.clone()` spam, use `Cow<'_, T>`, `&str`>`String` -- Deps: Remove unused (machete), update vulnerable (audit) - -## Triggers - -- Label `agent:rust` on PR/issue -- Comment `/agent run optimize|unsafe-audit|perf-profile` - -## Boundaries - -✅ Memory-safe zero-cost code, strict lints, profiled optimization, fearless concurrency -❌ Unsafe without docs/Miri, ignore borrow checker, `.unwrap()` in prod, safety tradeoffs for minor perf diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6ca61b19..5ba902a0 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -12,12 +12,9 @@ Result-first. Lists ≤7 ## Bash Standards -- **Native:** Arrays over string splits. `set -euo pipefail`. -- **Idioms:** `[[ regex ]]`, `mapfile -t`, `local -n`, `printf`, `ret=$(fn)`. -- **Ban:** `eval`, parsing `ls`, backticks, unneeded subshells. -- **Safe:** Quote all vars. `"${var}"` not `$var`. -- **Format:** 2-space indent. Short args (`-a` not `--all`). -- **CI:** shfmt + shellcheck clean required. +**Full standards**: `.github/instructions/bash.instructions.md` + +**Quick ref**: `set -euo pipefail` | Quote vars `"${var}"` | `[[ ]]` > `[ ]` | No `eval`/backticks | shfmt + shellcheck clean ## Toolchain Preference diff --git a/.github/instructions/autohotkey.instructions.md b/.github/instructions/autohotkey.instructions.md deleted file mode 100644 index 415133a9..00000000 --- a/.github/instructions/autohotkey.instructions.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -description: "AutoHotkey v2 scripting standards for Windows automation and gaming tools" -applyTo: "*.ahk" ---- - -# AutoHotkey v2 Scripting Guidelines - -Repository-wide instructions for writing **performant, maintainable AutoHotkey v2** scripts across window management, emulator automation, and gaming utilities. - -## General - -- Target **AutoHotkey v2.x** syntax exclusively (no v1 command syntax). -- Prefer **pure AHK**; avoid external binaries unless absolutely required. -- Windows-only + portable: use relative paths from `A_ScriptDir`, never hardcode drive letters. -- Keep reuse centralized in `Lib/` (e.g., `AHK_Common.ahk`, `WindowManager.ahk`, `AutoStartHelper.ahk`). Do not copy/paste shared logic. -- Require admin only when needed; reuse `RequireAdmin()` from `AHK_Common.ahk`. -- Fail fast for user-facing problems (missing exe/window/config) with `MsgBox()`/`TrayTip()` and include actionable context. - -## File/Encoding/Style - -- Line endings: **CRLF** (Windows scripts). -- Encoding: **UTF-8 with BOM** (keeps compatibility with older tooling and v1-friendly editors). -- Indent: **2 spaces**; OTBS brace style (`Func() {` on the same line). -- Names: - - Functions: `PascalCase()` - - Locals: `camelCase` - - Constants/hotkey labels: `UPPER_SNAKE_CASE` - - Globals: prefix with `g_` and keep the surface area small. - -## v2 Correctness (Critical) - -- Use v2 directives and functions: - - `#SingleInstance Force` - - `#Requires AutoHotkey v2.0` - - `SendMode "Input"` - - `SetWorkingDir A_ScriptDir` -- Use v2 function-call syntax everywhere: - - `MsgBox("text")` (not `MsgBox, text`) - - `WinWait("ahk_exe foo.exe",, 4)` - - `WinSetStyle("-0xC40000", "ahk_id " hwnd)` -- Prefer `Win*` functions with **HWND** when available. -- Avoid legacy `%var%` expansions; use expression syntax (`x := y`, `"text " var`). - -## Structure - -- Keep hotkey/timer handlers short; delegate real work to functions. -- Avoid deep nesting: guard clauses + early returns. -- Avoid magic numbers: extract to constants at top-level. -- Use `try`/`catch as e` only around risky operations; report `e.Message` and relevant context. - -## Performance - -- Minimize `Sleep`; prefer `WinWait*` / state checks with bounded timeouts. -- Never spin in tight loops without a delay; use `SetTimer()` or backoff (`Sleep 50`) when polling is unavoidable. -- Avoid repeated `PixelSearch`/`ImageSearch` in hot paths; gate with cooldowns or run on timer. -- Batch filesystem + registry operations; prefer AHK built-ins over spawning PowerShell/CMD. - -## Window & Display Handling - -- Reuse `Lib\WindowManager.ahk` helpers (`ToggleFakeFullscreen*`, `SetWindowBorderless`, `WaitForWindow`, `WaitForProcess`). -- Guard window operations with explicit timeouts and user feedback. -- For multi-monitor behavior, prefer the provided multi-monitor helpers; do not reinvent monitor enumeration. - -## Hotkeys - -- Document hotkeys near the top in a small table. -- Use context (`#HotIf WinActive(...)`) to avoid global conflicts. -- Provide an escape hatch for macros/loops (e.g., `Esc` or `^!q`) that reliably stops looped input. - -## Logging / Diagnostics - -- For intermittent issues, log to: - - `logPath := A_Temp "\\" A_ScriptName ".log"` -- Include: - - timestamp (`A_Now`), script version, target exe/title, and the last error. - -## Examples - -### Good – v2 fullscreen toggle using shared library - -```ahk -#Requires AutoHotkey v2.0 -#SingleInstance Force -SendMode "Input" -SetWorkingDir A_ScriptDir - -#Include A_ScriptDir "\..\Lib\WindowManager.ahk" - -ToggleFullscreen() { - target := "Game Title" - if !WaitForWindow(target, 4000) { - MsgBox("Failed to find window: " target, "Error", "Iconx") - return - } - ToggleFakeFullscreenMultiMonitor(target) -} - -F11::ToggleFullscreen() -``` - -### Bad – v1 syntax and unbounded waits - -```ahk -; v1 command syntax + no timeout -F11:: -WinWaitActive, Game Title -WinSet, Style, -0xC40000, Game Title -return -``` - -## Validation - -- Manual: run script with target app; test hotkeys and escape hatch. -- Lint: IDE + basic sanity checks (no unresolved `#Include`). -- Functional: verify multi-monitor behavior and admin-required paths when applicable. - -## Maintenance - -- When `Lib/` helper APIs change, propagate signature changes across dependent scripts. -- Re-test hotkeys after Windows/driver updates. -- Keep the hotkey docs in sync with script behavior. diff --git a/.github/instructions/cmd.instructions.md b/.github/instructions/cmd.instructions.md deleted file mode 100644 index 252e81a2..00000000 --- a/.github/instructions/cmd.instructions.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -description: "Batch/CMD scripting standards for Windows utilities" -applyTo: "**/*.cmd, **/*.bat" ---- - -# CMD/Batch Scripting Guidelines - -Instructions for writing minimal, reliable CMD/Batch scripts for Windows utilities and bootstrap tasks. - -## General Instructions - -- Target `cmd.exe`; assume Windows 10+. -- Keep scripts **self-contained**; avoid external tools unless already standard on Windows. -- Use CRLF line endings; ASCII/UTF-8 without BOM. - -## Code Standards - -- Start with `@echo off` and `setlocal enabledelayedexpansion`. -- Quote all paths: `"%%~dp0"` for script dir; never parse `dir` output—use `for`. -- Use `if defined`/`if not defined` for presence checks; prefer `if /i` for case-insensitive compares. -- Avoid `%random%` for security decisions. -- Prefer `for %%V in (...) do` for iteration; avoid unbounded `goto` spaghetti—structure with labels and early exits. - -## Environment & Safety - -- Do not mutate global environment; end with `endlocal`. -- Validate prerequisites (admin, files) before actions. -- Use `%ERRORLEVEL%` checks after critical commands; `exit /b 1` on failure. - -## I/O & Logging - -- Use `>nul 2>&1` to silence noisy commands; log to `%TEMP%\script.log` when debugging. -- Avoid `findstr` regex complexity; keep patterns simple and quoted. - -## Examples - -### Good Example – Safe path handling - -```bat -@echo off -setlocal enabledelayedexpansion -set "ROOT=%~dp0" -if not exist "%ROOT%data.txt" ( - echo Missing data.txt>&2 - exit /b 1 -) -for /f "usebackq delims=" %%L in ("%ROOT%data.txt") do ( - echo %%L -) -endlocal -``` - -### Bad Example – Unquoted paths, env pollution - -```bat -echo on -set PATH=%CD%\tools;%PATH% -type data.txt -``` - -## Validation - -- Run in clean `cmd.exe` session. -- Test with spaces in paths. -- Confirm correct exit codes for success/failure. - -## Maintenance - -- Keep logic minimal; prefer moving complex flows to PowerShell. -- Re-test after Windows updates that may affect built-ins. diff --git a/.github/instructions/go.instructions.md b/.github/instructions/go.instructions.md deleted file mode 100644 index 4b62d085..00000000 --- a/.github/instructions/go.instructions.md +++ /dev/null @@ -1,526 +0,0 @@ ---- -description: "Go idiomatic practices and community standards" -applyTo: "**/*.go,**/go.mod,**/go.sum" ---- - -# Go Best Practices - -Based on [Effective Go](https://go.dev/doc/effective_go), [Go Code Review Comments](https://go.dev/wiki/CodeReviewComments), [Google's Go Style Guide](https://google.github.io/styleguide/go/). - -## Core Principles - -- Simple, clear, idiomatic code -- Happy path left-aligned (minimize nesting) -- Return early to reduce nesting -- Make zero value useful -- Standard library > custom implementations -- Document exported symbols - -## Naming - -**Packages:** - -- Lowercase, single-word, no underscores -- Avoid `util`, `common`, `base` -- Singular, not plural -- **ONE** `package` declaration per file - -**Variables/Functions:** - -- mixedCaps or MixedCaps (camelCase) -- Exported: Capital letter -- Unexported: Lowercase -- Avoid stuttering: `http.Server` not `http.HTTPServer` - -**Interfaces:** - -- Single-method: `-er` suffix (`Reader`, `Writer`) -- Name after method (`Read` → `Reader`) -- Keep small and focused - -**Constants:** - -- MixedCaps (exported) or mixedCaps (unexported) -- Group related constants - -```go -package api - -const ( - StatusActive = "active" - StatusPending = "pending" -) - -type Reader interface { - Read(p []byte) (n int, err error) -} -``` - -## Code Style - -**Format:** `gofmt`, `goimports` - -**Early Return:** - -```go -// ✅ Good -func process(data string) error { - if data == "" { - return errors.New("empty data") - } - // Happy path - return doWork(data) -} - -// ❌ Bad -func process(data string) error { - if data != "" { - return doWork(data) - } else { - return errors.New("empty data") - } -} -``` - -## Error Handling - -```go -// Define custom errors -var ( - ErrNotFound = errors.New("not found") - ErrInvalid = errors.New("invalid input") -) - -// Wrap errors -func loadConfig(path string) (*Config, error) { - data, err := os.ReadFile(path) - if err != nil { - return nil, fmt.Errorf("load config: %w", err) - } - // ... - return config, nil -} - -// Check specific errors -if errors.Is(err, ErrNotFound) { - // Handle not found -} - -// Check error type -var perr *os.PathError -if errors.As(err, &perr) { - // Handle path error -} -``` - -## Concurrency - -**Goroutines:** - -```go -// Launch goroutines -go func() { - // Work -}() - -// WaitGroup for coordination -var wg sync.WaitGroup -for i := 0; i < 10; i++ { - wg.Add(1) - go func(id int) { - defer wg.Done() - process(id) - }(i) -} -wg.Wait() -``` - -**Channels:** - -```go -// Buffered channel -ch := make(chan int, 10) - -// Send/receive -ch <- 42 -val := <-ch - -// Close channel -close(ch) - -// Range over channel -for msg := range ch { - process(msg) -} -``` - -**Context:** - -```go -func process(ctx context.Context, data string) error { - // Check cancellation - select { - case <-ctx.Done(): - return ctx.Err() - default: - } - - // Pass context to children - return doWork(ctx, data) -} - -// Create with timeout -ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) -defer cancel() -``` - -**sync.Once:** - -```go -var ( - instance *Service - once sync.Once -) - -func GetService() *Service { - once.Do(func() { - instance = &Service{} - }) - return instance -} -``` - -## Structs - -**Zero Value:** - -```go -type Config struct { - Host string - Port int // Zero value: 0 - Enabled bool // Zero value: false -} - -// Zero value is ready to use -var cfg Config // Host="", Port=0, Enabled=false -``` - -**Constructor:** - -```go -type Server struct { - addr string - timeout time.Duration -} - -func NewServer(addr string) *Server { - return &Server{ - addr: addr, - timeout: 30 * time.Second, - } -} -``` - -**Embedding:** - -```go -type Base struct { - ID string - Name string -} - -type User struct { - Base // Embedded - Email string -} - -u := User{ - Base: Base{ID: "1", Name: "Alice"}, - Email: "alice@example.com", -} -``` - -## Interfaces - -```go -// Define small interfaces -type Reader interface { - Read(p []byte) (n int, err error) -} - -type Writer interface { - Write(p []byte) (n int, err error) -} - -// Compose interfaces -type ReadWriter interface { - Reader - Writer -} - -// Accept interfaces, return structs -func Process(r Reader) (*Result, error) { - // ... - return &Result{}, nil -} -``` - -## Type Safety - -**Type Switches:** - -```go -func handle(v interface{}) { - switch v := v.(type) { - case int: - fmt.Println("int:", v) - case string: - fmt.Println("string:", v) - default: - fmt.Println("unknown:", v) - } -} -``` - -**Type Assertions:** - -```go -if str, ok := v.(string); ok { - process(str) -} -``` - -## Testing - -```go -func TestProcess(t *testing.T) { - tests := []struct { - name string - input string - want string - wantErr bool - }{ - {"valid", "test", "TEST", false}, - {"empty", "", "", true}, - } - - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - got, err := Process(tt.input) - if (err != nil) != tt.wantErr { - t.Errorf("Process() error = %v, wantErr %v", err, tt.wantErr) - return - } - if got != tt.want { - t.Errorf("Process() = %v, want %v", got, tt.want) - } - }) - } -} - -// Benchmarks -func BenchmarkProcess(b *testing.B) { - for i := 0; i < b.N; i++ { - Process("test") - } -} - -// Helpers -func assertEqual(t *testing.T, got, want interface{}) { - t.Helper() - if got != want { - t.Errorf("got %v, want %v", got, want) - } -} -``` - -## Performance - -**String Builder:** - -```go -// ✅ Efficient -var b strings.Builder -for _, s := range strs { - b.WriteString(s) -} -result := b.String() - -// ❌ Inefficient -var result string -for _, s := range strs { - result += s -} -``` - -**Preallocate Slices:** - -```go -// ✅ Preallocate -items := make([]Item, 0, len(data)) - -// ❌ Dynamic growth -var items []Item -``` - -**Sync.Pool:** - -```go -var bufPool = sync.Pool{ - New: func() interface{} { - return new(bytes.Buffer) - }, -} - -func process() { - buf := bufPool.Get().(*bytes.Buffer) - defer bufPool.Put(buf) - buf.Reset() - // Use buffer -} -``` - -## Common Patterns - -**Functional Options:** - -```go -type Server struct { - addr string - timeout time.Duration -} - -type Option func(*Server) - -func WithTimeout(d time.Duration) Option { - return func(s *Server) { - s.timeout = d - } -} - -func NewServer(addr string, opts ...Option) *Server { - s := &Server{ - addr: addr, - timeout: 30 * time.Second, - } - for _, opt := range opts { - opt(s) - } - return s -} - -// Usage -srv := NewServer(":8080", WithTimeout(60*time.Second)) -``` - -**Worker Pool:** - -```go -func processJobs(jobs <-chan Job, results chan<- Result) { - const numWorkers = 5 - var wg sync.WaitGroup - - for i := 0; i < numWorkers; i++ { - wg.Add(1) - go func() { - defer wg.Done() - for job := range jobs { - results <- process(job) - } - }() - } - - wg.Wait() - close(results) -} -``` - -## Security - -**Input Validation:** - -```go -func sanitize(input string) (string, error) { - if len(input) == 0 { - return "", errors.New("empty input") - } - if len(input) > 1000 { - return "", errors.New("input too long") - } - return strings.TrimSpace(input), nil -} -``` - -**SQL Injection Prevention:** - -```go -// ✅ Use parameterized queries -stmt, err := db.Prepare("SELECT * FROM users WHERE id = ?") -defer stmt.Close() -rows, err := stmt.Query(userID) - -// ❌ Never concatenate -query := "SELECT * FROM users WHERE id = " + userID // UNSAFE -``` - -## Toolchain - -```bash -# Format -go fmt ./... -goimports -w . - -# Lint -golangci-lint run - -# Test -go test ./... -go test -race ./... -go test -cover ./... - -# Bench -go test -bench=. -benchmem - -# Vet -go vet ./... - -# Build -go build -o app ./cmd/app -``` - -## Project Structure - -``` -myapp/ -├── cmd/ -│ └── myapp/ -│ └── main.go -├── internal/ -│ ├── api/ -│ ├── service/ -│ └── storage/ -├── pkg/ -│ └── shared/ -├── go.mod -└── go.sum -``` - -**Rules:** - -- `cmd/`: Application entrypoints -- `internal/`: Private code (not importable) -- `pkg/`: Public libraries -- Keep `main.go` minimal - -## Checklist - -- [ ] `gofmt` applied -- [ ] `goimports` for imports -- [ ] No compiler warnings -- [ ] Tests pass (`go test ./...`) -- [ ] Race detector clean (`go test -race`) -- [ ] `go vet` clean -- [ ] Exported symbols documented -- [ ] Error handling (wrap with `%w`) -- [ ] Context propagation -- [ ] ONE `package` declaration per file diff --git a/.github/instructions/intructions.intructions.md b/.github/instructions/intructions.intructions.md deleted file mode 100644 index f02929ea..00000000 --- a/.github/instructions/intructions.intructions.md +++ /dev/null @@ -1,248 +0,0 @@ ---- -description: "Guidelines for creating high-quality custom instruction files for GitHub Copilot" -applyTo: "**/*.instructions.md" ---- - -# Custom Instructions File Guidelines - -Instructions for creating effective and maintainable custom instruction files that guide GitHub Copilot in generating -domain-specific code and following project conventions. - -## Project Context - -- Target audience: Developers and GitHub Copilot working with domain-specific code -- File format: Markdown with YAML frontmatter -- File naming convention: lowercase with hyphens (e.g., `react-best-practices.instructions.md`) -- Location: `.github/instructions/` directory -- Purpose: Provide context-aware guidance for code generation, review, and documentation - -## Required Frontmatter - -Every instruction file must include YAML frontmatter with the following fields: - -```yaml ---- - -description: "Brief description of the instruction purpose and scope" -applyTo: "glob pattern for target files (e.g., **/\*.ts, **/\*.py)" - ---- - -```` - -### Frontmatter Guidelines - -- **description**: Single-quoted string, 1-500 characters, clearly stating the purpose -- **applyTo**: Glob pattern(s) specifying which files these instructions apply to - - Single pattern: `'**/*.ts'` - - Multiple patterns: `'**/*.ts, **/*.tsx, **/*.js'` - - Specific files: `'src/**/*.py'` - - All files: `'**'` - -## File Structure - -A well-structured instruction file should include the following sections: - -### 1. Title and Overview - -- Clear, descriptive title using `#` heading -- Brief introduction explaining the purpose and scope -- Optional: Project context section with key technologies and versions - -### 2. Core Sections - -Organize content into logical sections based on the domain: - -- **General Instructions**: High-level guidelines and principles -- **Best Practices**: Recommended patterns and approaches -- **Code Standards**: Naming conventions, formatting, style rules -- **Architecture/Structure**: Project organization and design patterns -- **Common Patterns**: Frequently used implementations -- **Security**: Security considerations (if applicable) -- **Performance**: Optimization guidelines (if applicable) -- **Testing**: Testing standards and approaches (if applicable) - -### 3. Examples and Code Snippets - -Provide concrete examples with clear labels: - -```markdown -### Good Example - -\`\`\`language // Recommended approach code example here \`\`\` - -### Bad Example - -\`\`\`language // Avoid this pattern code example here \`\`\` -```` - -### 4. Validation and Verification (Optional but Recommended) - -- Build commands to verify code -- Linting and formatting tools -- Testing requirements -- Verification steps - -## Content Guidelines - -### Writing Style - -- Use clear, concise language -- Write in imperative mood ("Use", "Implement", "Avoid") -- Be specific and actionable -- Avoid ambiguous terms like "should", "might", "possibly" -- Use bullet points and lists for readability -- Keep sections focused and scannable - -### Best Practices - -- **Be Specific**: Provide concrete examples rather than abstract concepts -- **Show Why**: Explain the reasoning behind recommendations when it adds value -- **Use Tables**: For comparing options, listing rules, or showing patterns -- **Include Examples**: Real code snippets are more effective than descriptions -- **Stay Current**: Reference current versions and best practices -- **Link Resources**: Include official documentation and authoritative sources - -### Common Patterns to Include - -1. **Naming Conventions**: How to name variables, functions, classes, files -1. **Code Organization**: File structure, module organization, import order -1. **Error Handling**: Preferred error handling patterns -1. **Dependencies**: How to manage and document dependencies -1. **Comments and Documentation**: When and how to document code -1. **Version Information**: Target language/framework versions - -## Patterns to Follow - -### Bullet Points and Lists - -```markdown -## Security Best Practices - -- Always validate user input before processing -- Use parameterized queries to prevent SQL injection -- Store secrets in environment variables, never in code -- Implement proper authentication and authorization -- Enable HTTPS for all production endpoints -``` - -### Tables for Structured Information - -```markdown -## Common Issues - -| Issue | Solution | Example | -| ---------------- | ------------------- | ----------------------------- | -| Magic numbers | Use named constants | `const MAX_RETRIES = 3` | -| Deep nesting | Extract functions | Refactor nested if statements | -| Hardcoded values | Use configuration | Store API URLs in config | -``` - -### Code Comparison - -```markdown -### Good Example - Using TypeScript interfaces - -\`\`\`typescript interface User { id: string; name: string; email: string; } - -function getUser(id: string): User { // Implementation } \`\`\` - -### Bad Example - Using any type - -\`\`\`typescript function getUser(id: any): any { // Loses type safety } \`\`\` -``` - -### Conditional Guidance - -```markdown -## Framework Selection - -- **For small projects**: Use Minimal API approach -- **For large projects**: Use controller-based architecture with clear separation -- **For microservices**: Consider domain-driven design patterns -``` - -## Patterns to Avoid - -- **Overly verbose explanations**: Keep it concise and scannable -- **Outdated information**: Always reference current versions and practices -- **Ambiguous guidelines**: Be specific about what to do or avoid -- **Missing examples**: Abstract rules without concrete code examples -- **Contradictory advice**: Ensure consistency throughout the file -- **Copy-paste from documentation**: Add value by distilling and contextualizing - -## Testing Your Instructions - -Before finalizing instruction files: - -1. **Test with Copilot**: Try the instructions with actual prompts in VS Code -1. **Verify Examples**: Ensure code examples are correct and run without errors -1. **Check Glob Patterns**: Confirm `applyTo` patterns match intended files - -## Example Structure - -Here's a minimal example structure for a new instruction file: - -```markdown ---- -description: "Brief description of purpose" -applyTo: "**/*.ext" ---- - -# Technology Name Development - -Brief introduction and context. - -## General Instructions - -- High-level guideline 1 -- High-level guideline 2 - -## Best Practices - -- Specific practice 1 -- Specific practice 2 - -## Code Standards - -### Naming Conventions - -- Rule 1 -- Rule 2 - -### File Organization - -- Structure 1 -- Structure 2 - -## Common Patterns - -### Pattern 1 - -Description and example - -\`\`\`language code example \`\`\` - -### Pattern 2 - -Description and example - -## Validation - -- Build command: `command to verify` -- Linting: `command to lint` -- Testing: `command to test` -``` - -## Maintenance - -- Review instructions when dependencies or frameworks are updated -- Update examples to reflect current best practices -- Remove outdated patterns or deprecated features -- Add new patterns as they emerge in the community -- Keep glob patterns accurate as project structure evolves - -## Additional Resources - -- [Custom Instructions Documentation](https://code.visualstudio.com/docs/copilot/customization/custom-instructions) -- [Awesome Copilot Instructions](https://github.com/github/awesome-copilot/tree/main/instructions) diff --git a/.github/instructions/java.instructions.md b/.github/instructions/java.instructions.md deleted file mode 100644 index 0bbf810f..00000000 --- a/.github/instructions/java.instructions.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -description: 'Guidelines for building Java base applications' -applyTo: '**/*.java' ---- - -# Java Development - -## General Instructions - -- First, prompt the user if they want to integrate static analysis tools (SonarQube, PMD, Checkstyle) into their project setup. - - If yes, document a recommended static-analysis setup. - - Prefer SonarQube/SonarCloud (SonarLint in IDE + `sonar-scanner` in CI). - - Create a Sonar project key. - - Store the scanner token in CI secrets. - - Provide a sample CI job that runs the scanner. - - If the team declines Sonar, note this in the project README and continue. - - If Sonar is bound to the project: - - Use Sonar as the primary source of actionable issues. - - Reference Sonar rule keys in remediation guidance. - - If Sonar is unavailable: - - Perform up to 3 troubleshooting checks: - 1. Verify project binding and token. - 1. Ensure SonarScanner runs in CI. - 1. Confirm SonarLint is installed and configured. - - If still failing after 3 attempts: - - Enable SpotBugs, PMD, or Checkstyle as CI fallbacks. - - Open a short tracker issue documenting the blocker and next steps. -- If the user declines static analysis tools or wants to proceed without them, continue with implementing the Best practices, bug patterns and code smell prevention guidelines outlined below. -- Address code smells proactively during development rather than accumulating technical debt. -- Focus on readability, maintainability, and performance when refactoring identified issues. -- Use IDE / Code editor reported warnings and suggestions to catch common patterns early in development. - -## Best practices - -- **Records**: For classes primarily intended to store data (e.g., DTOs, immutable data structures), **Java Records should be used instead of traditional classes**. -- **Pattern Matching**: Utilize pattern matching for `instanceof` and `switch` expression to simplify conditional logic and type casting. -- **Type Inference**: Use `var` for local variable declarations to improve readability, but only when the type is explicitly clear from the right-hand side of the expression. -- **Immutability**: Favor immutable objects. Make classes and fields `final` where possible. Use collections from `List.of()`/`Map.of()` for fixed data. Use `Stream.toList()` to create immutable lists. -- **Streams and Lambdas**: Use the Streams API and lambda expressions for collection processing. Employ method references (e.g., `stream.map(Foo::toBar)`). -- **Null Handling**: Avoid returning or accepting `null`. Use `Optional` for possibly-absent values and `Objects` utility methods like `equals()` and `requireNonNull()`. - -### Naming Conventions - -- Follow Google's Java style guide: - - `UpperCamelCase` for class and interface names. - - `lowerCamelCase` for method and variable names. - - `UPPER_SNAKE_CASE` for constants. - - `lowercase` for package names. -- Use nouns for classes (`UserService`) and verbs for methods (`getUserById`). -- Avoid abbreviations and Hungarian notation. - -### Common Bug Patterns - -Below are concise, human-readable rules you can apply regardless of which static analysis tool you use. If you run Sonar/SonarLint, the IDE will show the matching rule and location — direct Sonar connections are preferred and should override this ruleset. - -- Resource management — Always close resources (files, sockets, streams). Use try-with-resources where possible so resources are closed automatically. -- Equality checks — Compare object equality with `.equals()` or `Objects.equals(...)` rather than `==` for non-primitives; this avoids reference-equality bugs. -- Redundant casts — Remove unnecessary casts; prefer correct generic typing and let the compiler infer types where possible. -- Reachable conditions — Avoid conditional expressions that are always true or false; they indicate bugs or dead code and should be corrected. - -For contributors who _do_ use Sonar or SonarLint: the IDE/scan will show the specific rule key (for example, S2095 for resource leaks) and the affected file/line. Use that information to navigate to the exact location, then apply the recommended remediation. - -### Common Code Smells - -These patterns are phrased for humans; they map cleanly to checks in Sonar, SpotBugs, PMD, or Checkstyle but do not require those tools to be useful. - -- Parameter count — Keep method parameter lists short. If a method needs many params, consider grouping into a value object or using the builder pattern. -- Method size — Keep methods focused and small. Extract helper methods to improve readability and testability. -- Cognitive complexity — Reduce nested conditionals and heavy branching by extracting methods, using polymorphism, or applying the Strategy pattern. -- Duplicated literals — Extract repeated strings and numbers into named constants or enums to reduce errors and ease changes. -- Dead code — Remove unused variables and assignments. They confuse readers and can hide bugs. -- Magic numbers — Replace numeric literals with named constants that explain intent (e.g., MAX_RETRIES). - -If you run a static analyzer like Sonar or SonarLint — direct Sonar connections are preferred and should override this ruleset. Sonar rule keys are useful for automation and suppression, but they are not required in day-to-day developer guidance. - -## Build and Verification - -- After adding or modifying code, verify the project continues to build successfully. -- If the project uses Maven, run `mvn clean install`. -- If the project uses Gradle, run `./gradlew build` (or `gradlew.bat build` on Windows). -- Ensure all tests pass as part of the build. diff --git a/.github/instructions/nodejs-javascript-vitest.instructions.md b/.github/instructions/nodejs-javascript-vitest.instructions.md deleted file mode 100644 index a8a262b0..00000000 --- a/.github/instructions/nodejs-javascript-vitest.instructions.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -description: "Guidelines for writing Node.js and JavaScript code with Vitest testing" -applyTo: "**/*.js, **/*.mjs, **/*.cjs" ---- - -# Code Generation Guidelines - -## Coding standards - -- Use JavaScript with ES2022 features and Node.js (20+) ESM modules -- Use Node.js built-in modules and avoid external dependencies where possible -- Ask the user if you require any additional dependencies before adding them -- Always use async/await for asynchronous code, and use 'node:util' promisify function to avoid callbacks -- Keep the code simple and maintainable -- Use descriptive variable and function names -- Do not add comments unless absolutely necessary, the code should be self-explanatory -- Never use `null`, always use `undefined` for optional values -- Prefer functions over classes - -## Testing - -- Use Vitest for testing -- Write tests for all new features and bug fixes -- Ensure tests cover edge cases and error handling -- NEVER change the original code to make it easier to test, instead, write tests that cover the original code as it is - -## Documentation - -- When adding new features or making significant changes, update the README.md file where necessary - -## User interactions - -- Ask questions if you are unsure about the implementation details, design choices, or need clarification on the requirements -- Always answer in the same language as the question, but use english for the generated content like code, comments or docs diff --git a/.github/instructions/powershell.instructions.md b/.github/instructions/powershell.instructions.md deleted file mode 100644 index 75026ee6..00000000 --- a/.github/instructions/powershell.instructions.md +++ /dev/null @@ -1,309 +0,0 @@ ---- -applyTo: '**/*.ps1,**/*.psm1' -description: 'PowerShell cmdlet development and Windows automation best practices' ---- - -# PowerShell Guidelines - -**Target:** PowerShell 7+ (note 5.1 compat if needed) | **Style:** OTBS, 2-space indent | **Deps:** Prefer built-in cmdlets - -## Naming - -- **Verb-Noun**: Approved verbs (`Get-Verb`), singular nouns, PascalCase -- **Parameters**: PascalCase, standard names (`Path`, `Name`, `Force`, `ComputerName`) -- **Variables**: PascalCase (public), camelCase (private), ALL_CAPS (constants) -- **No Aliases**: Full cmdlet/parameter names in scripts (aliases OK in interactive shell) - -```powershell -# ✅ Good -function Get-UserProfile { - [CmdletBinding()] - param( - [Parameter(Mandatory)] - [ValidateNotNullOrEmpty()] - [string]$Username, - - [ValidateSet('Basic', 'Detailed')] - [string]$ProfileType = 'Basic' - ) - process { $userInfo = Get-ADUser -Identity $Username } -} - -# ❌ Bad -function GetUsrProf($u) { - gci HKLM:\Software | ? {$_.Name -like "*$u*"} -} -``` - -## Parameters - -- **Types**: Use .NET types (`[string]`, `[int]`, `[datetime]`) -- **Validation**: `[ValidateSet()]`, `[ValidateScript()]`, `[ValidateNotNullOrEmpty()]` -- **Switches**: Use `[switch]` for booleans (not `[bool]`) -- **Pipeline**: `ValueFromPipeline`, `ValueFromPipelineByPropertyName` - -```powershell -param( - [Parameter(Mandatory, ValueFromPipelineByPropertyName)] - [ValidateNotNullOrEmpty()] - [string]$Name, - - [ValidateSet('Dev', 'Test', 'Prod')] - [string]$Environment = 'Dev', - - [ValidateRange(1, 100)] - [int]$Priority = 50, - - [ValidateScript({Test-Path $_ -PathType Container})] - [string]$Path, - - [switch]$Force -) -``` - -## Pipeline & Output - -- **Begin/Process/End**: Use for pipeline handling -- **Objects**: Return `PSCustomObject`, not formatted text -- **Streaming**: Output one object at a time in `process` block -- **PassThru**: Return object after modification when `-PassThru` specified - -```powershell -function Process-Item { - [CmdletBinding()] - param( - [Parameter(ValueFromPipeline)] - [string[]]$Name, - [switch]$PassThru - ) - begin { $count = 0 } - process { - foreach ($item in $Name) { - # Process - $count++ - if ($PassThru) { - [PSCustomObject]@{ - Name = $item - Status = 'Processed' - } - } - } - } - end { Write-Verbose "Processed $count items" } -} -``` - -## Error Handling - -```powershell -function Invoke-SafeOperation { - [CmdletBinding()] - param([string]$Path) - - try { - $ErrorActionPreference = 'Stop' - $result = Get-Item -Path $Path - return $result - } - catch [System.IO.FileNotFoundException] { - Write-Error "File not found: $Path" - return $null - } - catch { - Write-Error "Unexpected error: $_" - throw - } -} -``` - -## Performance - -- **Pipeline**: Stream objects, don't collect in arrays -- **StringBuilder**: For string concatenation in loops -- **Where-Object**: Use `.Where({})` method for large collections -- **ForEach-Object**: Use `.ForEach({})` method for better performance -- **Measure**: Use `Measure-Command` to profile - -```powershell -# ❌ Slow -$items = Get-ChildItem -Recurse -$filtered = $items | Where-Object {$_.Extension -eq '.txt'} - -# ✅ Fast -$filtered = (Get-ChildItem -Recurse).Where({$_.Extension -eq '.txt'}) -``` - -## Module Structure - -```powershell -# MyModule.psm1 -$Public = @(Get-ChildItem -Path "$PSScriptRoot/Public/*.ps1") -$Private = @(Get-ChildItem -Path "$PSScriptRoot/Private/*.ps1") - -foreach ($import in @($Public + $Private)) { - try { . $import.FullName } - catch { Write-Error "Failed to import $($import.FullName): $_" } -} - -Export-ModuleMember -Function $Public.BaseName -``` - -## Advanced Functions - -```powershell -function Set-Configuration { - [CmdletBinding(SupportsShouldProcess, ConfirmImpact='High')] - param( - [Parameter(Mandatory, ValueFromPipeline)] - [string]$Name, - - [ValidateNotNullOrEmpty()] - [hashtable]$Settings, - - [switch]$Force - ) - - begin { - Write-Verbose "Starting configuration update" - } - - process { - if ($PSCmdlet.ShouldProcess($Name, 'Update configuration')) { - try { - # Apply settings - Write-Verbose "Updated $Name" - } - catch { - Write-Error "Failed to update $Name: $_" - } - } - } - - end { - Write-Verbose "Configuration update complete" - } -} -``` - -## Testing (Pester) - -```powershell -Describe 'Get-UserProfile' { - BeforeAll { - Mock Get-ADUser { [PSCustomObject]@{Name='TestUser'} } - } - - It 'Returns user profile' { - $result = Get-UserProfile -Username 'test' - $result.Name | Should -Be 'TestUser' - } - - It 'Validates username parameter' { - { Get-UserProfile -Username '' } | Should -Throw - } -} -``` - -## Security - -- **Credentials**: Use `[PSCredential]`, never plain text -- **SecureStrings**: For passwords/secrets -- **Constrained Language**: Support for restricted environments -- **Input Validation**: Always validate external input - -```powershell -function Connect-Service { - param( - [Parameter(Mandatory)] - [PSCredential]$Credential, - - [ValidateScript({$_ -match '^https://'})] - [string]$Uri - ) - - # Use credential securely -} -``` - -## Common Patterns - -**Splatting:** - -```powershell -$params = @{ - Path = 'C:\Temp' - Recurse = $true - Filter = '*.log' -} -Get-ChildItem @params -``` - -**Calculated Properties:** - -```powershell -Get-Process | Select-Object Name, @{ - Name = 'MemoryMB' - Expression = {[math]::Round($_.WorkingSet / 1MB, 2)} -} -``` - -**Hash Tables:** - -```powershell -$config = @{ - Server = 'prod-srv01' - Port = 443 - EnableSSL = $true - Tags = @('production', 'web') -} -``` - -## Windows-Specific - -**Registry:** - -```powershell -$regPath = 'HKLM:\SOFTWARE\MyApp' -if (!(Test-Path $regPath)) { - New-Item -Path $regPath -Force -} -Set-ItemProperty -Path $regPath -Name 'Version' -Value '1.0' -``` - -**Services:** - -```powershell -Get-Service -Name 'MyService' | - Where-Object {$_.Status -eq 'Running'} | - Stop-Service -Force -PassThru -``` - -**Event Logs:** - -```powershell -Get-EventLog -LogName Application -EntryType Error -Newest 10 -``` - -## Style Guide - -- OTBS braces (opening on same line) -- 2-space indentation -- `$PSScriptRoot` for relative paths -- `[CmdletBinding()]` for advanced functions -- `Write-Verbose` for diagnostic output -- `Write-Error` for non-terminating errors -- `throw` for terminating errors -- Comment-based help (`<#`, `#>`) - -## Checklist - -- [ ] Verb-Noun naming with approved verbs -- [ ] `[CmdletBinding()]` on functions -- [ ] Parameter validation attributes -- [ ] Pipeline support (Begin/Process/End) -- [ ] Return objects (not formatted text) -- [ ] Error handling (try/catch) -- [ ] `SupportsShouldProcess` for state changes -- [ ] Comment-based help -- [ ] Pester tests -- [ ] No aliases in scripts diff --git a/.github/instructions/python.instructions.md b/.github/instructions/python.instructions.md index 65ed4dc9..f4f8e289 100644 --- a/.github/instructions/python.instructions.md +++ b/.github/instructions/python.instructions.md @@ -1,28 +1,58 @@ --- applyTo: "**/*.py" -description: "Python coding conventions and guidelines" +description: "Production Python: strict typing, security, performance" --- -# Python Conventions +# Python Standards -## Core +## Toolchain -- **Style**: PEP 8; 4-space indent; max 80 chars. -- **Types**: Use `typing` (`List`, `Dict`, `Optional`); hints on all funcs. -- **Doc**: PEP 257 docstrings (Args/Returns) immediately after def. +- **Lint/Fmt**: `ruff check --fix && ruff format` (PEP 8, 4-space, 80 chars) +- **Types**: `mypy --strict` (no `Any`; full annotations) +- **Test**: `pytest -v --cov` (95%+ coverage, edge cases) +- **Deps**: `uv sync && uv audit` (security checks) -## Quality +## Core Rules -- **Funcs**: Small, atomic, descriptive names. -- **Readability**: Priority #1; comment complex algos/decisions. -- **Err**: Handle specific exceptions; no bare `except:`. -- **Test**: Unit tests for crit paths; cover edge cases (empty/invalid/large). +- **Style**: PEP 8, PEP 257 (docstrings), PEP 484 (type hints) +- **Types**: Modern generics (`list[str]`); `Protocol` for interfaces; no `Any` +- **Security**: Input validation, no hardcoded secrets, OWASP awareness +- **Perf**: O(n) algorithms; `lru_cache` for expensive ops; generators for large data +- **Arch**: SOLID principles, dependency injection, clean architecture -## Example +## Patterns + +**Type Safety:** ```python -def calc_area(r: float) -> float: - """Calc circle area. Args: r(float). Ret: area(float).""" - import math - return math.pi * r ** 2 +from typing import Protocol, TypeVar + +Entity = TypeVar("Entity") + +class Repository(Protocol): + def get(self, id: str) -> Entity | None: ... + def save(self, entity: Entity) -> None: ... ``` + +**Performance:** + +```python +from functools import lru_cache + +@lru_cache(maxsize=128) +def expensive(n: int) -> int: + return sum(range(n)) + +def stream_file(path: str) -> Iterator[str]: + with open(path) as f: + for line in f: + yield line.strip() +``` + +## Forbidden + +- Bare `except:` → catch specific exceptions +- `Any` type → use concrete types or `Protocol` +- Hardcoded secrets → use env vars +- O(n²) loops → use sets/dicts for lookups +- Global mutable state → use DI/parameters diff --git a/.github/instructions/rust.instructions.md b/.github/instructions/rust.instructions.md deleted file mode 100644 index 9de89320..00000000 --- a/.github/instructions/rust.instructions.md +++ /dev/null @@ -1,440 +0,0 @@ ---- -description: 'Rust coding conventions and idiomatic patterns' -applyTo: '**/*.rs' ---- - -# Rust Best Practices - -**Goal:** Memory-safe, performant, idiomatic Rust with zero-cost abstractions. - -## Core Rules - -- **Safety**: Ownership+borrowing > GC; no `.unwrap()` in prod; `Result` for errors -- **Performance**: Zero-cost abstractions; iterators > loops; stack > heap -- **Idioms**: Traits for polymorphism; lifetimes for safety; `?` operator -- **Format**: `cargo fmt`; Clippy strict (`-D warnings`); lines \<100; 2-space indent -- **Quality**: No warnings; comprehensive tests; rustdoc for public APIs - -## Project Structure - -```rust -// lib.rs or main.rs -mod error; // thiserror for custom errors -mod model; // Domain types -mod service; // Business logic -mod storage; // Persistence - -pub use error::{Error, Result}; -pub use model::*; -``` - -**Cargo.toml:** - -- Semantic versioning -- Metadata: `description`, `license`, `repository`, `keywords`, `categories` -- Feature flags for optional functionality - -## Ownership & Borrowing - -```rust -// ✅ Prefer borrowing -fn process(data: &str) -> String { data.to_uppercase() } - -// ✅ Mutable borrowing when needed -fn modify(data: &mut Vec) { data.push(42); } - -// ❌ Avoid unnecessary cloning -fn bad(data: String) -> String { data } -``` - -**Smart Pointers:** - -- `Box`: Heap allocation, single owner -- `Rc`: Shared ownership, single-threaded -- `Arc`: Shared ownership, multi-threaded -- `RefCell`: Interior mutability, single-threaded -- `Mutex`, `RwLock`: Interior mutability, multi-threaded - -## Error Handling - -```rust -use thiserror::Error; - -#[derive(Error, Debug)] -pub enum AppError { - #[error("IO error: {0}")] - Io(#[from] std::io::Error), - #[error("Parse error: {0}")] - Parse(String), - #[error("Not found: {0}")] - NotFound(String), -} - -pub type Result = std::result::Result; - -// Use ? operator -fn load_config() -> Result { - let data = std::fs::read_to_string("config.toml")?; - let config: Config = toml::from_str(&data) - .map_err(|e| AppError::Parse(e.to_string()))?; - Ok(config) -} -``` - -## Traits - -```rust -// Define behavior -pub trait Processor { - type Output; - fn process(&self, input: &str) -> Self::Output; -} - -// Implement for types -impl Processor for JsonProcessor { - type Output = serde_json::Value; - fn process(&self, input: &str) -> Self::Output { - serde_json::from_str(input).unwrap_or_default() - } -} - -// Generic constraints -fn run(p: &P, data: &str) -> P::Output { - p.process(data) -} -``` - -## Patterns - -**Builder Pattern:** - -```rust -pub struct Config { - host: String, - port: u16, - timeout: Duration, -} - -impl Config { - pub fn builder() -> ConfigBuilder { - ConfigBuilder::default() - } -} - -#[derive(Default)] -pub struct ConfigBuilder { - host: Option, - port: Option, - timeout: Option, -} - -impl ConfigBuilder { - pub fn host(mut self, h: impl Into) -> Self { - self.host = Some(h.into()); - self - } - - pub fn build(self) -> Result { - Ok(Config { - host: self.host.ok_or(AppError::Parse("host required".into()))?, - port: self.port.unwrap_or(8080), - timeout: self.timeout.unwrap_or(Duration::from_secs(30)), - }) - } -} -``` - -**Newtype Pattern:** - -```rust -#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub struct UserId(u64); - -impl UserId { - pub fn new(id: u64) -> Self { Self(id) } - pub fn inner(&self) -> u64 { self.0 } -} -``` - -**Iterator Chains:** - -```rust -// ✅ Idiomatic -let evens: Vec<_> = (0..100) - .filter(|x| x % 2 == 0) - .map(|x| x * 2) - .collect(); - -// ❌ Not idiomatic -let mut evens = Vec::new(); -for i in 0..100 { - if i % 2 == 0 { - evens.push(i * 2); - } -} -``` - -## Performance - -**Stack vs Heap:** - -```rust -let small = [0u8; 64]; // Stack (fast) -let large = vec![0u8; 1024*1024]; // Heap (necessary) -``` - -**Zero-Copy:** - -```rust -// ✅ Borrow instead of clone -fn process(data: &[u8]) -> usize { data.len() } - -// ✅ Cow for conditional ownership -use std::borrow::Cow; -fn maybe_modify(data: &str, modify: bool) -> Cow<'_, str> { - if modify { - Cow::Owned(data.to_uppercase()) - } else { - Cow::Borrowed(data) - } -} -``` - -**Inline:** - -```rust -#[inline] -pub fn hot_path(x: i32) -> i32 { x * 2 } - -#[inline(always)] -pub fn critical(x: i32) -> i32 { x + 1 } -``` - -## Concurrency - -**Channels:** - -```rust -use std::sync::mpsc; -use std::thread; - -let (tx, rx) = mpsc::channel(); -thread::spawn(move || { - tx.send(42).unwrap(); -}); -let value = rx.recv().unwrap(); -``` - -**Async:** - -```rust -use tokio; - -#[tokio::main] -async fn main() -> Result<()> { - let data = fetch_data().await?; - process(data).await?; - Ok(()) -} - -async fn fetch_data() -> Result { - let response = reqwest::get("https://api.example.com/data").await?; - response.text().await.map_err(Into::into) -} -``` - -**Rayon (Data Parallelism):** - -```rust -use rayon::prelude::*; - -let sum: i32 = (0..1000000) - .into_par_iter() - .map(|x| x * 2) - .sum(); -``` - -## Type Safety - -**Phantom Types:** - -```rust -use std::marker::PhantomData; - -struct Buffer { - data: Vec, - _marker: PhantomData<(T, State)>, -} - -struct Empty; -struct Full; - -impl Buffer { - fn new() -> Self { - Buffer { data: Vec::new(), _marker: PhantomData } - } - - fn fill(mut self, data: Vec) -> Buffer { - self.data = data; - Buffer { data: self.data, _marker: PhantomData } - } -} - -impl Buffer { - fn read(&self) -> &[u8] { &self.data } -} -``` - -## Unsafe Code - -```rust -// Only when absolutely necessary -// ALWAYS document safety invariants -unsafe fn from_raw_parts(ptr: *const u8, len: usize) -> &'static [u8] { - // SAFETY: Caller must ensure: - // 1. ptr is valid for reads of len bytes - // 2. ptr is properly aligned - // 3. Data at ptr outlives 'static - std::slice::from_raw_parts(ptr, len) -} -``` - -**Minimize unsafe:** - -- Use safe abstractions when possible -- Isolate unsafe code in small functions -- Document all safety invariants -- Test with Miri: `cargo miri test` - -## Testing - -```rust -#[cfg(test)] -mod tests { - use super::*; - - #[test] - fn test_basic() { - assert_eq!(process("test"), "TEST"); - } - - #[test] - #[should_panic(expected = "not found")] - fn test_error() { - load_missing_file().unwrap(); - } - - #[test] - fn test_result() -> Result<()> { - let config = load_config()?; - assert_eq!(config.port, 8080); - Ok(()) - } -} -``` - -**Property Testing:** - -```rust -use proptest::prelude::*; - -proptest! { - #[test] - fn test_reversible(s in "\\PC*") { - let encoded = encode(&s); - let decoded = decode(&encoded)?; - prop_assert_eq!(s, decoded); - } -} -``` - -## Documentation - -````rust -/// Processes input data and returns transformed output. -/// -/// # Arguments -/// * `input` - The input string to process -/// -/// # Returns -/// Transformed output string -/// -/// # Errors -/// Returns `AppError::Parse` if input is invalid -/// -/// # Examples -/// ``` -/// use mylib::process; -/// assert_eq!(process("test"), "TEST"); -/// ``` -pub fn process(input: &str) -> Result { - Ok(input.to_uppercase()) -} -```` - -## Toolchain - -```bash -# Format -cargo fmt - -# Lint (strict) -cargo clippy --all-targets --all-features -- -D warnings - -# Test -cargo test --all-features - -# Safety check -cargo miri test - -# Audit dependencies -cargo audit - -# Bench -cargo bench - -# Flamegraph -cargo flamegraph --bin myapp -``` - -## Cargo.toml Best Practices - -```toml -[package] -name = "myapp" -version = "0.1.0" -edition = "2021" -rust-version = "1.75" - -[dependencies] -serde = { version = "1.0", features = ["derive"] } -thiserror = "1.0" -tokio = { version = "1.35", features = ["full"] } - -[dev-dependencies] -proptest = "1.4" - -[profile.release] -lto = true # Link-time optimization -codegen-units = 1 # Better optimization -panic = "abort" # Smaller binary -strip = true # Remove debug symbols - -[lints.clippy] -all = "deny" -pedantic = "warn" -nursery = "warn" -``` - -## Checklist - -- [ ] No compiler warnings -- [ ] `cargo fmt` applied -- [ ] `cargo clippy` clean (no warnings) -- [ ] All tests pass -- [ ] Public APIs have rustdoc -- [ ] Error types use `thiserror` -- [ ] No `.unwrap()` in production code -- [ ] Unsafe code documented with safety invariants -- [ ] Feature flags for optional dependencies -- [ ] Semantic versioning diff --git a/.github/prompts/bash.prompt.md b/.github/prompts/bash.prompt.md deleted file mode 100644 index 8e8216d2..00000000 --- a/.github/prompts/bash.prompt.md +++ /dev/null @@ -1,34 +0,0 @@ -# Bash Agent Prompt - -## Context - -- **Target**: Bash/Shell. **Std**: `.github/instructions/bash.instructions.md`. -- **Platforms**: Arch, Debian, Termux. - -## Task: ${TASK_NAME} - -- **In**: Files:${FILES}, Trig:${TRIGGER}, Scope:${SCOPE}. - -## Exec Steps - -1. **Find**: `fd -e sh -e bash -t f -H -E . git` -1. **Lint**: `shellcheck --severity=style --format=diff ${files}` -1. **Fmt**: `shfmt -i 2 -bn -s -ln bash -w ${files}` -1. **Val**: Shebang (`#!/usr/bin/env bash`), Strict (`set -euo pipefail`), opts, traps. -1. **Rep**: Count mods/fixes/issues; Risk: L/M/H. -1. **Opt**: Replace external calls with builtins, modern tools (fd, rg, jaq, aria2), min subshell/forks, caching - -## Success ✅ - -- 0 Lint warns. Consist fmt. No break change. Tests pass. -- PR: Atomic commits (`[agent] task:...`); full changelog. - -# Lint check - -```bash -fd -e sh -e bash -t f -H -E .git ${scope} -bash -n ${files[@]} -shellcheck -S style -f diff ${files[@]} -shellharden --replace ${files[@]} -shfmt -i 2 -bn -s -ln bash ${files[@]} -``` diff --git a/.github/prompts/python.prompt.md b/.github/prompts/python.prompt.md deleted file mode 100644 index 4c84f6f4..00000000 --- a/.github/prompts/python.prompt.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -name: Python Architect -role: Senior Python Architect & SRE -description: Refactor and optimize Python code with strict typing, high performance (orjson/uvloop), ruff formatting, and atomic workflows. -model: claude-4-5-sonnet-latest -applyTo: "**/*.py" ---- - -**Goal**: Refactor existing Python code to maximize maintainability, type safety, and performance. Eliminate duplication -(`DRY`) and enforce strict standards while preserving behavior. - -## 1. Tooling & Standards - -- **Format**: Enforce **Black** style via `ruff format`. Soft limit **80 chars**. -- **Lint**: `ruff check .` (Python) and `biome` (configs/docs). -- **Deps**: Manage via `uv`. Lazy-import heavy modules. -- **Tests**: `pytest --durations=0`. New code **must** include tests (edge cases/boundaries). - -## 2. Strict Type Safety - -- **Rules**: Fully annotate functions/params/returns. Run `mypy --strict`. -- **Syntax**: Use modern generics (`list[str]`) over `typing` imports where possible. -- **Constraint**: No `Any` unless justified with `# TODO`. Prefer `DataClasses`/`TypedDict` over ad-hoc dicts. - -## 3. High-Performance Stack - -Prioritize speed and low memory footprint. Replace standard libs where applicable: | Standard | **Optimized -Replacement** | **Why** | | :--- | :--- | :--- | | `json` | **`orjson`** | ~6x faster serialization. | | `asyncio` | -**`uvloop`** | Node.js-level event loop speed. | | `requests` | **`httpx`** | Async, HTTP/2 support. | | `pandas` | -**`csv`** (Std Lib) | Use streaming `csv` for ETL to save RAM; Pandas only for complex analytics. | - -## 4. Code Quality & Logic - -- **Complexity**: Target **O(n)** or better. Use sets/dicts for lookups; avoid nested loops. -- **Structure**: Small, atomic functions (SRP). Snake_case naming. -- **Errors**: Catch specific exceptions only. Use `raise ... from e`. -- **State**: Avoid global mutable state. - -## 5. Workflow (Mandatory) - -Do **not** output code immediately. Follow this process: - -1. **Plan**: Bullet-point summary of changes, rationale, and verification steps. -1. **Refactor**: Incremental, atomic changes. -1. **Verify**: Run linters/tests. Compare metrics (complexity, coverage) if possible.