ma-agents 2.0.0 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor)",
   "main": "index.js",
   "bin": {

package/skills/README.md

@@ -302,6 +302,43 @@ Enforces target-based, property-oriented CMake patterns (CMake 3.0+ philosophy).
 
 ---
 
+### 14. Code Documentation Best Practices
+**Directory:** `code-documentation/`
+
+Enforces standardized file headers and method documentation across C++, C#, JS, and TS.
+
+**Key Features:**
+- ✅ **Standardized Headers**: Mandatory purpose, author, and version metadata.
+- ✅ **Language Standards**: Supporting Doxygen (C++), XML (C#), and JSDoc (JS/TS).
+- ✅ **Semantic Richness**: Mandates documenting `@param`, `@returns`, and `@throws`.
+
+---
+
+### 15. Python Security Best Practices
+**Directory:** `python-security-skill/`
+
+Enforces secure Python coding standards aligned with OWASP Top 10 2025.
+
+**Key Features:**
+- ✅ **Injection Prevention**: Bans `eval()`, `exec()`, and insecure shell commands.
+- ✅ **Secure Serialization**: Mandates `json` over `pickle` for untrusted data.
+- ✅ **Crypto Standards**: Enforces `secrets` module and modern hashing (SHA256+).
+- ✅ **Supply Chain**: Integrated with `pip-audit` and version pinning logic.
+
+---
+
+### 16. Python Dependency Management
+**Directory:** `python-dependency-mgmt/`
+
+Standardizes Python dependency handling using `uv` and `pip` (requirements.txt).
+
+**Key Features:**
+- ✅ **uv Mastery**: Full support for `uv lock`, `uv sync`, and `pyproject.toml`.
+- ✅ **Legacy Support**: Layered `requirements.txt` (pinned + hashes).
+- ✅ **Isolation**: Enforces virtual environment discipline and `.venv` usage.
+
+---
+
 ## Requirements
 
 ### All Skills

package/skills/code-documentation/SKILL.md

@@ -0,0 +1,53 @@
+# Code Documentation Best Practices
+
+This skill enforces high-quality, standardized documentation for source code files and methods. It ensures consistent metadata and clear explanations of intent across different programming languages.
+
+## Policies
+
+### 1. Mandatory File Headers
+*   **Rule**: Every source file must begin with a standardized header block.
+*   **Contents**:
+    - **Purpose**: A brief description of what the file contains/solves.
+    - **Author/Project**: Project name or author information.
+    - **Metadata**: Date created/modified and version if applicable.
+
+### 2. Mandatory Method Documentation
+*   **Rule**: Every public or non-trivial internal function/method must have a documentation block immediately preceding it.
+*   **Standards**:
+    - **C++**: Use Doxygen style (`/** ... */`).
+    - **C#**: Use XML Documentation style (`/// <summary> ...`).
+    - **JS/TS**: Use JSDoc style (`/** ... */`).
+    - **Python**: Use PEP 257 Docstrings (`""" ... """`).
+*   **Required Fields**:
+    - **Summary**: Concise description of what the method does.
+    - **Parameters**: Name and purpose of each argument.
+    - **Return Value**: Description of the output.
+    - **Exceptions/Errors**: Document significant error states or exceptions thrown.
+
+### 3. Focus on "Why" and "What"
+*   **Rule**: Do not document trivial code (e.g., `i++ // increment i`).
+*   **Action**: Document the **intent** and **usage constraints**. If the code is complex, explain the high-level logic rather than line-by-line mechanics.
+
+### 4. Semantic Linking
+*   **Rule**: Use language-specific linking features (e.g., `@see`, `{@link}`, `<see cref=.../>`) to refer to related types or methods.
+
+## Language Specifics
+
+| Language | Format | Key Tags |
+| :--- | :--- | :--- |
+| **C++** | Doxygen | `\brief`, `\param`, `\return`, `\throw` |
+| **C#** | XML Doc | `<summary>`, `<param>`, `<returns>`, `<exception>` |
+| **JS/TS** | JSDoc | `@description`, `@param`, `@returns`, `@throws` |
+| **Python** | Docstrings | `Args:`, `Returns:`, `Raises:` (Google/NumPy style) |
+
+---
+
+## Example (Generic Pattern)
+
+```text
+[File Header]
+[Imports]
+
+[Component Documentation]
+[Implementation]
+```

package/skills/code-documentation/examples/cpp.md

@@ -0,0 +1,29 @@
+# C++ Documentation (Doxygen Style)
+
+### File Header
+```cpp
+/**
+ * @file DataProcessor.hpp
+ * @brief Handles high-performance transformation of raw sensor data.
+ * @author Antigravity / ma-agents
+ * @date 2026-02-22
+ * @version 1.0.0
+ */
+```
+
+### Method Documentation
+```cpp
+/**
+ * @brief Calculates the moving average of a dataset.
+ * 
+ * This method uses a sliding window algorithm to smooth out volatility 
+ * in sensor inputs.
+ * 
+ * @param data A span of float values to process.
+ * @param windowSize The size of the averaging window (must be > 0).
+ * @return The calculated moving average as a float.
+ * @throw std::invalid_argument If data is empty or windowSize is invalid.
+ * @see SignalFilter
+ */
+float calculateMovingAverage(gsl::span<const float> data, size_t windowSize);
+```

package/skills/code-documentation/examples/csharp.md

@@ -0,0 +1,28 @@
+# C# Documentation (XML Style)
+
+### File Header
+```csharp
+/*
+ * File: AuthenticationService.cs
+ * Purpose: Manages user login, token validation, and multi-factor authentication.
+ * Author: Antigravity / ma-agents
+ * Date: 2026-02-22
+ */
+```
+
+### Method Documentation
+```csharp
+/// <summary>
+/// Validates a user's credentials against the secure identity store.
+/// </summary>
+/// <param name="username">The unique identifier for the user.</param>
+/// <param name="password">The plain-text password (will be hashed internally).</param>
+/// <returns>
+/// An <see cref="AuthResult"/> indicating success or failure with a details message.
+/// </returns>
+/// <exception cref="SecurityException">Thrown if the account is locked.</exception>
+public async Task<AuthResult> LoginAsync(string username, string password)
+{
+    // ...
+}
+```

package/skills/code-documentation/examples/javascript_typescript.md

@@ -0,0 +1,28 @@
+# JavaScript & TypeScript Documentation (JSDoc Style)
+
+### File Header
+```typescript
+/**
+ * @file api-client.ts
+ * @description Centralized HTTP client with automatic retry and error handling.
+ * @author Antigravity / ma-agents
+ * @version 1.2.0
+ */
+```
+
+### Method Documentation
+```typescript
+/**
+ * Fetches data from a specific endpoint with optional caching.
+ * 
+ * @template T The expected type of the response data.
+ * @param {string} url The target URL (must be absolute).
+ * @param {RequestOptions} [options] Optional configuration for headers and timeouts.
+ * @returns {Promise<T>} A promise that resolves to the parsed JSON response.
+ * @throws {NetworkError} If the server is unreachable.
+ * @throws {ValidationError} If the response schema does not match T.
+ */
+async function fetchData<T>(url: string, options?: RequestOptions): Promise<T> {
+  // ...
+}
+```

package/skills/code-documentation/examples/python.md

@@ -0,0 +1,57 @@
+# Python Documentation (Google/NumPy Style)
+
+### File Header
+Every module should start with a docstring that provides a high-level overview.
+
+```python
+"""
+data_processor.py
+~~~~~~~~~~~~~~~~~
+Handles high-performance transformation of raw sensor data using NumPy.
+
+:copyright: (c) 2026 by Antigravity.
+:license: MIT, see LICENSE for more details.
+"""
+```
+
+### Method Documentation
+Preferred style is Google or NumPy style for readability and integration with tools like Sphinx.
+
+```python
+def calculate_moving_average(data, window_size):
+    """Calculates the moving average of a dataset.
+
+    This method uses a sliding window algorithm to smooth out volatility 
+    in sensor inputs.
+
+    Args:
+        data (list[float]): A list or array of float values to process.
+        window_size (int): The size of the averaging window (must be > 0).
+
+    Returns:
+        float: The calculated moving average.
+
+    Raises:
+        ValueError: If data is empty or window_size is invalid.
+
+    Note:
+        This implementation assumes data is already cleaned.
+    """
+    if not data or window_size <= 0:
+        raise ValueError("Invalid data or window_size")
+    # ... implementation
+```
+
+### Class Documentation
+```python
+class SignalFilter:
+    """A collection of signal processing utilities.
+    
+    Attributes:
+        sampling_rate (int): The frequency at which signals are sampled.
+    """
+    
+    def __init__(self, sampling_rate):
+        """Initializes the SignalFilter with a specific sampling rate."""
+        self.sampling_rate = sampling_rate
+```

package/skills/code-documentation/skill.json

@@ -0,0 +1,23 @@
+{
+    "name": "Code Documentation Best Practices",
+    "description": "Standardize file headers and method documentation across C++, C#, JS, TS, and Python.",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "documentation",
+        "best-practices",
+        "cpp",
+        "csharp",
+        "javascript",
+        "typescript",
+        "doxygen",
+        "jsdoc"
+    ],
+    "applies_when": [
+        "creating or modifying source code files",
+        "defining new functions, methods, or classes",
+        "refactoring code logic",
+        "documenting APIs"
+    ],
+    "always_load": true
+}

package/skills/python-dependency-mgmt/SKILL.md

@@ -0,0 +1,38 @@
+# Python Dependency Management (uv & pip)
+
+This skill ensures consistent and reproducible Python environments using modern tools like `uv` and traditional standards like `requirements.txt`.
+
+## Policies
+
+### 1. Modern Workflow with `uv`
+*   **Rule**: Use `uv` for lightning-fast project management if available.
+*   **Action**: 
+    - Use `uv lock` to generate `uv.lock`.
+    - Use `uv sync` to keep the environment in sync with the lockfile.
+    - Declare dependencies in `pyproject.toml`.
+*   **Rationale**: `uv` is significantly faster than `pip` and provides deterministic builds via lockfiles.
+
+### 2. Standardized `requirements.txt`
+*   **Rule**: If not using a modern manager, use a layered and pinned `requirements.txt` structure.
+*   **Action**: 
+    - **Layered**: Use `requirements.in` (top-level deps) and `requirements.txt` (fully pinned transitive deps).
+    - **Environment Split**: Separate `requirements.txt` from `dev-requirements.txt`.
+    - **Hashes**: Generate hashes for security (`--generate-hashes` via `pip-compile`).
+
+### 3. Strict Version Pinning
+*   **Rule**: All production dependencies must be pinned to a specific version.
+*   **Action**: Use `package==1.2.3`, never `package>=1.2.3` in the final lock/txt file.
+
+### 4. Virtual Environment Discipline
+*   **Rule**: Never install dependencies globally. 
+*   **Action**: 
+    - Always create a `.venv` in the project root.
+    - For `uv`, it handles this automatically with `uv venv` or implicitly via `uv run`.
+
+### 5. Standard Build Systems (PEP 517/518)
+*   **Rule**: Use `pyproject.toml` as the source of truth for build metadata.
+
+## Tools of Choice
+1. **uv**: (Recommended) Fastest all-in-one manager.
+2. **pip-tools**: For generating pinned `requirements.txt` from `.in` files.
+3. **venv**: Core standard for isolation.

package/skills/python-dependency-mgmt/examples/dependency_mgmt.md

@@ -0,0 +1,67 @@
+# Python Dependency Management Examples
+
+### 1. Modern Workspace with `uv`
+**pyproject.toml:**
+```toml
+[project]
+name = "my-app"
+version = "0.1.0"
+dependencies = [
+    "requests==2.31.0",
+    "structlog>=24.1.0",
+]
+
+[tool.uv]
+managed = true
+```
+
+**Commands:**
+```bash
+# Add a new dependency and update lockfile
+uv add pandas
+
+# Run a script within the isolated environment
+uv run main.py
+
+# Sync environment with the lockfile
+uv sync
+```
+
+### 2. Traditional `requirements.txt` (pip-tools)
+**requirements.in:**
+```text
+flask
+psycopg2-binary
+```
+
+**Workflow:**
+```bash
+# Generate pinned requirements.txt with hashes
+pip-compile --generate-hashes requirements.in
+
+# Install exactly what is pinned
+pip install -r requirements.txt
+```
+
+### 3. Development vs Production Deps
+**dev-requirements.in:**
+```text
+-c requirements.txt
+pytest
+black
+ruff
+```
+
+```bash
+# Generate dev-requirements.txt
+pip-compile dev-requirements.in
+```
+
+### 4. Virtual Environment Setup (Standard)
+```bash
+python -m venv .venv
+# Linux/macOS
+source .venv/bin/activate
+# Windows
+.venv\Scripts\activate
+```

package/skills/python-dependency-mgmt/skill.json

@@ -0,0 +1,21 @@
+{
+    "name": "Python Dependency Management",
+    "description": "Standardize Python dependency handling using uv and pip (requirements.txt).",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "python",
+        "uv",
+        "pip",
+        "dependencies",
+        "packaging",
+        "best-practices"
+    ],
+    "applies_when": [
+        "managing Python project dependencies",
+        "configuring Python build systems",
+        "updating requirements.txt or uv.lock",
+        "setting up Python development environments"
+    ],
+    "always_load": true
+}

package/skills/python-security-skill/SKILL.md

@@ -0,0 +1,52 @@
+# Python Security Best Practices (OWASP 2025 aligned)
+
+This skill provides mandatory security guardrails for Python applications, ensuring protection against common vulnerabilities and alignment with OWASP Top 10 standards.
+
+## Policies
+
+### 1. Zero Insecure Function Usage
+*   **Rule**: Ban functions that allow arbitrary code execution or insecure OS commands.
+*   **Action**: 
+    - NEVER use `eval()` or `exec()`.
+    - Avoid `subprocess.run(..., shell=True)`. Use lists for commands instead.
+    - Avoid `yaml.load()` without specifying a loader (use `yaml.safe_load()`).
+
+### 2. Secure Data Serialization
+*   **Rule**: Protect against insecure deserialization.
+*   - **Action**: 
+    - NEVER use `pickle` for untrusted data. Use `json` instead.
+    - Be cautious with `xml.etree.ElementTree` (vulnerable to XXE); use `defusedxml` if possible.
+
+### 3. Injection Prevention (A05:2025)
+*   **Rule**: Use parameterized queries for all database and API interactions.
+*   **Action**: 
+    - Never use f-strings or `.format()` for SQL queries.
+    - Use ORM features (Django ORM, SQLAlchemy) or parameter placeholders (`%s`, `?`).
+
+### 4. Cryptographic Standards (A04:2025)
+*   **Rule**: Use modern, collision-resistant hashing and encryption.
+*   **Action**: 
+    - Use `hashlib.sha256()` or better. Ban MD5 and SHA1.
+    - Use `secrets` module for tokens/passwords, not `random`.
+
+### 5. Dependency Integrity (A03:2025)
+*   **Rule**: Lock dependencies and scan for known vulnerabilities.
+*   **Action**: 
+    - Always commit lockfiles (`uv.lock`, `poetry.lock`, or `requirements.txt` with hashes).
+    - Periodically run `pip-audit` or `safety`.
+
+### 6. Secure Error Handling (A10:2025)
+*   **Rule**: Do not leak sensitive information in tracebacks or logs.
+*   **Action**: 
+    - Never log `pydantic` models or raw request bodies containing PII/Secrets.
+    - Use generic error messages for end-users while keeping detailed logs internally.
+
+## Python Security Mapping (OWASP 2025)
+
+| Category | Python Vulnerability | Secure Alternative |
+| :--- | :--- | :--- |
+| **A01: Access Control** | URL hijacking in `requests` | Validate redirect targets |
+| **A02: Configuration** | Debug mode in Flask/Django | `DEBUG = False` in production |
+| **A03: Supply Chain** | Typosquatting/Old deps | Pin versions + `pip-audit` |
+| **A05: Injection** | `os.system()` / RAW SQL | `subprocess.run()` list / ORM |
+| **A08: Integrity** | `pickle.load()` | `json.loads()` |

package/skills/python-security-skill/examples/security.md

@@ -0,0 +1,56 @@
+# Python Security Examples
+
+### 1. Secure Subprocess (Avoiding Injection)
+**Dangerous:**
+```python
+import os
+def delete_file(filename):
+    os.system(f"rm -rf {filename}") # VULNERABLE to injection
+```
+
+**Secure:**
+```python
+import subprocess
+def delete_file(filename):
+    # Pass as a list, shell=False by default
+    subprocess.run(["rm", "-rf", filename], check=True)
+```
+
+### 2. Secure Serialization
+**Dangerous:**
+```python
+import pickle
+def load_user(data):
+    return pickle.loads(data) # VULNERABLE to arbitrary code execution
+```
+
+**Secure:**
+```python
+import json
+def load_user(data):
+    return json.loads(data) # Safe for untrusted input
+```
+
+### 3. Preventing SQL Injection
+**Dangerous:**
+```python
+cursor.execute(f"SELECT * FROM users WHERE id = '{user_id}'")
+```
+
+**Secure:**
+```python
+cursor.execute("SELECT * FROM users WHERE id = %s", (user_id,))
+```
+
+### 4. Secure Randomness
+**Dangerous:**
+```python
+import random
+token = str(random.random()) # Predictable
+```
+
+**Secure:**
+```python
+import secrets
+token = secrets.token_urlsafe(32) # Cryptographically secure
+```

package/skills/python-security-skill/skill.json

@@ -0,0 +1,20 @@
+{
+    "name": "Python Security Best Practices",
+    "description": "Enforce secure Python coding standards following OWASP Top 10 2025.",
+    "version": "1.0.0",
+    "author": "Antigravity",
+    "tags": [
+        "python",
+        "security",
+        "owasp",
+        "vulnerability-prevention",
+        "best-practices"
+    ],
+    "applies_when": [
+        "writing or reviewing Python code",
+        "managing Python dependencies",
+        "configuring Python application environments",
+        "handling sensitive data in Python"
+    ],
+    "always_load": true
+}

package/skills/test-accompanied-development/SKILL.md

@@ -33,7 +33,14 @@ To ensure high code quality and maintainability by mandating that all public int
 
 ## Example Workflow
 
+### TypeScript (Jest)
 1.  **Agent**: "I am adding a `calculateTotal` method to the `InvoiceService`. I will also create `InvoiceService.test.ts` to verify it."
 2.  **Agent**: [Writes `calculateTotal` in `InvoiceService.ts`]
 3.  **Agent**: [Writes tests in `InvoiceService.test.ts` using `test-generator` patterns]
 4.  **Agent**: "Method and tests are complete. Running tests now..."
+
+### Python (Pytest)
+1.  **Agent**: "I am adding a `validate_user` function to `auth.py`. I will also create `tests/test_auth.py` to verify it."
+2.  **Agent**: [Writes `validate_user` in `auth.py`]
+3.  **Agent**: [Writes tests in `tests/test_auth.py` using `test-generator` patterns]
+4.  **Agent**: "Implementation and tests are ready. Running `pytest`."

package/skills/test-accompanied-development/skill.json

@@ -7,7 +7,9 @@
         "testing",
         "quality",
         "policy",
-        "tdd"
+        "tdd",
+        "python",
+        "pytest"
     ],
     "applies_when": [
         "writing or reviewing public APIs",

package/skills/test-generator/SKILL.md

@@ -35,8 +35,9 @@ Generate comprehensive unit and integration tests for code.
 - Mock external dependencies
 - Clear assertion messages
 
-## Example Output
+## Example Outputs
 
+### JavaScript (Jest)
 ```javascript
 describe('ComponentName', () => {
   test('should [behavior] when [condition]', () => {
@@ -49,13 +50,25 @@ describe('ComponentName', () => {
     // Assert
     expect(result).toEqual(expectedOutput);
   });
+});
+```
 
-  test('should handle edge case', () => {
-    // ...
-  });
+### Python (Pytest)
+```python
+import pytest
+from app.module import function_under_test
 
-  test('should throw on invalid input', () => {
-    expect(() => fn(invalid)).toThrow();
-  });
-});
+def test_should_behavior_when_condition():
+    # Arrange
+    input_data = setup_test_data()
+    
+    # Act
+    result = function_under_test(input_data)
+    
+    # Assert
+    assert result == expected_output
+
+def test_should_raise_on_invalid_input():
+    with pytest.raises(ValueError):
+        function_under_test(None)
 ```

package/skills/test-generator/skill.json

@@ -7,6 +7,8 @@
     "testing",
     "unit-tests",
     "integration-tests",
+    "python",
+    "pytest",
     "quality"
   ],
   "applies_when": [